godot-genre-simulation

NEVER Do (Expert Anti-Patterns)

Simulation & Economy

• NEVER use floating-point for primary currency; strictly use Integer Cents (or fixed-point math) to prevent accumulated precision errors in financial models.
• NEVER process 1000+ entities individually in _process(); strictly use a Tick Manager to batch updates or process entities in rotating pools.
• NEVER rely on linear cost scaling; strictly use Exponential Growth (Base * pow(1.15, Level)) to maintain challenge and strategic tension.
• NEVER hide critical metrics from the player; strictly provide Detailed Breakdowns (Income vs. Expense) so players can make optimization-based decisions.
• NEVER allow infinite resource stacking; strictly enforce Logistical Caps (warehouses/silos) to create meaningful space-management gameplay loops.
• NEVER let the early game become a "Waiting Simulator"; strictly Front-Load Decisions and quick early wins to build player momentum.
• NEVER modify a shared Resource directly; strictly use duplicate() to avoid unintentionally updating every building of that type.
• NEVER tie simulation logic to the visual framerate; strictly use _physics_process() or delta accumulators for deterministic simulation results.

Performance & Threading

• NEVER update UI labels every frame; strictly use Event-Driven Signals to refresh UI ONLY when the underlying data changes.
• NEVER run heavy economic loops synchronously; strictly use WorkerThreadPool to offload complex calculations and prevent UI stutters.
• NEVER store massive resource data as Nodes; strictly use RefCounted or Data Resources to avoid the memory/CPU overhead of the SceneTree.
• NEVER ignore OS.low_processor_usage_mode; strictly enable it for stationary management screens to save massive CPU/Battery life.
• NEVER manipulate the SceneTree from background threads; strictly use call_deferred() for thread-safe UI updates.
• NEVER parse large JSON save files on the main thread; strictly use Threaded Serialization or optimized binary .res formats.
• NEVER use standard equality (==) for needs; strictly use is_equal_approx() to prevent floating-point jitter failures in logic gates.

---

🛠 Expert Components (scripts/)

> MANDATORY reads before implementing the matching system:

> 1. [tycoon_economy.gd](scripts/tycoon_economy.gd) — integer cents / discrete stocks

> 2. [sim_tick_manager.gd](scripts/sim_tick_manager.gd) — _physics_process tick accumulator

> 3. [simulation_tick_controller.gd](scripts/simulation_tick_controller.gd) — speed / pause control surface

Original Expert Patterns

• [tycoon_economy.gd](scripts/tycoon_economy.gd) - Multi-resource economy with integer currency (cents).
• [sim_tick_manager.gd](scripts/sim_tick_manager.gd) - Framerate-decoupled game-hour ticks on physics.

Modular Components

• [simulation_tick_controller.gd](scripts/simulation_tick_controller.gd) - UI/speed wiring for the tick manager.
• [economy_graph_manager.gd](scripts/economy_graph_manager.gd) - Producer/consumer graph edges.
• [npc_schedule_agent.gd](scripts/npc_schedule_agent.gd) - Schedule-driven NPC agents on ticks.
• [simulation_patterns.gd](scripts/simulation_patterns.gd) - CSV→Resource bake, AStarGrid2D logistics, low_processor helpers.

---

Core Loop

1. Place/build → 2. Tick economy → 3. Read income vs expense → 4. Unlock / expand → 5. Optimize logistics

Decision Trees

Currency & time (must match NEVER)

| Need | Action |

|------|--------|

| Money / wallets | MANDATORY [tycoon_economy.gd](scripts/tycoon_economy.gd) — integer cents, never float primary |

| Sim clock | MANDATORY [sim_tick_manager.gd](scripts/sim_tick_manager.gd) — accumulator on _physics_process |

| Speed UI | [simulation_tick_controller.gd](scripts/simulation_tick_controller.gd) |

Tick rate vs UI vs threads

| Entity / load | Strategy |

|---------------|----------|

| < ~200 entities | Tick signal → direct update; UI via resource_changed only |

| Hundreds of agents | Rotate pools per tick; [npc_schedule_agent.gd](scripts/npc_schedule_agent.gd) |

| Heavy graph / path logistics | Offload with WorkerThreadPool; call_deferred UI — see [simulation_patterns.gd](scripts/simulation_patterns.gd) / [economy_graph_manager.gd](scripts/economy_graph_manager.gd) |

| Stationary management screens | Enable OS.low_processor_usage_mode |

Do not re-inline TycoonEconomy / SimulationTime / Worker tutorials — load the scripts.

Skill Chain

| Phase | Skills | Purpose |

