Worlds

analyze_scene_performance

EXECUTES the Creator CLI scene performance analyzer and returns its report to the agent. Call after the first build or imported Scene exists, then again with final snapshot/Package/runtime evidence. It runs canonical Scene/Package validation, and unresolved non-bundle resources keep affected checks unknown. It separates authored mesh-definition triangles from runtime submitted triangles; file-local/slot/unique/source/native/Package/observed Palette materials; declared/GPU texture costs; owned/transitive/cold/warm delivery; and static estimated reference-budget utilization from supplied runtime claims. Runtime proof records compile/stream/GI readiness, grounded route, occupancy, frame count/duration, bundle/dirty-code identity, canvas/DPR, and internal compositor resolution separately. Unknown metrics stay unknown and never improve the result. Read scene-performance for the interpretation and matched visual-QA workflow.

bake_world_lighting

Bake a world's lighting field from its BUILT bundle and point its visual contract at the artifact (same code path as helix bake-lighting): serves the build headlessly, drives the in-page bake driver across sun keyframes plus the practical lights, audits and repairs the probe field, then writes helix.visuals.bake.json and patches helix.visuals.json to mode "baked" in BOTH the source public/ and the built root. USE IT FOR a bounded, static-geometry world whose visual contract declares — or should declare — mode "baked": interiors, arenas, dioramas, anything whose geometry and lights do not move. A BOUNDED INTERIOR authors probes: { center, size } in helix.visuals.json to fit the bake volume to its room BEFORE baking — the default volume is sized for open ground, and the bake warns when its volume does not fit the play space (heed that warning by authoring the block and re-baking); an authored center also pins the still-dynamic world's runtime volume to the same box, so author the block at build time, not bake time. Run it AFTER npm run build, on the built world, never on an unbuilt source tree, and expect MINUTES of blocking GPU work (a small world is a minute or two — do not interrupt it, and do not call it in a loop). NOTHING IT WRITES SHIPS until the world is re-validated and re-published: build → bake_world_lighting → validate_world → publish_world, and re-bake whenever the geometry, the lights, or any TRANSPORT knob in helix.visuals.json changes (sun, sky, environment, shadows, probes — the bake photographs all of them). LEAVE keys ALONE unless you know better: omitted, the engine plans them — ONE key for a static sun (timeOfDay.cycleSeconds 0), 9 for a cycle — and the pointer it writes records the count as bakedLighting.keys, which validate_world re-checks against the world clock. Pass gpu: true to bake on the machine GPU through a system Chrome/Edge when the wait hurts (measured 41 s against 27 minutes on a 45 MiB world); it is not bit-reproducible across machines, so the software renderer stays the default. It fails loudly rather than write a wrong artifact — an unbuilt world, a world that never publishes the bake handle (nothing called createVisualRuntime, so it is not runtime-lit and has no probe field), a boot slower than timeoutSeconds, or the donor-occlusion gate — and the failure text leads with the page errors, which are the diagnosis. It never installs a browser: a launch failure relays the install instructions for the human. The decision tree (baked vs dynamic vs the opt-out) and the full helix.visuals.json reference: read_doc({name:"lighting-world"}).

capture_world_screenshot

Capture headless screenshots of a built world via its in-page screenshot helper (Playwright, in-process — same code path as the helix screenshot CLI command). Returns a compact preview image per capture PLUS a text block listing every file written. LOOK at the returned image(s) and judge the framing before attaching one with set_world_thumbnail. FOR PLACEMENT QUESTIONS USE inspect_world, NOT this tool — do not answer "is it floating / how far apart / does it fit" by looking harder; distances and depth read from an image are measurably unreliable. This is the CLOSING check for how the scene reads (framing, materials, lighting, mood), after the numbers are already right. Prefer a declared shot (world code calls screenshots.register — read_doc "screenshots") over the camera/lookAt/fov override or blindMs, both non-deterministic fallbacks.

clear_world_thumbnail

RETURNS A COMMAND, NOT DATA. This tool hands you a helix … command string to RUN yourself — it executes nothing and returns no results. The answer is in that command’s output. Revert a world thumbnail/preview slot to the auto-generated placeholder.

