World API 0.3

api_version since 0.1

Import · group: core

iamar.api_version(): number

wasm iamar.api_version() -> i32

(major << 16) | minor of the browser's API: 3 for 0.3.

log since 0.1

Import · group: core

iamar.log(text: string): void

wasm iamar.log(i32, i32) -> void

A line in the world's log (the author's console). <= 512 bytes, 50/s.

rand since 0.1

Import · group: core

iamar.rand(): number

wasm iamar.rand() -> f32

Uniform in [0, 1). Seeded per world, so every visitor's copy draws the same sequence.

time since 0.1

Import · group: core

iamar.time(): number

wasm iamar.time() -> f64

Seconds since the script started (game time; pauses with the game).

entity_spawn since 0.1

Import · group: entity

iamar.entity_spawn(kind: EntityKind, x: number, y: number, z: number, yaw: number): EntityHandle

wasm iamar.entity_spawn(i32, i32, f32, f32, f32, f32) -> i32

A new entity; returns its handle (> 0). Kinds: chicken, box, sphere, marker, cylinder, capsule, cone, plane, light, spot, particles, label, mesh:<id> (from mesh_create), or asset:<path>.glb from the world's own package. <= 256 entities (manifest budget up to 1024).

A negative return is an error code (IAMAR_E_*).

entity_remove since 0.1

Import · group: entity

iamar.entity_remove(h: EntityHandle): Status

wasm iamar.entity_remove(i32) -> i32

Remove one of this script's entities.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_set_pos since 0.1

Import · group: entity

iamar.entity_set_pos(h: EntityHandle, x: number, y: number, z: number, yaw: number): Status

wasm iamar.entity_set_pos(i32, f32, f32, f32, f32) -> i32

Jump there; stops any move_to.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_move_to since 0.1

Import · group: entity

iamar.entity_move_to(h: EntityHandle, x: number, y: number, z: number, speed: number): Status

wasm iamar.entity_move_to(i32, f32, f32, f32, f32) -> i32

Walk there in a straight line at speed m/s (<= 50), turning to face the way it goes.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_pos since 0.1

Import · group: entity

iamar.entity_pos(h: EntityHandle): Position | null

wasm iamar.entity_pos(i32, i32) -> i32

Writes x, y, z, yaw.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_play_anim since 0.1

Import · group: entity

iamar.entity_play_anim(h: EntityHandle, name: string): Status

wasm iamar.entity_play_anim(i32, i32, i32) -> i32

chicken: idle, walk, run, peck, flap; glTF assets: any animation in the file.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_set_tint since 0.1

Import · group: entity

iamar.entity_set_tint(h: EntityHandle, r: number, g: number, b: number, a: number): Status

wasm iamar.entity_set_tint(i32, f32, f32, f32, f32) -> i32

Wash the entity in a colour (0-1); a = 0 removes it.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_set_grounded since 0.1

Import · group: entity

iamar.entity_set_grounded(h: EntityHandle, on: boolean): Status

wasm iamar.entity_set_grounded(i32, i32) -> i32

A grounded entity stays on the terrain while it moves.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_set_scale since 0.2

Import · group: entity

iamar.entity_set_scale(h: EntityHandle, sx: number, sy: number, sz: number): Status

wasm iamar.entity_set_scale(i32, f32, f32, f32) -> i32

Each axis clamped to 0.01-100.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_set_visible since 0.2

Import · group: entity

iamar.entity_set_visible(h: EntityHandle, on: boolean): Status

wasm iamar.entity_set_visible(i32, i32) -> i32

Show or hide.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_set_rot since 0.2

Import · group: entity

iamar.entity_set_rot(h: EntityHandle, pitch: number, yaw: number, roll: number): Status

wasm iamar.entity_set_rot(i32, f32, f32, f32) -> i32

Radians; pitch about +X, yaw about +Y, roll about +Z.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_stop_anim since 0.2

Import · group: entity

iamar.entity_stop_anim(h: EntityHandle): Status

