Action Definition

Action Definitions enhance the right-click context menus that are available to the player in-game and provide game-specific game play interactions. Any number of Action Definitions may be included in the <Table>, <hand> or <group> elements within the Game Definition, each one representing a command that the player can use to execute a gameplay function.

<groupaction>

A groupaction is called on the group as a whole, and doesn't reference any card in particular. All groupactions will appear in the context menu, regardless of if a card was right-clicked or not.

They contain the following attributes:

• menu (The text displayed in the context menu for this action.)
• shortcut (The shortcut hotkey which can be used to directly execute the action.)
• default (If set to True, enables double-click as a valid shortcut for this action. Defaults to False.)
• execute (The name of the Python defined function to be invoked when the action is executed.)
• showIf (See below)
• getName (See below)

A <groupaction> will pass the Group object (either Table, Hand or Pile depending on what type of group it is) as a parameter to the associated Python functions. Functions executed on the Table will pass the mouse's X and Y coordinates as well. As an example,

   <groupaction menu="Shuffle Deck" shortcut="CTRL+S" execute="shuffle" />

def shuffle(group, x = 0, y = 0):
    mute()
    group.shuffle()
    notify("{} shuffles their {}.".format(me, group))

<cardaction>

A cardaction will only manipulate a specific card within that group. The player must right-click directly over a card to see the available cardactions.

They contain the following attributes:

• menu (The text displayed in the context menu for this action.)
• shortcut (The shortcut hotkey which can be used to directly execute the action.)
• default (If set to True, enables double-click as a valid shortcut for this action. Defaults to False.)
• execute (The name of the Python defined function to be invoked when the action is executed.)
• batchExecute (To be used instead of execute in specific cases, see below.)
• showIf (See below)
• getName (See below)

A <cardaction> will pass the Card object as a parameter to the associated Python functions. Functions executed on the Table will pass the mouse's X and Y coordinates as well. As an example,

  <cardaction menu="Discard Card" shortcut="del" execute="discard"/>

def discard(card, x = 0, y = 0):
    mute()
    card.moveTo(me.Discard)
    notify('{} discards {}.'.format(me, card))

You can execute <cardaction>s on a selection of multiple cards. If a <cardaction> is executed on a selection of cards, the associated Python function will be invoked individually for every card in the selection. In many cases, this may cause increased processor loading times or spam the chat box. To prevent this, you may use batchExecute instead of execute in your attributes. This will cause the Python function to be invoked only ONCE, and passes a List of Card objects as the parameter instead. For example:

  <cardaction menu="Discard Cards" shortcut="del" batchExecute="discardMany"/>

def discardMany(cards, x = 0, y = 0):
    mute()
    for c in cards:
        c.moveTo(me.Discard)
    notify('{} discards {} cards.'.format(me, len(cards)))

<groupactions> and <cardactions>

These tags can be used to create nested sub-menus, useful for organizing your various actions into categories. Include any number of <groupaction> and <cardaction> as children elements. There is no limit to the nesting of sub-menus.

The following attributes are to be used:

• menu (The text displayed in the context menu for this sub-menu.)

<cardseparator /> and <groupseparator />

These tags create a separator bar in the context menus. They do not contain any attributes or child tags.

showIf

This parameter defines a Python function which dynamically determines whether or not the card/group action should appear or hide from the menu. It passes the same parameters to Python as execute or batchExecute. The Python function MUST return a True/False boolean value, indicating the visibility of the action. The Python function is executed every time the menu is opened, allowing its visibility to change depending on the function's return value.

getName

This parameter defines a Python function which will alter the label name of the card/group action in the menu. It passes the same parameters to Python as execute or batchExecute. The Python function MUST return a String value, determining the text that will appear as the label of that action. The Python function is executed every time the menu is opened, allowing its text to change depending on the function's return value.