Skip to main content

Player Party

Guide

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.

SettingRuntime 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 orderMaps 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​

IdentityPurpose
UnitIdIdentifies one battle instance, creating the same Player Unit asset twice produces different IDs
Team / TeamIdDetermines ally and opponent relationships, built-in players and enemies use Player and Enemy
SlotIndexMaps the runtime unit to a visible slot on its side
JoinOrderPreserves 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.

PolicyRule
IPartyActivationPolicyFree selection or ordered member activation
IAutomaticPartyActivationPolicyAutomatic companion actions during ordered turns
IActionWindowPolicyPhases that accept player card requests
IReactionWindowPolicyPausable reaction windows before enemy actions
ICardPlayPolicyProject rules for action sources and card permission
IUnitTargetPolicyDefault opposing targets resolved without relying on the selected view
IBattleResultPolicyWhether 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 TargetPlayer inputBehavior source
Single AllySelect any living ally, including the sourceUse the submitted Target or target port, Opponent does not select an ally
Other AllySelect a living ally other than the sourceUse the submitted Target, the runtime rejects the source itself
All AlliesNo single-target inputAll Allies
Random AllyNo single-target inputSelects one living ally and supplies it through Target
Random OpponentNo single-target inputSelects one living unit on the source's opposing side and supplies it through Target
Any UnitSelect any living player or enemyUse 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.

Party Showcase running with three player units, three enemies, a shared hand, and shared energy

Player Unit 1, Scout, supplies Party Tactics for the shared eight-card pool

  1. Check that each player slot displays HP, armor, and statuses
  2. Select different members and check the active player and energy display
  3. Switch members before playing an attack from Party Tactics, check that shared energy pays the cost, the selected member becomes SourceUnit, and the original OwnerUnitId stays unchanged
  4. Play Field Mend, Interpose, Shared Resolve, and Emergency Aid to check single-ally, other-ally, all-ally, and random-ally targeting
  5. End the party turn and check that enemy actions begin after all members finish their turn triggers
  6. 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.