create_world

Mint a world's IDENTITY — the row, as a Draft with no build — so products and achievements can be registered BEFORE the first publish. Both registries live outside the bundle and hang off a world id, so on a brand-new project register_world_product and register_achievement fail with "No world of yours has the slug ..." until this has run; publishing is what adds a build, not what creates the world. Idempotent for a slug you already own — the existing world is reported and nothing is sent; a slug someone else owns is refused by the backend. The slug is globally unique and permanent, so choose it once.

inspect_world

Measure the layout of a built world as DATA (same code path as helix world inspect): boots it headlessly, snapshots the scene graph — world positions, extents, oriented boxes, visibility, physics colliders — and runs placement checks: floating/sunk/intersecting geometry, collider-vs-visual divergence (including the classic half-extent/full-size slip), mirrored or degenerate transforms, stray coordinates. THE INNER LOOP FOR PLACEMENT: measure here until the numbers are right (this answers "is the bench 0.4 m in the air" exactly — a screenshot measurably cannot), then capture_world_screenshot ONCE before handing to a human. FINDINGS ARE MEASUREMENTS, NOT VERDICTS: check each against your intent. Hovering pickups, ramps embedded in the ground, and walls overlapping at their corners all warn on perfectly good worlds — a warn that matches what you meant needs no fix; a warn that surprises you is the bug. NEVER edit geometry just to silence a finding. WHAT IT CANNOT ANSWER: whether the scene READS as intended — materials, lighting mood, animation, art direction — that is the closing screenshot check. Requires the world to integrate @helix/engine-core/inspect (one line at end of boot: world.ready({ scene, body, spawn }) — read_doc "world-inspect"; the scaffold recipe shows the wiring). EXISTING worlds scaffolded before this integration usually lack the call — check_for_updates({ projectDir }) reports the wiring state up front, cheaper than a 60s timeout. DENSE HAND-BUILT worlds warn a lot on intended decor (hanging lights read as floating): uniform same-parent runs collapse to one line automatically, and after you adjudicate, writeBaseline persists the verdict so later inspects report only what CHANGED. Object paths are canonicalized (content order) — stable across runs; coordinates remain the strongest cross-run handle.

list_abilities

List the abilities published on HELIX Instant (e.g. fly, swim). Abilities plug into a system; optionally filter by the host system id. Returns slug@version + title + target system.

list_achievements

List a world's registered achievements. Run it BEFORE publishing multiplayer rules to confirm every key an awardAchievement effect names actually exists — publish cannot check the registry, and a missing key fails silently at runtime.

list_my_worlds

List the worlds owned by the logged-in creator (including drafts), with their slugs and build state.

No arguments.

list_templates

List the available multiplayer world TEMPLATES — complete, publish-shaped worked worlds, one per capability cluster (presence, server/owned/shared/physics entities, collections, state machine, time, checkpoints, teams, voice channels). After get_started({kind:"multiplayer"}), pick the closest and read it with read_template({name}).

No arguments.

list_world_products

List what a world sells: each registered product, the pkey:<key> world code buys it by, its price and whether it is still on sale. Run it BEFORE writing purchase code to confirm the key you are about to name exists — an unregistered key fails only at runtime, as ProductNotFound. Omit worldSlug for every PUBLISHED world of the creator's and its registry (that route lists Published worlds only, so name the slug to see a draft world's).

placements_bake

Bake deterministic instanced placements on authored terrain from a helix.placements-source/1 JSON file: solid records placed exactly, decorative records scattered by rule. The CLI validates prepared prototype LOD/texture closure, masks and stable solid placements, then writes placements.json and pinned binary regions. Local authoring only; this does not publish. Read the terrain recipe first.

placements_inspect

Validate a baked placements folder and report prototype LODs, texture families, stable solid counts, region bytes and format caps. Read-only. Run after every bake and before scene publication; inspect runtime residency and visual passes as well.

publish_unreal_world

