Topview 3D Builder

View saved version →

---
name: topview-3d-cli
description: >
  Block out, edit, check and render 3D staging scenes on the local machine with the topview-3d-cli command:
  simple primitive props, built-in mannequin characters, static library poses, story cameras plus a
  bird's-eye layout camera, numerical checks and PNG renders; building and rendering run offline in a
  project directory. After the renders it offers an image or video generation from the frames, run only
  once the user confirms.
  Use when the user asks to stage, block out, lay out or storyboard a scene in 3D; place people,
  props or cameras; pose characters; check framing, grounding, spacing or collisions; render views
  of a scene as a reference for video generation; or works in a directory that contains
  `.topview-3d/`. Also use when a topview-3d-cli command fails or topview-3d-cli still has to be installed.
  The Codex plugin is shown as Topview 3D Builder. Change the 3D scene only with topview-3d-cli.
  After a scene is built, open the local Studio in the In-App Browser to view it, not to edit it.
---

# topview-3d-cli

`topview-3d-cli` edits and renders a local director project: a directory with a `.topview-3d/` folder. The
goal is an abstract, physically consistent staging reference for video generation: simple shapes,
correct scale and support, clear blocking, one world seen from several static cameras. Character
positions come first, then plausibility and camera continuity, then composition. Fine visual detail
is not a goal; a phone can be a slab. Respond in the user's language.

Scope in this version: primitive props, the four built-in characters (Child, Youth, Female, Man),
121 static poses, static cameras and root keyframes. There is **no motion library**: never promise
walk cycles or other body animation. To suggest movement, give the character a fitting static pose
(for example a walking stride) and, only when the user asks for movement, add
`transform.position` / `transform.rotation` keyframes (see `references/edit.md`). Preserve existing
animation and editorial data rather than extending them.

## Step 1: check the environment

Run this before anything else in a session:

```bash
topview-3d-cli doctor --json
```

It always exits 0; gate on the top-level `ok`. When `ok` is false, read each failing
`checks.<name>.hint` and follow `references/doctor-browser.md`:

- **`topview-3d-cli` not found:** it is installed once per machine, in an environment every project
  shares. Look there before installing anything: `~/.local/share/topview-3d-cli/venv/bin/topview-3d-cli`
  on macOS and Linux, `$env:LOCALAPPDATA\topview-3d-cli\venv\Scripts\topview-3d-cli.exe` on Windows.
  When it exists and its `doctor --json` reports the `cliVersion` of this skill's pin,
  `topview-3d-cli==0.1.8`, use that path for every command.
  Otherwise install it once as `references/doctor-browser.md` describes (Installing topview-3d-cli).
  Never create a virtual environment inside the user's project or workspace, and do not use
  `pip install --user`.
- **`node` fails:** Node.js 20.6 or newer (with npm) is required; ask the user to install it.
- **Checkout:** when the folder that holds this skill also has `agent/` and `editor/` (plugin installs
  are checkouts), install by running its `scripts/install.sh` (or `install.ps1` on Windows) once. It
  puts the CLI into the shared environment and installs the renderer and Studio's Next.js together.
  Do not install only the renderer package.
- **`playwright` or `chromium` fails:** run `topview-3d-cli browser ensure` once (it downloads the pinned
  Chromium into the user cache).
- **Rendering fails inside an agent sandbox** although `doctor` passes: the sandbox blocks the
  browser, not topview-3d-cli. Say so, ask the user to approve running the render command outside the
  sandbox, and keep working on everything that does not need a browser. Never build a substitute
  renderer (image libraries, SVG, hand-drawn frames).

## CLI contract

- Every command p

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 12 — file references are metadata, not package contents.