assets
Pictures, painted textures, fonts and pixel shaders, and reading the files that ship with the script.
Assets are created on worker threads and become ready a few frames later. Until then drawing them does nothing, so either check ready() or wait for one with task.await(tex). Textures and shaders are released when the script stops. Fonts are the exception: the font atlas cannot drop a font, so a font a script added stays in memory until the overlay restarts (loading the same font again costs nothing).
Paths are relative to the script's installed folder, which is read-only. "data:name.png" reads from the script's data folder instead (where file.write puts things).
Reference#
assets.texture#since 1.0
assets.texture(path: string): TextureLoads a picture. Up to 64 textures and 64 MB per script.
| Parameter | Type | Description |
|---|---|---|
path | string | PNG, JPEG, BMP or TGA, up to 4096 x 4096. "data:name.png" reads the data folder. |
| Returns | Description |
|---|---|
Texture | A texture handle. |
local logo = assets.texture("assets/logo.png")
events.on("draw", function()
if logo:ready() then draw.image(logo, 20, 20, 64, 64) end
end)assets.canvas#since 1.0
assets.canvas(w: integer, h: integer): TextureCreates an empty texture you fill with set_pixel, fill or set_pixels. It uploads when changed.
| Parameter | Type | Description |
|---|---|---|
w | integer | Width, up to 1024. |
h | integer | Height, up to 1024. |
| Returns | Description |
|---|---|
Texture | A texture whose pixels you paint. |
assets.font#since 1.0
assets.font(path: string, size: number): FontLoads a font. It is built into the atlas before the next frame (one short hitch). At most 8 per script and 24 in all.
| Parameter | Type | Description |
|---|---|---|
path | string | A font file in the script folder, or "system:arial.ttf" for a font in the Windows font folder. |
size | number | Pixel size. |
| Returns | Description |
|---|---|
Font | A font handle. |
local f = assets.font("system:segoeui.ttf", 18)
events.on("draw", function()
if f:ready() then draw.text(20, 20, 0xFFFFFFFF, "hello", { font = f }) end
end)assets.shader#since 1.0
assets.shader(options: table): ShaderCompiles a pixel shader for draw.shader_rect. A shader that breaks a rule is refused with a message in the script's console.
| Parameter | Type | Description |
|---|---|---|
options | table | {hlsl = "float4 shade(float2 uv, float4 col) { ... }"}. Inside: u_p[0..3] (16 floats), u_time, u_size. No loops, no # directives, no resource declarations; at most 400 instructions and 8 KB. |
| Returns | Description |
|---|---|
Shader | A shader handle (compiled on a worker). |
local s = assets.shader{ hlsl = "float4 shade(float2 uv, float4 col) { return float4(uv.x, uv.y, 0.5, 1.0); }" }assets.read#since 1.0
assets.read(path: string): string | nil, string?Reads a file that ships with the script. Read only.
| Parameter | Type | Description |
|---|---|---|
path | string | A path inside the script's folder. |
| Returns | Description |
|---|---|
string | nil | The file's contents. |
string? | The error when it is nil. |
assets.exists#since 1.0
assets.exists(path: string): booleanChecks for a shipped file.
| Parameter | Type | Description |
|---|---|---|
path | string | A path inside the script's folder. |
| Returns | Description |
|---|---|
boolean | Whether it exists. |
assets.list#since 1.0
assets.list(dir?: string): string[]Lists a folder of the script.
| Parameter | Type | Description |
|---|---|---|
dir optional | string | A folder inside the script's folder. default the root |
| Returns | Description |
|---|---|
string[] | File names. |
Texture#
Returned by assets.texture, assets.canvas and media.cover.
tex:ready#since 1.0
tex:ready(): booleanAsks whether the texture can be drawn.
| Returns | Description |
|---|---|
boolean | Whether the picture is decoded and uploaded. |
tex:failed#since 1.0
tex:failed(): boolean, string?Asks whether loading failed. A missing or unsupported file fails here, with the reason.
| Returns | Description |
|---|---|
boolean | Whether loading failed. |
string? | The reason. |
tex:size#since 1.0
tex:size(): integer, integerThe picture's size in pixels.
| Returns | Description |
|---|---|
integer | Width. |
integer | Height. |
tex:free#since 1.0
tex:free()Releases the texture now instead of at unload.
tex:set_pixel#since 1.0
tex:set_pixel(x: integer, y: integer, col: integer)Sets one pixel. Canvas textures only.
| Parameter | Type | Description |
|---|---|---|
x | integer | Column. |
y | integer | Row. |
col | integer | Colour. |
tex:fill#since 1.0
tex:fill(col: integer)Fills the whole canvas. Canvas textures only.
| Parameter | Type | Description |
|---|---|---|
col | integer | Colour. |
tex:set_pixels#since 1.0
tex:set_pixels(rgba: string)Replaces all the pixels at once. Canvas textures only.
| Parameter | Type | Description |
|---|---|---|
rgba | string | Raw RGBA bytes, 4 per pixel, row by row. |
Font#
Returned by assets.font. Pass it as {font = f} to draw.text.
font:ready#since 1.0
font:ready(): booleanAsks whether the font can be used.
| Returns | Description |
|---|---|
boolean | Whether the font is in the atlas. |
Shader#
Returned by assets.shader.
shader:state#since 1.0
shader:state(): boolean, string?Asks whether the shader compiled.
| Returns | Description |
|---|---|
boolean | Ready. |
string? | The compile error, if it failed. |