Publish a COOKED UNREAL world to HELIX and make it the world's active build. Takes the candidate directory the Unreal HelixWorldPublish commandlet writes (it contains world-build-manifest.json, its .sha256 receipt, cook-plan.json, and artifacts/<role>/…) — NOT an Unreal project directory, and NOT a web bundle. Verifies the candidate against the bytes on disk, registers the Build, uploads every artifact, has the server re-verify and countersign it, then promotes it. This is the ONLY way a cooked Unreal world reaches HELIX. Requires login (check whoami first) and the world must already exist (create_world). YOU CANNOT COOK FROM HERE: cooking is an Unreal Editor / commandlet step on a Windows machine with UE 5.8 — if there is no candidate directory yet, say so and stop rather than looking for one to invent. Web worlds use publish_world instead; the two are not interchangeable.

publish_world

Publish a validated world bundle to HELIX Instant. Refuses a World whose engine systems are pinned to an exact version (use ^ ranges; there is no agent override — only the human can run the CLI with --allow-exact-engine-pin "<reason>"). Automatically captures a ready world thumbnail unless a custom cover is already selected, uploads it with the files, and activates the Build and cover together; returns the public play URL. Capture failure refuses publication. Requires login (check whoami first). Re-publishing the same slug creates the next build of that world.

read_template

Read a complete, publish-shaped multiplayer world template: its DSL checklist, the full public/helix.json (incl. the multiplayer block), the client src/main.ts delta, and build/publish steps. Pick the name from the hub (get_started multiplayer) or list_templates — e.g. "hangout".

register_achievement

Register an achievement on one of the creator's worlds — the registry a world's badges live in, which is NOT part of helix.json and cannot be declared in the bundle. REGISTER BEFORE PUBLISHING the rule that awards it: awardAchievement with an unregistered key publishes clean and is a silent runtime no-op, the single most common authoring trap. Needs a 2D icon file (required — an achievement always has a graphic; generate one with generate_image if the human has no art, and note that a blank or sub-16px placeholder is refused). Leave unlockMode alone for a badge a room rule awards (the default); declare signal + value instead for a criteria badge the backend measures with no room at all. Pass dryRun to validate everything locally — no network, works logged out. TEST THE UNLOCK FIRST: the same row seeds .helix/dev-achievements.json for helix dev, where a criteria badge unlocks off simulated evidence as you play — the seed uses the STORED nested shape (criteria: { signal, op, value, key, field, metric }; this tool flattens key/field into criteriaKey/criteriaField because key is already the badge slug) and needs no icon. Registration takes effect immediately, live worlds included — no republish; the backfill pass credits players who already qualify.

register_world_product

Register a product one of the creator's worlds SELLS — the registry Helix.marketplace.purchaseProduct buys from, which is NOT part of helix.json and cannot be declared in the bundle or minted at runtime. REGISTER BEFORE WRITING the code that buys it: world code names the creator-authored key (purchaseProduct("speed_boost") buys pkey:speed_boost) and the key is IMMUTABLE once registered, so it is chosen here, once. The PRICE lives server-side only — a world never sends an amount; the shell raises the confirm popup and settles. priceLix 0 is legitimate: it registers a free "Claim". AUTHOR WHAT IT HANDS OVER as a grants effect array — pass | currency; several effects = a bundle, an empty array = a tip jar. The backend fulfils it DURABLY at settle. World Products do not mint universal Items; use the Creator approved Publications workflow for those. The effect list is IMMUTABLE once registered. Pass dryRun to validate everything locally — no network, works logged out. TEST THE LOOP FIRST: the same product row seeds .helix/dev-products.json for helix dev — buy/entitlements/consume answer locally with nothing charged, and the debug menu forces the failure paths. Registration takes effect on a live world immediately — no republish.

scaffold_world

