Economy System

Team 7 | Core API: stable, Persistence: confirmed with Team 4 | Issues: #10

Overview

This page describes how other teams interact with the player's gold resource. The component is InventoryComponent — it tracks the player's gold, exposes safe spend/add methods for the shop and reward systems, and enforces a hard floor of 0 (gold can never go negative).

There's no separate inventory class for enemies — InventoryComponent is player-only, attached directly by PlayerFactory.

Quick Start

Real game (inside a GameArea)

Entity player = PlayerFactory.createPlayer();
InventoryComponent inventory = player.getComponent(InventoryComponent.class);

Tests / isolated usage — no factory needed

Entity entity = new Entity();
InventoryComponent inventory = new InventoryComponent(/* gold */ 100);
entity.addComponent(inventory);

inventory.subtractGold(40);   // deducts gold if affordable
inventory.addGold(20);        // adds gold (also accepts negative deltas)

Core Economy API

Method	Description
InventoryComponent(int gold)	Initializes with the given starting gold, floored at 0
int getGold()	Current gold
Boolean hasGold(int gold)	Read-only check for whether current gold covers the amount. Does not modify state
void setGold(int gold)	Sets gold directly, clamped to a minimum of 0. Fires updateGold
void addGold(int gold)	Adds to gold; accepts negative deltas (e.g. for effects that drain gold). Result is clamped at 0
boolean subtractGold(int amount)	Deducts gold if affordable. Fails safely (no state change, returns false) if insufficient funds or amount is negative

Persistence

Per the sprint spec, the Player entity (and therefore this component) must remain the same instance across node/room transitions — gold should never reset or be recreated when moving between combat and the map.

Confirmed with Team 4 (Discord, 2026.08.31): the map system currently only manages node generation, connections, and progression state — it does not create or recreate the Player entity during node transitions, and there is no map-side save/load mechanism. As a result, InventoryComponent state (gold) persists automatically across rooms without additional save/load logic.

This was verified with an automated test (shouldRetainGoldAcrossSimulatedNodeTransition) confirming the same InventoryComponent instance is retained across a simulated transition.

Open Questions

Should shop purchases use subtractGold() or addGold(-price)? Open — the two behave differently on insufficient funds. Recommend standardizing on subtractGold() for anything that should be able to fail (purchases), and reserving addGold() for gains and effects that shouldn't block gameplay.

Does gold need a naming-convention pass to match EnergyComponent's canAfford()? hasGold() here is equivalent to canAfford() on EnergyComponent. Not blocking, but worth aligning naming across resource components for consistency if other teams expect it.

Where to Get It

Currently on: Feature-7 Contact: Keira0206 (Team 7)

Related Pages

• Energy System
• Combat Stats System
• Player API
• Event System
• Components