The assets folder

assets is client.assets() and reads files under %APPDATA%\Nursultan\scripts\assets. base64(...) is the alternative: it turns string literals in the .kts itself into bytes a font or an image can be built from. Everything on this page is API 2 except sound, which is API 9.

val greeting = assets.text("messages/hello.txt") ?: "no file"

val FONT = base64(
    "AAEAAAAOAIAAAwBgT1MvMg…",
    "…AAAAAAAAAAAAAAAAAAAA=",
)
font("myfont", FONT)

var siren: SoundHandle? = null
onEnable { siren = sound.loop("sounds/siren.ogg", 0.3f, 1f) }

on<Render2DEvent> { e ->
    e.render().text(greeting, 10f, 10f, 12f, Colors.WHITE, "myfont")
}

on<AttackEvent> {
    siren?.stop()
    sound.play("sounds/hit.wav", 0.6f, 1.2f)
}

Reading a file

Method Type Description
assets.exists(path) boolean true when the path resolves inside scripts/assets and is a regular file (API 2)
assets.bytes(path) byte[]? whole file, null when rejected, missing, over 8 MiB or unreadable (API 2)
assets.text(path) String? the same bytes decoded as UTF-8, null under the same conditions (API 2)
assets.list() List<String> sorted file names directly in the assets root, capped at 1024 (API 2)
assets.list(directory) List<String> same for one subfolder, empty when it does not resolve or is not a directory; null, blank or "." means the root (API 2)

Paths are relative to scripts/assets, forward or backslash separated. Nothing here throws: a rejected, missing or oversized file gives null or an empty list plus one warning in the script console. list returns file names only — no paths, no directories, no recursion.

Playing a sound

sound is client.sound() and plays a .wav or .ogg file out of the same folder.

Method Type Description
sound.play(path) SoundHandle? plays the file once at full volume, null when rejected (API 9)
sound.play(path, volume, pitch) SoundHandle? the same with volume 0..1 and pitch 0.5..2, both clamped (API 9)
sound.loop(path) SoundHandle? plays the file over and over until it is stopped (API 9)
sound.loop(path, volume, pitch) SoundHandle? the same with volume 0..1 and pitch 0.5..2, both clamped (API 9)
sound.stopAll() void stops every sound this script started (API 9)
handle.path() String the path the handle was made from (API 9)
handle.stop() void stops that one sound (API 9)

.wav and .ogg decode, .mp3 gives null; paths and rejections are the ones above. A sound is flat and volume is its only level; every sound of a script stops when it is switched off or unloaded.

Limit Value
file size 8 MiB
looping sounds at a time 8
calls per second 32

Going over a limit warns once in the script console and returns null.

What is rejected

Rejected What you get
.. in any path segment null / empty list
absolute path, drive letter or UNC path null / empty list
empty, blank or malformed path null / empty list
a path whose real target leaves scripts/assets null / empty list
a file larger than 8 MiB null from bytes and text
more than 1024 files in one folder the first 1024 names, the rest skipped

Each case warns once per path in the script console. There is no way to open a file by absolute path and nothing in the API writes files — for a script's own data see Saving data.

Assets inside the script

Method Type Description
base64(vararg parts) ByteArray joins the parts and MIME-decodes them, empty vararg gives an empty array (API 2) (throws ScriptApiException when the payload is not valid base64)
base64Encode(bytes) String standard base64 on one line, the other direction (API 2)
font(name, ttf) void registers a TTF family from bytes, ignored when the name is taken, the array is empty or over 8 MiB (API 2)
image(name, png) Texture? PNG from bytes cached under name, null for a blank name, empty bytes or over 8 MiB (API 2)

The joined text may be a data: URL: everything up to and including ;base64, is dropped, and a data: prefix without that marker throws ScriptApiException. Whitespace and line breaks inside a part are ignored. A single string literal in a class file cannot exceed 64 KB, and Kotlin folds "a" + "b" back into one — that is why base64 takes a vararg. name in image(name, png) is a per-script cache key, not a path; both byte overloads are also listed on 2D render.

Files from older scripts

font(name, file), image(file), client.fonts().register(name, file), client.textures().image(file) and Render.image(file, …) fall back to the scripts root when the file is not in scripts/assets, and warn once in the console. exists, bytes, text and list have no fallback — they only ever read scripts/assets. texture(identifier) takes a Minecraft resource id, not a file, and touches neither folder.

Last updated