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 — integer cents / discrete stocks
2. sim_tick_manager.gd — _physics_process tick accumulator
3. simulation_tick_controller.gd — speed / pause control surface

Original Expert Patterns

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

Modular Components

• simulation_tick_controller.gd - UI/speed wiring for the tick manager.
• economy_graph_manager.gd - Producer/consumer graph edges.
• npc_schedule_agent.gd - Schedule-driven NPC agents on ticks.
• 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 — integer cents, never float primary
Sim clock	MANDATORY sim_tick_manager.gd — accumulator on _physics_process
Speed UI	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
Heavy graph / path logistics	Offload with WorkerThreadPool; call_deferred UI — see simulation_patterns.gd / 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 + tycoon_economy.gd
Sim clock / speed	time-system.md + sim_tick_manager.gd
Workers & facilities	entity-management.md + npc_schedule_agent.gd
Demand & customers	customer-demand.md
Feedback & dashboards	feedback-systems.md
Unlock progression	progression-unlocks.md
Production graphs / CSV bake	elite-technical-patterns.md + 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.