-
Notifications
You must be signed in to change notification settings - Fork 34
Card Components Reference
This section describes some of the major components that are used in the definitions of cards:
- Context objects
- Game systems
- Target resolvers
When the game starts to resolve an ability, it creates a context object for that ability. Generally, the context ability has the following structure:
class AbilityContext {
constructor(properties) {
this.game = properties.game;
this.source = properties.source || new OngoingEffectSource(this.game);
this.player = properties.player;
this.ability = properties.ability || null;
this.costs = properties.costs || {};
this.costAspects = properties.costAspects || [];
this.targets = properties.targets || {};
this.selects = properties.selects || {};
this.stage = properties.stage || Stage.Effect;
this.targetAbility = properties.targetAbility;
this.playType = this.player && this.player.findPlayType(this.source);
}
}context.source is the card with the ability being used, and context.player is the player who is using the ability (almost always the controller of the context.source). When implementing actions and other triggered abilities, context should almost always be used (instead of this) to reference cards or players. The only exception is that this.game can be used as an alternative to context.game.
Note that in the case of upgrade abilities that give an ability to the attached card, context.source has to be used slightly differently than normal:
// Attached character gains ability 'On Attack: Exhaust the defender'
this.addGainTriggeredAbilityTargetingAttached({
title: 'Exhaust the defender on attack',
// note here that context.source refers to the attached unit card, not the upgrade itself
when: { onAttackDeclared: (event, context) => event.attack.attacker === context.source },
targetResolver: {
cardCondition: (card, context) => card === context.event.attack.target,
immediateEffect: AbilityHelper.immediateEffects.exhaust()
}
});Whereas in most cases context.source refers to this (i.e., the source card of the ability), since in this case the ability is being triggered on the attached unit card, context.source refers to the unit that the upgrade is attached to. The above when condition is equivalent to:
when: { onAttackDeclared: (event, context) => event.attack.attacker === this.parentCard }
Most ability types (other than constant, keyword, and replacement abilities) can specify to 'choose' or otherwise target a specific card. This should be implemented using a "target resolver," which defines a set of criteria that will be used to select the set of target cards to allow the player to choose between. Target resolvers are provided using targetResolver or targetResolvers property.
The targetResolver property should include any limitations set by the ability, using the cardTypeFilter, locationFilter, controller and/or cardCondition property. A game system can also be included by using the immediateEffect property, which will restrict the card chosen to those for which that game system is legal (e.g. only units in an arena and base can be damaged, only upgrades can be unattached, etc.).
For example, see the Sabine Wren (unit) "on attack" ability:
// cardCondition returns true only for cards that are a base or the target of Sabine's attack
this.addOnAttackAbility({
title: 'Deal 1 damage to the defender or a base',
targetResolver: {
cardCondition: (card, context) => card.isBase() || card === context.event.attack.target,
immediateEffect: AbilityHelper.immediateEffects.damage({ amount: 1 })
}
});See additional details in the GameSystems section below. If an array of game systems is specified in immediateEffect, then the target only needs to meet the requirements of one of them.
As mentioned above, targets can be filtered using one of multiple properties. The cardCondition property is the most flexible but the most cumbersome to write and to read, as it requires passing a handler function. Since most ability targets are restricted by a simple category such as "non-leader unit" or "friendly ground unit", properties are available for filtering on these attributes (see example below).
'Wildcard' enum types: for location and card type, we have a concept of "wildcard" enum types which represent more than one concrete value. For example, Location.SpaceArena and Location.GroundArena are concrete locations, but WildcardLocation.AnyArena is a value that represents both (or either) for matching and filtering purposes. Similarly for card types, we have values such as WildcardCardType.Unit which represents leader and non-leader units as well as token units. For a detailed list, see Constants.ts.
// Death Trooper
this.addWhenPlayedAbility({
title: 'Deal 2 damage to a friendly ground unit and an enemy ground unit',
targetResolvers: {
myGroundUnit: {
cardTypeFilter: WildcardCardType.Unit,
controller: RelativePlayer.Self,
locationFilter: Location.GroundArena,
immediateEffect: AbilityHelper.immediateEffects.damage({ amount: 2 })
},
theirGroundUnit: {
cardTypeFilter: WildcardCardType.Unit,
controller: RelativePlayer.Opponent,
locationFilter: Location.GroundArena,
immediateEffect: AbilityHelper.immediateEffects.damage({ amount: 2 })
}
},
effect: 'deal 2 damage to {1} and {2}',
effectArgs: (context) => [context.targets.myGroundUnit, context.targets.theirGroundUnit]
});Some card abilities require multiple targets. These may be specified using the targetResolvers property. Each sub key under targetResolvers is the name that will be given to the chosen card, and the value is the prompt properties. See the Death Trooper example above for reference.
Once all targets are chosen, they will be set using their specified name under the targetResolvers property on the handler context object.
Some abilities require the player (or their opponent) to choose between multiple options. This is done in the same way as targets above, but by using the mode property set to 'select'. In addition, a choices object should be included, which contains key:value pairs where the key is the option to display to the player, and the value is either a function which takes the context object and returns a boolean indicating whether this option is legal, or a game action which will be evaluated on the basis of the specified target (or default as detailed below) to determine whether the choice is legal. The selected option is stored in context.select.choice (or context.selects[targetName].choice for an ability with multiple targets).
// Action: During a conflict at this province, select one – switch the contested ring with an unclaimed
// ring, or switch the conflict type.
this.action({
title: 'Switch the conflict type or ring',
condition: context => context.source.isConflictProvince(),
target: {
player: 'self',
mode: 'select',
choices: {
'Switch the contested ring': () => _.any(this.game.rings, ring => ring.isUnclaimed()),
'Switch the conflict type': () => true
}
},
// ...
});// Action: If an opponent has declared 2 or more conflicts against you this phase, select one –
// take 1 fate or 1 honor from that opponent.
this.action({
title: 'Take 1 fate or 1 honor',
phase: 'conflict',
condition: context => this.game.getConflicts(context.player.opponent).filter(conflict => !conflict.passed).length > 1,
target: {
player: 'self',
mode: 'select',
choices: {
'Take 1 fate': AbilityHelper.actions.takeFate(),
'Take 1 honor': AbilityHelper.actions.takeHonor()
}
}
});Some cards refer back to events that have happened previously in this phase or round, such as Medal Ceremony or the Cassian leader. To add this kind of game memory to a card, add a state watcher. Here is an example with Medal Ceremony:
export default class MedalCeremony extends EventCard {
// this watcher records every instance of an attack that happened in the past phase
private attacksThisPhaseWatcher: AttacksThisPhaseWatcher;
protected override setupStateWatchers(registrar: StateWatcherRegistrar) {
this.attacksThisPhaseWatcher = AbilityHelper.stateWatchers.attacksThisPhase(registrar, this);
}
public override setupCardAbilities() {
this.setEventAbility({
title: 'Give an experience to each of up to three Rebel units that attacked this phase',
targetResolver: {
mode: TargetMode.UpTo,
numCards: 3,
optional: true,
immediateEffect: AbilityHelper.immediateEffects.giveExperience(),
// this condition gets the list of Rebel attackers this phase from the watcher and checks if the specified card is in it
cardCondition: (card, context) => {
const rebelUnitsAttackedThisPhase = this.attacksThisPhaseWatcher.getCurrentValue()
.filter((attack) => attack.attacker.hasSomeTrait(Trait.Rebel))
.map((attack) => attack.attacker as Card);
return rebelUnitsAttackedThisPhase.includes(card);
}
}
});
}
}A "state watcher" is a set of event triggers which are used to log events that occur during the game. For example, the AttacksThisPhaseWatcher used above is called on every onAttackDeclared event and adds the event to the list of attacks this phase. The getCurrentValue() method on a watcher will return the state object for that watcher, which varies by watcher type.
For a list of available state watchers, see StateWatcherLibrary.
When using a state watcher, it's important to remember that card properties will have changed since the relevant watched event(s) took place and the current properties of a card may be different than what they were when the event happened.
As an example, consider the Vanguard Ace ability, which creates one experience token for each card played by the controller this phase. It uses a CardsPlayedThisPhaseWatcher, which returns the list of all cards played this phase by either player. Each entry gives the played card and the player who played it:
public override setupCardAbilities() {
this.addWhenPlayedAbility({
title: 'Give one experience for each card you played this turn',
immediateEffect: AbilityHelper.immediateEffects.giveExperience((context) => {
const cardsPlayedThisPhase = this.cardsPlayedThisWatcher.getCurrentValue();
const experienceCount = cardsPlayedThisPhase.filter((playedCardEntry) =>
// playedCardEntry.card.controller === context.source.controller <-- THIS IS THE WRONG WAY TO CHECK IF WE PLAYED THE CARD
playedCardEntry.playedBy === context.source.controller &&
playedCardEntry.card !== context.source
).length;
return { amount: experienceCount };
})
});
}Since Vanguard Ace only counts cards that were played by its controller, we need to filter the results of the CardsPlayedThisPhaseWatcher to only cards that we (the controller) played. However, we can't do this by just checking the controller property of each card that was played, because it is possible that control of the card has changed since the card was played (e.g. with Traitorous). If we just did card.controller === context.source.controller, then a card that we played which was stolen with Traitorous would not be counted by the Vanguard Ace ability.
Therefore, it is imporant that the code checks the provided playedBy property from the watcher, which recorded the acting player at the time the card was played. Otherwise, the card's behavior will be incorrect in some cases.
In general, the effects of an ability should be implemented using game systems represented by the GameSystem class, which is turn wrapped by helper methods under the AbilityHelper import.
All ability types rely on GameSystems for making changes to game state. Available game systems can be found in GameSystemLibrary.ts, along with any parameters and their defaults. The cost and immediateEffect fields of AbilityHelper provide access to the GameSystem classes for use in changing the game state as either the cost or the immediate effect of an ability, respectively. For example, the Grogu action ability uses the exhaust both as a cost (via AbilityHelper.costs.exhaustSelf()) and as an effect (via AbilityHelper.immediateEffects.exhaust()).
this.addActionAbility({
title: 'Exhaust an enemy unit',
cost: AbilityHelper.costs.exhaustSelf(),
targetResolver: {
controller: RelativePlayer.Opponent,
immediateEffect: AbilityHelper.immediateEffects.exhaust()
}
});Game systems as an immediate effect default to targeting the card generating the ability (for cards) or the opponent (for players).
Game systems included in targetResolver (or in one of targetResolvers) will default to the target chosen by the targetResolver's resolution. You can change the target of a game system or the parameters by passing either an object with the properties you want, or a function which takes context and returns those properties.
this.addActionAbility({
title: 'Defeat this upgrade to give the attached unit a shield',
cost: AbilityHelper.costs.defeatSelf(),
// we don't need a target resolver, can just provide the target directly here
immediateEffect: AbilityHelper.immediateEffects.giveShield(context => ({ target: context.source.parentCard }))
});Some actions have text limiting the number of times they may be used in a given period. You can pass an optional limit property using one of the duration-specific ability limiters. See /server/game/abilitylimit.js for more details.
this.addActionAbility({
title: 'Damage an opponent\'s base',
limit: AbilityHelper.limit.perPhase(1),
// ...
});Once costs have been paid and targets chosen (but before the ability resolves), the game automatically displays a message in the chat box which tells both players the ability, costs and targets of the effect. Game actions will automatically generate their own effect message, although this will only work for a single game action. If the effects of the ability involve two or more game actions, or the effect is a lasting effect or uses a handler, then an effect property is required. The effect property will be passed the target (card(s) or ring) of the effect (or the source if there are no targets) as its first parameter (and so can be referenced using '{0}' in the effect property string). If other references are required, this can be done using curly bracket references in the effect string('{1}', '{2', etc) and supplying an effectArgs property (which generally will be a function taking the context object):
this.action({
// Action: Return this attachment to your hand and dishonor attached character.
title: 'Return court mask to hand',
effect: 'return {0} to hand, dishonoring {1}',
effectArgs: context => context.source.parent,
gameAction: [AbilityHelper.actions.returnToHand(), AbilityHelper.actions.dishonor(context => ({ target: context.source.parent }))]
});this.action({
// Action: While this character is participating in a conflict, choose another participating character – until the end of the conflict, that character gets +2/+2 for each holding you control.
title: 'Give a character a bonus for each holding',
condition: context => context.source.isParticipating(),
target: {
cardType: 'character',
cardCondition: (card, context) => card.isParticipating() && card !== context.source,
gameAction: AbilityHelper.actions.cardLastingEffect(context => ({
effect: AbilityHelper.effects.modifyBothSkills(2 * context.player.getNumberOfHoldingsInPlay())
}))
},
effect: 'give {0} +{1}{2}/+{1}{3}',
effectArgs: context => [2 * context.player.getNumberOfHoldingsInPlay(), 'military', 'political']
});Certain actions, such as that of Ancestral Guidance, can only be activated while the character is in the discard pile. Such actions should be defined by specifying the location property with the location from which the ability may be activated. The player can then activate the ability by simply clicking the card. If there is a conflict (e.g. both the ability and playing the card normally can occur), then the player will be prompted.
this.action({
title: 'Play from discard pile',
location: 'conflict discard pile',
// ...
})Game messages should begin with the name of the player to ensure a uniform format and make it easy to see who triggered an ability.
- Bad: Kaiu Shuichi triggers to gain 1 fate for Player1
- Good: Player1 uses Kaiu Shuichi to gain 1 fate
No game messages should end in a period, exclaimation point or question mark.
- Bad: Player1 draws 2 cards.
- Good: Player1 draws 2 cards
All game messages should use present tense.
- Bad: Player1 has used Isawa Masahiro to discard Miya Mystic
- Bad: Player1 chose to discard Miya Mystic
- Good: Player1 uses Isawa Masahiro to discard Miya Mystic
- Good: Player1 chooses to discard Miya Mystic
Targeting prompts should ask the player to choose a card or a card of particular type to keep prompt titles relatively short, without specifying the final goal of card selection.
- Bad: Choose a character to return to hand
- Good: Choose a character
Exception: If a card requires the player to choose multiple cards (e.g. Rebuild), or if a card requires the player's opponent to choose a card (e.g. Endless Plains) you can add context about which one they should be selecting. Just keep it as short as reasonably possible.
As valid selections are already presented to the user via visual clues, targeting prompts should not repeat selection rules in excessive details. Specifying nothing more and nothing less than the eligible card type (if any) is the good middle ground (this is what most prompts will default to).
-
Bad: Choose a Bushi
-
Good: Choose a character
-
Bad: Choose a defending Crab character
-
Good: Choose a character
-
Bad: Choose a card from your discard pile
-
Good: Choose a card
-
Good: Choose an attachment or location