Block a scene, pose the cast, cut the camera — in a browser tab.
Created and maintained by Doyun at NomaDamas.
Demo reel · Quick start · Features · AI control · Controls · Issues
CozyClay is a browser-based 3D staging studio built with Three.js and React Three Fiber. Block a scene, pose characters, sequence motion prompts on a timeline, and preview generated motion — all in one local workspace.
npx cozyclayThat is the whole install. cozyclay.org has the demo reel and a walkthrough of what the studio does; to use it, run it on your own machine. It ships seeded with a pre-generated motion clip, so you can scrub the timeline, drive the cameras and draw a dolly rail straight away — generating new motion needs a local ARDY machine, so that part stays off until you point it at one.
cozyclay-demo.mp4
| Stage a scene | Create primitives and set pieces, then move, rotate and scale them with a W/E/R gizmo. Grid snapping is a preference, not a law — hold Ctrl mid-drag to invert it. A bird's-eye plan view drives 2D root waypoints for character paths. |
| Fly the camera | Right-drag flies (WASD walks, Q/E cranes), middle-drag pans, Alt+drag orbits the selection, click selects, F frames — the muscle memory you already have from a 3D editor. |
| Undo anything | Every scene mutation goes through one history store: a drag, a scrub, an inspector edit is exactly one undo entry. Esc cancels an in-flight drag and restores the pre-drag transform. |
| Generate motion | Pose characters and export poses, sequence multi-phase motion as Prompt Blocks on a resizable timeline, send them to ARDY, then play the result back with sparse IK correction where the generated motion needs fixing. |
| Direct it with an AI | Connect Claude — or any MCP client — and ask for a shot in plain language. It places the cast, frames “a low wide profile”, generates multi-phase motion, and the viewport moves in front of you. See AI control. |
- Node.js 22 or newer
- npm, or bun
- A Chromium-based browser
- Optional: an SSH-accessible NVIDIA machine running ARDY, for motion generation
npx cozyclay
# or
bunx cozyclayThat downloads the built studio and opens it at http://127.0.0.1:5180. Nothing to compile, no dependency tree to install. Useful flags: --port 5200, --no-open, --no-ardy.
Motion generation stays off until you point it at a machine that can run it:
CCLAY_ARDY_HOST=user@your-gpu-box npx cozyclayEverything else — staging through camera work and playback — runs without it.
The studio ships an MCP server, so an AI assistant can drive it — the same scene, the same viewport, live:
“Put a detective and a courier in an alley, give me a low wide profile shot, then make her stand up from the chair, sprint, and trip.”
{
"mcpServers": {
"cozyclay": {
"command": "npx",
"args": ["-y", "cozyclay", "mcp"]
}
}
}Drop that into claude_desktop_config.json (or any MCP client config) and restart the client. The
first run automatically installs the MCP SDK's 95-package tree; opening the studio never waits on
it, so those dependencies are fetched only when you actually want the server.
- Editor open? Tool calls move the visible viewport — camera, cast, set, generated motion, prompt blocks on the timeline.
- No editor? The same tools run headless: block scenes, derive film vocabulary (“wide shot · right profile · knee level · 24mm”), render AI video prompts, and write
.cclayprojectfiles the studio opens.
Tools, transports and the live-control protocol are documented in mcp/README.md.
git clone https://github.com/NomaDamas/CozyClay.git
cd CozyClay
npm install
npm run devOpen http://127.0.0.1:5180. npm run dev starts the studio together with its local ARDY bridge; npm run dev:ui starts the browser UI alone, without Block Generation. The bridge listens on loopback only; the environment variables that point it at a remote ARDY machine are documented in tools/ardy/BRIDGE.md.
Token-free ARDY text encoder — skip the Hugging Face gate
ARDY's text encoder normally requires a Hugging Face account, gated-model approval, and an access token on the ARDY machine. CozyClay ships a token-free alternative — one command provisions the same encoder stack from public repositories, pinned by commit and SHA-256:
CCLAY_ARDY_HOST=user@your-gpu-box tools/ardy/setup-text-encoder-on-box.shSee tools/ardy/README.md for details. This workflow is built with Meta Llama 3; the encoder's base weights are licensed under the Meta Llama 3 Community License.
| Input | Action |
|---|---|
| Right-drag | Look around (fly) |
| RMB + WASD | Walk while flying |
| RMB + Q/E | Crane down / up |
| Middle-drag | Pan |
| Alt + drag | Orbit the selection |
| Scroll | Dolly |
| Click | Select; empty space clears |
| W / E / R | Move / rotate / scale tool |
| Ctrl (during drag) | Invert grid snapping |
| Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z | Undo / redo |
| Esc | Cancel the in-flight drag |
| End | Drop the selection to the surface |
| Ctrl/Cmd+D | Duplicate the selection |
| F | Frame the selection |
| Command | Covers |
|---|---|
npm run test:history |
Undo/redo store and transaction coordinator |
npm run test:scene-objects |
Scene-object model |
npm run test:hierarchy |
Hierarchy panel model |
npm run test:objects |
Gizmo interaction in a real browser — needs npm run dev:ui in another shell |
npm run test:theme / test:appearance / test:layout |
UI theme, appearance, layout |
npm run test:lifecycle |
Dev-server process lifecycle |
npm run test:ardy |
ARDY conversion, playback, and IK pipeline |
cd mcp && npm install && npm run verify |
MCP server over real stdio — all 420 framing combinations |
cd mcp && npm run verify:live |
Live-control protocol against a fake editor (same npm install first) |
npm run build |
Production build |
Ad-hoc browser QA, while a dev server is available:
npm run qa:browser -- <qa-script>Found something broken, or want a feature? Open an issue — bug reports with a repro are the most useful thing you can send. Contributions are accepted under AGPL-3.0-or-later.
Repository hygiene. Generated motion archives, QA output, build output, logs and local runtime artifacts are not source files and must not be committed. Keep tools/ardy/out/, artifacts/, dist/, .gjc/ and .npz files local.
All runtime libraries intentionally live in devDependencies because the published npm package ships the prebuilt dist/, so npx cozyclay must not install the studio's dependency tree.
GNU Affero General Public License v3.0 or later — see LICENSE and the transition details in LICENSING.md. Modified network services must offer their users the corresponding source. Third-party projects retain their own licenses and copyright; see THIRD_PARTY_NOTICES.md.
CozyClay can connect to NVIDIA ARDY for motion generation. ARDY is a separate third-party project owned and maintained by NVIDIA; it is not included in this repository, and CozyClay is not affiliated with or endorsed by NVIDIA.