Currency System

Description

The Currency System introduces collectible resources that players can gather and spend on building, upgrading, and unlocking game features. It uses an ECS-based design with components for managing currencies, handling collection, and updating the UI. Three types of currencies exist: Metal Scrap (common), Titanium Core (rare), and Neurochip (epic). A factory ensures consistent entity creation, while event-driven updates keep the UI in sync.

Key Components

CurrencyComponent

A component that stores the type and value of a currency item. Each CurrencyComponentis associated with exactly one CurrencyType. For example, a metal scrap worth 1 unit would be represented here.

• Method getType returns the type of this currency.
• Method getValue returns the currency value.

CollectibleComponent

A component that makes an entity collectible by the player. It checks for clicks near the entity and, if collected, triggers events such as collectCurrencyso that the manager can update totals.

• Method update handles player interaction for collecting the entity.
• Method getCamera gets the camera from the current Renderer.
• Method isCollected returns true if the component has been collected, false otherwise.

CurrencyManagerComponent

A component that tracks all the currencies collected by the player. It maintains a list of currency entities and a map of CurrencyType → amount. It listens for collectCurrencyevents and updates the player’s currency balance. It also triggers the updateScrap event to refresh the UI display.

• Method addCurrencyAmount adds a specified amount of the given currency type.
• Method subtractCurrencyAmount subtracts a specified amount of the given currency type.
• Method getCurrencyAmount returns the current amount of the specified currency or 0 if none exists.
• Method addCurrencyEntity adds the currency entity to the list if it is not already present.
• Method getCurrencyList returns the current list of currency entities.
• Method collectCurrency increments the counter and triggers to update UI.
• Method dropCurrency updates currency amount on UI when enemy drop currency.
• Method canAffordAndSpendCurrency deducts the player's currencies according to the cost map if the player can afford it; otherwise, it returns false and leaves the currencies unchanged.
• Method refundCurrency refunds a portion of the cost according to the specified refund rate.
• Method updateCurrencyUI updates UI rendering for a specific currency type.
• Method updateAllCurrencyUI updates UI rendering for all currency types.

CurrencyFactory

A utility class for creating currency entities. It combines CurrencyComponent, CollectibleComponent, and rendering into a complete Entity.

• Method createCurrency creates a new currency entity with the given parameters and returns a fully initialized currency entity.

CurrencyType (enumeration)

An enum representing the different types of currency in the game, currently it includes METAL_SCRAP.

Design Process

• Factory Pattern → CurrencyFactory encapsulates creation logic, ensuring consistency and easier extension.

• Observer Pattern → Event system decouples collectCurrency from UI updates.

• Component Pattern (ECS) → Flexible entity composition with CurrencyComponent, CollectibleComponent, etc.

• MVC Separation → Game logic (currency) is independent of UI rendering.

Currency Types

Metal Scrap (Common)

A basic and plentiful resource, scavenged from the battlefield. Useful for early upgrades and essential constructions.

Titanium Core (Rare)

A rare and valuable resource, often obtained from tougher enemies. Needed for powerful upgrades and advanced technology.

Neurochip (Epic)

A highly advanced implant once designed to enhance human intelligence, now repurposed by AI to control and outsmart its creators. Extremely rare and vital for high-level upgrades.

UML Diagram

• Component: The superclass for all components in the game.

Test Plan

https://github.com/UQcsse3200/2025-studio-4/wiki/Currency-System's-Test-Plan