wasm iamar.entity_stop_anim(i32) -> i32

Stop the current animation.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_set_color since 0.3

Import · group: render

iamar.entity_set_color(h: EntityHandle, r: number, g: number, b: number, a: number): Status

wasm iamar.entity_set_color(i32, f32, f32, f32, f32) -> i32

Base colour of a primitive or label, or the colour of a light / particles. a < 1 makes primitives see-through. Components clamped to 0-1.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_set_material since 0.3

Import · group: render

iamar.entity_set_material(h: EntityHandle, metallic: number, roughness: number, emission: number, unshaded: number): Status

wasm iamar.entity_set_material(i32, f32, f32, f32, f32) -> i32

Surface of a primitive or mesh entity: metallic 0-1, roughness 0-1, emission energy 0-16 (glows in its own colour), unshaded >= 0.5 ignores lighting.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_set_light since 0.3

Import · group: render

iamar.entity_set_light(h: EntityHandle, energy: number, range: number, angle: number): Status

wasm iamar.entity_set_light(i32, f32, f32, f32) -> i32

For light and spot entities: energy 0-16, range 0.1-60 m, spot cone angle 1-89 degrees (ignored for light). Colour comes from entity_set_color. <= 16 lights per world; no shadows.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_set_particles since 0.3

Import · group: render

iamar.entity_set_particles(h: EntityHandle, preset: ParticlePreset, rate: number): Status

wasm iamar.entity_set_particles(i32, i32, i32, f32) -> i32

For particles entities: preset smoke, fire, sparks, dust, magic, rain, snow, bubbles; rate 0-200 particles/s (0 stops it). <= 8 emitters per world.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_set_text since 0.3

Import · group: render

iamar.entity_set_text(h: EntityHandle, text: string, size: number): Status

wasm iamar.entity_set_text(i32, i32, i32, f32) -> i32

For label entities: text floating in the world, always facing the camera. <= 128 bytes; size 0.05-4 m per line.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

mesh_create since 0.3

Import · group: render

iamar.mesh_create(vertices: Float32Array | readonly number[], indices: Uint32Array | readonly number[]): number

wasm iamar.mesh_create(i32, i32, i32, i32) -> i32

A custom triangle mesh; returns a mesh id (> 0) to spawn as kind mesh:<id>. vertices: vertex_count x 8 f32 (x, y, z, nx, ny, nz, u, v); indices: index_count u32 (triangles, so a multiple of 3). <= 4096 vertices and 12288 indices per mesh (bigger models belong in a .glb asset), 64 meshes, 1,000,000 vertices and 3,000,000 indices per world, 4 calls per second.

A negative return is an error code (IAMAR_E_*).

ground_y since 0.1

Import · group: world

iamar.ground_y(x: number, z: number): number

wasm iamar.ground_y(f32, f32) -> f32

Terrain height at (x, z).

raycast since 0.2

Import · group: physics

iamar.raycast(x1: number, y1: number, z1: number, x2: number, y2: number, z2: number): RaycastHit | null

wasm iamar.raycast(f32, f32, f32, f32, f32, f32, i32) -> i32

Read-only ray query (<= 10 km): writes hit x, y, z and normal x, y, z; returns the hit entity's handle, 0 for world geometry, -4 on a miss.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_set_collider since 0.3

Import · group: physics

iamar.entity_set_collider(h: EntityHandle, shape: number, sx: number, sy: number, sz: number): Status

wasm iamar.entity_set_collider(i32, i32, f32, f32, f32) -> i32

Give an entity a solid shape players bump into and raycasts hit: shape 0 none, 1 box (sx, sy, sz = full size), 2 sphere (sx = radius), 3 capsule (sx = radius, sy = height). Sizes 0.01-100.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_set_physics since 0.3

Import · group: physics

iamar.entity_set_physics(h: EntityHandle, mode: number, mass: number): Status

wasm iamar.entity_set_physics(i32, i32, f32) -> i32

