{ "version": "0.3", "version_code": 3, "module": "iamar", "about": "The iamar world API in machine-readable form: every import a world script may call and every callback it may export. scripts/sandbox/world_api.gd (IMPORTS/CALLBACKS) must match this file exactly (tests/sandbox/world_api_json_test.gd checks it); the TypeScript adapter, the C header and the Rust crate are written from it. Types: i32, f32, f64, ptr (i32 offset into the script's memory), len (i32 byte count). 'out' params are pointers the host writes into. Strings are UTF-8 (ptr, len). Errors are negative i32: -1 bad handle, -2 bad argument, -3 limit, -4 not found.", "imports": [ { "name": "api_version", "sig": ">i", "since": "0.1", "params": [], "returns": "i32", "group": "core", "doc": "(major << 16) | minor of the browser's API: 3 for 0.3." }, { "name": "log", "sig": "ii>", "since": "0.1", "params": [ [ "text", "str" ] ], "returns": "void", "group": "core", "doc": "A line in the world's log (the author's console). <= 512 bytes, 50/s." }, { "name": "ui_note", "sig": "ii>", "since": "0.1", "params": [ [ "text", "str" ] ], "returns": "void", "group": "ui", "doc": "A short note on the player's screen, marked as the world's. <= 512 bytes, 4/s." }, { "name": "rand", "sig": ">f", "since": "0.1", "params": [], "returns": "f32", "group": "core", "doc": "Uniform in [0, 1). Seeded per world, so every visitor's copy draws the same sequence." }, { "name": "time", "sig": ">F", "since": "0.1", "params": [], "returns": "f64", "group": "core", "doc": "Seconds since the script started (game time; pauses with the game)." }, { "name": "entity_spawn", "sig": "iiffff>i", "since": "0.1", "params": [ [ "kind", "str" ], [ "x", "f32" ], [ "y", "f32" ], [ "z", "f32" ], [ "yaw", "f32" ] ], "returns": "handle", "group": "entity", "doc": "A new entity; returns its handle (> 0). Kinds: chicken, box, sphere, marker, cylinder, capsule, cone, plane, light, spot, particles, label, mesh: (from mesh_create), or asset:.glb from the world's own package. <= 256 entities (manifest budget up to 1024)." }, { "name": "entity_remove", "sig": "i>i", "since": "0.1", "params": [ [ "h", "handle" ] ], "returns": "status", "group": "entity", "doc": "Remove one of this script's entities." }, { "name": "entity_set_pos", "sig": "iffff>i", "since": "0.1", "params": [ [ "h", "handle" ], [ "x", "f32" ], [ "y", "f32" ], [ "z", "f32" ], [ "yaw", "f32" ] ], "returns": "status", "group": "entity", "doc": "Jump there; stops any move_to." }, { "name": "entity_move_to", "sig": "iffff>i", "since": "0.1", "params": [ [ "h", "handle" ], [ "x", "f32" ], [ "y", "f32" ], [ "z", "f32" ], [ "speed", "f32" ] ], "returns": "status", "group": "entity", "doc": "Walk there in a straight line at speed m/s (<= 50), turning to face the way it goes." }, { "name": "entity_pos", "sig": "ii>i", "since": "0.1", "params": [ [ "h", "handle" ], [ "out", "out_f32x4" ] ], "returns": "status", "group": "entity", "doc": "Writes x, y, z, yaw." }, { "name": "entity_play_anim", "sig": "iii>i", "since": "0.1", "params": [ [ "h", "handle" ], [ "name", "str" ] ], "returns": "status", "group": "entity", "doc": "chicken: idle, walk, run, peck, flap; glTF assets: any animation in the file." }, { "name": "entity_set_tint", "sig": "iffff>i", "since": "0.1", "params": [ [ "h", "handle" ], [ "r", "f32" ], [ "g", "f32" ], [ "b", "f32" ], [ "a", "f32" ] ], "returns": "status", "group": "entity", "doc": "Wash the entity in a colour (0-1); a = 0 removes it." }, { "name": "entity_set_grounded", "sig": "ii>i", "since": "0.1", "params": [ [ "h", "handle" ], [ "on", "bool" ] ], "returns": "status", "group": "entity", "doc": "A grounded entity stays on the terrain while it moves." }, { "name": "entity_set_scale", "sig": "ifff>i", "since": "0.2", "params": [ [ "h", "handle" ], [ "sx", "f32" ], [ "sy", "f32" ], [ "sz", "f32" ] ], "returns": "status", "group": "entity", "doc": "Each axis clamped to 0.01-100." }, { "name": "entity_set_visible", "sig": "ii>i", "since": "0.2", "params": [ [ "h", "handle" ], [ "on", "bool" ] ], "returns": "status", "group": "entity", "doc": "Show or hide." }, { "name": "entity_set_rot", "sig": "ifff>i", "since": "0.2", "params": [ [ "h", "handle" ], [ "pitch", "f32" ], [ "yaw", "f32" ], [ "roll", "f32" ] ], "returns": "status", "group": "entity", "doc": "Radians; pitch about +X, yaw about +Y, roll about +Z." }, { "name": "entity_stop_anim", "sig": "i>i", "since": "0.2", "params": [ [ "h", "handle" ] ], "returns": "status", "group": "entity", "doc": "Stop the current animation." }, { "name": "entity_set_color", "sig": "iffff>i", "since": "0.3", "params": [ [ "h", "handle" ], [ "r", "f32" ], [ "g", "f32" ], [ "b", "f32" ], [ "a", "f32" ] ], "returns": "status", "group": "render", "doc": "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." }, { "name": "entity_set_material", "sig": "iffff>i", "since": "0.3", "params": [ [ "h", "handle" ], [ "metallic", "f32" ], [ "roughness", "f32" ], [ "emission", "f32" ], [ "unshaded", "f32" ] ], "returns": "status", "group": "render", "doc": "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." }, { "name": "entity_set_light", "sig": "ifff>i", "since": "0.3", "params": [ [ "h", "handle" ], [ "energy", "f32" ], [ "range", "f32" ], [ "angle", "f32" ] ], "returns": "status", "group": "render", "doc": "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." }, { "name": "entity_set_particles", "sig": "iiif>i", "since": "0.3", "params": [ [ "h", "handle" ], [ "preset", "str" ], [ "rate", "f32" ] ], "returns": "status", "group": "render", "doc": "For particles entities: preset smoke, fire, sparks, dust, magic, rain, snow, bubbles; rate 0-200 particles/s (0 stops it). <= 8 emitters per world." }, { "name": "entity_set_text", "sig": "iiif>i", "since": "0.3", "params": [ [ "h", "handle" ], [ "text", "str" ], [ "size", "f32" ] ], "returns": "status", "group": "render", "doc": "For label entities: text floating in the world, always facing the camera. <= 128 bytes; size 0.05-4 m per line." }, { "name": "mesh_create", "sig": "iiii>i", "since": "0.3", "params": [ [ "vertices", "ptr" ], [ "vertex_count", "i32" ], [ "indices", "ptr" ], [ "index_count", "i32" ] ], "returns": "i32", "group": "render", "doc": "A custom triangle mesh; returns a mesh id (> 0) to spawn as kind mesh:. 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." }, { "name": "ground_y", "sig": "ff>f", "since": "0.1", "params": [ [ "x", "f32" ], [ "z", "f32" ] ], "returns": "f32", "group": "world", "doc": "Terrain height at (x, z)." }, { "name": "raycast", "sig": "ffffffi>i", "since": "0.2", "params": [ [ "x1", "f32" ], [ "y1", "f32" ], [ "z1", "f32" ], [ "x2", "f32" ], [ "y2", "f32" ], [ "z2", "f32" ], [ "out", "out_f32x6" ] ], "returns": "i32", "group": "physics", "doc": "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." }, { "name": "sound_play", "sig": "iifff>i", "since": "0.2", "params": [ [ "name", "str" ], [ "x", "f32" ], [ "y", "f32" ], [ "z", "f32" ] ], "returns": "status", "group": "audio", "doc": "A sound at a point: cluck, squawk, bell, click, door, jump, land, select, gear, or asset:.ogg from the world's package (<= 2 MiB each, 32 files). 10/s." }, { "name": "entity_set_collider", "sig": "iifff>i", "since": "0.3", "params": [ [ "h", "handle" ], [ "shape", "i32" ], [ "sx", "f32" ], [ "sy", "f32" ], [ "sz", "f32" ] ], "returns": "status", "group": "physics", "doc": "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." }, { "name": "entity_set_physics", "sig": "iif>i", "since": "0.3", "params": [ [ "h", "handle" ], [ "mode", "i32" ], [ "mass", "f32" ] ], "returns": "status", "group": "physics", "doc": "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." }, { "name": "entity_apply_impulse", "sig": "ifff>i", "since": "0.3", "params": [ [ "h", "handle" ], [ "x", "f32" ], [ "y", "f32" ], [ "z", "f32" ] ], "returns": "status", "group": "physics", "doc": "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." }, { "name": "entity_set_velocity", "sig": "ifff>i", "since": "0.3", "params": [ [ "h", "handle" ], [ "x", "f32" ], [ "y", "f32" ], [ "z", "f32" ] ], "returns": "status", "group": "physics", "doc": "Set a dynamic entity's velocity (m/s, each component clamped to +/-200)." }, { "name": "entity_velocity", "sig": "ii>i", "since": "0.3", "params": [ [ "h", "handle" ], [ "out", "out_f32x3" ] ], "returns": "status", "group": "physics", "doc": "Writes the entity's velocity x, y, z (0 for scripted entities that are not moving)." }, { "name": "entity_set_trigger", "sig": "if>i", "since": "0.3", "params": [ [ "h", "handle" ], [ "radius", "f32" ] ], "returns": "status", "group": "physics", "doc": "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." }, { "name": "timer_after", "sig": "ii>i", "since": "0.2", "params": [ [ "ms", "i32" ], [ "tag", "i32" ] ], "returns": "status", "group": "time", "doc": "Calls on_timer(tag) after ms (0-86,400,000). <= 64 pending." }, { "name": "timer_cancel", "sig": "i>i", "since": "0.2", "params": [ [ "tag", "i32" ] ], "returns": "i32", "group": "time", "doc": "Cancels every pending timer with this tag; returns how many." }, { "name": "timer_repeat", "sig": "ii>i", "since": "0.2", "params": [ [ "ms", "i32" ], [ "tag", "i32" ] ], "returns": "status", "group": "time", "doc": "Calls on_timer(tag) every ms (1-86,400,000) until cancelled." }, { "name": "players_count", "sig": ">i", "since": "0.2", "params": [], "returns": "i32", "group": "players", "doc": "Players in the world now, including remote visitors." }, { "name": "player_id", "sig": "i>i", "since": "0.2", "params": [ [ "index", "i32" ] ], "returns": "i32", "group": "players", "doc": "Id of the index-th player (0 <= index < count), ascending." }, { "name": "player_pos", "sig": "ii>i", "since": "0.1", "params": [ [ "id", "player" ], [ "out", "out_f32x4" ] ], "returns": "status", "group": "players", "doc": "Writes x, y, z, yaw." }, { "name": "player_set_pos", "sig": "iffff>i", "since": "0.2", "params": [ [ "id", "player" ], [ "x", "f32" ], [ "y", "f32" ], [ "z", "f32" ], [ "yaw", "f32" ] ], "returns": "status", "group": "players", "doc": "Teleport the local player (portals, respawns, checkpoints). A remote player's own copy of the script moves them; here it returns -1." }, { "name": "player_is_local", "sig": "i>i", "since": "0.3", "params": [ [ "id", "player" ] ], "returns": "i32", "group": "players", "doc": "1 for the player at this keyboard, 0 for a remote visitor, -1 for an unknown id." }, { "name": "player_name", "sig": "iii>i", "since": "0.3", "params": [ [ "id", "player" ], [ "out", "out_bytes" ], [ "cap", "i32" ] ], "returns": "i32", "group": "players", "doc": "Copies up to cap bytes of the player's display name (UTF-8); returns its full length." }, { "name": "player_key", "sig": "iii>i", "since": "0.3", "params": [ [ "id", "player" ], [ "out", "out_bytes" ], [ "cap", "i32" ] ], "returns": "i32", "group": "players", "doc": "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." }, { "name": "kv_get", "sig": "iiii>i", "since": "0.1", "params": [ [ "key", "str" ], [ "out", "out_bytes" ], [ "cap", "i32" ] ], "returns": "i32", "group": "storage", "doc": "Copies up to cap bytes of the value; returns its full length, or -4." }, { "name": "kv_set", "sig": "iiii>i", "since": "0.1", "params": [ [ "key", "str" ], [ "value", "bytes" ] ], "returns": "status", "group": "storage", "doc": "A value of 0 bytes deletes the key. Keys <= 128 bytes, values <= 4 KiB, 64 KiB per world. Stored on this visitor's machine." }, { "name": "world_message", "sig": "ii>i", "since": "0.1", "params": [ [ "data", "bytes" ] ], "returns": "status", "group": "network", "doc": "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." }, { "name": "message_to", "sig": "iii>i", "since": "0.3", "params": [ [ "id", "player" ], [ "data", "bytes" ] ], "returns": "status", "group": "network", "doc": "Send bytes to one remote player's copy of this script (same limits as world_message, sharing its rate)." }, { "name": "is_authority", "sig": ">i", "since": "0.3", "params": [], "returns": "i32", "group": "network", "doc": "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." }, { "name": "camera_set", "sig": "iffffff>i", "since": "0.3", "params": [ [ "mode", "i32" ], [ "x", "f32" ], [ "y", "f32" ], [ "z", "f32" ], [ "tx", "f32" ], [ "ty", "f32" ], [ "tz", "f32" ] ], "returns": "status", "group": "camera", "doc": "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)." }, { "name": "input_bind", "sig": "ii>i", "since": "0.3", "params": [ [ "key", "i32" ], [ "on", "bool" ] ], "returns": "status", "group": "input", "doc": "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." }, { "name": "ui_text", "sig": "iiifff>i", "since": "0.3", "params": [ [ "id", "i32" ], [ "text", "str" ], [ "x", "f32" ], [ "y", "f32" ], [ "size", "f32" ] ], "returns": "status", "group": "ui", "doc": "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." }, { "name": "ui_button", "sig": "iiiffff>i", "since": "0.3", "params": [ [ "id", "i32" ], [ "text", "str" ], [ "x", "f32" ], [ "y", "f32" ], [ "w", "f32" ], [ "h", "f32" ] ], "returns": "status", "group": "ui", "doc": "Create or update a clickable button (position and size in 0-1 of the window); a click calls on_ui(id)." }, { "name": "ui_bar", "sig": "iffff>i", "since": "0.3", "params": [ [ "id", "i32" ], [ "value", "f32" ], [ "x", "f32" ], [ "y", "f32" ], [ "w", "f32" ] ], "returns": "status", "group": "ui", "doc": "Create or update a progress bar filled to value (0-1); its colour follows entity-style ui_color." }, { "name": "ui_color", "sig": "iffff>i", "since": "0.3", "params": [ [ "id", "i32" ], [ "r", "f32" ], [ "g", "f32" ], [ "b", "f32" ], [ "a", "f32" ] ], "returns": "status", "group": "ui", "doc": "Colour of a UI element's text or fill (0-1)." }, { "name": "ui_remove", "sig": "i>i", "since": "0.3", "params": [ [ "id", "i32" ] ], "returns": "status", "group": "ui", "doc": "Remove a UI element. Ids are the script's own (1-2,147,483,647); <= 32 elements." } ], "callbacks": [ { "name": "on_init", "sig": ">", "since": "0.1", "params": [], "doc": "Once, after instantiation." }, { "name": "on_tick", "sig": "f>", "since": "0.1", "params": [ [ "dt", "f32" ] ], "doc": "About 10 times a second (tick_hz); dt is seconds since the last tick (<= 0.5)." }, { "name": "on_enter", "sig": "i>", "since": "0.1", "params": [ [ "player", "player" ] ], "doc": "A player arrives (after on_init for everyone already there). The local player is id 1." }, { "name": "on_leave", "sig": "i>", "since": "0.1", "params": [ [ "player", "player" ] ], "doc": "A player leaves." }, { "name": "on_interact", "sig": "ii>", "since": "0.1", "params": [ [ "player", "player" ], [ "entity", "handle" ] ], "doc": "A player uses an entity (the interact key within 2.5 m)." }, { "name": "on_timer", "sig": "i>", "since": "0.2", "params": [ [ "tag", "i32" ] ], "doc": "A timer_after / timer_repeat fired." }, { "name": "on_message", "sig": "ii>", "since": "0.1", "params": [ [ "data", "bytes" ] ], "doc": "Bytes from another copy of the script (used when on_message_from is not exported)." }, { "name": "on_message_from", "sig": "iii>", "since": "0.3", "params": [ [ "player", "player" ], [ "data", "bytes" ] ], "doc": "Bytes from the copy of the script running for this player." }, { "name": "on_trigger_enter", "sig": "ii>", "since": "0.3", "params": [ [ "player", "player" ], [ "entity", "handle" ] ], "doc": "A player walked into a trigger zone." }, { "name": "on_trigger_exit", "sig": "ii>", "since": "0.3", "params": [ [ "player", "player" ], [ "entity", "handle" ] ], "doc": "A player left a trigger zone." }, { "name": "on_contact", "sig": "ii>", "since": "0.3", "params": [ [ "a", "handle" ], [ "b", "handle" ] ], "doc": "Two of the script's dynamic entities, or a dynamic entity and the world (b = 0), started touching." }, { "name": "on_click", "sig": "ii>", "since": "0.3", "params": [ [ "player", "player" ], [ "entity", "handle" ] ], "doc": "The local player clicked an entity with the mouse (needs a collider)." }, { "name": "on_input", "sig": "ii>", "since": "0.3", "params": [ [ "key", "i32" ], [ "pressed", "bool" ] ], "doc": "A key asked for with input_bind went down (1) or up (0)." }, { "name": "on_ui", "sig": "i>", "since": "0.3", "params": [ [ "id", "i32" ] ], "doc": "A ui_button was clicked." }, { "name": "iamar_alloc", "sig": "i>i", "since": "0.1", "params": [ [ "len", "i32" ] ], "doc": "Required with on_message / on_message_from: returns a buffer of len bytes the host fills; the script owns it afterwards." } ], "limits_added_in_0_3": { "max_lights": 16, "max_emitters": 8, "max_dynamic": 128, "max_meshes": 64, "max_mesh_vertices": 4096, "mesh_vertices_total": 1000000, "max_ui": 32, "max_ui_text": 256, "max_label_text": 128, "max_bound_keys": 32, "max_sounds": 32, "max_sound_bytes": 2097152, "max_mesh_indices": 12288, "mesh_indices_total": 3000000, "meshes_per_sec": 4, "max_speed": 200, "camera_lockout_s": 10 } }