# Kiduna Isometric Scene System

Version 0.1.0 · 2026-08-21

This package is a production-oriented visual and runtime reference system for creating 2.5D Kiduna Scenes. It defines the visual constitution, projection, scale, anchors, depth, occlusion, lighting, materials, state language, animation, component metadata and Scene format required for independently created assets to remain compatible.

It is a reference implementation and specification—not a finished game engine or a library of final shipping atlases. The supplied Commons images remain untouched primary visual evidence. The generated Component sheets and new Scenes are reference exemplars tied to machine-readable contracts.

## Start here

1. Read [`docs/VISUAL-DNA.md`](docs/VISUAL-DNA.md).
2. Use [`schemas/component.schema.json`](schemas/component.schema.json) for a new Component.
3. Author against [`docs/ISOMETRIC-SYSTEM.md`](docs/ISOMETRIC-SYSTEM.md), [`docs/LIGHTING.md`](docs/LIGHTING.md) and [`docs/MATERIALS.md`](docs/MATERIALS.md).
4. Generate or illustrate with the packet in [`docs/AI-ASSET-GENERATION.md`](docs/AI-ASSET-GENERATION.md).
5. Validate with [`docs/VALIDATION.md`](docs/VALIDATION.md) and `npm run validate:system`.
6. Insert the asset into at least two structured Scene fixtures before acceptance.

## Run the reference Site

```sh
npm install
npm run dev
```

The Site requires no external backend. `npm run build` creates the deployable worker bundle.

## Package map

- `app/` — interactive documentation Site.
- `docs/` — human-readable specifications.
- `schemas/` — Component, Scene and validation JSON Schemas.
- `data/` — palette, materials, 50-specimen catalog and nine-Background catalog.
- `components/` — nine transparent specimen sheets, 50 full foreground records and nine full atmospheric Background records.
- `scenes/` — nine structured Scene JSON files.
- `public/references/` — four untouched supplied Commons images.
- `public/scenes/` — five new visual system demonstrations.
- `public/components/` — transparent final sheets plus source generations.
- `scripts/` — validation and packaging utilities.
- `references/` — canon provenance and supplied-source manifest.

## Canon grounding

This release applies Kiduna Canon V0.36 (2026-08-16 14:11 EDT, SHA-256 `df2ead9b000482057b4f2ed909d1242e0cdfd32d0e8c3027807e309856a2a17c`). Canon is copied for provenance; this project does not mutate it.

Canonical distinctions matter:

- A **Source** is the human.
- An **Avatar** is the representation of that Source within a Realm.
- **Ki**, **Allies** and **Actors** are distinct kinds of intelligence with bounded authority.
- A **Scene** spatially organizes Components; an **Area** logically organizes Components and Scenes.
- **Panels** live inside the Scene, **Overlays** sit over it, and **Chrome** belongs to the surrounding application.

## Acceptance rule

A Component is accepted only when it passes every hard gate, scores at least 88/100 and works in two Scene fixtures. A Scene is accepted only when it remains beautiful, legible and actionable with Overlays removed.

> Beauty is one of the constraints of the system.