ClaySpace

ClaySpace is a lightweight spatial modeling toolkit for building places.

Make a room, a building, a street, a stage, a landscape blockout, an abstract structure, or a larger world from reusable local pieces called Cells. Keep each piece simple and portable, then place and compose those pieces into the space you need.

ClaySpace is useful when where things are matters: environment planning, background layout, continuity, shot design, collaborative worldbuilding, and spatial studies that do not need a heavyweight 3D pipeline.

python -m pip install clayspace==0.1.3

Use ClaySpace with an LLM

ClaySpace includes a compact agent guide so an LLM can learn the same Cell and world conventions the CLI uses instead of guessing at a parallel format. After installing ClaySpace, ask your coding assistant to inspect the package's LLM onboarding material, or print it directly:

clayspace llm
clayspace llm show cell-contract
clayspace llm show workflows

A typical instruction to an LLM can be as short as:

Install clayspace, read its packaged LLM onboarding guide, and use ClaySpace to build this as a portable Cell. Validate it and give me the JSON plus an HTML preview.

The LLM kit is platform-neutral. For ChatGPT, the installed ClaySpace package also contains the version-matched public Skill source. Export a fresh Skill from the package you are actually running:

clayspace llm export-chatgpt-skill --out skill.zip

Upload that skill.zip through ChatGPT's Skill interface if you want the ClaySpace workflow available as a reusable ChatGPT Skill. The Skill does not contain a second copy of the ClaySpace wheel; it points back to the public package as the executable modeling layer. After upgrading ClaySpace, export the Skill again from the upgraded package rather than keeping a hand-edited stale copy.

Make something

Start a Cell:

clayspace cell init --id MY-HOUSE --name "My house" --size 12,8,18 --out house.json

Add and edit geometry:

clayspace cell add-box house.json --id GARAGE --position 8,1.5,3 --size 6,3,7 --out house-2.json
clayspace cell add-cylinder house-2.json --id TOWER --position -4,6,0 --radius 2 --height 12 --out house-3.json
clayspace cell add-sphere house-3.json --id DOME --position -4,12,0 --radius 2.4 --out house-4.json
clayspace cell move house-4.json --id GARAGE --position 8,1.5,-2 --out house-5.json
clayspace cell preview house-5.json --out house-preview.html

preview writes a self-contained HTML view with orbit, zoom, grid, and wireframe/shaded primitive display. Open it in a modern browser and look around.

You can work directly in Python too:

from clayspace import new_box_cell, add_box, add_cylinder, save_cell

cell = new_box_cell(cell_id="MY-SET", name="My set", size=(20, 1, 20))
cell = add_box(cell, object_id="WALL-A", position=(0, 2, -8), size=(20, 4, 0.4))
cell = add_cylinder(cell, object_id="COLUMN", position=(3, 2, 0), radius=0.5, height=4)
save_cell(cell, "my-set.json")

Compose a world

Cells use their own local coordinates. A world places them with transforms, so the source Cell stays reusable.

clayspace world init --id MY-WORLD --name "My world" --out world.json
clayspace world place world.json --cell house-5.json --entity-id HOUSE-01 --position 30,0,-12 --yaw-radians 0.6 --out world-2.json
clayspace world preview world-2.json --out world-preview.html

The same building can appear more than once, move later, or be handed to someone else without rewriting its internal geometry.

Cells and geometry

The clayspace.cell.local-fragment format uses meters with x-right / y-up / z-forward coordinates. ClaySpace 0.1.3 supports:

• boxes;
• prisms with arbitrary X/Z footprints;
• cylinders;
• spheres;
• planes/cards.

Cells can also carry metadata and asset references. The validator checks that a Cell is structurally well-formed and portable.

ClaySpace also reads the earlier compact 0.1 Cell form and richer Cells that carry additional metadata, making it practical to move existing spatial work into the same composition workflow.

Current scope

ClaySpace is early-stage modeling software focused on spatial blockout and composition: portable primitives, Cells, transforms, worlds, validation, and browser previews. Mesh import, advanced materials, rigging, sculpting, and a full desktop interface are future territory rather than the focus of this release.

Fly With Me

Part of ClaySpace's lineage comes from Fly With Me, Kun Chen's open-source browser world and flight project. That work helped establish the browser-space foundation ClaySpace grew from.

Fly With Me is MIT-licensed, copyright (c) 2026 Kun Chen. Its original license notice ships in licenses/FLY_WITH_ME_MIT.txt, with additional detail in THIRD_PARTY_NOTICES.md.

ClaySpace is released under the MIT License; see LICENSE.