API reference¶

API version: 1.0.0

Source review: 2026-10-21

Find a callable by namespace or exact name. Each page explains its parameters, return values and usage.

Runtime¶

Callable	Purpose
`gos.on_tick`	Register bounded work on the update scheduler; optional interval_ms controls cadence.
`gos.time_ms`	Read monotonic milliseconds for elapsed time, not wall-clock time.

World and units¶

Shared contracts and examples

Callable	Purpose
`gos.actor_names`	Read a bounded, epoch-checked snapshot of retained actor names without live-unit lookup.
`gos.target.cancel`	Cancel an owned target request only while it is still queued.
`gos.target.select`	Request an intentional persistent selected-target change; confirm it in a later snapshot.
`gos.target.status`	Observe an owned target-selection request without replaying it.
`gos.world`	Acquire the current generation-bound world and its optional player and target.
`unit:basis`	Read the current normalized yaw basis with forward, right and up axes, or nil.
`unit:combat_style`	Read a stable lowercase combat-style key, or nil.
`unit:discipline`	Read the observed display discipline, or nil.
`unit:distance`	Current distance in game-world units, or nil; multiply by 10 for metres.
`unit:handle`	Get an opaque identity that can be resolved in a fresh world; do not parse it.
`unit:hp`	Read observed health and optional percentage, or nil.
`unit:is_current_target`	Test whether this current unit is the selected target.
`unit:is_local_player`	Test whether this current unit is the local player.
`unit:is_on_screen`	Read whether this unit has a current on-screen observation.
`unit:item_rating`	Read the prepared overall equipped item rating, or nil when unavailable.
`unit:name`	Read the observed display name, or nil.
`unit:position`	Read game-world coordinates for this observation, or nil.
`unit:reaction`	Read friendly, neutral, hostile or unclassified relationship.
`unit:resource`	Read observed resource, kind and optional percentage.
`unit:rotation`	Read current character yaw in radians, or nil when its prepared pose is unavailable.
`unit:screen_position`	Read a current projected top, center or bottom unit anchor in pixels; return nil when unavailable.
`unit:speed`	Read available velocity magnitude, or nil.
`unit:target`	Read this unit's observed target and target-observation availability.
`unit:toughness`	Read the observed toughness label and number, or nil.
`unit:type`	Read the canonical unit classification, including unknown.
`unit:velocity`	Read available velocity in game-world coordinate units, or nil.
`world:presence`	Read bounded camera-independent character-roster presence; unknown is not absence.
`world:resolve`	Resolve an opaque handle in the current world; absent units return nil.
`world:units`	Get currently captured units with strict AND-combined filters.

Effects¶

Shared contracts and examples

Callable	Purpose
`unit:effect`	Query a named or definition-key-matched aggregate; check readiness and completeness.
`unit:effects`	Read current effect rows and separately marked presentation-only history.

Input¶

Shared contracts and examples

Callable	Purpose
`gos.input.cursor`	Read the current cursor in render-viewport pixels without capturing input; unavailable samples omit coordinates.
`gos.input.is_down`	Read whether a supported keyboard or mouse button is held.
`gos.input.state`	Read held and edge state for a key; unrecognized keys are marked unknown.
`gos.input.was_pressed`	Read the shared press edge for this update without consuming it.
`gos.input.was_released`	Read the shared release edge for this update without consuming it.

Settings¶

Shared contracts and examples

Callable	Purpose
`gos.settings.get`	Read current settings, enabled/active state and field values.
`gos.settings.register`	Register this script's settings schema at load time, never from a tick.
`gos.settings.set`	Queue a validated update to one of the caller's registered fields.

Abilities¶

Shared contracts and examples

Callable	Purpose
`gos.abilities.abandon_command`	Query compatibility release eligibility without changing an in-flight command.
`gos.abilities.action_slots`	Read an array of observed on-bar abilities; availability is reported by loadout.
`gos.abilities.can_cast`	Check current readiness and supported local conditions without owning a command.
`gos.abilities.cast`	Queue one asynchronous action. Queued does not mean activated.
`gos.abilities.command_status`	Read command lifecycle, activation evidence, cleanup and observed outcome.
`gos.abilities.cooldown_duration`	Read observed total cooldown in seconds, or nil when unavailable.
`gos.abilities.cooldown_remaining`	Read observed remaining cooldown in seconds, or nil when unavailable.
`gos.abilities.current_cast`	Read current cast identity and optional timing, or nil.
`gos.abilities.gcd_remaining`	Read remaining global cooldown in seconds, or nil.
`gos.abilities.info`	Read one local ability row by name or opaque ability handle.
`gos.abilities.is_casting_or_channeling`	Read the current busy observation; named cast details can be independently unavailable.
`gos.abilities.is_ready`	Read the local ability-row readiness flag, not target-specific cast admission.
`gos.abilities.loadout`	Read local loadout identity, known abilities and talents, and availability flags.
`gos.abilities.release_command`	Request safe cancellation; a rejected cancellation does not release ownership.

