Global scripting API

These functions and objects are provided to every gameplay script. Use them for entity lookup, input, physics, navigation, saving, debugging, pooling and timing.

#Entity lookup

#Scene (scene)

scene contains the same entity-lookup functions above, plus load(sceneName), restart(), pause(), resume(), the read-only properties current and isPaused, and scene-wide lighting. scene.pause() freezes gameplay simulation while leaving the editor/Play window responsive; call scene.resume() to continue.

#Physics (physics)

physics.raycast(x1, y1, x2, y2, opts?) casts a ray against Rapier collider shapes and returns the closest hit or null. A hit contains the entity, world point, surface normal (when available) and distance. Pass { exclude: [this] } to skip an entity, { debug: true } to draw the ray for one frame, or { layerMask: physics.layer(0, 2) } to filter by layer bits. physics.layer(...indices) creates the bitmask for slots 0–15.

function onUpdate() {
  var hit = physics.raycast(this.x, this.y, this.x + 200, this.y, {
    exclude: [this],
    debug: true
  });
  if (hit) debug.log("Ray hit", hit.entity.name);
}

#Navigation (nav)

For moving entities every frame, use this.navMoveToward() or (for a Car controller) this.navDriveToward(). See Pathfinding.

#Keyboard (input)

input.keyDown(key) is true while a key is held. input.keyPressed(key) is true only on the frame it is first pressed. Both accept "Any" to test whether any key is held or was pressed that frame. Use the Input guide for key naming and patterns.

#Mouse and pointer (mouse)

mouse.x and mouse.y are world coordinates. screenX and screenY are canvas pixels. over reports whether the pointer is over the game canvas. down(button?), pressed(button?) and released(button?) read mouse buttons (0 left, 1 middle, 2 right; omitted means left). isOver(entityOrName, opts?) tests hover and clickedOn(entityOrName, opts?, button?) tests a click on a specific entity.

#Touch (touch)

touch is a live array of active touches. Each touch exposes id, world-space x/y, canvas-pixel screenX/screenY, start coordinates, displacement (dx/dy), distance, and one-frame justStarted/justEnded flags. The array also exposes count, first, anyJustStarted and anyJustEnded. Gesture helpers are swipe.active/direction/dx/dy/distance and pinch.active/scale/delta/distance. touch.isOver(entityOrName, opts?) checks a finger over an entity; touch.tappedOn(entityOrName, opts?) detects the initial tap. See Input guide.

#Time (time)

time.deltaTime is scaled frame time, time.unscaledDeltaTime is frame time before time scaling, time.elapsed is elapsed game time, and time.scale controls game speed. A scale of 0 pauses time-driven simulation; 1 is normal speed. See Time scale & game speed.

#Random and math helpers

random.int(min, max) returns an inclusive random integer. random.float(min, max) returns a random float in the half-open range [min, max). mathx provides lerp, smoothstep, clamp, moveToward, remap and approximately. A bare smoothstep(a, b, value) global is also available. Native JavaScript Math is available as well.

#Shared in-memory state (global)

global is a shared key/value object visible to all scripts in the current running game. Read and write named properties directly, for example global.score = 10. It is memory-only; it does not survive reloading the game page. Use save for persistent data.

#Persistent save data (save)

save stores JSON-safe values in IndexedDB, separated into named save slots. Its full 13-member API is listed in SaveAPI. Common calls are get, set, has, delete, keys and clear. Use await save.load("slot2") to change slots, await save.listSlots() to list them, await save.deleteSlot("slot2") to remove a slot, and await save.flushNow() to wait for pending writes. See Persistence.

#Debug HUD (debug)

debug.show() enables the gameplay HUD and system timing display in the Play window; debug.show(false) turns it off. debug.showFps(false) hides only its FPS line. debug.log(label, value) adds or updates a custom line; debug.clear(label) removes one line; debug.clearAll() removes all custom lines. This is separate from the editor Console.

#Object pools (pool)

pool.create(name, options) creates a named pool using a source prefab, scene entity or EntityContext. pool.find(name) retrieves a named pool, pool.get(name, x, y) gets an active object, and pool.release(entity) returns it for reuse. A pooled entity can call this.releaseToPool(delay?). Pooled scripts can use onEnable and onDisable for work that should run each time an object is borrowed or returned.

#Spawn, timers, messages and tweens

Read Timers, state & messaging, Finding and spawning and Tween API for complete examples and option details. The script module index contains all 24 component/global API module allow-lists.