godot-economy-system

$npx mdskill add thedivergentai/GD-Agentic-Skills/godot-economy-system

Designs robust game economies with currency, shops, and dynamic pricing.

  • Solves currency management, shop systems, and economic balance for games.
  • Depends on Godot 4.7+ and its built-in data structures.
  • Uses decision trees for currency representation and supply/demand logic.
  • Delivers expert patterns and code examples for immediate implementation.

SKILL.md

.github/skills/godot-economy-systemView on GitHub ↗
---
name: godot-economy-system
description: "Expert patterns for game economies including currency management (multi-currency, wallet system), shop systems (buy/sell prices, stock limits), dynamic pricing (supply/demand), loot tables (weighted drops, rarity tiers), and economic balance (inflation control, currency sinks). Use for RPGs, trading games, or resource management systems. Trigger keywords: EconomyManager, currency, shop_item, loot_table, dynamic_pricing, buy_sell_spread, currency_sink, inflation, item_rarity."
---

## Godot 4.7 Baseline

- Expert patterns in this skill target **Godot 4.7+** (stable, 2026-06-18).
- Consult the [Godot 4.7 migration guide](https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.7.html) 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.

# Economy System

Wallet + transaction authority — not beginner "gold int" tutorials.

## Decision Tree: Currency Representation

| Economy type | Store as | Why |
|--------------|----------|-----|
| Soft currency (gold, scrap) with UI decimals | **`int` cents / smallest unit** | Exact math; display `value / 100.0` |
| Premium / idle quantities >> 2^31 | **BigInt / multi-limb int** (or carefully scaled `float` only if approx OK) | 32-bit `int` caps ~2.1B |
| Multiplayer / persistent wallet | **Authoritative `int` (or BigInt) on server** | Client never finalizes spends |
| Prices with fractional display only | Still **int smallest unit** | Avoid `0.1 + 0.2` float drift |

**NEVER** mix "use float for money" and "never use float for money" without this tree — pick one column and stick to it.

## NEVER Do in Economy Systems

- **NEVER skip buy/sell spread** — Same buy/sell price = infinite money.
- **NEVER skip currency sinks** — Repairs, taxes, fees, consumables prevent inflation.
- **NEVER validate spends only on the client** — Server/host is source of truth in multiplayer.
- **NEVER hardcode loot weights in scripts** — Use Resources ([loot_table_weighted.gd](scripts/loot_table_weighted.gd)).
- **NEVER subtract before `current >= amount`** — Underflow / negative wallets corrupt saves.
- **NEVER let UI mutate balances directly** — UI requests; [wallet_manager_singleton.gd](scripts/wallet_manager_singleton.gd) / [transaction_manager.gd](scripts/transaction_manager.gd) decides.
- **NEVER ignore transaction logs in serious RPGs** — Audit trail for missing currency.
- **NEVER exceed max caps without clamping** — Cap before wrap / overflow.

---

## Golden Path (MANDATORY)

1. [currency_resource.gd](scripts/currency_resource.gd) — denomination metadata
2. [wallet_manager_singleton.gd](scripts/wallet_manager_singleton.gd) — balances + signals
3. [transaction_manager.gd](scripts/transaction_manager.gd) — validated spend/grant pipeline
4. Shop / loot / UI only after wallet+transactions exist

**Delete** ad-hoc `EconomyManager` gold tutorials — do not re-inline wallet logic in scenes.

## Decision Points → Scripts

| Task | Load | Do NOT Load |
|------|------|-------------|
| Balances / Autoload wallet | wallet_manager_singleton.gd | Inline gold ints on Player |
| Spend/grant validation | transaction_manager.gd | UI calling `gold -= n` |
| Shop buy/sell + stock | shop_item_data.gd + shop_system_logic.gd | Equal buy/sell prices |
| Sales / reputation pricing | dynamic_price_modifier.gd | — |
| Weighted loot | loot_table_weighted.gd | Hardcoded `%` in enemy scripts |
| Loot → wallet bridge | loot_drop_economy_bridge.gd | — |
| HUD sync | currency_label_sync.gd | Polling wallet in `_process` without signals |
| Save wallet | economy_persistence_handler.gd | — |
| Pickup VFX | currency_pickup_effect.gd | — |
| Multi-item barter | trade_contract_resource.gd | — |

