Metadata-Version: 2.4
Name: clayspace
Version: 0.1.2
Summary: Lightweight spatial modeling toolkit for building reusable Cells and composing worlds.
Author: ClaySpace contributors
License-Expression: MIT
Project-URL: Upstream lineage: Fly With Me, https://github.com/kunchenguid/fly-with-me
Keywords: clayspace,modeling,spatial,3d,blockout,worldbuilding,geometry,offline
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: licenses/FLY_WITH_ME_MIT.txt
Dynamic: license-file

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

```bash
python -m pip install clayspace==0.1.2
```

## Make something

Start a Cell:

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

Add and edit geometry:

```bash
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:

```python
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.

```bash
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.2 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**](https://github.com/kunchenguid/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`.
