datumhue.uuid
functiondatumhue.uuid() -> stringGenerate a fresh random UUID in canonical hyphenated form.
In the guide: Save data between runs
namespace10 functions, 2 fields
datumhue
The table every app is given as the global datumhue: its namespaces, and the functions and fields on it directly.
Functions 10
datumhue.stat
functiondatumhue.stat(key: StatKey) -> number | integerQuery a performance counter by key. A counter that has not produced a sample yet reports 0. An unknown key raises.
In the guide: Find what's slow
datumhue.on_update
functiondatumhue.on_update(callback: (fun(dt: number))?)Register the per-frame update handler; dt is the seconds since the previous invocation. At most one handler is active per app — calling again replaces the previous one. Pass nil to clear it. Timer callbacks due in a frame run before it in that frame. At most one invocation is in flight: frames that pass while one is still running (a suspending call keeps it running) start none, and their time accrues into the next dt.
In the guide: Draw and animate Make it interactive Pixel art and sprites
datumhue.on_terminate
functiondatumhue.on_terminate(callback: (fun())?)Register the termination handler. It runs once, when the app is being terminated — its own terminate, a manager's terminate_app, an ancestor's termination cascading down, or a service app ending with nothing left to run — but not when the app crashes or the workstation itself exits. The handler gets a short, bounded time budget to flush state; suspending calls are allowed and the budget keeps counting while they wait, and when it runs out the ending goes on regardless. It cannot cancel the termination. When a termination cascades to several descendants, the order in which their handlers run is unspecified. Registering a handler does not keep an idle service app alive. At most one handler is active per app — calling again replaces the previous one, and one registered while the handler runs never runs. Pass nil to clear it.
In the guide: Launch other apps How your app runs
datumhue.ready(handles: any[])Wait until every handle in the array is ready — a barrier across a mixed batch of loadable assets (Image, AudioAsset, SceneAsset, CubemapAsset, Font, Shader, DataHandle), Bytes (file-backed bytes are read into memory, as their :ready() does), and request handles (each class with a :ready() method). Returns nothing; chain a single handle with its own :ready() instead. Raises on the first failure. A never-arriving remote target waits indefinitely.
local store = datumhue.storage.open()
local name = store:get("name")
local level = store:get("level")
-- One wait for both lookups.
datumhue.ready({ name, level })
print(name.state, level.state) --> ready readyIn the guide: Troubleshooting Waiting: suspending calls and handles
datumhue.bytes
functiondatumhue.bytes(s: string) -> BytesLift a Lua string to opaque Bytes.
datumhue.math.vec2
functiondatumhue.math.vec2(x: number, y: number) -> Vec2Construct a 2D vector: vec2() is (0,0), vec2(s) splats, vec2(x, y) is component-wise.
print(datumhue.math.vec2()) --> vec2(0.0, 0.0)
-- One number fills both components.
print(datumhue.math.vec2(2)) --> vec2(2.0, 2.0)
print(datumhue.math.vec2(3, 4)) --> vec2(3.0, 4.0)datumhue.math.vec3
functiondatumhue.math.vec3(x: number, y: number, z: number) -> Vec3Construct a 3D vector: vec3() is (0,0,0), vec3(s) splats, vec3(x, y) sets z=0, vec3(x, y, z) is component-wise.
Also accepts:
datumhue.math.vec3() -> Vec3datumhue.math.vec3(scalar: number) -> Vec3datumhue.math.vec3(x: number, y: number) -> Vec3print(datumhue.math.vec3()) --> vec3(0.0, 0.0, 0.0)
print(datumhue.math.vec3(2)) --> vec3(2.0, 2.0, 2.0)
-- Two numbers set x and y, and z is 0.
print(datumhue.math.vec3(3, 4)) --> vec3(3.0, 4.0, 0.0)
print(datumhue.math.vec3(3, 4, 5)) --> vec3(3.0, 4.0, 5.0)datumhue.math.ray
functionConstruct a ray from an origin and a direction (normalized on construction). Raises if the origin is not finite or the direction is zero or not finite.
-- The direction is normalized: 4 units along -Z becomes 1.
local origin = datumhue.math.vec3(0, 1, 0)
local ray = datumhue.math.ray(origin, datumhue.math.vec3(0, 0, -4))
print(ray.direction) --> vec3(0.0, 0.0, -1.0)datumhue.color
functiondatumhue.color(r: number, g: number, b: number, a?: number) -> ColorConstruct a color from a hex string (#RRGGBB/#RRGGBBAA) or r, g, b[, a] numbers (0..1).
Also accepts:
datumhue.color(hex: string) -> Color-- A hex string, or r, g, b and an optional alpha, each 0 to 1.
print(datumhue.color("#ff0000")) --> color(1.0, 0.0, 0.0, 1.0)
print(datumhue.color(0.25, 0.5, 1)) --> color(0.25, 0.5, 1.0, 1.0)
print(datumhue.color(0.25, 0.5, 1, 0.5)) --> color(0.25, 0.5, 1.0, 0.5)Fields 2
| Field | Type | Access | Description |
|---|---|---|---|
args | AppArgs | read-only | Filesystem and launch capabilities granted to this app at spawn. |
package | Package? | read-only | The running app's own loaded package bundle — its manifest metadata (.name, :version(), :kind()) and a read-only :dir() over its files. nil when the app was launched from inline code rather than a package. |
Types 2
AppArgs
recordrecord 6 keys
| Key | Type | Description |
|---|---|---|
| dirs | table<string, Dir> | Granted directory capabilities, keyed by mount name. |
| files | table<string, File> | Granted file capabilities, keyed by mount name. |
| data_mounts | table<string, DataMount> | Granted data-mount capabilities, keyed by mount name. |
| http_mounts | table<string, HttpMount> | Granted HTTP mount capabilities, keyed by mount name. |
| ingress_mounts | table<string, IngressMount> | Granted ingress mount capabilities, keyed by mount name. |
| argv | string[] | Positional launch arguments passed to this app. |
Used by: datumhue.args
StatKey
enum| Value | Description |
|---|---|
"fps" | Smoothed frames per second. |
"frame_time" | Smoothed frame time in seconds. |
"frame_count" | Frames rendered since launch. |
"entity_count" | Objects alive across the whole workstation, its own and every running app's: UI elements, draw primitives, scene nodes and the like. |
"app_count" | Apps running on the workstation, the bootstrap included. |
"cpu" | Fraction of the per-frame script budget this app consumed during the previous frame. Raw per-frame value, no smoothing. |
"memory" | Script memory currently allocated by this app, in bytes. |
Used by: datumhue.stat