ThicketScript

App and System ​

The app lifecycle (App), process and platform info (System), and autotest hooks.

Always available

No import needed. These names are in scope in every file.

App static class ​

ts
static class App

The application lifecycle surface shared by console and windowed programs. App.onFrame is the canonical frame hook. Window projects additionally provide the resize and focus lifecycle callbacks.

App.onTick ​

ts
static onTick(handler: any): Function

Registers a fixed-tick handler, called once per logic tick (App.tps per second, catching up to maxCatchUpTicks ticks after a slow frame). Returns the function that unsubscribes it. A console program with a tick handler keeps running until App.quit().

App.ticker ​

ts
static readonly ticker: Ticker

The app-lifetime Ticker (App.ticker.every(1, fn), await App.ticker.wait(2)), advanced once per scaled tick by the runtime, after App.onTick handlers. Created on first use. Reading it makes the program tick (a console program with ticker entries runs until App.quit()).

App.tps ​

ts
static tps: float

Logic ticks per second (default 60; also tps in thicket.json). Set to App.SYNC_WITH_FPS for one tick per drawn frame.

App.SYNC_WITH_FPS ​

ts
static readonly SYNC_WITH_FPS: float

App.tps value that runs one tick per drawn frame.

App.tickDelta ​

ts
static readonly tickDelta: float

