# Component System

## Canonical classes

The generic model supports Background, Terrain, Tile, Wall, Architecture, Object, Entity, Avatar, Ally, Actor, Portal, Light, Vegetation, Fauna, Effect, Panel, Overlay, Chrome and Interactive Component.

This extends the canonical Kiduna Component distinctions without changing them. Avatars, Allies and Actors remain Elements; their visible representations may be Entity Components.

## Identity, Dimension and Design

Keep these separate:

- **Identity** says what the Component is and what it means.
- **Dimension** says how it occupies 2D, 2.5D or 3D space.
- **Design** says how it appears under the active Realm and Scene visual system.

The same lantern can retain identity while receiving a different dimensional representation or Design. Never make an asset filename the identity.

## Required metadata

Every Component record includes stable ID and version, canonical name, category, subtype, description, asset, world dimensions, pixel bounds, footprint, anchors, orientations, layer band, depth bias, detail tier, occlusion policy, materials, palette roles, light reception/emission, shadow, animations, states and transitions, interactions, accessibility, tags and provenance.

## Asset package

For a mastered raster Component, ship:

- color RGBA PNG with real alpha;
- optional separable contact/cast-shadow PNG;
- optional emission mask;
- material-region mask or region list;
- orientation/state variants;
- Component JSON;
- validation Record;
- source-generation or illustration provenance.

## Family-specific constraints

### Backgrounds

An atmospheric Background is a full Component, not anonymous Scene prose. Its opaque plate declares horizon, principal light vector, haze, reflection, a foreground transition band and at least two physical connection methods. The nine reference bindings are indexed in `data/background-catalog.json` and implemented in `components/backgrounds/`.

### Ground and terrain

Use irregular feathered edges, transition masks and overlap gutters. The logical footprint may be rectangular; the visible silhouette should not announce it.

The supported field vocabulary includes stone, earth, grass, meadow, forest floor, water, paths, plazas, gardens, terraces, bridges, platforms, stairs and explicit elevation changes. Each uses the same world basis while transitions cross technical boundaries with material, vegetation, shadow and wear.

### Architecture

Use shared floor, sill, lintel, cornice and roof datum lines. Every joinable edge exposes typed sockets and a seam-safe overlap zone.

The structural grammar covers exterior and interior walls, columns, arches, windows, doors, railings, stairs, roofs, balconies, terraces, towers, gates, pavilions, pergolas and platforms. Junctions must resolve structure, thickness, load path and shadow before ornament is added.

### Objects and furniture

Declare user-relative scale, interaction point, contact footprint, occlusion behavior and material channels. Avoid icon-like outlines and exaggerated proportions.

### Vegetation and fauna

Vegetation carries clustered alpha edges and authored occlusion groups. Fauna includes ambient, focused and absent states; it is meaningful motion, not clutter.

`data/nature-catalog.json` defines the supported living vocabulary: trees, shrubs, vines, flowers, moss, grasses, reeds, mushrooms, canopy, roots, fallen leaves and water plants; plus fireflies, butterflies, bees, birds, turtles, hummingbirds, prairie dogs, foxes and owls. A status distinguishes supplied visual specimens from supported archetypes awaiting individual mastering.

### Effects and light

Effects preserve semi-transparent falloff. They are composited by layer and blend mode and must offer a reduced-motion alternative.

### Panels, Overlays and Chrome

Panels occupy the world and obey projection, depth and light. Overlays align to semantic anchors above the Scene and withdraw when their context ends. Chrome belongs to the surrounding application and never enters world-space sorting. An Interactive Component may use any visual family, but still declares full state, Permission, accessibility and provenance contracts.

## Reference specimen sheets

The nine PNG sheets in `public/components/` contain 50 reference specimens. Their logical cell mapping is in `data/component-catalog.json`, and every specimen has a complete schema-valid record in `components/records/`. These are validation exemplars; engineers should master individual shipping assets from approved source art rather than sampling cells at runtime.