wolfhacklua API 1.1 Forum

assets

Pictures, painted textures, fonts and pixel shaders, and reading the files that ship with the script.

since 1.0no permission needed

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): Texture

Loads a picture. Up to 64 textures and 64 MB per script.

ParameterTypeDescription
pathstringPNG, JPEG, BMP or TGA, up to 4096 x 4096. "data:name.png" reads the data folder.
ReturnsDescription
TextureA texture handle.
lua
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): Texture

Creates an empty texture you fill with set_pixel, fill or set_pixels. It uploads when changed.

ParameterTypeDescription
wintegerWidth, up to 1024.
hintegerHeight, up to 1024.
ReturnsDescription
TextureA texture whose pixels you paint.

assets.font#since 1.0

assets.font(path: string, size: number): Font

Loads a font. It is built into the atlas before the next frame (one short hitch). At most 8 per script and 24 in all.

ParameterTypeDescription
pathstringA font file in the script folder, or "system:arial.ttf" for a font in the Windows font folder.
sizenumberPixel size.
ReturnsDescription
FontA font handle.
lua
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): Shader

Compiles a pixel shader for draw.shader_rect. A shader that breaks a rule is refused with a message in the script's console.

ParameterTypeDescription
optionstable{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.
ReturnsDescription
ShaderA shader handle (compiled on a worker).
lua
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.

ParameterTypeDescription
pathstringA path inside the script's folder.
ReturnsDescription
string | nilThe file's contents.
string?The error when it is nil.

assets.exists#since 1.0

assets.exists(path: string): boolean

Checks for a shipped file.

ParameterTypeDescription
pathstringA path inside the script's folder.
ReturnsDescription
booleanWhether it exists.

assets.list#since 1.0

assets.list(dir?: string): string[]

Lists a folder of the script.

ParameterTypeDescription
dir optionalstringA folder inside the script's folder. default the root
ReturnsDescription
string[]File names.

Texture#

Returned by assets.texture, assets.canvas and media.cover.

tex:ready#since 1.0

tex:ready(): boolean

Asks whether the texture can be drawn.

ReturnsDescription
booleanWhether 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.

ReturnsDescription
booleanWhether loading failed.
string?The reason.

tex:size#since 1.0

tex:size(): integer, integer

The picture's size in pixels.

ReturnsDescription
integerWidth.
integerHeight.

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.

ParameterTypeDescription
xintegerColumn.
yintegerRow.
colintegerColour.

tex:fill#since 1.0

tex:fill(col: integer)

Fills the whole canvas. Canvas textures only.

ParameterTypeDescription
colintegerColour.

tex:set_pixels#since 1.0

tex:set_pixels(rgba: string)

Replaces all the pixels at once. Canvas textures only.

ParameterTypeDescription
rgbastringRaw 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(): boolean

Asks whether the font can be used.

ReturnsDescription
booleanWhether 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.

ReturnsDescription
booleanReady.
string?The compile error, if it failed.
API 1.1 · source docs-src/api/assets.json