Seconds per tick: 1 / tps (this frame's dt in SYNC_WITH_FPS mode).

App.tick ​

ts
static readonly tick: int

Ticks run since start; during a tick handler, the index of that tick.

App.time ​

ts
static readonly time: float

Scaled seconds since start, advanced per tick.

App.realTime ​

ts
static readonly realTime: float

Unscaled wall seconds since start.

App.tickAlpha ​

ts
static readonly tickAlpha: float

How far the current frame is between the last tick and the next, 0 to 1.

App.actualTps ​

ts
static readonly actualTps: float

Ticks per second measured over the last second.

App.actualFps ​

ts
static readonly actualFps: float

Frames per second measured over the last second.

App.maxCatchUpTicks ​

ts
static maxCatchUpTicks: int

Most ticks run per frame to catch up (default 8); the excess is dropped.

App.droppedTicks ​

ts
static readonly droppedTicks: int

Ticks dropped because a frame needed more than maxCatchUpTicks.

App.maxFrameDelta ​

ts
static maxFrameDelta: float

The longest dt the frame phase sees, in seconds (default 0.25).

App.timeScale ​

ts
static timeScale: float

Scales App.time (default 1).

Other members of App ​

ts
static onFrame(handler: any): Function
static onQuit(handler: any): Function
static onResize(handler: any): Function
static onFocus(handler: any): Function
static onBlur(handler: any): Function
static quit(code?: int): void

Autotest static class ​

ts
static class Autotest

Hooks for thicket run --autotest scripts. Present in every program; outside --autotest nothing reads them.

Autotest.probe ​

ts
static probe(id: string, probe: () => boolean): void

Names a condition an autotest script can wait on: { "action": "wait_until", "probe": "<id>", "max": 600 } holds the script until probe returns true, checking once per frame for at most max frames (default 600), and fails the step if it never does. Registering the same id again replaces the probe.

System static class ​

ts
static class System

Process-level introspection and lifecycle. System is pre-bound in every scope (no import required) and is frozen at startup; its fields cannot be reassigned from script. It is a native static class at runtime.

System.capabilities ​

ts
readonly capabilities: SystemCapabilities

Frozen host capabilities. Native-module fields describe modules embedded in this host, independent of project permissions. gamepad, fullscreen, and persistentStorage describe the current host's runtime ability; engine targets populate those meaningfully, while the headless tks CLI reports false.

System.debug ​

ts
readonly debug: SystemDebug

Runtime stack-trace diagnostics.

System.audio ​

ts
readonly audio: any

Deprecated

Use the imported Audio static class.

System.DARWIN ​

ts
readonly DARWIN: string

Platform constant: "darwin". Compare against System.platform().

System.LINUX ​

ts
readonly LINUX: string

Platform constant: "linux". Compare against System.platform().

System.WIN32 ​

ts
readonly WIN32: string

Platform constant: "win32". Compare against System.platform().

System.WEB ​

ts
readonly WEB: string

Platform constant: "web". Compare against System.platform().

System.args ​

ts
readonly args: string[]

Command-line arguments passed to the script, in order. Does not include the interpreter path or the script path itself.

System.isPackaged ​

ts
readonly isPackaged: boolean

true when the program runs from a thicket build output (any strategy, release or not); false under thicket run. Set before the script starts, so it is readable at the top of a file.

System.cwd ​

ts
cwd(): string

Current working directory of the host process. Returns undefined if the underlying getcwd call fails.

System.storageDir ​

ts
storageDir(): string

The app's persistent folder, for saves and settings. Created on first call. Needs no permission: an app always owns it, and Files reads and writes inside it pass without fs in thicket.json.

The folder is keyed by the app id (id in thicket.json, else the project folder's name). Linux $XDG_DATA_HOME or ~/.local/share/<id>; Windows %APPDATA%\<id>; macOS ~/Library/Application Support/<id>. Returns "" when no home folder is known.

System.cacheDir ​

ts
cacheDir(): string

The app's cache folder, always safe to delete (compiled themes, baked fonts). Created on first call. Needs no permission, like storageDir(). Linux $XDG_CACHE_HOME or ~/.cache/<id>; Windows %LOCALAPPDATA%\<id>\Cache; macOS ~/Library/Caches/<id>. Returns "" when no home folder is known.

System.exit ​

ts
exit(code?: int): void

Request process exit. Runs every registered onQuit handler before the host exits; the request is honored at the next safe point in the VM loop, so callers see the function return normally.

Example

ts
System.exit(0);

System.frameDepth ​

ts
frameDepth(): int

Current call-stack frame depth. Diagnostic.

System.gc ​

ts
gc(): int

Run a garbage-collection cycle and return the number of objects freed.

System.instructions ​

ts
instructions(): float64

Total instructions executed by the VM since startup. Returned as float64 because the count routinely exceeds the int32 range.

System.memUsage ​

ts
memUsage(): int

Bytes currently allocated by the VM (sum of live object sizes). Diagnostic.

System.objectCount ​

ts
objectCount(): int

Number of live VM objects. Diagnostic.

System.onFrame ​

ts
onFrame(handler: any): Function

Migration alias for App.onFrame, retained for compatibility and scheduled for removal. Window hosts invoke it once per frame; console programs invoke it once per event-loop turn, after the preceding Promise microtasks.

System.onQuit ​

ts
onQuit(handler: any): void

Register a callback to run during shutdown — after natural completion, System.exit(), or SIGINT/SIGTERM. Handlers run in registration order and are guaranteed to run at most once. Late registrations made while shutdown is already in progress are silently ignored.

System.platform ​

ts
platform(): string

Host platform: "darwin", "linux", "win32", "web", or "unknown" if the build was made on an unrecognized target. Equal to one of DARWIN/LINUX/WIN32/WEB by construction on supported platforms.

Example

ts
const os: string = System.platform();
console.log(os == "linux" || os == "darwin" || os == "win32" || os == "web"); // true

System.scriptPath ​

ts
scriptPath(): string

Absolute path to the running script. Returns undefined when the VM was embedded without a script path (e.g. tks repl).

System.stackDepth ​

ts
stackDepth(): int

Current operand-stack depth. Diagnostic.

System.time ​

ts
time(): float64

Wall-clock time as milliseconds since the Unix epoch.

Example

ts
const msSinceEpoch: float64 = System.time();
console.log(msSinceEpoch > 0); // true

System.uptime ​

ts
uptime(): float64

Milliseconds elapsed since process start, measured against the steady clock. Suitable for interval timing; not tied to wall-clock changes.

System.version ​

ts
version(): string

Runtime version string (e.g. "0.1.0").

Example

ts
console.log(System.version());

SystemDebug class ​

ts
class SystemDebug

Type only: the runtime hands you instances; you never construct it yourself.

Diagnostic helpers exposed through System.debug.

SystemDebug.traceback ​

ts
traceback(): string

Return the current ThicketScript call stack as a string.

SystemCapabilities class ​

ts
class SystemCapabilities

Type only: the runtime hands you instances; you never construct it yourself.

Frozen fields exposed by System.capabilities. All capability fields are present on every target so guarded branches type-check; their values report host availability, not permission grants.

SystemCapabilities.audio ​

ts
readonly audio: boolean

Native audio module is embedded in this host.

SystemCapabilities.bitmap ​

ts
readonly bitmap: boolean

Native bitmap module is embedded in this host.

SystemCapabilities.compress ​

ts
readonly compress: boolean

Native compress module is embedded in this host.

SystemCapabilities.crypto ​

ts
readonly crypto: boolean

Native crypto module is embedded in this host.

SystemCapabilities.database ​

ts
readonly database: boolean

Native database module is embedded in this host.

SystemCapabilities.env ​

ts
readonly env: boolean

Native env module is embedded in this host.

SystemCapabilities.events ​

ts
readonly events: boolean

Native events module is embedded in this host.

SystemCapabilities.fs ​

ts
readonly fs: boolean

Native fs module is embedded in this host.

SystemCapabilities.http ​

ts
readonly http: boolean

Native http module is embedded in this host.

SystemCapabilities.net ​

ts
readonly net: boolean

Native net module is embedded in this host.

SystemCapabilities.reactivity ​

ts
readonly reactivity: boolean

The reactivity script module is embedded in this host.

SystemCapabilities.shell ​

ts
readonly shell: boolean

Native shell module is embedded in this host.

SystemCapabilities.terminal ​

ts
readonly terminal: boolean

Native terminal module is embedded in this host.

SystemCapabilities.udp ​

ts
readonly udp: boolean

Native udp module is embedded in this host.

SystemCapabilities.wsClient ​

ts
readonly wsClient: boolean

This host supports outbound WebSocket connections.

SystemCapabilities.wsServer ​

ts
readonly wsServer: boolean

This host supports listening for inbound WebSocket connections.

SystemCapabilities.ws ​

ts
readonly ws: boolean

Deprecated

Use wsClient or wsServer; equivalent to wsClient || wsServer.

SystemCapabilities.engine ​

ts
readonly engine: boolean

Engine component engine is linked into this host.

SystemCapabilities.willow ​

ts
readonly willow: boolean

Engine component willow is linked into this host.

SystemCapabilities.gamepad ​

ts
readonly gamepad: boolean

Current host can receive gamepad input; tks reports false.

SystemCapabilities.fullscreen ​

ts
readonly fullscreen: boolean

Current host can enter fullscreen; tks reports false.

SystemCapabilities.persistentStorage ​

ts
readonly persistentStorage: boolean

Current host offers persistent storage; tks reports false.

Generated from lang/types/system.d.tks in the ThicketScript repository.