---
title: "Authoring with a build program (world_author_program)"
description: "Any intent with more than one part: a scene, a loop, a HUD, a lit and framed world. A program is typed, so most mistakes are caught before a request is sent; a document is checked only when it is applied."
engineVersion: v1.0.234
date: 2026-09-28
license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/."
canonical: https://gessa.ai/docs/knowledge/playbooks/authoring-with-a-build-program/
---

# Authoring with a build program

## When to use

Any intent with more than one part: a scene, a loop, a HUD, a lit and framed
world. A program is typed, so most mistakes are caught before a request is
sent; a document is checked only when it is applied.

## The two tools

1. `world_builder_sdk` (read once per project): returns the generated `.d.ts`
   for this project, including its real asset ids and project components. The
   types are the discovery surface; do not enumerate the catalog first.
2. `world_author_program`: takes the program source (`build.ts`), typechecks it
   against that SDK, compiles it to the same lowered operations the document
   path uses, applies them as one atomic idempotent transaction, then frames a
   rendered look at the entities that landed and runs the default playtest.
   One call, one receipt.

## The loop

1. Fetch the SDK once. Write `build.ts` exporting `default function build(g: Gessa)`.
2. Call `world_author_program` with `dry_run: true` only when you want the
   compile diagnostics without applying. Otherwise apply directly.
3. Read the receipt: `apply` (what landed, per stage), `frame` (the rendered
   look, when the renderer lane is available), `playtest` (possession, movement,
   collection, completion), `diagnostics` (typed, source mapped to the program
   line).
4. Fix the program and apply again. A key you already landed converges: the
   slots you declare win, slots you do not name are left alone, new keys are
   created. You do not need to delete and recreate.

## Rules that save round trips

- Positions and scales accept `{x, y, z}` or `[x, y, z]`; both lower identically.
- Rotations are euler DEGREES.
- Group repeated props through the `instances` verb (one aggregate) instead of
  one entity per prop; per operation item bounds and the program operation
  budget are enforced with a typed diagnostic that names the repair.
- Keep one program per scene. Few fat applies beat many small edits.
- Take a rendered look at milestones (the receipt already carries one), not
  after every apply.

## The fallback (document) and the repair tier

The world build document (`world_build_apply_semantic_operations`) remains the
path for a single structural batch when no program is warranted; see
authoring-with-the-world-build-document. Per mutation tools are for one
targeted edit or a repair, never the default.

## Verify

The receipt's `playtest` section is the proof; the `frame` is evidence of the
look. Claim done only when both are present or the receipt names the exact
seam that made one unavailable.