Definitions and runtime instances

⚡

Guide

Distinguish reusable content definitions from live battle instances so runtime changes never become authoring-asset edits

Build battle state from authored definitions

The diagram above establishes the GCS data boundary. The Game Card Editor stores reusable content definitions. When an Encounter starts, runtime uses those definitions to create the units, cards, statuses, and piles for that battle. Live HP, costs, stack counts, and card locations belong only to their current instances and are not written back to authored assets

Unit definitions and unit state

Content	Stored data	Lifetime
GamePlayerUnit	Name, base HP, energy presentation, Starting Deck, Prefab, and art	Reusable project asset
GameEnemyUnit	Name, HP range, Tier, Prefab, Intent, and Behavior	Reusable project asset
UnitState	Current and maximum HP, Armor, team, alive state, status stacks, and active Hooks	Current battle
EnemyUnitState	All UnitState data plus the current Intent and Pattern progress	Current battle

When an enemy enters battle, its starting HP is chosen from the definition's inclusive range. Editing the original GameEnemyUnit in the Inspector afterward does not update an existing EnemyUnitState

Card definitions and card instances

Content	Stored data	Used for
GameCard	Name, description, base cost, type, rarity, Target, art, and Behavior	Content authoring, database queries, and deck configuration
CardInstance	Instance ID, base-card reference, upgrade state, and instance cost changes	Hand, draw pile, discard pile, and exhaust pile
Active Card	Base card or current upgraded variant	Card-face display and actual resolution
Effective Cost	Final result of base cost, Run modifiers, temporary rules, and cost Hooks	Play validation and battle UI

tip

Two copies of Strike can share one GameCard while remaining separate CardInstance objects in the piles. Upgrading one or changing its temporary cost does not affect the other

Runtime operations should receive instances; content browsing, deck configuration, and database lookup use definitions. See card and pile lifecycle for complete pile rules

Status definitions and unit stacks

GameStatus stores the name, description, icon, stack rule, cap, decay rule, and Behavior. During battle, UnitState records only which statuses that unit currently holds, how many stacks it has, and the known applier. Changing GameStatus.MaxStacks affects later status resolution, but changing the stacks already held by one unit requires a runtime entry. See status lifecycle for application, decay, and expiration rules

GameDeck, Master Deck, and battle piles

These three data layers serve authored configuration, cross-battle progression, and the current battle respectively

Layer	Purpose
GameDeck	Configure a player's Starting Deck or an Encounter's reward pool
Run Master Deck	Persist cards, upgrade state, and cost changes across battles in the same Run
Battle piles	Store the current battle's CardInstance objects and their ordered locations

A new battle creates its piles from the Run Master Deck or the player's Starting Deck. Changing the Master Deck after battle start does not retroactively alter those piles

Choose the correct data layer

Need	Object to modify
Change the base cost of every Strike created later	GameCard definition
Change the cost of one Strike in the current battle	Supported cost rules on that CardInstance
Change an enemy's authored HP range	GameEnemyUnit definition
Change the current enemy's HP	Modify EnemyUnitState through GCSApi or Controller
Change status stacking or decay rules	GameStatus definition
Change a status count currently held by one unit	Use the status API or a FlowGraph node
Change the deck used by future battles in the Run	Master Deck
Move a card in the current battle	Its CardInstance in the battle piles

Inspect live Play Mode data in Game Card Monitor. The Inspector shows authored definitions, not battle instances that have already been created

Read and modify safely

Project code should prefer named GCSApi methods:

• Read current state through methods such as Player(), AliveEnemies(), Hand(), and StatusesOn()

• Submit changes through methods such as DealDamage(), GainArmor(), ApplyStatus(), and MoveCardToPile()

• Modify state from custom nodes through ctx.Controller

tip

These entries run the corresponding Hooks, boundary checks, event notifications, and Monitor records. Directly editing fields or collections on live objects may produce a temporarily correct value while leaving other systems without a synchronization signal

See the API guide for complete code entry points and API reference for available members