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.