RETURNS A COMMAND, NOT DATA. This tool hands you a helix … command string to RUN yourself — it executes nothing and returns no results. The answer is in that command’s output. REQUIRED FIRST BUILD STEP when no project exists yet (a workspace that already has package.json and public/helix.json is scaffolded: skip this) — the command is helix init <dir>, and running it writes a complete, build-ready world project: package.json, vite.config.ts (base: "./"), tsconfig.json, index.html with the import-map markers + loading overlay, .gitignore, public/helix.json (v0.2, pinning humanoid-character AND engine-core), src/helix.runtime.ts, src/loading.ts, and a RUNNABLE src/main.ts — a real character world that builds and renders, with the world-owned InputService pre-wired (register game keys on it — never raw addEventListener), the floor collider, the world.ready() inspect hook, and the ability base resolved against document.baseURI so it survives the sub-path a published world is served from. DO NOT HAND-WRITE THESE FILES from the recipe prose: the recipe is explanation, the scaffold is the source. An agent that typed them out instead got four API calls wrong against the installed .d.ts and shipped a world that built, validated, and rendered nothing. Multiplayer scaffolds include proximity VOICE CHAT by default (the voice.proximity permission + the fail-soft join) — remove both only for a deliberately silent world. A scene scaffold can also come with GROUND: terrain: "<preset>" adds --terrain <preset>, which generates a 4 x 4-tile (1 km x 1 km) heightfield into public/scene/mall/terrain/, paints it from the preset, lifts the starter mall onto the flat spawn plateau, and declares it in the sealed document — public/.helixignore already covers terrain/, so those bytes stay a dev override. Scene worlds ONLY; read_doc({name:"terrain"}). Existing files are SKIPPED (safe to run inside an existing project); the CLI never destructively overwrites. Then: npm install → install_world_packages → npm run build → validate_world → helix verify-subpath dist → publish_world.

set_achievement_icon

Replace a registered achievement's ICON ART in place (HYPR-5142). Same UniversalItem, same key — every holder keeps their badge, and the default trophy plaque is re-baked with the new art (a bespoke trophy mesh is left untouched). This is the RIGHT way to change art: do NOT re-register the achievement to swap an icon (that re-keys it and leaves the old one delisted). image is a path to a local icon file (png/jpeg/webp); it is validated (a single flat colour is rejected) before anything is uploaded.

set_preview_video

RETURNS A COMMAND, NOT DATA. This tool hands you a helix … command string to RUN yourself — it executes nothing and returns no results. The answer is in that command’s output. Set or clear a published world's YouTube preview. The CLI and the API own what counts as a valid YouTube link — the URL is normalised server-side.

set_world_thumbnail

RETURNS A COMMAND, NOT DATA. This tool hands you a helix … command string to RUN yourself — it executes nothing and returns no results. The answer is in that command’s output. Attach a custom thumbnail or preview image to a published world (fills the generated-placeholder slot). Filling an EMPTY slot is a normal finishing step after a good capture — do it without asking. Pass overwrite ONLY when the human explicitly asked to replace an existing image; an occupied slot without overwrite is refused by the CLI (with the current URL intact) so you can relay the situation instead of silently skipping it.

terrain_generate

Generate the GROUND a scene world stands on: runs helix terrain generate and writes a terrain source folder (per-tile 16-bit heights, the painted splats, terrain.json). Deterministic — the same preset, seed and size always produce the same bytes, so a re-run is free and a diff is real. USE IT for open ground under a scene world: a scene document declares the folder (the terrain element of a scene-elements document, or scaffold_world({ kind: "scene", terrain }) which already wired one) and the scene system streams the tiles as the world loads. A tile is 256 cells and this generator always writes the 1 m authoring grid, so a tile is 256 m: the default 4x4 grid is 1 km x 1 km (~2.4 MiB) and the cap is 16x16 = 4 km x 4 km (~39 MiB, ~25 s of work). A coarser authoring grid (0.5, 2, 4 or 8 m per sample) is an IMPORT-side choice — terrain_import takes outputMetresPerSample, generate has no spacing flag. Pass tiles OR sizeKm, never both. The preset picks BOTH the landform and the surfaces painted onto it. ALWAYS run terrain_inspect on the folder before publishing — folded layers and over-cap tiles are reported there and nowhere else. Terrain worlds run DYNAMIC lighting: never bake_world_lighting a world whose ground is streamed terrain. Full recipe: read_doc({ name: "terrain" }).

terrain_import