mode 0 scripted (the default: only the script moves it), 1 dynamic (falls, bounces and is pushed; needs a collider), 2 static. mass 0.01-10000 kg. <= 128 dynamic bodies per world.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_apply_impulse since 0.3

Import · group: physics

iamar.entity_apply_impulse(h: EntityHandle, x: number, y: number, z: number): Status

wasm iamar.entity_apply_impulse(i32, f32, f32, f32) -> i32

Push a dynamic entity (N*s). Its velocity afterwards is capped at 200 m/s however many impulses a callback gives, and a dynamic entity never moves faster than 200 m/s.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_set_velocity since 0.3

Import · group: physics

iamar.entity_set_velocity(h: EntityHandle, x: number, y: number, z: number): Status

wasm iamar.entity_set_velocity(i32, f32, f32, f32) -> i32

Set a dynamic entity's velocity (m/s, each component clamped to +/-200).

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_velocity since 0.3

Import · group: physics

iamar.entity_velocity(h: EntityHandle): Vector3 | null

wasm iamar.entity_velocity(i32, i32) -> i32

Writes the entity's velocity x, y, z (0 for scripted entities that are not moving).

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

entity_set_trigger since 0.3

Import · group: physics

iamar.entity_set_trigger(h: EntityHandle, radius: number): Status

wasm iamar.entity_set_trigger(i32, f32) -> i32

Make the entity a trigger zone of this radius (0.1-50 m; 0 turns it off): on_trigger_enter / on_trigger_exit fire as players come and go.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

sound_play since 0.2

Import · group: audio

iamar.sound_play(name: SoundName, x: number, y: number, z: number): Status

wasm iamar.sound_play(i32, i32, f32, f32, f32) -> i32

A sound at a point: cluck, squawk, bell, click, door, jump, land, select, gear, or asset:<path>.ogg from the world's package (<= 2 MiB each, 32 files). 10/s.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

timer_after since 0.2

Import · group: time

iamar.timer_after(ms: number, tag: number): Status

wasm iamar.timer_after(i32, i32) -> i32

Calls on_timer(tag) after ms (0-86,400,000). <= 64 pending.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

timer_cancel since 0.2

Import · group: time

iamar.timer_cancel(tag: number): number

wasm iamar.timer_cancel(i32) -> i32

Cancels every pending timer with this tag; returns how many.

A negative return is an error code (IAMAR_E_*).

timer_repeat since 0.2

Import · group: time

iamar.timer_repeat(ms: number, tag: number): Status

wasm iamar.timer_repeat(i32, i32) -> i32

Calls on_timer(tag) every ms (1-86,400,000) until cancelled.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

players_count since 0.2

Import · group: players

iamar.players_count(): number

wasm iamar.players_count() -> i32

Players in the world now, including remote visitors.

A negative return is an error code (IAMAR_E_*).

player_id since 0.2

Import · group: players

iamar.player_id(index: number): number

wasm iamar.player_id(i32) -> i32

Id of the index-th player (0 <= index < count), ascending.

A negative return is an error code (IAMAR_E_*).

player_pos since 0.1

Import · group: players

iamar.player_pos(id: PlayerId): Position | null

wasm iamar.player_pos(i32, i32) -> i32

Writes x, y, z, yaw.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

player_set_pos since 0.2

Import · group: players

iamar.player_set_pos(id: PlayerId, x: number, y: number, z: number, yaw: number): Status

wasm iamar.player_set_pos(i32, f32, f32, f32, f32) -> i32

Teleport the local player (portals, respawns, checkpoints). A remote player's own copy of the script moves them; here it returns -1.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

player_is_local since 0.3

Import · group: players

iamar.player_is_local(id: PlayerId): number

wasm iamar.player_is_local(i32) -> i32

1 for the player at this keyboard, 0 for a remote visitor, -1 for an unknown id.

A negative return is an error code (IAMAR_E_*).

player_name since 0.3

Import · group: players

