| purpose | Introduce Voxela and provide the shortest path to using and understanding it. |
|---|---|
| status | Current; v0.1.0 released |
Voxela is an AI-native, repository-first workspace for creating small MagicaVoxel .vox assets with Codex. The repository preserves specifications, recipes, validation evidence, decisions, and human feedback so a fresh agent session can reuse verified project knowledge.
Open the repository in Codex and describe the asset you want. For example:
Make a small voxel van. Plan it first, preserve an editable recipe, validate the result, and open it in MagicaVoxel for my review.
The intended workflow is:
Describe an asset
↓
Codex reads Voxela's repository memory and proposes a plan
↓
Codex constructs, checks, and opens the asset
↓
You review it in MagicaVoxel and approve or refine it
You remain responsible for visual and artistic approval. Technical validation or a successful MagicaVoxel launch never counts as approval.
- A Codex session with this repository open
- Python 3 with the standard library; no package installation is required
- MagicaVoxel for visual inspection
Clone or download Voxela, open its directory in Codex, and begin with your asset request. Codex should read AGENTS.md and the repository memory before acting.
Voxela can deterministically:
- generate a single-model VOX version 150 file from explicit voxel coordinates
- expand
line,rectangle, andboxbuilders - apply one
translate,mirror, or axis-alignedrotate90transformation - merge flat, named composition parts with collision detection
- evaluate bounds, dimensions, floating components, ground contact, connectivity, and expected voxel count
- validate final geometry and the supported
MAIN > SIZE, XYZIchunk structure independently
Codex can plan and coordinate these stages from a natural-language request. Voxela does not include its own natural-language model or autonomous art generator.
See STATE.md for verified status, ARCHITECTURE.md for responsibility boundaries, and CHANGELOG.md for milestone history.
Voxela does not yet provide custom palettes, materials, animation, scene graphs, automatic repair, arbitrary rotations, transformation chaining, a unified command-line interface, or GUI automation. Its VOX support is intentionally limited to single-model exact-list geometry using MagicaVoxel's default palette.
Voxela treats the repository as durable memory. Work follows LOOP.md, observations qualify through LEARN.md, and facts, decisions, experiments, opportunities, and human approvals remain distinct. The repository improves because verified work produced reusable knowledge—not because an agent guessed.
Read VISION.md for the human-agent boundary and AGENTS.md for operating rules.
| Path | Responsibility |
|---|---|
assets/recipes/ |
Human-readable inputs and compiled explicit geometry |
assets/source/ |
Generated .vox files, specifications, and validation evidence |
assets/palettes/, assets/previews/, assets/exports/ |
Reserved asset outputs; capabilities are not implied |
tools/ |
Small, standard-library pipeline stages |
experiments/ |
Uncertain investigations, currently empty |
references/ |
Focused source notes and evaluation evidence |
| Root memory documents | State, workflow, decisions, style, learning, and review rules |
Developers can run individual stages without a conversational agent.
Generate and structurally validate the smallest demonstration:
python3 tools/generate_vox.py assets/recipes/HelloVoxel.json
python3 tools/validate_vox.py assets/recipes/HelloVoxel.jsonRun the composed-and-constrained demonstration:
python3 tools/compose_voxels.py assets/recipes/HelloComposition.composition.json
python3 tools/evaluate_constraints.py assets/recipes/HelloComposition.constraints.json
python3 tools/generate_vox.py assets/recipes/HelloComposition.json
python3 tools/validate_vox.py assets/recipes/HelloComposition.jsonGenerated files are written under assets/source/. See ARCHITECTURE.md before changing stage boundaries.
There is no committed feature roadmap. Candidate directions are recorded in OPPORTUNITIES.md and become work only after review and approval.
Contributions should be focused, reversible, tested against existing skills, and honest about what is implemented. Read CONTRIBUTING.md before proposing a change.
Voxela is available under the MIT License.