tarinai/AI_MAP.md

tarinai_ AI map

Purpose: static Japanese browser simulation/game. Optimize context by reading this file only after README.md, then open the relevant subsystem files. For exact file expansion, use scripts/ai_inventory.ps1 or scripts/ai_inventory.py.

Architecture

• Entrypoint: index.html defines the app shell, canvas, dialogs, right panels, and exact script order.
• Runtime style: plain browser JS, global IIFEs, exports on window, no bundler/module loader.
• Version/cache: app_manifest.json, js/version.js, and generated service-worker.js share 39.15.47.
• Main loop: js/main.js initializes assets/audio/world/UI/save, then drives update/render.
• Update order: js/system_order.js calls phase facades from js/world_update_phases.js / js/simulation_systems.js.
• Command path: UI/input emits command objects; js/command_dispatcher.js routes tool, pointer, selection, save, reset, and UI intents.
• Persistence: save files are schema/codec/storage/coordinator modules; snapshot/history modules keep world restoration and stats consistent.

Subsystem Map

• Core/bootstrap: js/version.js, js/event_bus.js, registries, js/data.js, js/ground_types.js, js/health.js, js/main.js, js/debug_tools.js, js/perf_profiler.js.
• Rendering/assets/audio: js/assets.js, js/audio.js, js/render.js, js/tarinai_render.js, js/item_render_runtime.js, js/sound_pack.js.
• Simulation phases: js/sim_core.js, js/simulation*.js, js/world_update*.js, js/system_order.js.
• World domain: js/world*.js, js/weather_system.js; covers state, camera/view, environment, combat/effects, placement/history, tools, family/social, ants, spatial budgets.
• Creature domain: js/tarinai*.js; covers state, identity, needs, actions, forced behavior, social life, item effects, disease/nests, movement/update pipeline, rendering.
• Item/structure domain: js/item*.js, js/items.js, js/structures.js, js/structure_lifecycle.js; covers definitions, spawning defaults, lifecycle, dynamic behavior, rendering.
• Physics/mechanics: js/physics*.js, js/mechanical_system.js, js/constraint_system.js, js/collision_footprint_system.js.
• UI/input: js/ui*.js, js/text_catalog.js, js/command_dispatcher.js; covers panels, tools, selected creature, logs, charts, family tree, mouse/touch, dialogs, labels.
• Family tree: js/family_graph.js, js/ui_family_*.js; data transform, layout, paths, async rendering, validation.
• Save/history: js/save*.js, js/snapshot_system.js, js/restore_coordinator.js, js/history_system.js.
• Scripts: scripts/generate_app_files.py, scripts/generate_item_icons.py, scripts/regression_check.py, scripts/ai_inventory.py, scripts/ai_inventory.ps1.

File Pattern Semantics

• *_pipeline.js: ordered runner/facade for update or lifecycle work.
• *_step_*.js: narrow pipeline step wrapper.
• *_system.js: domain service, phase service, or compatibility facade.
• *_runtime.js: stable runtime-facing facade around split modules.
• *_registry.js: definition registry and lookup/normalization helpers.
• world_*: world-owned behavior; tarinai_*: creature-owned behavior; item_*: item-owned behavior; ui_*: DOM/input/panel behavior.
• assets/sprites/tarinai_*.webp: creature visual state sprites; numeric prefix is stable asset ID/order.
• assets/ui/tool_*: tool palette icons; assets/ui/favicon*, apple-touch-icon, ecology_* are app/help icons.
• assets/objects/*: field object sprites for ants, zunchi, pushpin, oshibyo, genkotsu, plushie.
• assets/sounds/voice_*: creature voice samples; shoot_*, major_damage_*, firecracker_* are SFX.

Task-Oriented Read Sets

• UI/layout bug: index.html, relevant css/*.css, js/ui_bind.js, js/ui_layout_dialogs.js, matching js/ui_*.js.
• Tool behavior: js/command_dispatcher.js, js/world_tool_actions.js, js/item_registry.js, relevant js/item_* or js/tarinai_item_*.
• Creature behavior: js/tarinai.js, js/tarinai_update_pipeline.js, relevant js/tarinai_*, js/system_order.js.
• World/environment/combat: matching js/world_*, js/simulation_*, js/system_order.js.
• Save/load: js/save_schema.js, js/save_codec.js, js/save_system.js, js/snapshot_system.js, js/restore_coordinator.js.
• Family tree: js/world_family_social.js, js/family_graph.js, js/ui_family_*.js.
• Static app/cache/version: app_manifest.json, scripts/generate_app_files.py, service-worker.js, js/version.js, index.html.

Invariants

• Preserve index.html script order unless all dependent manifests/generated files are updated together.
• Keep app_manifest.json, js/version.js, service-worker.js, and cache query versions synchronized.
• Keep global exports for compatibility with regression checks and browser runtime.
• Prefer focused edits in the owning subsystem; split modules are intentional compatibility boundaries.
• Run node --check js/*.js and python scripts/regression_check.py for behavior changes.