more

docs/ARCHITECTURE.md

@@ -0,0 +1,31 @@
+# Architecture
+
+Build target: static browser page. No bundler. Globals and ordered deferred scripts are intentional.
+
+## Load order
+
+`app_manifest.json` owns CSS/JS order. Regenerate `index.html` and `service-worker.js` with `python3 scripts/generate_app_files.py` after version/order changes. `js/version.js` exposes `TARINAI_APP.version`, cache name, and query helper.
+
+## Runtime objects
+
+- `World`: constructor in `js/world.js`; methods split into view, family/social, combat/effects, environment, spatial/budget, ants, update, placement/log, bootstrap.
+- `Tarinai`: constructor in `js/tarinai.js`; methods split into identity/social, disease/nest, item effects, needs/items, social/move/life, render.
+- `Item`: item state, lifecycle, scaling, and field rendering in `js/items.js`.
+- `Effect`: transient visuals in `js/sim_core.js`; combat/weather/food effects are spawned through `World` helpers.
+- `TarinaiEvents`: global event bus for logs, terrain dirtiness, audio failures, phase/performance changes.
+- `TarinaiPerformance`: FPS quality manager; provides effect caps, ant stride, terrain redraw cadence, UI intervals.
+
+## Data ownership
+
+- `js/data.js`: item/tool definitions, config, image metrics, field presets.
+- `js/text_catalog.js`: Japanese UI copy/tooltips. Keep JS strings escaped where existing style uses escapes.
+- `js/effect_registry.js`: item-effect display names, exclusivity, random-effect candidates, UI colors.
+- `js/sound_pack.js`: sound IDs, category, volume multiplier, cooldown, optional sample path.
+
+## State loops
+
+`main.js` starts asset preload, world bootstrap, animation loop, deferred image loading, service-worker registration. `World.update(dt)` advances time, weather, items, ants, Tarinai, effects, budgets, terrain dirtiness. `render()` draws cached background/terrain, visible entities, weather overlay, cards, HUD, and debug overlays.
+
+## Spatial/performance rules
+
+Use `World.nearby*` helpers rather than full-array scans in hot paths. Terrain cache uses dirty/version flags; do not reintroduce every-frame full terrain hashing. Performance degradation should be centralized in `performance_manager.js`.