Combat events¶

Shared contracts and examples

Callable	Purpose
`gos.events.casts`	Read current cast/channel presentation observations, not a history stream.
`gos.events.combat`	Consume ordered combat events using a retained cursor, with loss and backlog reporting.
`gos.events.instants`	Read current instant-action observations, not a history stream.

Overlay¶

Shared contracts and examples

Callable	Purpose
`gos.overlay.draw_bar`	Draw a bounded bar at a shared screen, world or unit PointSpec.
`gos.overlay.draw_circle`	Draw a screen-radius or world-radius circle at a shared PointSpec.
`gos.overlay.draw_image`	Draw an image at a shared screen, world or unit PointSpec.
`gos.overlay.draw_line`	Draw a line between independent screen, world or unit PointSpecs.
`gos.overlay.draw_rect`	Draw a rectangle at a shared screen, world or unit PointSpec.
`gos.overlay.draw_rectangle`	Alias draw_rect at a shared screen, world or unit PointSpec.
`gos.overlay.draw_text`	Draw text at a shared screen, world or unit PointSpec.
`gos.overlay.interact`	Refresh a screen interaction rectangle and read mouse interaction state.
`gos.overlay.unit_label`	Add or refresh a temporary unit-anchored label.
`gos.overlay.viewport`	Read exact viewport dimensions only when available.

Logging¶

Shared contracts and examples

Callable	Purpose
`gos.log.debug`	Write a debug-level message to this script's log.
`gos.log.error`	Write an error-level message to this script's log.
`gos.log.info`	Write an info-level message to this script's log.
`gos.log.success`	Write a success-level message to this script's log.
`gos.log.warn`	Write a warning-level message to this script's log.
`gos.log.write`	Write one structured log message with an optional level, tag and color.
`print`	Log at info level. Returns no values.

Modules and files¶

Shared contracts and examples

Callable	Purpose
`DeleteFile`	Remove one file or empty directory without recursion; false without an error means nothing was removed.
`DownloadFileAsync`	Perform a blocking load-time download; the optional callback runs synchronously.
`FileExist`	Test for a regular file in an approved root; a missing file returns false without an error.
`GetFromWebOrLocal`	Ensure a local file exists, downloading only on a cache miss; returns a boolean, not contents.
`ListFiles`	List immediate regular-file names with optional exact extension filtering and truncation reporting.
`MakeDirectory`	Create approved directories; false without an error can mean they already exist.
`ReadFile`	Read binary-safe file contents, or nil and an error.
`UnzipArchive`	Extract a validated ZIP at load time within sandbox and size limits.
`WriteFile`	Write or append bytes in approved roots, creating missing parent directories.
`gos.file.delete`	Remove one file or empty directory without recursion; false without an error means nothing was removed.
`gos.file.download_async`	Perform a blocking load-time download; the optional callback runs synchronously.
`gos.file.exists`	Test for a regular file in an approved root; a missing file returns false without an error.
`gos.file.get_from_web_or_local`	Ensure a local file exists, downloading only on a cache miss; returns a boolean, not contents.
`gos.file.list`	List immediate regular-file names with optional exact extension filtering and truncation reporting.
`gos.file.mkdir`	Create approved directories; false without an error can mean they already exist.
`gos.file.read`	Read binary-safe file contents, or nil and an error.
`gos.file.unzip`	Extract a validated ZIP at load time within sandbox and size limits.
`gos.file.write`	Write or append bytes in approved roots, creating missing parent directories.
`gos.import`	Load a sandbox Lua module cached per top-level script environment.
`import`	Load a sandbox Lua module cached per top-level script environment.
`require`	Load a sandbox Lua module cached per top-level script environment.

Inventory¶

Shared contracts and examples

Callable	Purpose
`gos.inventory.bag`	Read occupied carried-bag slots and optional item metadata.
`gos.inventory.materials`	Read prepared Materials storage totals and available names.
`gos.inventory.snapshot`	Read the bag and Materials subtables from one prepared inventory snapshot.