Turn an EXISTING heightmap — a real-world DEM, a sculpted export, ground shaped in another tool — into a terrain source folder: runs helix terrain import, resamples the file onto the authoring grid and paints it with a preset. Use it instead of terrain_generate whenever the shape of the ground is already decided somewhere else; everything after this point (inspect, the scene document, publishing, lighting) is identical. TWO SPACINGS, never confuse them: metresPerSample is the SOURCE posting — metres between two samples IN THE FILE, taken from the source data and never guessed — while outputMetresPerSample is the AUTHORING grid the world is built on, one of 0.5, 1, 2, 4 or 8 m (default 1). Author at 1 m for hand-scale ground a player walks over; go coarser when the extent is the point — a tile is 257 samples, so at 4 m one tile spans 1 km and a city-scale landscape costs a sixteenth of the tiles the same ground would at 1 m. HEIGHTS: png16 and r16 store 0..65535, so heightRange says what the darkest and brightest sample mean in metres (e.g. [0, 900]) and a wrong pair yields a plausible-looking world at the wrong scale; f32 (headerless little-endian float32) already holds absolute metres and REJECTS heightRange. Either way the ground belongs near y = 0 — the sky, the height fog and the numeric precision are all built for it, and the absolute altitude is a fact for the docs, not for the world: with png16/r16 shift heightRange (a 1900..3900 m DEM becomes [0, 2000]), with f32 pass heightOffset, which is added to every decoded height, so a DEM whose sea level reads 507 m re-bases with heightOffset: -507. The extension picks the format when format is omitted (.png, .r16/.raw, .f32). A source posting coarser than the authoring grid is upsampled with a cubic that keeps the slope continuous across the source samples; bilinear (resample) creases along every source row and column and the light draws each one. Three more inputs when the source needs them: origin puts sample (0, 0) at a chosen world position instead of centring the grid, samples gives the row length of a raw r16/f32 file that is not square, and splat + splatRoles paint from an AUTHORED RGBA image covering the grid extent — every role bound to a channel there takes its weight from that channel instead of the preset rule, and the roles left unnamed keep theirs. Then run terrain_inspect. read_doc({ name: "terrain" }).

terrain_inspect

Report what a terrain source folder would actually ship, as numbers (helix terrain inspect): extent and tile count, authored samples, delivered bytes split into heights and splats, the height range, the coarse layer, which material roles the bake had to FOLD into a kept role on which tiles (a tile carries four layers; a preset may declare six), and every warning — an over-cap tile, an unbaked or splat-less folder, a grid past 16 x 16. THE GATE BEFORE PUBLISHING: none of this is visible in a screenshot and none of it is reported at publish time, so an unbaked or over-cap terrain otherwise ships silently. Read-only — it writes nothing. Returns the human summary followed by the same report as JSON.

update_achievement

Patch a registered achievement's presentation (name/description/points/hidden/active). The key, unlock mode and criteria are FIXED at registration — rules name the key, and re-labelling how a badge is earned would rewrite what every already-granted copy claims; register a new achievement instead. To change the ICON ART in place, use set_achievement_icon (the key and every holder's badge are preserved — do NOT re-register just to swap art). Set active:false to delist one (existing holders keep theirs).

update_world_product

Patch a registered product's presentation, price or ownership cap, or set active:false to take it off sale (the row stays, so past purchases and the items they granted keep resolving). The key and the type are FIXED at registration — world code buys the key, and changing what a purchase hands over would re-label every copy already sold; register a new product and deactivate this one instead.

validate_world

Validate a built world bundle directory (the Vite dist/ folder containing helix.json) against the exact rules the platform enforces at publish. Run this after building and fix every reported problem before publishing. A World whose engine systems are pinned to an exact version (not a ^ range) is refused: use ranges, and promote an engine fix instead of pinning to it.

world_metrics

The static traversal/movement reference from a world’s OWN installed character system — read it instead of guessing spatial constraints while building: player capsule (height/radius/crouch), step height (what auto-steps vs blocks), max walkable slope, movement speeds, and the derived jump envelope (air time, max flat-ground gap at run/sprint) plus corridor/ceiling clearances. Values are the system DEFAULTS a world starts from; worlds may override via config. Use it to size gaps, steps, ramps, corridors, and ceilings BEFORE placing geometry, and pair it with inspect_world to verify what you placed.