Skill v1.0.2

version: "1.0.2" name: godot-genre-simulation description: "Expert blueprint for simulation and tycoon games (SimCity, RollerCoaster Tycoon, Factorio, Two Point Hospital) covering economy management, time progression, interconnected systems, NPC simulation, and feedback loops. Use when building management sims, tycoon games, city builders, or resource optimization games. Keywords tycoon, economy system, resource management, time scale, feedback loop, progression unlock, simulation tick."

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)

Tick rate vs UI vs threads

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

Skill Chain

Common Pitfalls

Deep recipes (on demand)

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.