Block a scene, pose the cast, cut the camera — in a browser tab.

Demo reel · Quick start · Features · 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 cozyclay

That 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.

Demo

cozyclay-demo.mp4

What you can do

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.

Requirements

• Node.js 22 or newer
• npm, or bun
• A Chromium-based browser
• Optional: an SSH-accessible NVIDIA machine running ARDY, for motion generation

Quick start

npx cozyclay
# or
bunx cozyclay

That 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 cozyclay

Everything else — staging through camera work and playback — runs without it.

From a clone

git clone https://github.com/HaD0Yun/CozyClay.git
cd CozyClay
npm install
npm run dev

Open 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.sh

See 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.

Controls

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

Validate

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
npm run build	Production build

Ad-hoc browser QA, while a dev server is available:

npm run qa:browser -- <qa-script>

Contributing

Found something broken, or want a feature? Open an issue — bug reports with a repro are the most useful thing you can send.

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.

License & credits

GNU General Public License v3.0 or later — see LICENSE. 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.