Metadata-Version: 2.4
Name: clayspace
Version: 0.1.1
Summary: Standalone local spatial modeling toolkit for building portable Cells and worlds on your own computer.
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 standalone spatial modeling toolkit you can install on your
own computer and use without an account, hosted service, or host-world SDK.**
Build a room, a building, a street, a stage, a landscape
blockout, an abstract structure, or a whole world from portable local pieces
called **Cells**.

ClaySpace is intentionally lightweight. Its job is to give geometry stable
identity, coordinates, placement, and a viewable spatial structure without
forcing a particular art pipeline or story system on top of it.

> **Upstream license notice:** ClaySpace's development lineage includes
> [Fly With Me](https://github.com/kunchenguid/fly-with-me) by Kun Chen, used
> under the MIT License. The original `Copyright (c) 2026 Kun Chen` notice and
> MIT terms are included with this distribution in
> `licenses/FLY_WITH_ME_MIT.txt`. ClaySpace is an independent project and is
> not maintained or endorsed by the Fly With Me project.

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

There are no required runtime dependencies and no network calls in the core
package.

## Make something

Start a local Cell:

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

Add and edit primitive 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 file** with a dependency-free orbit,
zoom, grid, and wireframe/shaded primitive viewer. Open it in any modern
browser. Nothing is uploaded anywhere.

You can also work directly in Python:

```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 stay local and portable. A **world** places them with transforms without
rewriting the Cell itself.

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

That separation means the same building can be placed many times, moved, or
shared without baking any one world's coordinates into the source object.

## Cells and geometry

The public `clayspace.cell.local-fragment` format uses meters with
`x-right / y-up / z-forward` coordinates. 0.1.1 supports these procedural
primitives:

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

Cells may also carry additional metadata and asset references. The validator
checks structural portability; it is not a structural-engineering, collision,
or mesh-quality certification system.

For compatibility, ClaySpace also reads the earlier compact `0.1` Cell form and
richer production Cells that carry extra host metadata. Host-specific fields do
not become part of ClaySpace policy.

## What ClaySpace does *not* require

You do **not** need:

- another project's SDK;
- a cloud account;
- a ledger or database service;
- a server;
- a particular renderer;
- permission from a host system to make your own Cells and worlds.

Other projects can choose to depend on ClaySpace. ClaySpace itself does not
depend on their identity, workflow, publication, or governance systems.

## Fly With Me provenance and license

ClaySpace's development lineage includes
[**Fly With Me**](https://github.com/kunchenguid/fly-with-me), the open-source
browser world/flight project by **Kun Chen**. Fly With Me is licensed under the
MIT License, copyright (c) 2026 Kun Chen. Its original MIT notice is included
verbatim in `licenses/FLY_WITH_ME_MIT.txt` and described in
`THIRD_PARTY_NOTICES.md`.

We are deliberately explicit about that origin. ClaySpace is an independent
project and is not maintained or endorsed by Kun Chen or the Fly With Me
project.

The ClaySpace package itself is also released under the MIT License; see
`LICENSE`.

## Current scope

ClaySpace 0.1.1 is an early modeling/blockout release, not a replacement for a
full DCC such as Blender. It provides portable spatial primitives, Cell/world
composition, transforms, validation, and local browser previews. Mesh import,
advanced materials, rigging, sculpting, and a full desktop GUI are not part of
this release.