iamar.player_name(id: PlayerId): string | null

wasm iamar.player_name(i32, i32, i32) -> i32

Copies up to cap bytes of the player's display name (UTF-8); returns its full length.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

player_key since 0.3

Import · group: players

iamar.player_key(id: PlayerId): string | null

wasm iamar.player_key(i32, i32, i32) -> i32

A stable key for the player that is the same in every visitor's copy of the script (player ids are local to each copy). ASCII, <= 64 bytes; returns its full length.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

kv_get since 0.1

Import · group: storage

iamar.kv_get(key: string): Uint8Array | null

wasm iamar.kv_get(i32, i32, i32, i32) -> i32

Copies up to cap bytes of the value; returns its full length, or -4.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

kv_set since 0.1

Import · group: storage

iamar.kv_set(key: string, value: Bytes): Status

wasm iamar.kv_set(i32, i32, i32, i32) -> i32

A value of 0 bytes deletes the key. Keys <= 128 bytes, values <= 4 KiB, 64 KiB per world. Stored on this visitor's machine.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

world_message since 0.1

Import · group: network

iamar.world_message(data: Bytes): Status

wasm iamar.world_message(i32, i32) -> i32

Send bytes (<= 1 KiB, 20/s) to every other visitor's copy of this script; they arrive in on_message_from (or on_message). Peer-to-peer over the room's encrypted links.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

message_to since 0.3

Import · group: network

iamar.message_to(id: PlayerId, data: Bytes): Status

wasm iamar.message_to(i32, i32, i32) -> i32

Send bytes to one remote player's copy of this script (same limits as world_message, sharing its rate).

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

is_authority since 0.3

Import · group: network

iamar.is_authority(): number

wasm iamar.is_authority() -> i32

1 if this copy is the world's authority, else 0: the copy whose visitor has the smallest player key among everyone in the room, so normally exactly one copy is. Use it to coordinate (who spawns, who keeps score), never as security: a hostile visitor can arrange to be the authority, so check what other copies send you.

A negative return is an error code (IAMAR_E_*).

camera_set since 0.3

Import · group: camera

iamar.camera_set(mode: number, x: number, y: number, z: number, tx: number, ty: number, tz: number): Status

wasm iamar.camera_set(i32, f32, f32, f32, f32, f32, f32) -> i32

mode 0 gives the camera back to the player; mode 1 looks from (x, y, z) at (tx, ty, tz) (cutscenes, puzzles). Esc, the browser's menus and leaving the world always give it back, and after Esc the script cannot take it again for 10 seconds (-3).

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

input_bind since 0.3

Import · group: input

iamar.input_bind(key: number, on: boolean): Status

wasm iamar.input_bind(i32, i32) -> i32

Ask for on_input events for a key: Godot key codes for A-Z (65-90), 0-9 (48-57), Space (32) and the arrows (4194319-4194322). Esc, Enter, Tab and the F keys are the browser's and are refused. The key keeps its normal game meaning too. <= 32 keys.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

ui_note since 0.1

Import · group: ui

iamar.ui_note(text: string): void

wasm iamar.ui_note(i32, i32) -> void

A short note on the player's screen, marked as the world's. <= 512 bytes, 4/s.

ui_text since 0.3

Import · group: ui

iamar.ui_text(id: number, text: string, x: number, y: number, size: number): Status

wasm iamar.ui_text(i32, i32, i32, f32, f32, f32) -> i32

Create or update text on the world's screen layer at (x, y) in 0-1 of the window, size 8-64 px. <= 256 bytes. The layer sits under the browser's own UI and is framed as the world's.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

ui_button since 0.3

Import · group: ui

iamar.ui_button(id: number, text: string, x: number, y: number, w: number, h: number): Status

wasm iamar.ui_button(i32, i32, i32, f32, f32, f32, f32) -> i32

Create or update a clickable button (position and size in 0-1 of the window); a click calls on_ui(id).

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

ui_bar since 0.3

Import · group: ui