|-------|--------|---------|

| 1. Data | resources, godot-economy-system | Stocks / sinks |

| 2. Time | tick manager | Deterministic hours |

| 3. Agents | schedules / nav | NPCs & logistics |

| 4. Perf | WorkerThreadPool | Heavy ticks |

| 5. Balance | godot-monte-carlo-balancer | Bankruptcy / growth bands |

Common Pitfalls

| Pitfall | Solution |

|---------|----------|

| Float money | Integer cents in tycoon_economy |

| _process sim step | Physics accumulator tick manager |

| UI every frame | Signal on resource_changed only |

Deep recipes (on demand)

| Topic | Reference / script |

|-------|-------------------|

| Economy & wallets | [economy-design.md](references/economy-design.md) + [tycoon_economy.gd](scripts/tycoon_economy.gd) |

| Sim clock / speed | [time-system.md](references/time-system.md) + [sim_tick_manager.gd](scripts/sim_tick_manager.gd) |

| Workers & facilities | [entity-management.md](references/entity-management.md) + [npc_schedule_agent.gd](scripts/npc_schedule_agent.gd) |

| Demand & customers | [customer-demand.md](references/customer-demand.md) |

| Feedback & dashboards | [feedback-systems.md](references/feedback-systems.md) |

| Unlock progression | [progression-unlocks.md](references/progression-unlocks.md) |

| Production graphs / CSV bake | [elite-technical-patterns.md](references/elite-technical-patterns.md) + [simulation_patterns.gd](scripts/simulation_patterns.gd) |

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Idle and physics processing — Simulation clocks and economy ticks must accumulate with delta (or a dedicated tick), never frame-count assumptions.
• Using signals — Emit resource/tick changes so dashboards refresh only when wallets or hours actually change.
• Resources — Recipes, facilities, and unlock tables belong as .tres Resources so designers retune chains without code edits.
• GDScript exports — @export build costs, wages, and growth bases so balance sheets stay Inspector-driven.
• Saving games — Persist stocks, day/hour, unlocks, and facility graphs so long management sessions survive restarts.
• Data paths — Keep large binary/JSON sim saves under user:// across platforms.
• Using multiple threads — Heavy production-graph and upkeep passes belong on WorkerThreadPool, not the main-thread UI loop.
• Thread-safe APIs — Marshaling sim results to Labels/Tree requires call_deferred / main-thread SceneTree rules.
• WorkerThreadPool — API for batching economy ticks without blocking manager screens.
• OS — Enable OS.low_processor_usage_mode on stationary management UIs to cut CPU/battery burn.
• AStarGrid2D — Grid logistics and worker paths on factory floors without manually wiring AStar points.
• Using NavigationServers — Direct NavigationServer3D.map_get_path queries for schedule-driven NPCs without per-agent node overhead.

Related Skills

Prerequisites

• godot-project-foundations — Autoloads, Resources, and scene structure before building tick managers and economy graphs.
• godot-gdscript-mastery — Typed Dictionaries, signals, is_equal_approx, and fixed-point-safe math for currency and needs.
• godot-resource-data-patterns — Production recipes and unlock tables should be Resource-first .tres assets, not hard-coded Node trees.
• godot-signal-architecture — Tick and resource_changed buses must drive UI without Labels mutating the simulation wallet.

Complements

• godot-economy-system — Soft-currency wallets, sinks, and transaction ledgers that compose with tycoon multi-resource stocks.
• godot-save-load-systems — Versioned serialization for large world states, binary store_var, and threaded save/load.
• godot-navigation-pathfinding — NavigationServer / grid pathing for worker jobs and schedule agents after the tick clock exists.
• godot-performance-optimization — Entity batching, low-processor mode, and thread offload budgets for 1000+ sim entities.
• godot-autoload-architecture — TimeManager / Economy autoloads that survive scene reloads need clear ownership rules.
• godot-ui-containers — Income/expense dashboards and facility lists are Tree/VBoxContainer layouts bound to throttled signals.

Downstream / consumers

• godot-monte-carlo-balancer — After cost curves, production yields, and CSV→.tres balance sheets exist, Monte Carlo career sims prove minutes-to-milestone and bankruptcy bands before shipping growth factors.
• godot-genre-idle-clicker — Offline catch-up and prestige loops reuse tick + integer-currency patterns from management sims.
• godot-genre-rts — Build-order economies and worker logistics consume the same tick/graph and pathfinding primitives at combat scale.

Master

• godot-master — Library router and mirrored module entry; use when discovering peer skills or syncing shared script mirrors after Domain Skill edits.