## Available Scripts (full catalog)

- [currency_resource.gd](scripts/currency_resource.gd)
- [wallet_manager_singleton.gd](scripts/wallet_manager_singleton.gd) — **MANDATORY**
- [transaction_manager.gd](scripts/transaction_manager.gd) — **MANDATORY**
- [shop_item_data.gd](scripts/shop_item_data.gd)
- [shop_system_logic.gd](scripts/shop_system_logic.gd)
- [dynamic_price_modifier.gd](scripts/dynamic_price_modifier.gd)
- [currency_label_sync.gd](scripts/currency_label_sync.gd)
- [loot_table_weighted.gd](scripts/loot_table_weighted.gd) — weights / rarity
- [loot_drop_economy_bridge.gd](scripts/loot_drop_economy_bridge.gd) — Do NOT Load if loot never grants currency
- [economy_persistence_handler.gd](scripts/economy_persistence_handler.gd)
- [currency_pickup_effect.gd](scripts/currency_pickup_effect.gd)
- [trade_contract_resource.gd](scripts/trade_contract_resource.gd) — Do NOT Load unless barter exists
- [economy_logger.gd](scripts/economy_logger.gd) — GPM / inflation telemetry Logger
- [item_value_estimator.gd](scripts/item_value_estimator.gd) — rarity-based merchant valuation

## Elite Deltas

- **Barter contracts:** multi-item quid-pro-quo via [trade_contract_resource.gd](scripts/trade_contract_resource.gd).
- **GPM analytics:** [economy_logger.gd](scripts/economy_logger.gd) — gold-per-minute from `[ECON]` log lines.
- **Value estimator:** [item_value_estimator.gd](scripts/item_value_estimator.gd) — rarity-driven sell curves; always below buy.

> **MANDATORY** for GPM logging, dynamic valuation, and moved shop/loot tutorials: [economy-elite-patterns.md](references/economy-elite-patterns.md). **Do NOT Load** for wallet + transaction golden path only.

