tarinai/README.md

# tarinai_

AI-first entrypoint for a static browser simulation/game. Keep this file small; read deeper docs only when needed.

## Read Strategy

- Start here for architecture, script order constraints, and where to look next.
- For game mechanics, UI, items, and tarinai behavior, read `GAME_FEATURES.md`.
- For subsystem work, read `AI_MAP.md` plus only the matching files.
- For exact file inventory, run `powershell -NoProfile -ExecutionPolicy Bypass -File scripts/ai_inventory.ps1 -All` or narrow it: `powershell -NoProfile -ExecutionPolicy Bypass -File scripts/ai_inventory.ps1 ui`. Python equivalent: `python scripts/ai_inventory.py --all`.
- For machine-readable routing, read `FILES.json`.
- Avoid loading all assets into context; asset filenames are mostly self-describing and grouped by glob.

## Runtime Shape

- Mutable runtime lives on `window`; primary entities are `World`, `Tarinai`, items, structures, ants, family graph, weather, and save snapshots.
- Update loop: `main.js` creates the world/UI loop; `World.update` delegates to `TarinaiSystemOrder.update`; `system_order.js` runs named phases.
- UI loop: pointer/tool/UI intents go through `command_dispatcher.js`; canvas drawing is in render modules; side panels are `ui_*.js`.
- Generated/static app shell: `app_manifest.json`, `service-worker.js`, `FILES.json`, and `js/version.js` must stay version-aligned.

## File Routing

- `index.html`: DOM shell, CSS/JS load order, panels/dialogs/canvas.
- `css/*.css`: base/layout/panel/components/mobile styling.
- `js/domain_ids.js`, `js/item_type_catalog.js`, `js/data.js`, `js/ground_types.js`: stable domain ids, current item-type save catalog, core config, field/ground definitions.
- `js/world*.js`: world state, view, update phases, tools, placement, combat, environment, family/social, ants.
- `js/tarinai*.js`: creature state, needs, actions, behavior, social life, item effects, update pipeline, rendering.
- `js/item*.js`, `js/structures*.js`: item registry/runtime/lifecycle/dynamic behavior/rendering plus structures.
- `js/simulation*.js`, `js/system_order.js`, `js/sim_core.js`: concrete update systems and phase ordering.
- `js/ui*.js`, `js/text_catalog.js`, `js/command_dispatcher.js`: DOM UI, input, selected panel, logs, charts, family tree, tools, labels.
- `js/save*.js`, `js/snapshot_system.js`, `js/restore_coordinator.js`, `js/history_system.js`: persistence and history.
- `js/physics*.js`, `js/mechanical_system.js`, `js/constraint_system.js`, `js/collision_footprint_system.js`: geometry, mechanics, constraints, collisions.
- `assets/sprites/tarinai_*.webp`: creature state sprites.
- `assets/ui/tool_*`: tool palette icons; other `assets/ui/*` are app/help icons.
- `assets/objects/*`: field object images.
- `assets/sounds/*`: voice and SFX samples.
- `scripts/*`: generators, regression checks, and AI inventory.

## Conventions

- `*_pipeline` = ordered runner/facade.
- `*_step_*` = pipeline stage wrapper.
- `*_system` = domain service or compatibility facade.
- `*_runtime` = stable runtime-facing facade.
- `*_registry` = definition lookup/normalization.
- Many split files preserve regression contracts; do not collapse them casually.

## Checks

- Syntax: `node --check js/*.js`
- Regression: `python scripts/regression_check.py`
- Inventory sanity: `powershell -NoProfile -ExecutionPolicy Bypass -File scripts/ai_inventory.ps1 -All`


### Shared achievement percentage deployment
- Upload `achievement_api.php` and the hidden `.achievement_data` directory with the game.
- PHP must be enabled, and `.achievement_data` must be writable by the PHP process.
- On a static-only host, local unlocks still work; the global percentage is shown as unavailable.
- Set `window.TARINAI_ACHIEVEMENT_API` before `achievements.js` to use a different same-origin endpoint.
- The current release tracks 76 achievement IDs, supports per-player reset, and accepts additive bulk synchronization for automatic recovery after aggregate-data loss. A separate backup remains necessary to recover players who never return.
- `python3 scripts/achievement_server_state_audit.py` creates deterministic randomized achievement histories at runtime; it does not require or modify a production `state.json`.