Class: Action<A>
Actions represent discreet moves players can make. These contain the choices needed to take this action and the results of the action. Create Actions using the Game#action function. Actions are evaluated at the time the player has the option to perform the action, so any expressions that involve game state will reflect the state at the time the player is performing the action.
Type parameters
| Name | Type |
|---|---|
A | extends Record<string, Argument> = NonNullable<unknown> |
Behaviour
do
▸ do(move): Action<A>
Add behaviour to this action to alter game state. After adding the choices
to an action, calling do causes Boardzilla to use the player choices to
actually do something with those choices. Call this method after all the
methods for player choices so that the choices are properly available to
the do function.
Parameters
| Name | Type | Description |
|---|---|---|
move | (args: A) => any | The action to perform. This function accepts one argument with key-value pairs for each choice added to the action using the provided names. |
Returns
Action<A>
Example
player => action({
prompt: 'Take resources',
}).chooseFrom({
'resource', ['lumber', 'steel'],
{ prompt: 'Select resource' }
}).chooseNumber(
'amount', {
prompt: 'Select amount',
max: 3
}).do(({ resource, amount }) => {
// the choices are automatically passed in with their proper type
game.firstN(amount, Resource, {resource}).putInto(
player.my('stockPile')
);
})
Defined in
boardzilla-core/src/action/action.ts:383
message
▸ message(text, args?): Action<A>
Add a message to this action that will be broadcast in the chat. Call this
method after all the methods for player choices so that the choices are
properly available to the message function. However the message should be
called before or after any do behaviour depending on whether you want the
message to reflect the game state before or after the move is performs. The
action's message and do functions can be intermixed in this way to
generate messages at different points int the execution of a move.
Parameters
| Name | Type | Description |
|---|---|---|
text | string | The text of the message to send. This can contain interpolated strings with double braces just as when calling Game#message directly. However when using this method, the player performing the action, plus any choices made in the action are automatically made available. |
args? | Record<string, Argument> | (a: A) => Record<string, Argument> | If additional strings are needed in the message besides 'player' and the player choices, these can be specified here. This can also be specified as a function that accepts the player choices and returns key-value pairs of strings for interpolation. |
Returns
Action<A>
Example
action({
prompt: 'Say something',
}).enterText({
'message',
}).message(
'{{player}} said {{message}}' // no args needed
).message(
"I said, {{player}} said {{loudMessage}}",
({ message }) => ({ loudMessage: message.toUpperCase() })
)
Defined in
boardzilla-core/src/action/action.ts:422
messageTo
▸ messageTo(player, text, args?): Action<A>
Add a message to this action that will be broadcast in the chat to the
specified player(s). Call this method after all the methods for player
choices so that the choices are properly available to the message
function. However the message should be called before or after any do
behaviour depending on whether you want the message to reflect the game
state before or after the move is performs. The action's message and do
functions can be intermixed in this way to generate messages at different
points int the execution of a move.
Parameters
| Name | Type | Description |
|---|---|---|
player | number | Player<BaseGame, BasePlayer> | (number | Player<BaseGame, BasePlayer>)[] | Player or players to receive the message |
text | string | The text of the message to send. This can contain interpolated strings with double braces just as when calling Game#message directly. However when using this method, the player performing the action, plus any choices made in the action are automatically made available. |
args? | Record<string, Argument> | (a: A) => Record<string, Argument> | If additional strings are needed in the message besides 'player' and the player choices, these can be specified here. This can also be specified as a function that accepts the player choices and returns key-value pairs of strings for interpolation. |
Returns
Action<A>
Example
action({
prompt: 'Say something',
}).enterText({
'message',
}).message(
'{{player}} said {{message}}' // no args needed
).message(
"I said, {{player}} said {{loudMessage}}",
({ message }) => ({ loudMessage: message.toUpperCase() })
)
Defined in
boardzilla-core/src/action/action.ts:463
move
▸ move(piece, into): Action<A>
Perform a move with the selected element(s) into a selected Space/Piece. This is almost the equivalent of calling Action#do and adding a putInto command, except that the game will also permit the UI to allow a mouse drag for the move.
Parameters
| Name | Type | Description |
|---|---|---|
piece | Piece<Game<BaseGame, BasePlayer>, BasePlayer> | keyof A | A Piece to move or the name of the piece selection in this action |
into | GameElement<BaseGame, BasePlayer> | keyof A | A GameElement to move into or the name of the destination selection in this action. player => action({ prompt: 'Discard a card from hand' }).chooseOnBoard( 'card', player.my(Card) ).move( 'card', $.discard ) |
Returns
Action<A>
Defined in
boardzilla-core/src/action/action.ts:973
swap
▸ swap(piece1, piece2): Action<A>
Swap the location of two Pieces. Each of the two pieces can either be the
name of a previous chooseOnBoard, or a simply provide a piece if it is
not a player choice. The game will also allow a mouse drag for the swap.
Parameters
| Name | Type | Description |
|---|---|---|
piece1 | Piece<Game<BaseGame, BasePlayer>, BasePlayer> | keyof A | A Piece to swap or the name of the piece selection in this action |
piece2 | Piece<Game<BaseGame, BasePlayer>, BasePlayer> | keyof A | A Piece to swap or the name of the piece selection in this action player => action({ prompt: 'Exchange a card from hand with the top of the deck' }).chooseOnBoard( 'card', player.my(Card) ).swap( 'card', $.deck.first(Card)! ) |
Returns
Action<A>
Defined in
boardzilla-core/src/action/action.ts:1010
reorder
▸ reorder(collection, options?): Action<A & { __reorder_to__: Piece<Game<BaseGame, BasePlayer>, BasePlayer> ; __reorder_from__: number }>
Have the player select one of the Pieces in the collection and select a new position within the collection while keeping everything else in the same order. The game will also permit a mouse drag for the reorder.
Parameters
| Name | Type | Description |
|---|---|---|
collection | Piece<Game<BaseGame, BasePlayer>, BasePlayer>[] | A collection of Pieces to reorder |
options? | Object | - |
options.prompt? | string | (args: A) => string | Prompt displayed to the user for this reorder choice. player => action({ prompt: 'Reorder cards in hand' }).reorder( player.my(Card) ) |
Returns
Action<A & { __reorder_to__: Piece<Game<BaseGame, BasePlayer>, BasePlayer> ; __reorder_from__: number }>
Defined in
boardzilla-core/src/action/action.ts:1050
Choices
chooseFrom
▸ chooseFrom<N, T>(name, choices, options?): Action<A & { [key in string]: T }>
Add a choice to this action from a list of options. These choices will be displayed as buttons in the UI.
Type parameters
| Name | Type |
|---|---|
N | extends string |
T | extends SingleArgument |
Parameters
| Name | Type | Description |
|---|---|---|
name | N | The name of this choice. This name will be used in all functions that accept the player's choices |
choices | T & string | number | boolean[] | { label: string ; choice: T }[] | (args: A) => T & string | number | boolean[] | { label: string ; choice: T }[] | An array of choices. This may be an array of simple values or an array of objects in the form: { label: string, choice: value } where value is the actual choice that will be passed to the rest of the action, but label is the text presented to the player that they will be prompted to click. Use the object style when you want player text to contain additional logic or differ in some way from the choice, similiar to <option value="key">Some text</option> in HTML. This can also be a function that returns the choice array. This function will accept arguments for each choice the player has made up to this point in the action. |
options? | Object | |
options.prompt? | string | (args: A) => string | Prompt displayed to the user for this choice. |
options.confirm? | string | [string, undefined | Record<string, Argument> | (args: A & { [key in string]: T }) => Record<string, Argument>] | A confirmation message that the player will always see before commiting this choice. This can be useful to present additional information about the consequences of this choice, or simply to force the player to hit a button with a clear message. This can be a simple string, or a 2-celled array in the same form as message with a string message and a set of key-value pairs for string interpolation, optionally being a function that takes an object of key-value pairs for all player choices, and returns the interpolation object. |
options.validate? | (args: A & { [key in string]: T }) => undefined | string | boolean | A function that takes an object of key-value pairs for all player choices and returns a boolean. If false, the game will not allow the player to submit this choice. If a string is returned, this will display as the reason for disallowing these selections. |
options.skipIf? | "always" | "never" | "only-one" | (args: A) => boolean | One of 'always', 'never' or 'only-one' or a function returning a boolean. (Default 'only-one').
|
Returns
Action<A & { [key in string]: T }>
Example
action({
prompt: 'Choose color',
}).chooseFrom(
'color', ['white', 'blue', 'red'],
).do(
({ color }) => ... color will be equal to the player-selected color ...
)
// a more complex example:
action({
prompt: 'Take resources',
}).chooseFrom(
'resource', ['lumber', 'steel', 'oil'],
{ prompt: 'Select resource' }
).chooseFrom(
// Use the functional style to include the resource choice in the text
// Also use object style to have the value simply be "high" or "low"
'grade', ({ resource }) => [
{ choice: 'high', label: `High grade ${resource}` }
{ choice: 'low', label: `Low grade ${resource}` }
],
{
// A follow-up choice that doesn't apply to "oil"
skipIf: ({ resource }) => resource === 'oil',
// Add an 'are you sure?' message
confirm: ['Buy {{grade}} grade {{resource}}?', ({ grade }) = ({ grade: grade.toUpperCase() })]
}
).do (
({ resource, grade }) => {
// resource will equal 'lumber', 'steel' or 'oil'
// grade will equal 'high' or 'low'
}
)
Defined in
boardzilla-core/src/action/action.ts:561
enterText
▸ enterText<N>(name, options?): Action<A & { [key in string]: string }>
Prompt the user for text entry. Use this in games where players submit text, like word-guessing games.
Type parameters
| Name | Type |
|---|---|
N | extends string |
Parameters
| Name | Type | Description |
|---|---|---|
name | N | The name of this text input. This name will be used in all functions that accept the player's choices |
options? | Object | |
options.prompt? | string | (args: A) => string | Prompt displayed to the user for entering this text. |
options.validate? | (args: A & { [key in string]: string }) => undefined | string | boolean | A function that takes an object of key-value pairs for all player choices and returns a boolean. If false, the game will not allow the player to submit this text. If a string is returned, this will display as the reason for disallowing this text. |
options.regexp? | RegExp | - |
options.initial? | string | (args: A) => string | Default text that can appear initially before a user types. |
Returns
Action<A & { [key in string]: string }>
Example
action({
prompt: 'Guess a word',
}).enterText({
'guess',
{ prompt: 'Your guess', }
}).message(
guess => `{{player}} guessed ${guess}`
})
Defined in
boardzilla-core/src/action/action.ts:611
chooseNumber
▸ chooseNumber<N>(name, options?): Action<A & { [key in string]: number }>
Add a numerical choice for this action. This will be presented with a number picker.
Type parameters
| Name | Type |
|---|---|
N | extends string |
Parameters
| Name | Type | Description |
|---|---|---|
name | N | The name of this choice. This name will be used in all functions that accept the player's choices |
options | Object | |
options.min? | number | (args: A) => number | Minimum allowed. Default 1. |
options.max? | number | (args: A) => number | Maximum allowed. Default Infinity |
options.prompt? | string | (args: A) => string | Prompt displayed to the user for entering this number. |
options.confirm? | string | [string, undefined | Record<string, Argument> | (args: A & { [key in string]: number }) => Record<string, Argument>] | A confirmation message that the player will always see before commiting this choice. This can be useful to present additional information about the consequences of this choice, or simply to force the player to hit a button with a clear message. This can be a simple string, or a 2-celled array in the same form as message with a string message and a set of key-value pairs for string interpolation, optionally being a function that takes an object of key-value pairs for all player choices, and returns the interpolation object. |
options.validate? | (args: A & { [key in string]: number }) => undefined | string | boolean | A function that takes an object of key-value pairs for all player choices and returns a boolean. If false, the game will not allow the player to submit this choice. If a string is returned, this will display as the reason for disallowing these selections. |
options.initial? | number | (args: A) => number | Initial value to display in the picker |
options.skipIf? | "always" | "never" | "only-one" | (args: A) => boolean | One of 'always', 'never' or 'only-one' or a function returning a boolean. (Default 'only-one').
|
Returns
Action<A & { [key in string]: number }>
Example
player => action({
prompt: 'Buy resources',
}).chooseNumber(
'amount', {
min: 5,
max: 10 // select from 5 - 10
}).do(
({ amount }) => player.resource += amount
);
Defined in
boardzilla-core/src/action/action.ts:686
chooseOnBoard
▸ chooseOnBoard<T, N>(name, choices, options?): Action<A & { [key in string]: T }>
Add a choice of game elements to this action. Users will click on the playing area to make their choice.
Type parameters
| Name | Type |
|---|---|
T | extends GameElement<BaseGame, BasePlayer> |
N | extends string |
Parameters
| Name | Type | Description |
|---|---|---|
name | N | The name of this choice. This name will be used in all functions that accept the player's choices |
choices | BoardQueryMulti<T, A> | Elements that may be chosen. This can either be an array of elements or a function returning an array, if the choices depend on previous choices. If using a function, it will accept arguments for each choice the player has made up to this point in the action. |
options? | Object | |
options.prompt? | string | (args: A) => string | Prompt displayed to the user for this choice. |
options.confirm? | string | [string, undefined | Record<string, Argument> | (args: A & { [key in string]: T }) => Record<string, Argument>] | A confirmation message that the player will always see before commiting this choice. This can be useful to present additional information about the consequences of this choice, or simply to force the player to hit a button with a clear message. This can be a simple string, or a 2-celled array in the same form as message with a string message and a set of key-value pairs for string interpolation, optionally being a function that takes an object of key-value pairs for all player choices up to this point, including this one, and returns the interpolation object. |
options.validate? | (args: A & { [key in string]: T }) => undefined | string | boolean | A function that takes an object of key-value pairs for all player choices and returns a boolean. If false, the game will not allow the player to submit this choice. If a string is returned, this will display as the reason for disallowing these selections. |
options.initial? | undefined | Optional list of game elements to be preselected |
options.min? | undefined | If supplied, the choice is for a set of elements and the minimum required is min. |
options.max? | undefined | If supplied, the choice is for a set of elements and the maximum allowed is max. |
options.number? | undefined | If supplied, the choice is for a set of exactly number elements. For example, if the player is being asked to pass 3 cards from their hand, the choices should be to the cards in their hand and the number to 3. |
options.skipIf? | "always" | "never" | "only-one" | (args: A) => boolean | One of 'always', 'never' or 'only-one' or a function returning a boolean. (Default 'only-one').
|
Returns
Action<A & { [key in string]: T }>
Example
player => action({
prompt: 'Mulligan',
}).chooseOnBoard(
'cards', player.allMy(Card), {
prompt: 'Mulligan 1-3 cards',
// select 1-3 cards from hand
min: 1,
max: 3
).do(
({ cards }) => {
// `cards` is an ElementCollection of the cards selected
cards.putInto($.discard);
$.deck.firstN(cards.length, Card).putInto(player.my('hand')!);
}
)
Defined in
boardzilla-core/src/action/action.ts:782
chooseGroup
▸ chooseGroup<R>(choices, options?): Action<ExpandGroup<A, R>>
Create a multi-selection choice. These selections will be presented all at once as a form. This is used for form-like choices that have a number of choices that are not board choices, i.e. chooseFrom, chooseNumber and enterText
Type parameters
| Name | Type |
|---|---|
R | extends Group |
Parameters
| Name | Type | Description |
|---|---|---|
choices | R | An object containing the selections. This is a set of key-value pairs where each key is the name of the selection and each value is an array of options where the first array element is a string indicating the type of choice ('number', 'select', 'text') and subsequent elements contain the options for the appropriate choice function (chooseNumber, chooseFrom or enterText). |
options? | Object | - |
options.validate? | (args: ExpandGroup<A, R>) => undefined | string | boolean | A function that takes an object of key-value pairs for all player choices and returns a boolean. If false, the game will not allow the player to submit these choices. If a string is returned, this will display as the reason for disallowing these selections. |
options.confirm? | string | [string, undefined | Record<string, Argument> | (args: ExpandGroup<A, R>) => Record<string, Argument>] | A confirmation message that the player will always see before commiting this choice. This can be useful to present additional information about the consequences of this choice, or simply to force the player to hit a button with a clear message. This can be a simple string, or a 2-celled array in the same form as message with a string message and a set of key-value pairs for string interpolation, optionally being a function that takes an object of key-value pairs for all player choices, and returns the interpolation object. |
Returns
Action<ExpandGroup<A, R>>
Example
action({
prompt: 'purchase'
}).chooseGroup({
lumber: ['number', { min: 2 }],
steel: ['number', { min: 2 }]
}, {
// may not purchase more than 10 total resources
validate: ({ lumber, steel }) => lumber + steel <= 10
});
Defined in
boardzilla-core/src/action/action.ts:901
placePiece
▸ placePiece<T>(piece, into, options?): Action<A & { __placement__: number[] } & { [key in string]: Object }>
Add a placement selection to this action. This will be presented as a piece that players can move into the desired location, snapping to the grid of the destination as the player moves.
Type parameters
| Name | Type |
|---|---|
T | extends string |
Parameters
| Name | Type | Description |
|---|---|---|
piece | T | The name of the piece selection in this action from a chooseOnBoard prior to this |
into | PieceGrid<Game<BaseGame, BasePlayer>> | A GameElement to move into |
options? | Object | - |
options.prompt? | string | (args: A) => string | Prompt displayed to the user for this placement choice. |
options.confirm? | string | [string, undefined | Record<string, Argument> | (args: A & { [key in string]: Object }) => Record<string, Argument>] | A confirmation message that the player will always see before commiting this choice. This can be useful to present additional information about the consequences of this choice, or simply to force the player to hit a button with a clear message. This can be a simple string, or a 2-celled array in the same form as message with a string message and a set of key-value pairs for string interpolation, optionally being a function that takes an object of key-value pairs for all player choices, and returns the interpolation object. |
options.validate? | (args: A & { [key in string]: Object }) => undefined | string | boolean | A function that takes an object of key-value pairs for all player choices and returns a boolean. The position selected during the piece placement can be checked by reading the 'column', 'row' and rotation properties of the piece as provided in the first argument. If false, the game will not allow the player to submit these choices. If a string is returned, this will display as the reason for disallowing these selections. |
options.rotationChoices? | number[] | = An array of valid rotations in degrees. These choices must be normalized to numbers between 0-359°. If supplied the piece will be given rotation handles for the player to set the rotation and position together. player => action({ prompt: 'Place your tile' }).chooseOnBoard( 'tile', player.my(Tile) ).placePiece( 'tile', $.map, { confirm: ({ tile }) => [ 'Place tile into row {{row}} and column {{column}}?', tile ] }) |
Returns
Action<A & { __placement__: number[] } & { [key in string]: Object }>
Defined in
boardzilla-core/src/action/action.ts:1120
Other
confirm
▸ confirm(prompt): Action<A>
Add a confirmtation step to this action. This can be useful if you want to present additional information to the player related to the consequences of their choice, like a cost incurred. Or this can simply be used to force the user to click an additional button on a particular important choice.
Parameters
| Name | Type | Description |
|---|---|---|
prompt | string | (args: A) => string | Button text for the confirmation step. This can be a function returning the text which accepts each choice the player has made up till now as an argument. |
Returns
Action<A>
Example
action({
prompt: "Buy resources",
}).chooseNumber({
'amount', {
prompt: "Amount",
max: Math.floor(player.coins / 5)
}).confirm(
({ amount }) => `Spend ${amount * 5} coins`
}).do(({ amount }) => {
player.resource += amount;
player.coins -= amount * 5;
});