Player Party
Configure up to three players and choose action sources and targets while sharing turns, card piles, and energy
Assign up to three Player Units to a GameEncounter. Each member has their own HP, armor, statuses, Hooks, and view. The default party takes one shared turn and uses the same cards and energy.
The diagram follows the party from Encounter setup to card play. The Encounter places each member in a slot. During battle, the active member plays a card from the shared hand. FlowGraph and events use unit IDs to identify the member acting and the units affected.
Build the initial party with an Encounter
In Encounter mode, add members to Player Units in the order they should appear. Row 1 is the primary player. Rows 2 and 3 fill the remaining slots.
| Setting | Runtime result |
|---|---|
Player Units[0] | Creates the primary player in slot 0, legacy PlayerUnit and GCSApi.Player() return this member |
Player Units[1..2] | Creates additional PlayerUnitState instances in row order |
| Row order | Maps directly to scene slots 0, 1, and 2 without separate slot configuration |
Check the party to the left of VS in the Encounter preview. Workbench reports missing members, too many players, and invalid or duplicate slots.
Identify members throughout the battle
| Identity | Purpose |
|---|---|
UnitId | Identifies one battle instance, creating the same Player Unit asset twice produces different IDs |
Team / TeamId | Determines ally and opponent relationships, built-in players and enemies use Player and Enemy |
SlotIndex | Maps the runtime unit to a visible slot on its side |
JoinOrder | Preserves arrival order, reinforcements and primary-player changes do not reorder other members |
Use GCSApi.Player() for the primary player and GCSApi.ActivePlayer() for the current action source. GCSApi.PlayerParty() includes living and dead members. To query one group, use AlivePlayers() or DeadPlayers().
Complete one turn as a party
By default, the party shares one player phase per turn. GCS prepares each member's armor, statuses, and triggers, then refreshes energy and draws once for the whole party. Switch members and play cards during this phase, then click End Turn to pass play to the enemies. SkipNextTurns affects individual members, so other living members can still act. The party turn ends immediately if every living member is skipped.
Surviving members can continue after the primary player dies. The default policy declares defeat when all members die. It checks for victory after the Encounter has had at least one enemy, so an empty battlefield can start and spawn its first enemy later.
For ordered actions, set BattlePolicySet.ActivationPolicy to OrderedPartyActivationPolicy and pass the set to GCSApi.StartBattle. GCS fills in omitted policies before creating units and cards. During the battle, call EndActivePlayerActivation() to finish one member's action and advance to the next. ActivePolicies is read-only, so pass a new set to the next battle to change the rules.
| Policy | Rule |
|---|---|
IPartyActivationPolicy | Free selection or ordered member activation |
IAutomaticPartyActivationPolicy | Automatic companion actions during ordered turns |
IActionWindowPolicy | Phases that accept player card requests |
IReactionWindowPolicy | Pausable reaction windows before enemy actions |
ICardPlayPolicy | Project rules for action sources and card permission |
IUnitTargetPolicy | Default opposing targets resolved without relying on the selected view |
IBattleResultPolicy | Whether the battle enters victory or defeat |
Share cards and energy
The party shares energy and four piles: Hand, Draw, Discard, and Exhaust. Draws, reshuffles, hand limits, and energy changes apply to the party.
When the persistent Master Deck is empty, the primary player's Starting Deck supplies the shared Draw pile. To use another member's Starting Deck in a different Encounter, put that member in the first row.
OwnerUnitId identifies the card's original owner. Other eligible members can play that card from the shared hand.
Specify the card's action source
TryPlayCard(card, target) uses ActivePlayer() as the action source. FlowGraph Self, source Hooks, and card-play events use that member, while the card keeps its OwnerUnitId. To choose the source directly, submit the SourceUnit and target through CardPlayRequest. Confirm that at least two party members are alive before selecting the second living member by index.
PlayerUnitState member = GCSApi.AlivePlayers()[1] as PlayerUnitState;
GCSApi.TrySetActivePlayerUnit(member);
foreach (CardInstance card in GCSApi.Hand(member))
{
var request = new CardPlayRequest(card, member, GCSApi.FirstAliveEnemy());
if (GCSApi.GetEffectiveEnergyCost(card) <= GCSApi.Energy(member)
&& GCSApi.CanPlayCard(request))
{
GCSApi.TryPlayCard(request);
}
}
After a successful play, CardInstance.LastPlayContext records the origin pile, owner, source, and targets. OnCardPlayed exposes those IDs for UI and statistics.
Target allies and relative teams
Use Card Target to control who the player can select. The Demo highlights eligible targets for single-unit selection. Group and random modes resolve when you play the card.
| Card Target | Player input | Behavior source |
|---|---|---|
Single Ally | Select any living ally, including the source | Use the submitted Target or target port, Opponent does not select an ally |
Other Ally | Select a living ally other than the source | Use the submitted Target, the runtime rejects the source itself |
All Allies | No single-target input | All Allies |
Random Ally | No single-target input | Selects one living ally and supplies it through Target |
Random Opponent | No single-target input | Selects one living unit on the source's opposing side and supplies it through Target |
Any Unit | Select any living player or enemy | Use the submitted Target without a team restriction |
FlowGraph resolves All Allies and All Opponents relative to the host. Use Active Player to get the selected living player and All Dead Allies to find revival targets. See Target selection for how the card's target reaches its Behavior.
Reinforce, replace, and revive members
Spawn Unit uses Team to create a player or enemy. A player reinforcement fills a slot within the three-player limit, uses the shared cards and energy, and fires OnPlayerUnitAdded.
ReplacePlayer swaps a member in the same slot. Despawn Unit removes the unit and fires OnUnitRemoved. A unit that dies stays in its slot and fires OnUnitDied. A successful Revive Unit fires OnUnitRevived.
PlayerUnitState joined = GCSApi.SummonPlayer(playerDefinition, 2, GCSApi.ActivePlayer());
if (joined != null)
GCSApi.SetEnergy(joined, GCSApi.MaxEnergyFor(joined));
PlayerUnitState replacement = GCSApi.ReplacePlayer(joined, replacementDefinition);
GCSApi.RemoveUnit(replacement);
Use revival on a dead member who is still in the party. When a member leaves or is replaced, the remaining members keep their shared piles and energy.
The Demo BattleBoard updates the unit views when party membership or the active player changes. Single-character scenes expand Player Area when members join. Party Showcase and scenes created with Initialize System have all three child slots.
Verify the party in Party Showcase
Open Demo/Scenes/Multi-Character/Party Showcase and enter Play Mode. Confirm that Scout, Squire, and Apprentice face Plague Stalker, Spore Brute, and Mire Reaper. The party has one hand and one energy display.

Player Unit 1, Scout, supplies Party Tactics for the shared eight-card pool
- Check that each player slot displays HP, armor, and statuses
- Select different members and check the active player and energy display
- Switch members before playing an attack from
Party Tactics, check that shared energy pays the cost, the selected member becomesSourceUnit, and the originalOwnerUnitIdstays unchanged - Play
Field Mend,Interpose,Shared Resolve, andEmergency Aidto check single-ally, other-ally, all-ally, and random-ally targeting - End the party turn and check that enemy actions begin after all members finish their turn triggers
- Open Game Card Monitor and check each member's
UnitId, slot, activation state, shared energy, and statuses
Confirm that the source and target IDs in Monitor match the units involved in the play.