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, generated service-worker.js, and index.html query params share 39.16.74.
• Main loop: js/main.js initializes assets/audio/world/UI/save, then drives update/render.
• Performance/display settings: js/perf_profiler.js owns manual visual settings and profiler buckets; display tiers affect rendering/visuals, not simulation-quality branches.
• Update order: js/system_order.js calls phase facades from 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.
• Fire/burning behavior: js/fire_runtime_system.js, js/item_dynamic_tool_system.js, relevant item definitions, js/world_combat_effects.js, and nearby environment helpers.
• Performance/crowding: js/perf_profiler.js, js/item_update_scheduler.js, js/tarinai_update_policy.js, js/constraint_system.js, js/world_spatial_budget.js, and render/detail code.
• 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 intentional global exports for compatibility with regression checks and browser runtime; remove public facades only after repo-wide caller checks.
• Prefer focused edits in the owning subsystem; split modules are intentional compatibility boundaries.
• Avoid reintroducing simulationQualityTier branches unless a real simulation-quality setting is restored; current quality controls are visual/detail controls.
• High display quality may include quality-preserving optimizations, but should not reduce simulation cadence, object limits, or visible fidelity in a noticeable way.
• Save format compatibility with old text saves is not required when intentionally shortening/replacing save hash text; keep current save/load internally consistent instead.
• Run node --check js/*.js and python scripts/regression_check.py for behavior changes.

Current Maintenance Notes

This section records current boundaries only. Version-by-version cleanup history and completed work logs are intentionally omitted.

Live Compatibility Surfaces

• Ordered global-IIFE loading is still part of the app contract; check repo-wide callers before removing bare globals or facade objects.
• Keep public event names with active listeners: audio:play, selection:changed, tool:selected, world:phase, log:entry, and tool:placed. Telemetry-only emit calls should stay removed.
• Save compatibility with old exported text is not required, but the current save/load round-trip must remain internally consistent.
• Tool icon ownership is TOOL_DEFINITIONS.icon; UI code converts asset paths for CSS variables. Avoid restoring CSS-local url(...) definitions.
• Shared geometry/display/domain helpers should stay in their owning helper modules unless a dedicated namespace migration is being done.

Open Architecture Candidates

• Full namespace migration for behavior/action/needs/tool helpers. This requires rewriting many bare global call sites and updating regression contracts.
• Effect-specific spatial indexing, fuller delta-history storage, and high-speed collision partitioning. These need new indexes or semantics beyond cleanup.
• UI/text-side meaning consolidation, including labels, wrapping/measurement helpers, and duplicated scalar helpers such as num, finiteOr, isObject, and clonePlain.
• Further World.prototype reduction is possible, but only for helpers proven not to be runtime-facing canvas/UI/tool APIs.

Current Feature Routing

• Achievement system: js/achievements.js, achievement_api.php, js/save_schema.js, js/save_codec.js, js/snapshot_system.js, and achievement audit scripts. Current save schema is 49; current app/cache version is 39.16.74.
• Achievement UI: index.html achievement dialog, css/components.css achievement rows/toast styles, and js/achievements.js DOM rendering.
• Achievement spell payload: TarinaiAchievements.exportSpellState(), snapshot.g.s, save_system.js spell export inclusion, and save_codec.js achievement metadata readers/writers.
• Logic board: js/circuit_board_system.js, js/signal_system.js, signal-related item definitions/metadata, and the generated circuit editor markup/styles.
• Shared play: js/seesaw_system.js, tarinai action/need modules, placement preview, and item/structure definitions.
• Reset presets: js/world_reset_presets.js; UI reset selection is in js/ui_layout_dialogs.js; social archive reset/fallback routing touches js/world_family_social.js.
• Physics tool icons and previews: js/ui_tools.js, js/render.js, js/placement_preview_system.js, js/physics_shape_editor_system.js, and js/item_tool_metadata.js.

Cleanup Candidate Audit - resolved

The previous cleanup candidate queue has been applied or adjusted. Current state:

• Version/docs routing was aligned to 39.16.74; js/version.js build identity now matches the app version, and README.md no longer points at an older cache-query script URL.
• One-version and overlapping audit scripts from the candidate list were removed; the broad audit suite remains scripts/achievement_audit.js, scripts/playstyle_achievement_audit.js, scripts/achievement_integration_audit.py, scripts/achievement_server_state_audit.py, and scripts/regression_check.py.
• Shared scalar/object/clone/hash/text helpers now live on TarinaiCoreHelpers in js/deterministic_helpers.js; action, behavior, structure, snapshot, save, geometry, physics, seesaw, placement-preview, circuit, and signal code route repeated helper logic through that shared surface or through TarinaiGeometry.
• UI HTML escaping is owned by js/ui_helpers.js; consumers bind explicitly to TarinaiUIHelpers.htmlEscape, and index.html loads ui_helpers.js before the consumers that need it.
• js/achievements.js uses renderIfDialogOpen() for progress refreshes instead of repeating the hidden-dialog check at each event recorder.
• js/world_placement_log.js uses shared close/backdrop binding for editor dialogs; deeper editor extraction can still be done as feature work, but the repeated close process from the cleanup list is removed.
• FILES.json now includes JavaScript audit scripts and newer core bootstrap files (domain_ids, deterministic helpers, item registries/definitions) in machine routing.