Godot Genre Simulation Agent Skill

Godot 4.7 Baseline

• Expert patterns in this skill target Godot 4.7+ (stable, 2026-06-18).
• Consult the Godot 4.7 migration guide when upgrading projects from 4.6.
• NEVER assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.

Genre: Simulation / Tycoon

Optimization, systems mastery, and satisfying feedback loops define management games.

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

• 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.