AI tools: Gameplay, kits and scripts
Starting a game, genre kits, scripts, game feel, vehicles and physics. 57 tools. You see every step your AI takes and can undo any of them.
add_brain
Attach/update an editable native enemy brain: patrol, hunter, chaser, shooter, pack, stalker or guard. Configure behavior with numeric params, squad/role and optional waypoints. Reuses existing awareness and preserves existing components; missing senses/stats/kinematic body defaults are added. Undoable. Refuses player controllers and competing guard/enemy scripts; never silently deletes them. See kit_playbook enemy-brains.
| Argument | Type | What it does |
|---|---|---|
debug | boolean | Draw geometry-derived cover/flank/ambush points, chosen route and observations in Play. |
definition | object | Optional complete arcwright.brain.v1 data recipe. Same bounded tree validator as shipped presets; not executable script. |
enabled | boolean | |
entity required | string | Entity name (e.g. "Tower_B") or id (e.g. "#7"). |
params | object | Merge numeric overrides into the editable brain recipe. Omitted overrides are preserved; unknown names, booleans and non-finite values are refused. |
preset required | patrol / hunter / chaser / shooter / pack / stalker / guard / tactical … | |
role | auto / leader / flanker / suppressor | |
squad | string | Shared radio group; empty means independent. Never joins all enemies implicitly. |
waypoints | list of any | Patrol waypoints, in order. Empty holds position. Movement is physical, not teleportation. |
add_camera_cut
Add a camera cut to a sequence: from t the picture comes from eye (a place: [x,y,z], an object, or {of, offset, frame: "world"} to track something without spinning with it) or from a camera object (key its transform for cranes and orbits), looking at look, with fov (degrees, default 50) or lens (mm, full frame: 24 wide, 50 normal, 85 portrait), roll (dutch), blend (seconds easing from the previous cut; none is a hard cut), to {...} for a move over the cut (absolute: eye, look, fov, lens, roll; rig moves relative to the start: dolly m toward the subject, truck m sideways, crane m up, orbit degrees round the look point, pan/tilt degrees; focus pull: focus / focus_distance, aperture; ease, bezier), focus / focus_distance and aperture (depth of field), shake {amplitude degrees, drift m, frequency Hz, clock} for a hand-held camera. A cut at the same t is replaced.
| Argument | Type | What it does |
|---|---|---|
aperture | number | |
blend | number | |
camera | string | |
camera_body | string | A physical camera for this cut: the sensor (camera_gear lists them). |
eye | any | A place: [x, y, z], an object's name, or {of, offset: [x, y, z], frame: "object" (heading only, default) | "full" | "world"}. |
focus | any | A place: [x, y, z], an object's name, or {of, offset: [x, y, z], frame: "object" (heading only, default) | "full" | "world"}. |
focus_distance | number | |
fov | number | |
lens | number | |
lens_kit | string | A physical lens kit for this cut (camera_gear); then lens is the focal length on that sensor and t_stop the iris. "none": the classic camera. |
look | any | A place: [x, y, z], an object's name, or {of, offset: [x, y, z], frame: "object" (heading only, default) | "full" | "world"}. |
name | string | |
rig | object | How the camera is carried, simulated: {kind: tripod | dolly | crane | steadicam | drone | car_mount | handheld, profile (handheld: breathe, walk, run, panic; steadicam: glide, walk; drone: smooth, agile, fpv), amount 0...3, seed (another take), vehicle + mount [x,y,z] (car_mount), arm m (crane), clock}. The cut's eye/look/move are the intent; the rig carries the camera there. |
roll | number | |
sequence required | string | The sequence's name (Sequences/<name>.sequence.json). |
shake | object | {amplitude: degrees (0.6), drift: metres (0.012), frequency: per second (1.4), clock: true}: hand-held. |
shutter_angle | number | |
t required | number | Story seconds from the start. |
t_stop | number | Iris T-stop with a lens kit (default T2.8, clamped to the lens). |
to | object | {eye, look, fov, lens, roll, dolly, truck, crane, orbit, pan, tilt, focus, focus_distance, aperture, t_stop, ease, bezier}: the move over the cut (lens on a zoom kit zooms; t_stop pulls the iris). |
add_cinematic25d
A 2.5D cinematic shot for a 2D game: the flat view turns 3D for a big moment (a boss intro, a reveal) and lands back on the 2D view, seamlessly. Every layer becomes a real depth plane (backdrops as deep as their parallax, the play layers on the play plane), sprites are cards; the camera pushes in, orbits, dollies or tilts round the target with depth of field, a light change and letterbox bars, then returns to play. With sequence (and t) it goes into that sequence (made if missing); with play: true it plays now in the running game; preview: n returns n stills across the shot rendered from a copy of the scene. remove: true takes the sequence's shot at t out.
| Argument | Type | What it does |
|---|---|---|
amount | number | Move strength: degrees for orbit/tilt/reveal/boss_intro, share of the view for dolly/push_in. |
blend_in | number | |
blend_out | number | |
cards | face / flat | Sprites turn to face the camera (default) or stay flat. |
depths | object | Per-object depth overrides: name -> depth behind the play plane (share of the view distance; negative is nearer). |
distance | number | How close, as a share of the 2D view's distance (default per move, about 0.5). |
dof | number | Depth of field 0...1 (default 0.6): nearer and further than the target blurs. |
duration | number | The whole shot in seconds, the swing in and back to the 2D view included (default 3.5). |
fov | number | Field of view in the shot, degrees (default 34). |
hold | boolean | Hold the player's controls while it plays (default true). |
layer_depth | number | Depth per layer step on the play plane, share of the view distance (default 0.002). |
letterbox | number | Black bar each side, share of the screen (default 0.09; 0 none). |
light | dramatic / warm / cold / dark / none | The light change (default dramatic). |
move | push_in / orbit / dolly / tilt / reveal / boss_intro / hold | push_in, orbit (round the target), dolly (sideways past it), tilt (from below up), reveal (pull back from close), boss_intro (low push in, then a swing round), hold. |
play | boolean | |
preview | number | Stills to render across the shot (1...6). |
remove | boolean | |
sequence | string | The sequence's name (Sequences/<name>.sequence.json). |
t | number | Story seconds from the start. |
target | string | The object the camera frames, orbits and focuses on (none: the middle of the screen). |
add_clip
Play an animation clip on a character in a sequence, from t on the timeline (until the next clip, or for duration), cross-fading in over blend seconds (default 0.25). The clip is any name animator.clip takes: the model's or its library's clips (e.g. Mannequin's Idle_Talking_Loop, Punch_Cross, Spell_Simple_Shoot, Hit_Head, Death01), captured action clips, or "auto" (back to walking by speed). Scrubbing shows exactly the right frame. Clips made elsewhere (keyframed or posed) drop in by name.
| Argument | Type | What it does |
|---|---|---|
blend | number | |
clip required | string | |
duration | number | |
from | number | Clip seconds to start at. |
library | string | Play another model's clips (as animator.library). |
loop | boolean | |
sequence required | string | The sequence's name (Sequences/<name>.sequence.json). |
speed | number | |
t required | number | Story seconds from the start. |
target required | string |
add_combatant
Give an existing object reusable combat rules and authoritative stats health. Humanoid rigs get anatomical head/torso/arm/leg hurtboxes automatically; supply explicit bone (or @root) receiving volumes for other shapes. Optional hurtboxes add/update numbered slots; unmentioned volumes remain. One undoable step; existing stats/settings are preserved unless supplied. Use edit_entity for detailed combatant guard/dodge/recovery fields.
| Argument | Type | What it does |
|---|---|---|
auto_hurtboxes | boolean | |
entity required | string | Existing entity name or #id. |
friendly_fire | boolean | |
health | number | |
hurtboxes | list of object | |
ragdoll | boolean | |
team | string |
add_door
Give a model a door it doesn't have as a separate part (a forged car's painted-on door): a hinged panel riding on the model, an interactable door that opens and closes through actions (players with E, bots, scripts with self.act("open"), cutscenes with the act event), and optionally a window riding on it. Numbers are in the model's own frame (x right, y up, +z its front: glTF and forged models face +z), e.g. a sedan's driver door: at [0.945, 0.32, 0.335], length 1.23, height 0.66.
| Argument | Type | What it does |
|---|---|---|
at required | list of number | |
color | list of number | |
height required | number | |
hinge | string | "front" (+z, default) or "back". |
length required | number | |
name | string | The door's name (default: <object>_Door). |
object required | string | The model to give a door (by name). |
side | string | "left" (+x, a car's driver side) or "right". |
swing | number | Degrees it opens outward (default 70). |
thickness | number | Default 0.04 m. |
window_height | number | A window above the panel (0: none). |
window_length | number |
add_event
Add a timed event to a sequence (do): launch (target, velocity [x,y,z] m/s, spin [x,y,z] degrees/s: a throw), release (back to physics now), ragdoll (a character goes limp), particles (target emitter shows count for seconds: a burst), shatter (target breaks into count shards, default 14, that fly on under live physics from where and how it was moving; velocity adds a push; color [r,g,b] tints them), sound (name, target or at, volume, pitch), send (target, message, data: a script message; target "*" every script), say (target, text), show (text, seconds), animate, expression, look_at, set (property, value), hide, unhide, remove, act, power, objective.
| Argument | Type | What it does |
|---|---|---|
action | string | |
at | any | A place: [x, y, z], an object's name, or {of, offset: [x, y, z], frame: "object" (heading only, default) | "full" | "world"}. |
by | string | |
clip | string | |
color | list of number | |
count | number | |
data | any | Any JSON. |
do required | act / animate / enter_vehicle / exit_vehicle / expression / fade / hide / launch … | |
expression | string | |
intensity | number | |
loop | boolean | |
message | string | |
name | string | |
on | boolean | |
pitch | number | |
property | string | |
seconds | number | |
sequence required | string | The sequence's name (Sequences/<name>.sequence.json). |
spin | list of number | |
subtitle | boolean | |
t required | number | Story seconds from the start. |
target | string | |
text | string | |
value | any | For set: the value. |
velocity | list of number | |
volume | number |
add_ground_cover
Lay ground cover grown by the GPU (no object per blade), cut from our photo atlases (material_library): grass (photo tufts), meadow (long grass with wild flowers), flowers (a bed of tulips and daisies), clover, pebbles, leaves (fallen leaf litter), reeds (cattails by water), ferns, weeds; or a preset (a kind with its own photo atlas and numbers): crack_weeds (small weeds from pavement cracks and kerb joints), flower_bed (a municipal bed: periwinkle, ixora, pentas, coleus, purple heart, duranta), lawn (a clipped tropical lawn (over a grass ground surface: the tufts break it up)), tropical_grass (tropical roadside grass: broad and fine blades, seed heads, dry tufts), tropical_litter (fallen tropical litter: sea almond and mango leaves, flame tree flowers and pods, palm bits), weedy_lot (vacant-lot weeds: Spanish needle, lantana, sensitive plant, castor bean, dry grass). On a flat area (center + size), or on the object named `on` (land/terrain or any mesh: it grows on the upward faces). Sways in the wind, thins with distance. Rules: under_trees (leaves under crowns), by_walls (weeds along walls), by_water (reeds and pebbles along shores), only_rules. keep_clear names objects whose full mesh/collider world boxes must stay bare; clear_buildings defaults true and clears anything tagged wall, roof, floor or building. clear_margin adds clearance in meters (default 0.3). Paint it afterwards with paint_ground_cover.
| Argument | Type | What it does |
|---|---|---|
accents | list of list of number | Petal colors (flowers, meadow). |
align_to_slope | number | kind mesh: 0 upright ... 1 lying flat on the slope (default 0.85). |
atlas | string | Photo atlas from material_library (cover_fern, cover_grass_dry, cover_dead_leaves, cover_pebbles...). Default: the kind's own photo atlas; "drawn" for drawn plants. |
by_walls | number | |
by_water | number | 0...1: more of it along shores, just above the water (reeds, pebbles). Nothing grows under water except reeds in the shallows. |
center | list of number | |
clear_buildings | boolean | Default true: clear every object tagged wall, roof, floor or building. |
clear_margin | number | Meters of clearance around each object's bounds; default 0.3, range 0...10. |
color_root | list of number | sRGB 0...1 |
color_tip | list of number | sRGB 0...1 |
density | number | Plants per m² (default per kind). |
distance | number | Grows out to this far from the camera (m, default 45; 5...150). |
dryness | number | |
height | number | |
in_clearings | number | Forest rule 0...1: only in the forests' clearings (meadows). |
keep_clear | list of string | Exact object names: leave their full mesh or collider bounds clear, plus clear_margin. |
kind required | grass / meadow / flowers / clover / pebbles / leaves / reeds / ferns … | |
mesh | string | kind mesh: the model each one is (a forge_litter piece, e.g. Forge/Nature/Litter/needle_clump_2.glb); `height` scales it (1 = as made). |
name | string | |
on | string | Grow on this object (exact name) instead of a flat area. |
only_rules | boolean | |
patch_size | number | Noise clumping: patch size in metres (default per kind). `patchiness` 0...1 sets how much ground stays open between patches. |
patchiness | number | |
scale_by_noise | number | 0...1 (default 0.5): plants bigger in a patch's middle, smaller at its edge. |
seed | integer | |
size | list of number | |
style | realistic / cartoon | |
under_forest | number | Forest rule 0...1: only under the forests' canopy (forest floor). |
under_trees | number | |
wind | number |
add_hedge
Add a clipped hedge along a path: segments of a hedge model (grow_plant kind hedge) laid end to end along `path` [[x,z],...], each turned along the path and stretched a little so the run ends exactly at the last point; solid colliders; one group, one undoable change (the same name replaces).
| Argument | Type | What it does |
|---|---|---|
ground_y | number | |
mesh required | string | Hedge segment model (Forge/Nature/<name>.glb). |
name required | string | |
path required | list of list of number | |
segment_length | number | The model's length (m, default 2). |
add_kit core
Install a ready-made gameplay kit into the project's Scripts/kits folder and get its manual. Available kits: shooter, zombies, collect, endless, platformer, stealth, platformer2d, hands, caving, builder, tactics, strategy, roguelike, abilities, survival, towers, fighting, rhythm, cameras, extraction, progression. Read kit_playbook for setup and controls.
| Argument | Type | What it does |
|---|---|---|
kit required | shooter / zombies / collect / endless / platformer / stealth / platformer2d / hands … | |
upgrade | boolean | Replace kit scripts you've changed with the shipped versions (yours are saved as .mine). Default false: changed copies are kept. |
add_reference
Save a reference picture (an https image link, e.g. from find_reference) to the project's reference board, Assets/References/<subject>/, with a record of its source and license. Then compare_reference and inspect can use it.
| Argument | Type | What it does |
|---|---|---|
license | string | The license find_reference reported. |
name | string | File name (default from the link). |
subject required | string | Folder name, e.g. super_hornet. |
url required | string |
add_requirement
Add (or replace, by id) a requirement in the open scene's game brief (Briefs/<game>.brief.json, created when the scene has none): a stable id, plain-language text, the kind of check that proves it by play (any game: play_inputs — keys at times, settings {inputs: "Space@1, R@2.5", expect: won|failed|playing}, for builders, puzzles, cards and rhythm; bot_finishes, exit_wins, player_dies, save_load, ui_pause_resume, first_frame; fights: combat_knockout {seconds ≤ 30, distance 0.2–3; settings isolate "true" tests the two alone}; horror and stealth: power_cycle, toggle_light, dark_only, holds_at_light_edge, flees_light, hears_noise, guard_sight; "manual" when only a person can judge it) and its params/settings. Leave check out for something not built yet (pending). proof_report proves the brief. Giving Game Plan route tests instead (tests) adds it to the scene's Game Plan, as before; agents add unprotected requirements; the person can protect them.
| Argument | Type | What it does |
|---|---|---|
check | string | Brief: the kind of check that proves it. Leave out for pending (not built yet). |
id required | string | Stable id, e.g. creature.flees_flashlight (Game Plan: Reach_Roof). |
links | list of string | Game Plan: objects this requirement depends on. |
note | string | Brief, with status unchecked: what is known without a check (how it was measured by hand, or the file with the measurements). |
params | object | Brief: numbers the check reads, e.g. {"within": 60}. |
settings | object | Brief: text settings the check reads, e.g. {"key": "F", "without": "Spawner"}. |
status | pending / unchecked | Brief: pending = planned, not built yet; unchecked = built, but no check kind proves it yet (proof_report shows UNCHECKED, never PASS; give a note). |
tests | string | Game Plan instead of the brief: test blocks, e.g. reach { from "Start" to "Roof_Door" within 30 radius 0.4 } or frame_budget { from "Start" max_gpu_ms 8 } |
text required | string | What must be true, in one plain sentence a non-programmer understands. |
add_shot
Put another sequence inside this one as a shot from t: its tracks, events and (cameras, default true) camera cuts come in shifted to t and grouped under the shot's name in the timeline; time_scale: true also brings its slow motion. Shots nest (a scene of shots, a shot of moves), up to 8 deep; a sequence can't contain itself. remove: true takes the shot at t out.
| Argument | Type | What it does |
|---|---|---|
cameras | boolean | |
muted | boolean | |
name | string | |
remove | boolean | |
sequence required | string | The sequence's name (Sequences/<name>.sequence.json). |
shot | string | The other sequence's name. |
t required | number | Story seconds from the start. |
time_scale | boolean |
add_track
Add a track to a sequence, bound to an object: kind "transform" (position/rotation/scale curves; with bone: one skeleton node, "#index" or a name), "property" (any component.field, e.g. point_light.intensity, mesh_renderer.color, particles.count, jiggle.amount, or "visible"), or "animation" (clips: add_clip). Returns its number. set_key and add_clip make tracks as needed, so this is for options: after ("hold" or "release": back to physics when its keys end), ease (the default for its keys), name, muted, group (a timeline folder, e.g. "Bottle/flight"). Layers: new: true adds another transform track on the same object (give it a name to address it); layer "additive" adds its keys as offsets on top of the tracks before it (nudge a baked physics arc), "override" replaces them by its weight; key weight 0...1 with set_key {weight} to cross-fade between a baked take and hand keys.
| Argument | Type | What it does |
|---|---|---|
after | hold / release | |
bone | string | |
ease | auto / bezier / cubic / ease_in / ease_in_back / ease_in_cubic / ease_in_expo / ease_in_out … | How the stretch from this key to the next moves (default auto: smooth through the keys, never overshooting). |
group | string | |
kind required | animation / property / transform | |
layer | override / additive | |
muted | boolean | |
name | string | |
new | boolean | |
property | string | |
sequence required | string | The sequence's name (Sequences/<name>.sequence.json). |
target required | string |
add_water
Place water: a lake or pond (outline `points` [[x,z],...] world, or `center` + `radius`), a clear `pool`, or a `river` flowing along `points` [[x, y, z, width],...] (y the surface there; it flows from the first point to the last, faster in the middle). Depth colour, reflections, ripples, flow, foam at the shore and around rocks, soft edges into the ground. Swimmable; things float. Set the outline a little into the banks: the water fades out where it gets thin.
| Argument | Type | What it does |
|---|---|---|
center | list of number | |
clarity | number | |
deep_color | list of number | sRGB 0...1 |
depth | number | |
flow | number | |
foam | number | |
kind required | lake / pond / pool / river | |
level | number | Surface height (lakes; default center y). |
lilies | number | |
name | string | |
points | list of list of number | |
radius | number | |
ripples | number | |
shallow_color | list of number | sRGB 0...1 |
style | realistic / cartoon | |
width | number |
add_waterfall
Add a waterfall: water pours over a lip at `position` (its middle), toward `facing` (compass degrees the water flows toward) or `toward` [x, z], `width` wide, falling `drop` meters into what's below (a pool, a river, the sea). Streaking sheet breaking into strands, spray where it lands, mist rolling off, foam spreading on the water below.
| Argument | Type | What it does |
|---|---|---|
drop | number | |
facing | number | |
flow | number | |
foam | number | |
mist | number | |
name | string | |
position required | list of number | |
speed | number | |
spray | number | |
style | realistic / cartoon | |
toward | list of number | |
width | number |
ai_debug
Read one NPC's actual LIVE thinking: tree trace, utility scores and rejected options, observation ages/confidence, original radio timestamps, orders, navigation, acoustic path and budgets, boss telegraph or traffic state. Same text as the AI Thinking editor tab. Read-only; never starts Play, simulates or changes the camera.
| Argument | Type | What it does |
|---|---|---|
entity required | string | Entity name (e.g. "Tower_B") or id (e.g. "#7"). |
assemble_vehicle
Turn a forged car model into a drivable car, assembled the way game vehicles are: a root with the dynamics (wheelbase and track measured from the model's hub_FL/FR/RL/RR points, each axle's wheel size from its own wheel models: bigger rear tyres roll at their own size), the body (the model without its corner parts FL_*, FR_*, RL_*, RR_*), four hub-centred wheel models that spin and steer (tag vehicle_wheel_i), calipers that steer and ride but don't spin (vehicle_knuckle_i), the lamps' LED and projector parts as their own glowing objects, a low-beam spot light at each lamp_head_* point, red glow at each lamp_tail_* point (points named lamp_head_left / lamp_head_right or numbered lamp_head_0, lamp_head_1..., the same for lamp_tail_), and at each exhaust_0...exhaust_15 point heat haze, cold-start and lift-off smoke and the pop flash. The lamp runtime switches them (vehicle_lights); everything is ordinary objects to tune.
| Argument | Type | What it does |
|---|---|---|
extras | list of string | More models in the car's own axes attached in place (e.g. Forge/sportscar01_interior.glb, the cabin built on its own). |
knuckles | string | Hub-centred caliper models with {corner} (default <model>_caliper_{corner}.glb; skipped if absent). |
lamp_glow | number | Glow of the lit LED parts (default 6). |
model | string | The forged car under Assets (e.g. Forge/sportscar01_car.glb): named parts plus hub_*, lamp_*, exhaust_* points. |
name | string | The car's root object (default: from the model). |
position | list of number | [x, y, z] on the ground. |
preset | sports / sedan / suv / pickup / truck / kart / motorbike | Vehicle class (default sports). |
replace | boolean | A car of this name already exists: take it and everything attached to it out first (one undo step), then build it again. |
traffic_template | boolean | Tag the car traffic_template: city traffic spawns copies of it (with everything attached). |
tuning | object | Vehicle settings as in tune_vehicle. |
wheels | string | Hub-centred wheel models with {corner} for FL FR RL RR (default <model>_wheel_{corner}.glb). |
yaw | number | Degrees about Y (0: nose toward +Z). |
board
While playing (play_mode): boards and bikes ridden standing up. With no arguments: each board (kind, phase rolling / air / grinding / down and why, speed, lean, the rider's lean, the grind's style, speed and balance), the rails and the jumps, landings, grinds and falls so far. `make` {name, kind: skate | snow | surf | bmx | hover, and any setting: wheelbase, steer, assist (0 full simulation ... 1 never thrown by a turn), grip, edgeGrip, rolling, push, cruise, brake, ollie, spin, riderHeight, skill, bailLean, land, landAngle, crash, grindSnap, grindDrag, grindTip, grindHold, grindLose, hover, turnRate} makes a moving body a board (or retunes one). `mount` {name, rider} puts a character on it (a player then rides it with their keys). `steer` {name, steer -1..1, push, brake, jump, spin} drives a board no player rides. `rail` {points: [[x, y, z], ...]} adds a rail to grind (objects tagged rail, grind, ledge or coping are rails already). `view` {on}: the board view (the rails in cyan; on each board the rider's lean, green going red toward the lean they fall past, the lean that balances the turn in white, the steering lean in yellow).
| Argument | Type | What it does |
|---|---|---|
make | object | {name, kind, settings...}. |
mount | object | {name, rider}. |
rail | object | {points: [[x, y, z], ...]}. |
steer | object | {name, steer, push, brake, jump, spin}. |
view | object | {on}: the board view. |
car_lab
Car Lab guides over a forged model in the viewport, read the way a car studio reads a surface: curvature combs along the recipe's f.curve lines (<model>.curves.json; a tooth at each sample as long as the line is curved there: a smooth comb is a fair line, a notch or a jump is a kink; it names each curve's biggest jump) and its f.hinge parts (<model>.hinges.json: the axis, the arc the part's farthest point sweeps, the part's box opened to its angle, how far it travels). They stay over the model while the camera moves, until {clear: true}. Returns a picture (current view or along an axis). move drags a curve's control point (the same edit a viewport handle makes) and rebuilds the model from its recipe.
| Argument | Type | What it does |
|---|---|---|
clear | boolean | Take the guides away. |
curves | list of string | Only these curves (default all). |
every | integer | A tooth every n samples (default about 90 teeth per curve). |
move | object | Move one control point of a recipe curve and rebuild the model: {curve, point (index from 0), by: [dx, dy, dz] metres in the model's own axes | to: [x, y, z] | reset: true}. Kept in Assets/Forge/<model>.curve_edits.json; the combs redraw from the rebuilt curves. |
object | string | The object showing the forged model. |
scale | number | Metres of tooth per 1/m of curvature (default: the 90th-percentile curvature makes a 10 cm tooth). |
show | list of combs / hinges | Which guides (default both). |
still | boolean | Return a picture (default true). |
view | current / side / top / front / rear / three_quarter | The picture's view (default current). |
crumple
While playing (play_mode): objects that crumple (junk cars, drums: a lattice of beams inside that bend, yield and set, the model and collider following). With no arguments: each one's lattice, how far it has gone (largest and mean node movement, share of beams set, the smallest cell left: below 0 a cell turned inside out), its size now, presses and hits so far. `make` {name, energy (J per m³ pushed in, default a car body's 400000), cell (m), collider (false keeps its own)} makes an object crumple. `dent` {name, at [x, y, z] world, impulse [x, y, z] N·s, mass (the hitter's kg, default 8), size (its face's radius m)} hits it and says how deep it went (a sledgehammer: impulse 80 at mass 8). `press` {name, on} makes a kinematic body (a crusher's plate) crush what crumples where it moves. `tune` {toughness (× every crush energy), threshold (J a hit needs to leave a mark), cell (m, objects made from now on), reshape, press_reshape (s between redraws)}. `view` {on}: the lattices drawn over the picture, beams green as made, orange to red shortened, blue stretched.
| Argument | Type | What it does |
|---|---|---|
dent | object | {name, at: [x, y, z], impulse: [x, y, z], mass, size}: a blow. |
make | object | {name, energy, cell, collider}: make an object crumple. |
press | object | {name, on}: a kinematic body that crushes what crumples. |
tune | object | {toughness, threshold, cell, reshape, press_reshape}. |
view | object | {on}: the lattice view. |
explode
While playing (play_mode): an explosion at a point (`point` [x, y, z] or `at` an object): a flash that lights the scene with shadows, a fireball, smoke that rises and lingers, sparks, chunks and a dust ring, a scorch on the ground, bodies thrown and characters knocked (ragdolls flung), damage by distance to anything with health, the camera shaken for whoever is near, and the boom. power 1 a hand grenade, 3 an RPG warhead, 10 a car bomb (reach 6 m × power^(1/3)); damage at the centre (default 150 × power). Scripts: game.explode(at, power, damage).
| Argument | Type | What it does |
|---|---|---|
at | string | An object: at its position. |
damage | number | Damage at the centre (default 150 × power). |
point | list of number | Where (world [x, y, z]). |
power | number | 1 a grenade (default), 3 an RPG warhead, 10 a car bomb. |
explode_object
Exploded view of an object built from a mechanical spec: each part moved away from its parent along the parent-to-part direction, factor 0...1 (0 reassembles: every part exactly back at rest). Undoable.
| Argument | Type | What it does |
|---|---|---|
factor required | number | 0 (assembled) ... 1 (fully apart). |
object required | string | The built object (its root, by name). |
feel
3D game feel in the running game (Beta 2): how much each hit gets and what every hit got so far. With settings (shake, flash, hit_stop 0...2; rumble, effects, reduced_motion) it changes them live; without, it reports: hits, how many got hit-stop, a shake, what flies off (blood off a body, sparks off metal, chips off stone), its sound, a flash, slow motion on a kill, the controller's rumble, and what was missing. Scripts do the same with game.feel(settings) and give any hit the whole feel with game.hitFeel(target, { strength }); melee hits get it by themselves. Needs Play; feel_check runs the scene's fight headless.
| Argument | Type | What it does |
|---|---|---|
effects | boolean | Particles, flashes and extra sounds (false: off; the hits themselves never change). |
flash | number | × the hit flash on bodies. |
hit_stop | number | × hit-stop (the hold on a hit). |
reduced_motion | boolean | No shake or slow motion, softer flashes. |
rumble | boolean | The controller's rumble on the player's hits. |
shake | number | × the camera shake on hits (0 off, 1 as made). |
flight
Flight games while playing (play_mode on): action "state" (default) lists every aircraft: team, player or AI mode, health, position, speed (m/s and knots), altitude, heading, g, Mach, angle of attack, throttle, gear, on the ground, weapons left, kills, its target and lock, and the player's HUD warnings. Action "fly" engages the player's autopilot through the real controls: goal "takeoff" (full power, rotate, gear up, climb), "hold" (heading degrees, altitude m, speed m/s), "point" (target [x, y, z], speed), "attack" (the nearest enemy, lead pursuit; fire with "fire"), "land" (runway threshold [x, y, z] and heading degrees: a 3° approach, flare, brakes). "off" hands the jet back. Action "fire": weapon "gun" (seconds), "missile" or "flares". Action "view": cockpit / chase / orbit (yaw, pitch degrees). Action "photo": a fixed camera (eye + target) or one riding with the jet (follow [x, y, z] in its frame), for stills and video of the game; photo alone restores the game camera. Engine heading 0 points +Z; compass = (180 - heading) mod 360.
| Argument | Type | What it does |
|---|---|---|
action | state / fly / off / fire / view / photo | |
altitude | number | Meters. |
eye | list of number | photo: a fixed camera [x,y,z] looking at `target`; or follow: [right,up,back] offset in the jet's frame (+X left, +Z nose). photo with neither: back to the game camera. |
follow | list of number | |
goal | takeoff / hold / point / attack / land / launch / trap / sortie | |
heading | number | Degrees, engine heading (0 = +Z). |
pitch | number | |
seconds | number | |
speed | number | m/s (default 220). |
target | list of number | [x, y, z]: a point, or the runway threshold for land. |
view | cockpit / chase / orbit | view: the player's camera (orbit takes yaw/pitch degrees). |
weapon | gun / missile / flares | |
yaw | number |
fracture
While playing (play_mode): breakable objects (pre-cut with f.fracture or `TTRForgeWorker fracture`). With no arguments: how many breakables and loose chunks there are, the debris budget, breaks so far and the tuning. `make` {name, material ("concrete", "stone", "plaster", "ceramic", "glass", "wood", "plastic", "metal"), anchored} makes an object breakable. `strike` {name, at [x, y, z] world, impulse [x, y, z] N·s} hits it (a sledgehammer is about 80 N·s, a 1 t wrecking ball at 5 m/s about 6500) and says how many pieces it broke into. `tune` {toughness (× every bond's strength), reach (how far a blow spreads), carry (share of the hitter's speed kept through, and given to nearby pieces), kick (m/s outward), big_hit (N·s: a break this hard sets off slow motion and a shake), slow_scale, slow_seconds (0 off), tier ("mac", "pc", "deck", "web", "phone": that device's debris budget), alive, awake}.
| Argument | Type | What it does |
|---|---|---|
make | object | {name, material, anchored}: make an object breakable. |
strike | object | {name, at: [x, y, z], impulse: [x, y, z]}: a blow. |
tune | object | {toughness, reach, carry, kick, big_hit, slow_scale, slow_seconds, tier, alive, awake}. |
fx_burst
Preview one-shot simulated effects (the GPU flies, collides and lights every particle; bursts are seeded, so the same seed shows the same particles). kind: "blood" (a spray along `direction`, default into the surface: look human/zombie, head, through), a struck material ("concrete", "plaster", "stone", "wood", "dirt", "leaves", "metal", "glass"), "burst" (`burst`: { kind droplet|mist|dust|chunk|splinter|shard|leaf|spark, count, cone°, speed [min,max], size [min,max] m, life [min,max] s, color, drag, gravity, collision stick|bounce|die, ... }), or "shot": while playing, a real bullet from `from` (default the camera) at `at` (an object; `limb` head/chest/belly/pelvis/thigh.L... aims at that limb) or `point`, with its holes, debris, blood, stains, drips and pools. Outside Play the particles show in the editor (no stains). `camera` {from, at, fov} while playing sets a watching camera first; `time_scale` slows the game (0.1: a tenth of real time) for close looks and slow-motion shots. report: true lists what blood and impacts made so far and the GPU particle window.
| Argument | Type | What it does |
|---|---|---|
at | string | An object: its position (shot: its limb, else its middle). |
burst | object | kind burst: the burst's values. |
camera | object | While playing: {from: [x,y,z], at: [x,y,z], fov: degrees} watching camera (from: [] lets go). |
damage | number | shot: damage (default 34). |
direction | list of number | Which way the bullet or spray travels. |
from | list of number | shot: where the bullet starts (default the camera). |
head | boolean | blood: a head wound's bigger, darker spray. |
kind | string | blood, concrete, plaster, stone, wood, dirt, leaves, metal, glass, burst or shot. |
limb | string | shot at a character: head, chest, belly, pelvis, upperarm.L, thigh.R... |
look | string | blood: human (default) or zombie. |
normal | list of number | The surface's normal there (default up). |
point | list of number | Where (world [x, y, z]). |
report | boolean | Also report the blood and impact counts and the GPU particle window. |
seed | integer | |
speed | number | Bullet speed m/s (default 880). |
through | boolean | blood: an exit spray along direction (default true). |
time_scale | number | While playing: slow motion for the whole game (0.05...1; 1 real time), for close looks. |
glass
Real glass on any object's see-through materials (windows, windscreens, bottles, lenses, visors): it bends what's behind (index of refraction, thickness: a thick lens magnifies, drops each hold a tiny upside-down world), blurs it by roughness and frost, tints it by absorption over the distance inside (green bottle edges), reflects the room and sky (Fresnel: a mirror at grazing angles) and tints the sunlight through it. Layers: rain beads, running drops with wet trails, condensation (wiped by the drops), frost growing in, smudges, fingerprints, dust, old-glass waviness. Pick a preset (bottle_clear, bottle_green, car_glass, clear, frosted, ice, lens, old_window, prism, rain_window, steamy, window) and/or set values; values you leave out keep their current setting. weather: true also wets it with the scene's rain (camera_look rain). Rain on glass is live by default: drops land, grow, merge, run down under gravity when parked and blow back and up the glass with the airflow as the object moves (airspeed stages a speed for stills). One undoable step. explain: true lists the object's glass materials (ior, thickness, absorption) and its current layers, changing nothing. clear: true removes the layers. Animate frost or rain over time with a sequence or script (glass.frost).
| Argument | Type | What it does |
|---|---|---|
absorption | list of number | sRGB colour light turns after absorption_distance metres inside. |
absorption_distance | number | Metres (0 = the material's). |
airflow | number | How exposed the glass is to the airflow when the object moves (1 open air, 0 sheltered). |
airspeed | number | Air speed over the glass in m/s for staging shots (-1 measures the object's motion and the wind; 150 m/s = 300 kt, 257 = 500 kt). |
clarity | number | Share of light let through (0 = the material's transmission); fixes glass forged too opaque. |
clear | boolean | |
condensation | number | Fog of fine droplets; running drops wipe lines through it. |
dirt | number | Dust film. |
dispersion | number | Colours splitting at thick glass and drops (rainbow edges). |
drop_size | number | Size of the drops the rain leaves (1 natural beads; 0.5 drizzle, 2 storm drops). |
entity required | string | An existing object name or #id whose model has glass (a material with transmission above 0). |
explain | boolean | |
fingerprints | number | Fingerprints. |
frost | number | Ice ferns growing in (1 covers the pane). |
ior | number | Index of refraction (0 = the material's): 1.5 glass, 1.33 water. |
live | boolean | Live drops (default true): rain simulated on the glass, landing, merging, running down under gravity or blown back by the airflow as the object moves, leaving wet trails. false: the fixed bead pattern. |
preset | bottle_clear / bottle_green / car_glass / clear / frosted / ice / lens / old_window … | A starting look; the values you pass go on top. |
rain | number | Beading drops sitting on the glass. |
refraction | number | Bending: -1 automatic (thin walls 0.3, solid optical glass 1), 1 physical, 0 none. |
seed | number | Another pattern of drops, prints and frost. |
smudges | number | Greasy smears. |
streaks | number | Drops running down and their wet trails. |
thickness | number | Metres (-1 = the material's): 0 thin pane, 0.004 bottle wall, 0.015 and up a solid piece (lens, block). |
waviness | number | Old hand-made glass ripples. |
weather | boolean | Also wet by the scene's rain (outdoor glass). |
input_actions
A game's named controls (jump, interact, attack, reload...): list them with their keys, mouse and controller buttons and any controller button on two actions; set one {id, key, pad: ["x"], label} (a declared controller button moves off the engine action that had it); remove one of the game's own. Scripts read them with input.action("attack") / pressed / prompt. The person has the same in the Input panel; players rebind them on the game's Controls screen. Changes only the controls in UI/game.json.
| Argument | Type | What it does |
|---|---|---|
remove | string | The id of one of the game's own actions. |
scene | string | A scene with its own UI layout (default: the game's). |
set | object |
inventory
In Play: an object's inventory (default the player): its slots, wallet, weight and room; with "give" ({item: count}, negative takes) or "do" (move, split, sort, take, loot) it changes them first, as the game's own calls do (inventory_changed goes to scripts). Objects without an inventory component show their plain item counts.
| Argument | Type | What it does |
|---|---|---|
count | integer | |
do | move / split / sort / take / loot | One change: move {from, to, count}, split {slot, count}, sort {order}, take {slot, count}, loot {table, seed}. |
entity | string | In Play: an object's name or id ("#7"); default the player. |
from | integer | |
give | object | {"coin": 20, "berry": -3} |
order | kind / name / tag / value | |
seed | integer | |
slot | integer | |
table | string | |
to | integer |
items_define
Make or change a project's items, loot tables, recipes and shops (Block 2: every game's items): writes Assets/Items/<id>.item.json (.loot / .recipe / .shop), one file each, after checking it. Items: {name, description, icon, model, stack, tags, value, weight, use, consumed, data, equip}; "currency" in tags puts it in the wallet. Loot: {rolls: [1, 2], nothing, entries: [{item | table, weight, count: [1, 3], chance, always}]}. Recipes: {name, inputs: [{item, count}], outputs: [...], station: ["kitchen"], time, known, tags}. Shops: {name, currency, markup, sell_rate, buys: [tags or "*"], stock: [{item, count (-1 endless), price}], restock: "day" | seconds | "never", money}. Several at once: "entries": [{kind, id, definition}]. A live game reloads them.
| Argument | Type | What it does |
|---|---|---|
definition | object | The item / table / recipe / shop (see the summary). |
entries | list of object | Several: [{kind, id, definition}]. |
id | string | Lowercase letters, digits, underscores: the file's name. |
kind | item / loot / recipe / shop | item (default), loot, recipe or shop. |
remove | boolean | Delete that file instead (moved to the project's .trash). |
kit_playbook core
A game kit's playbook: how to build that kind of game in this engine, step by step (scene templates, feel settings, level patterns, how the bot proves a level, the look, and art in three tiers). Kits: 2d-platformer, enemy-brains, topdown-zombies, kart-racer, escape-puzzle, game-ui, survival-horror, arena-shooter, 2d-paper-forge, builder, story, character-creator, items, retarget, combat, animation, tactics, strategy, roguelike, survival, towers, fighting, rhythm, progression, physics-joints, sports, board, fix-tools, online, collect, endless, platformer, stealth, hands, caving, abilities, cameras, extraction.
| Argument | Type | What it does |
|---|---|---|
kit required | 2d-platformer / enemy-brains / topdown-zombies / kart-racer / escape-puzzle / game-ui / survival-horror / arena-shooter … |
law
Crime and the law in play (WantedSystem): read the wanted level (0-5 stars), the police units out, crimes seen, and how long the player has gone unseen; `set` a level outright (0 clears it). Police come only with road_network police > 0 and cars tagged police_template; crimes count when a pedestrian (40 m) or a unit (90 m) sees them; staying unseen long enough clears the level; stopping beside a unit for 3 s is busted.
| Argument | Type | What it does |
|---|---|---|
set | integer | Wanted level to set, 0-5. |
loot_roll
Roll a loot table from the project's files many times (no game needed) and see what it gives: each item's share of rolls, its average and most per roll, and how often a roll gives nothing. The same seed always gives the same rolls, as in the game.
| Argument | Type | What it does |
|---|---|---|
seed | integer | Default 1. |
table required | string | |
times | integer | Default 1000. |
magnet
While playing (play_mode): lifting electromagnets (they pull loose metal to their face, a joint holds what reaches it, off drops it). With no arguments: each magnet (on, how many it holds, strength, reach), what is being pulled now, grips and drops so far. `make` {name, strength (N at the face, default 30000), reach (m, 1.6), grip (m, 0.08), radius (m), most, face [x, y, z], normal [x, y, z] (its own frame; default the origin, facing down)} makes a body a magnet. `on` {name, on} switches it. `view` {on}: lines from each face to what it pulls (orange, brighter the harder) and holds (white).
| Argument | Type | What it does |
|---|---|---|
make | object | {name, strength, reach, grip, radius, most, face, normal}. |
on | object | {name, on}: switch a magnet. |
view | object | {on}: the pull view. |
make_pickup
Make an object something the first-person hands pick up and look at (a note to read, a photo, a card, a key, a small thing): within reach, E: the free hand comes in open, settles onto it and closes on it, lifts it into view turning it square to the eyes, and holds it there breathing a little while it's read (right mouse brings it closer); E again puts it in the pocket or lays it back where it lay. Installs the hands kit (kits/inspect.js, kits/torch_hands.js) when the project hasn't got it, and works out how it's held from the object's own shape: its <model>.sockets.json grip socket when it has one, else its thin side faces the eyes, its long side runs up and the hand takes it by its left edge. Re-run to change anything: what isn't given is kept. The player needs first-person hands (a character with view "first_person" holding something one-handed, e.g. kits/torch_hands.js on it). Engine pieces underneath, also usable directly: game.offhand({at, fingers, palm, grip, grip_amount}) for the hand, attach { facing "eye" grip_at "pinch" face_blend } for an item held up to the eyes.
| Argument | Type | What it does |
|---|---|---|
entity required | string | Entity name (e.g. "Lab_Note_OpLog") or id (e.g. "#7"). |
grip | string | A finger preset over the kind's (grip_presets lists them: sheet, pinch, cup, wrap...). |
hold | list of number | The wrist while it's read: right, up, ahead of the eye (m; default -0.07, -0.03, 0.36). |
item | string | Inventory name when kept: game.state.item_<name> becomes true. |
keep | boolean | Into the pocket (true, the default) or put back where it lay (false). |
kind | auto / note / photo / card / key / small | What it is: note/photo/card are sheets held by their edge (grip sheet); key/small things are pinched (grip pinch). Default auto: thin and flat is a sheet. |
objective | string | An objective set the first time it's read. |
raise | number | Seconds to lift it to the eyes (default 0.6). |
range | number | How near it can be taken from (m, default 1.8). |
reach | number | Seconds for the hand to reach it (default 0.55; more when the player kneels). |
sends | string | Sent the first time it's read: "Object:message, ...". |
text | string | Read along at the bottom while it's held ("|" starts a new line); empty: what's printed on it is what's read. |
title | string | Its name (shown when it's kept). |
make_vehicle
Good for realistic cars, trucks, karts and bikes from a preset, and for real dynamics on any vehicle root. Weak for a cartoon or stylised vehicle (its preset bodies are realistic, a kart is a flat go-kart): for those, try forge_model per part, then assemble_vehicle. Create an original parametric wheeled vehicle or enable real dynamics on an existing vehicle root without replacing its art. Seven presets, per-wheel suspension/tyres, gearbox, assists, damage and cameras.
| Argument | Type | What it does |
|---|---|---|
ai | none / racing / traffic | |
name | string | |
object | string | |
paint | list of number | |
position | list of number | |
preset | sports / sedan / suv / pickup / truck / kart / motorbike | |
tuning | object | |
yaw | number |
missions
The game's missions (Missions/<id>.mission.json in the project: id, title, after [ids], giver {at [x, z], radius, label}, intro [lines], steps, fail rules, reward {money}). Without Play: check the files against the scene. In Play: what's open, what's being played and its step, money; `start` an open mission by id where the player stands (`force` for a passed or locked one); `reload` the files after editing them. Steps (do): goto / drive_to (at, radius), enter_vehicle (vehicle: a scene object's name, or any), wait (seconds), lose_wanted, wanted (level), say (lines); each takes text (the objective line), lines [{speaker, text, voice, seconds}] and time_limit. Fail rules (if): vehicle_destroyed (vehicle), wanted (level), out_of_vehicle (vehicle).
| Argument | Type | What it does |
|---|---|---|
force | boolean | Start it even if passed (no reward again) or not yet open. |
reload | boolean | |
start | string | Mission id to start now (one open to play). |
nav_crossings
While playing: the doorways and windows NPCs can cross for a body of `radius` (default 0.4, a zombie's). For each window: its centre, width, sill, boards still nailed, and its two standing points on the walking map (or why a side has none). Then the door crossings, and the shared route fields the horde is growing now (their goal, how far they have grown, whether each crossing's standing points are on the field and reached). Use it when zombies stand outside a boarded house with "no route".
| Argument | Type | What it does |
|---|---|---|
radius | number |
nav_probe
While playing: walk the NPC walking map along a straight line from `from` to `to` (world [x, y, z]) for a body of `radius` (default 0.4, a zombie's): the floor heights at every 10 cm where they change, and where there is no floor, which supports are there and which objects fill the body's footprint; then whether the straight walk connects. Use it when NPCs report "no route" or stop at a doorway.
| Argument | Type | What it does |
|---|---|---|
from required | list of number | |
radius | number | |
to required | list of number |
quests
In Play: the game's quests (QuestBook) — each quest's state (locked, open, active, done, failed), objectives with progress, journal lines and which one the HUD tracks. `start` a quest (`force` a locked or finished one), `advance` an objective (`objective`, `count`), `complete`, `fail`, `track` one on the HUD, `reload` the files after editing. Same as scripts' game.quests.
| Argument | Type | What it does |
|---|---|---|
advance | string | Quest id whose objective moves on. |
complete | string | |
count | integer | |
fail | string | |
force | boolean | |
objective | string | |
reload | boolean | |
start | string | |
track | string |
reload_author
Author a weapon hold's reload as keys, from the gun's own parts and the body: the support hand to the magazine (gripped as Grab & Hold solves it round the magazine), the magazine pulled and let fall, the hand to a pouch on the belt for a fresh one, up into the well and seated, then onto the charging handle (rifle) or over the slide (pistol) and pulled back, and back to its hold; the gun canted and brought in while it happens. style rifle or pistol (default from the set), seconds (the whole reload). Goes into the hold being edited (rig_edit_weapon_hold first; rig_save_weapon_hold writes it); reload_preview shows any moment, reload_check finds the hand in the gun.
| Argument | Type | What it does |
|---|---|---|
entity required | string | The character (name or #id) whose weapon hold is being edited. |
pouch_cm | list of number | The magazine pouch from the waist, cm: [left, up, forward] (default [15, -3, 8]). |
seconds | number | |
still | boolean | Return a picture of the viewport with the rig (default true). |
style | rifle / pistol / launcher |
reload_key
Change one key of a keyed reload (key: its name or number): move_cm [left, up, front] in the gun's frame (or the body's, for a pouch key), turn_deg [x, y, z] about the wrist (the gun's axes), t (its moment), mag (well, hand, drop, out), charge (0...1), gun [pitch, yaw, roll, back, up, right]; capture true takes the support hand (wrist, elbow, fingers) as it is drawn now, after placing it with hold, hold_finger or rig_move.
| Argument | Type | What it does |
|---|---|---|
add | string | Add a new key with this name: a copy of `key`, halfway to the next (or at t). |
capture | boolean | |
charge | number | |
entity required | string | The character (name or #id) whose weapon hold is being edited. |
fingers | open / hold | |
gun | list of number | |
key required | string | |
mag | well / hand / drop / out | |
move_cm | list of number | |
still | boolean | Return a picture of the viewport with the rig (default true). |
t | number | |
turn_deg | list of number |
reload_preview
Show a weapon hold's keyed reload on the character: t (0...1 through it) holds that moment; play true plays it through over its seconds (or `seconds`) and leaves the character back on its hold. Outside Play.
| Argument | Type | What it does |
|---|---|---|
entity required | string | The character (name or #id) whose weapon hold is being edited. |
play | boolean | |
seconds | number | |
still | boolean | Return a picture of the viewport with the rig (default true). |
t | number |
reload_shaders
Recompile the renderer's shaders from source and swap them in live (seconds; the game keeps running). folder: a Shaders folder to read (default: the editor's own resource bundle). If they don't compile the running shaders stay and the compiler's errors are returned.
| Argument | Type | What it does |
|---|---|---|
folder | string | A folder holding Scene.metal and its companions (default: the bundle's Shaders). |
script_reference core
The gameplay scripting API: events, entity properties and methods, and globals; the cutscene format; and the cinematic sequence format. query: only the lines about a word ("music", "game.saves"), far shorter than the whole 60 KB.
| Argument | Type | What it does |
|---|---|---|
query | string | Only the lines that mention this word or phrase, with the line before and after. Leave out for the whole reference. |
shop_trade
In Play: a shop's goods, prices, stock left and what it pays for the trader's things (default trader the player); with "buy" or "sell" ({item, count}) it trades as the shop screen would, all or nothing, with the reason when not. "new_day": move the game's day on (shops restocking by day restock).
| Argument | Type | What it does |
|---|---|---|
buy | object | {item, count} |
entity | string | In Play: an object's name or id ("#7"); default the player. |
new_day | boolean | |
sell | object | {item, count} |
shop required | string |
spawn_flock
Add a flock of birds: count, species sparrow/gull, position, optional half_extents and perch surface. Native flapping/gliding, flocking and swept obstacle clearance. Optional approach/landing folds the wings and places feet on a stationary horizontal collider. One shared Forge mesh, editable spec and undoable scene change. Aggregate scene authoring limit: 1000 creatures, including passive dogs; over-capacity requests are refused before writing assets or entities.
| Argument | Type | What it does |
|---|---|---|
count required | integer | |
group | string | Optional schooling/flocking group; omitted makes a separate group. |
half_extents | list of number | |
name | string | Name of this creature or group. Existing entities are preserved. |
perch | string | Birds: optional named, stationary, horizontal box collider to land on. All landing slots must fit its top inside the habitat. |
perch_after | number | |
position required | list of number | |
spec | object | A saved .creature.json (camelCase) or compact blueprint overrides: species, name, family, spine_length, spine_segments, body_segments, appendages (or limbs/fins/wings/tail), color, belly, speed, cadence, radial_sides. Body sections: {at,width,top,bottom,center}. Appendages: {name,kind,attach,points:[[x,y,z],...],radii:[],rootChord,tipChord,parent:null}. Dimensions are fractions of spine_length; +Y up, +Z nose. At=0 nose, at=1 rump. Chains must precede parts parented to them. |
species | minnow / bass / shark / sparrow / gull / dog | minnow, bass, shark, sparrow, gull or dog. |
water | string | Exact ocean, lake, pond or pool entity name (required for fish); habitat is clipped below its surface (an ocean: its lowest wave trough). |
spawn_school
Add a school of fish here: count (e.g. 30), species minnow/bass/shark, position and water (an ocean, lake, pond or pool). Native travelling swim wave, bending turns, schooling and swept obstacle/creature clearance; stays inside the finite water habitat. One shared, editable-spec Forge mesh and one undoable scene change. Fails without enough clear water. No external generator. Aggregate scene authoring limit: 1000 creatures, including passive dogs; over-capacity requests are refused before writing assets or entities.
| Argument | Type | What it does |
|---|---|---|
count required | integer | |
group | string | Optional schooling/flocking group; omitted makes a separate group. |
half_extents | list of number | |
name | string | Name of this creature or group. Existing entities are preserved. |
perch | string | Birds: optional named, stationary, horizontal box collider to land on. All landing slots must fit its top inside the habitat. |
perch_after | number | |
position required | list of number | |
spec | object | A saved .creature.json (camelCase) or compact blueprint overrides: species, name, family, spine_length, spine_segments, body_segments, appendages (or limbs/fins/wings/tail), color, belly, speed, cadence, radial_sides. Body sections: {at,width,top,bottom,center}. Appendages: {name,kind,attach,points:[[x,y,z],...],radii:[],rootChord,tipChord,parent:null}. Dimensions are fractions of spine_length; +Y up, +Z nose. At=0 nose, at=1 rump. Chains must precede parts parented to them. |
species | minnow / bass / shark / sparrow / gull / dog | minnow, bass, shark, sparrow, gull or dog. |
water | string | Exact ocean, lake, pond or pool entity name (required for fish); habitat is clipped below its surface (an ocean: its lowest wave trough). |
sports_physics
While playing (play_mode): a body's sports physics. `name` reads it: velocity, spin (rad/s and rpm), speed, drag, lift (Magnus), rolling, fast (swept for collisions whatever its speed), friction, restitution. `set` {velocity: [x, y, z] m/s, spin: [x, y, z] rad/s, drag (a baseball 0.35, a golf ball 0.25), lift (1 a baseball's), rolling, surface, fast} sets what's given (a pitch: velocity and spin). `surfaces`: true lists the surfaces a collider can name (grip, bounce, roll and how each combines). The air's density: `air` (kg/m³; 1.225 at sea level, 0 none).
| Argument | Type | What it does |
|---|---|---|
air | number | The air's density, kg/m³. |
name | string | The body's object. |
set | object | {velocity, spin, drag, lift, rolling, surface, fast}. |
surfaces | boolean | List the surfaces. |
start_game core
Start a new game scene ready to build on: ground, boundary walls, a player character with animations (and an armed first-person setup for shooters), game rules, and a look. Then follow builder_guide.
| Argument | Type | What it does |
|---|---|---|
genre | shooter / stealth / exploration / platformer / horror / survival / melee / rpg … | Default shooter. Each genre installs its kits and names its playbook (find_tools with the genre gives the recipe). |
look | string | apply_look preset (default bodycam for first-person shooters, cinematic otherwise). |
name required | string | Scene name (letters, digits, _). |
player | string | Rigged character model for the player (default Characters/Officer.glb if present). |
request | string | The person's request in their words: the style is read from it when style isn't given. |
size | number | Play area width in meters (default 60). |
style | realistic / stylized / toy / 2d | The game's one art style, kept by every asset (recorded in the Game Plan). Default: read from request, else realistic (the highest-quality look). |
view | first_person / third_person |
traversal
3D traversal moves for a character (engine moves, not scripts). action add_ladder: a ladder against a wall (at [x,y,z] on the floor, facing the way you climb from (degrees), height in m; model to use your own ladder model, else one is forged to fit) tagged traverse:ladder: walk into its front to get on, forward/back climbs, the top steps off onto the landing, the bottom onto the ground, jump lets go. Any object can be a ladder: tag it traverse:ladder (its front is its +Z). action setup: a character's numbers (ladder_speed, climb_speed for climbing any steep surface, ledge_grab: jump or fall past a top edge pushing toward it and the hands catch it; left/right shimmy, forward or jump pulls up, back lets go; wall_run_time: jump along a wall while running fast with forward held and run along it, jump kicks off). action check: what a character can reach (each ladder, its top landing clear or not). action play: drives the real controls in a private copy toward a ladder and up it (or inputs [{t, move:[x, z], jump}] of your own) and returns the timeline (on the ladder at, top at, off at). The animator's state machine gets params on_ladder, climb_dir, climb_pace, climbing, hanging, shimmy, pull_up, wall_running, wall_side, grappling, swinging, ziplining, in_cover, peeking, cover_side (anim_graph preset traversal); with no clip of its own, the move plays a pose solved on the rig. kit_playbook animation, section traversal. HTTP calls return a job_id immediately; read progress and the final result with tool_job instead of repeating the tool.
| Argument | Type | What it does |
|---|---|---|
action required | add_ladder / add_zipline / mark / setup / check / play | |
at | list of number | add_ladder: the ladder's foot, middle of its front, on the floor [x, y, z]. |
climb_speed | number | |
cover | boolean | setup: player cover: V (or the game's "cover" action) against a wall takes cover; slide, peek by aiming. |
entity | string | The character (setup, check, play). |
facing | number | add_ladder: degrees the ladder's front faces (the way a climber stands to climb it; 0 = +Z). |
from | list of number | add_zipline: the cable's high end [x, y, z]. |
grapple_any | boolean | |
grapple_pull | number | |
grapple_range | number | |
height | number | add_ladder: metres from the floor to the landing (optional: it is measured, the walkable surface just behind the ladder's top; a height that doesn't meet one is corrected to it). |
inputs | list of object | play: [{"t": 0, "move": [0, 1]}, {"t": 3, "jump": true}] (move [right, forward]), or play_test's controls ({from, to, move, look, keys, aim, sprint}: a cover press, a grapple, a peek); default walks to the ladder and climbs it to the top. |
kind | ladder / grapple / zipline / no_ledge / no_wallrun | mark: what the object (entity) becomes: traverse:<kind>. |
ladder | string | play: the ladder to go for (default the nearest). |
ladder_speed | number | |
ledge_grab | boolean | setup: ledges: jumping or falling past a top edge pushing toward it, the hands catch it (hang, shimmy, pull up). |
model | string | add_ladder: your own ladder model (mesh ref) instead of a forged one; scaled to the height. |
name | string | add_ladder: the new object's name (default Ladder_N). |
seconds | number | |
to | list of number | add_zipline: its low end [x, y, z]. |
trace | boolean | play: a line every quarter second: where it is, its move, and what it reads (the cover wall ahead and its height, the grapple points near and the one in sight, a game freeze). |
wall_run_time | number | setup: wall running: seconds a run along a wall lasts (jump along a wall while running fast, forward held; jump kicks off). 0: off. |
width | number | add_ladder: rail to rail (default 0.5). |
zip_speed | number |
tune_vehicle
Validate and undoably edit vehicle numbers and assists. While playing it applies live to the running car (grip, power, tyres, suspension, assists, steering feel at once; a chassis change rebuilds the car in place, keeping its speed), so you can drive and feel each change. Preserves mesh assets.
| Argument | Type | What it does |
|---|---|---|
object required | string | |
tuning required | object |
vehicle_budget
The city's car budget, read or tuned live in Play: the player's car always gets shadowed head-lamp beams and the full combined-slip tyre model; the nearest few others get beams (no shadows) and the full model; cars out to a radius run a reduced model (fewer substeps); the rest run the cheap far model and show lamp glow only. Reports how many cars sit at each level. Use it with frame_profile to measure what traffic costs.
| Argument | Type | What it does |
|---|---|---|
beams | integer | Cars besides the player's with real beams (default 6). |
full | integer | Cars besides the player's on the full tyre model (default 6). |
reduced_radius | number | Metres out to which the rest run the reduced model (default 120). |
vehicle_lights
A driving car's lamps and exhaust (Play mode): switch the head lamps auto (on when the sun is low), on, off or high beam, work the indicators or hazards, and read what the car shows now: head lamps, brake and reverse lamps, the cold-start plume, exhaust load (heat haze), lift-off puffs and pops. The car's parts tagged vehicle_lamp_* and vehicle_exhaust do the showing (assemble_vehicle makes them); their authored light, glow, haze and particles are full strength.
| Argument | Type | What it does |
|---|---|---|
indicator | left / right / hazards / off | Indicators. |
mode | auto / on / off / high | Head lamps: auto (default; on when the sun is below 4 degrees), on, off, high (high beam). |
object | string | The car (default: the first driving car with lamps). |
vehicle_telemetry
Read a car the way a racing engineer does while it drives (Play mode): samples speed, g-forces and every wheel's slip angle, slip ratio and load for a few seconds, then reports the grip used (lateral, braking, accelerating, combined: the g-g envelope), the balance in corners (front against rear slip angle: understeer, oversteer or balanced), load transfer (the front's share at rest, braking, accelerating), how often ABS and traction control step in, time with a wheel in the air, and a g-g plot coloured by speed. Drive (or let the AI drive) through corners while it records; compare runs before and after a tune.
| Argument | Type | What it does |
|---|---|---|
interval | number | Seconds between samples (default 0.05). |
object | string | The car to read (default: the first car driving). |
overlay | boolean | Show (true) or hide the live telemetry panel in the viewport (g-g circle and trail, tyres coloured by slide with load bars, ABS/TC, speed, gear, rpm). Alone it only switches the panel. |
seconds | number | How long to record (default 6, max 60). |
write_script core
Create or replace a gameplay script (JavaScript), or a kit's data file (Scripts/data/*.json), in the project's Scripts folder. It is syntax-checked first; errors come back with the line. Attach it with a script { file "name.js" } component.
| Argument | Type | What it does |
|---|---|---|
code required | string | JavaScript defining any of onStart(self), onTick(self, dt), onEnter(self, other), onExit(self, other), onMessage(self, name, data). See script_reference. |
file required | string | e.g. "door.js", "enemies/guard.js" or "data/waves.json" |