iamar.ui_bar(id: number, value: number, x: number, y: number, w: number): Status

wasm iamar.ui_bar(i32, f32, f32, f32, f32) -> i32

Create or update a progress bar filled to value (0-1); its colour follows entity-style ui_color.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

ui_color since 0.3

Import · group: ui

iamar.ui_color(id: number, r: number, g: number, b: number, a: number): Status

wasm iamar.ui_color(i32, f32, f32, f32, f32) -> i32

Colour of a UI element's text or fill (0-1).

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

ui_remove since 0.3

Import · group: ui

iamar.ui_remove(id: number): Status

wasm iamar.ui_remove(i32) -> i32

Remove a UI element. Ids are the script's own (1-2,147,483,647); <= 32 elements.

Fails with a negative error code (IAMAR_E_*); out-values come back null on failure.

on_init since 0.1

Callback (your world exports it)

function on_init(): void

wasm iamar.on_init() -> void

Once, after instantiation.

on_tick since 0.1

Callback (your world exports it)

function on_tick(dt: number): void

wasm iamar.on_tick(f32) -> void

About 10 times a second (tick_hz); dt is seconds since the last tick (<= 0.5).

on_enter since 0.1

Callback (your world exports it)

function on_enter(player: PlayerId): void

wasm iamar.on_enter(i32) -> void

A player arrives (after on_init for everyone already there). The local player is id 1.

on_leave since 0.1

Callback (your world exports it)

function on_leave(player: PlayerId): void

wasm iamar.on_leave(i32) -> void

A player leaves.

on_interact since 0.1

Callback (your world exports it)

function on_interact(player: PlayerId, entity: EntityHandle): void

wasm iamar.on_interact(i32, i32) -> void

A player uses an entity (the interact key within 2.5 m).

on_timer since 0.2

Callback (your world exports it)

function on_timer(tag: number): void

wasm iamar.on_timer(i32) -> void

A timer_after / timer_repeat fired.

on_message since 0.1

Callback (your world exports it)

function on_message(data: Uint8Array): void

wasm iamar.on_message(i32, i32) -> void

Bytes from another copy of the script (used when on_message_from is not exported).

on_message_from since 0.3

Callback (your world exports it)

function on_message_from(player: PlayerId, data: Uint8Array): void

wasm iamar.on_message_from(i32, i32, i32) -> void

Bytes from the copy of the script running for this player.

on_trigger_enter since 0.3

Callback (your world exports it)

function on_trigger_enter(player: PlayerId, entity: EntityHandle): void

wasm iamar.on_trigger_enter(i32, i32) -> void

A player walked into a trigger zone.

on_trigger_exit since 0.3

Callback (your world exports it)

function on_trigger_exit(player: PlayerId, entity: EntityHandle): void

wasm iamar.on_trigger_exit(i32, i32) -> void

A player left a trigger zone.

on_contact since 0.3

Callback (your world exports it)

function on_contact(a: EntityHandle, b: EntityHandle): void

wasm iamar.on_contact(i32, i32) -> void

Two of the script's dynamic entities, or a dynamic entity and the world (b = 0), started touching.

on_click since 0.3

Callback (your world exports it)

function on_click(player: PlayerId, entity: EntityHandle): void

wasm iamar.on_click(i32, i32) -> void

The local player clicked an entity with the mouse (needs a collider).

on_input since 0.3

Callback (your world exports it)

function on_input(key: number, pressed: boolean): void

wasm iamar.on_input(i32, i32) -> void

A key asked for with input_bind went down (1) or up (0).

on_ui since 0.3

Callback (your world exports it)

function on_ui(id: number): void

wasm iamar.on_ui(i32) -> void

A ui_button was clicked.

iamar_alloc since 0.1

Callback (your world exports it)

function iamar_alloc(len: number): number

wasm iamar.iamar_alloc(i32) -> i32

Required with on_message / on_message_from: returns a buffer of len bytes the host fills; the script owns it afterwards.