## 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
- [Resources](https://docs.godotengine.org/en/stable/tutorials/scripting/resources.html) — Currencies, shop items, loot tables, and trade contracts belong as shareable `Resource` assets so designers can retune prices and drop weights without code changes.
- [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) — Use `duplicate()` when applying runtime price modifiers or per-merchant stock so one shop cannot mutate the shared `.tres` template for every vendor.
- [GDScript exports](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_exports.html) — `@export` buy/sell spreads, stock caps, currency ids, and loot weights so economy balance stays Inspector-driven.
- [Singletons (Autoload)](https://docs.godotengine.org/en/stable/tutorials/scripting/singletons_autoload.html) — A WalletManager Autoload is the engine-supported pattern for balances that must survive scene changes (world ↔ shop ↔ menu).
- [Autoloads versus regular nodes](https://docs.godotengine.org/en/stable/tutorials/best_practices/autoloads_versus_regular_nodes.html) — Keep global wallet state in Autoload; keep merchant UI and one-off shop logic as scene nodes so tests and multiplayer authority stay composable.
- [Using signals](https://docs.godotengine.org/en/stable/getting_started/step_by_step/signals.html) — Emit `balance_changed` / `transaction_failed` so HUD labels and pickup VFX subscribe without writing wallet balances from the UI.
- [Saving games](https://docs.godotengine.org/en/stable/tutorials/io/saving_games.html) — Persist wallet dictionaries (and stocked shop state) with the rest of progression data; never leave soft currency only in memory.
- [FileAccess](https://docs.godotengine.org/en/stable/classes/class_fileaccess.html) — Read/write save payloads that include economy blobs; pair with project `user://` paths for player-writable balance files.
- [JSON](https://docs.godotengine.org/en/stable/classes/class_json.html) — Serialize `currency_id → amount` dictionaries as JSON-compatible structures for transparent save/load and analytics dumps.
- [Random number generation](https://docs.godotengine.org/en/stable/tutorials/math/random_number_generation.html) — Weighted loot and drop rolls must use Godot RNG APIs (`randf`, seeded RNG) rather than ad-hoc modulo hacks.
- [RandomNumberGenerator](https://docs.godotengine.org/en/stable/classes/class_randomnumbergenerator.html) — Seedable RNG instances make loot-table Monte Carlo and deterministic balance tests reproducible.
- [High-level multiplayer](https://docs.godotengine.org/en/stable/tutorials/networking/high_level_multiplayer.html) — Spend/grant validation must be authoritative on the server; clients request transactions and apply confirmed balance RPCs only.

### Related Skills

#### Prerequisites
- [godot-resource-data-patterns](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-resource-data-patterns/SKILL.md) — Currency, ShopItem, LootTable, and TradeContract definitions are Resource-first; load this before inventing parallel data formats for prices and drops.
- [godot-autoload-architecture](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-autoload-architecture/SKILL.md) — WalletManager as Autoload needs disciplined ownership, init order, and namespacing so economy state does not become a god-object dump.
- [godot-signal-architecture](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-signal-architecture/SKILL.md) — Balance and transaction signals must stay “signal up / call down” so UI never mutates the wallet directly.
- [godot-gdscript-mastery](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-gdscript-mastery/SKILL.md) — Typed Resources, Dictionary wallets, and atomic purchase helpers assume solid GDScript patterns (guards before subtract, no float money).

#### Complements
- [godot-inventory-system](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-inventory-system/SKILL.md) — Buy/sell and barter are atomic wallet↔inventory exchanges; stock and capacity checks belong with inventory, not only with price math.
- [godot-save-load-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-save-load-systems/SKILL.md) — Economy persistence handlers should plug into the project save schema (versioning, migrate, encrypt premium balances if needed).
- [godot-rpg-stats](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-rpg-stats/SKILL.md) — Charisma/reputation discounts and sink costs (repairs) need a consistent modifier layer rather than hardcoding multipliers in the shop UI.
- [godot-ui-containers](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-ui-containers/SKILL.md) — Shop screens and currency HUD layouts should bind to wallet signals; containers own presentation, WalletManager owns truth.
- [godot-quest-system](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-quest-system/SKILL.md) — Quest gold rewards and turn-in sinks are major currency sources/sinks; wire rewards through the transaction API, not ad-hoc `gold +=`.
- [godot-combat-system](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-combat-system/SKILL.md) — Loot-drop bridges listen to combat/loot events and grant funds without embedding economy rules inside damage pipelines.

#### Downstream / consumers
- [godot-monte-carlo-balancer](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-monte-carlo-balancer/SKILL.md) — After sinks, loot weights, and shop spreads are Resource-driven, Monte Carlo farm/career sims prove inflation and time-to-afford bands before shipping curves.
- [godot-multiplayer-networking](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-multiplayer-networking/SKILL.md) — Predicted UI spends and authoritative grant/spend RPCs build on the wallet’s request/validate/apply split.
- [godot-genre-idle-clicker](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-genre-idle-clicker/SKILL.md) — Idle/prestige currencies and sink loops assemble this skill with long-horizon balance and offline accrual genre glue.
- [godot-genre-action-rpg](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-genre-action-rpg/SKILL.md) — Action-RPG shops, crafting sinks, and drop economies compose wallet + inventory + loot tables for progression pacing.

#### Master
- [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) — Library router and mirrored module entry; use when discovering peer skills or syncing shared script mirrors after Domain Skill edits.

More from thedivergentai/GD-Agentic-Skills

SkillDescription
godot-2d-animationExpert patterns for 2D animation in Godot using AnimatedSprite2D and skeletal cutout rigs. Use when implementing sprite frame animations, procedural animation (squash/stretch), cutout bone hierarchies, or frame-perfect timing systems. Trigger keywords: AnimatedSprite2D, SpriteFrames, animation_finished, animation_looped, frame_changed, frame_progress, set_frame_and_progress, cutout animation, skeletal 2D, Bone2D, procedural animation, animation state machine, advance(0).
godot-2d-physicsExpert patterns for Godot 2D physics including collision layers/masks, Area2D triggers, raycasting, and PhysicsDirectSpaceState2D queries. Use when implementing collision detection, trigger zones, line-of-sight systems, or manual physics queries. Trigger keywords: CollisionShape2D, CollisionPolygon2D, collision_layer, collision_mask, set_collision_layer_value, set_collision_mask_value, Area2D, body_entered, body_exited, RayCast2D, force_raycast_update, PhysicsPointQueryParameters2D, PhysicsShapeQueryParameters2D, direct_space_state, move_and_collide, move_and_slide.
godot-3d-lightingExpert patterns for Godot 3D lighting including DirectionalLight3D shadow cascades, OmniLight3D attenuation, SpotLight3D projectors, VoxelGI vs SDFGI, and LightmapGI baking. Use when implementing realistic 3D lighting, shadow optimization, global illumination, or light probes. Trigger keywords: DirectionalLight3D, OmniLight3D, SpotLight3D, shadow_enabled, directional_shadow_mode, directional_shadow_split, omni_range, omni_attenuation, spot_range, spot_angle, VoxelGI, SDFGI, LightmapGI, ReflectionProbe, Environment, WorldEnvironment.
godot-3d-materialsExpert patterns for Godot 3D PBR materials using StandardMaterial3D including albedo, metallic/roughness workflows, normal maps, ORM texture packing, transparency modes, and shader conversion. Use when creating realistic 3D surfaces, PBR workflows, or material optimization. Trigger keywords: StandardMaterial3D, BaseMaterial3D, albedo_texture, metallic, metallic_texture, roughness, roughness_texture, normal_texture, normal_enabled, orm_texture, transparency, alpha_scissor, alpha_hash, cull_mode, ShaderMaterial, shader parameters.
godot-3d-world-buildingExpert patterns for 3D level design using GridMap with MeshLibrary, CSG constructive solid geometry, occlusion, and runtime GridMap builders. Use when building 3D levels, modular tilesets, or BSP-style geometry. For sky/fog/Environment recipes, route to godot-3d-lighting. Trigger keywords: GridMap, MeshLibrary, set_cell_item, get_cell_item, map_to_local, local_to_map, CSGCombiner3D, CSGBox3D, CSGSphere3D, CSGPolygon3D, OccluderInstance3D, bake CSG.
godot-ability-systemExpert patterns for RPG/action ability systems including cooldown strategies, combo systems, ability chaining, skill trees with prerequisites, upgrade paths, and resource management. Use when implementing unlockable abilities, character progression, or complex skill systems. Trigger keywords: PlayerAbility, AbilityManager, cooldown, SkillTree, SkillNode, prerequisites, can_use, execute, ComboSystem, ability_chain, global_cooldown, charge_system, upgrade_path.
godot-adapt-2d-to-3dExpert patterns for migrating 2D games to 3D including node type conversions, camera systems (third-person, first-person, orbit), physics layer migration, sprite-to-model art pipeline, and control scheme adaptations. Use when porting 2D projects to 3D or adding 3D elements. Trigger keywords: CharacterBody2D to CharacterBody3D, Area2D to Area3D, Camera2D to Camera3D, Vector2 to Vector3, collision_layer migration, sprite to MeshInstance3D, 2D to 3D conversion.
godot-adapt-3d-to-2dExpert patterns for simplifying 3D games to 2D including dimension reduction strategies, 2.5D fake-depth, isometric ports, camera flattening, physics conversion, 3D-to-sprite art pipeline, and control simplification. Use when porting 3D to 2D, building 2.5D / isometric / fake-depth gameplay, creating 2D versions for mobile, or prototyping. Trigger keywords: CharacterBody3D to CharacterBody2D, Camera3D to Camera2D, Vector3 to Vector2, flatten Z-axis, 2.5D, isometric, fake depth, Y-sort, simulated Z, orthogonal projection, 3D to sprite conversion, performance optimization.
godot-adapt-desktop-to-mobileExpert patterns for porting desktop games to mobile including touch control schemes (virtual joystick, gesture detection), UI scaling for small screens, performance optimization for mobile GPUs, battery life management, and platform-specific features. Use when creating mobile ports or cross-platform mobile builds. Trigger keywords: TouchScreenButton, virtual_joystick, gesture_detector, InputEventScreenTouch, InputEventScreenDrag, mobile_optimization, battery_saving, adaptive_performance, MOBILE_ENABLED.
godot-adapt-mobile-to-desktopExpert patterns for scaling mobile games to desktop including mouse/keyboard controls, increased resolution and graphical fidelity, expanded UI layouts, settings menus, window management, and platform-specific features. Use when creating desktop ports or cross-platform releases. Trigger keywords: mouse_controls, keyboard_shortcuts, resolution_scaling, graphics_settings, fullscreen_toggle, window_modes, Steam_integration, desktop_optimization.