Action definition

Actions are probably the most complicated part of a game definition. Actions define procedures that can be executed by the players by right-clicking on a group or card.

Action Definition

There are two kind of actions: Group actions and Card actions. Both kinds are defined and provided inside groups. A group action (defined by the tag) usually manipulates a whole set of cards or the group itself. A card action (defined by the tag) only manipulates one individual card of a group. An action definition contains a sequence of action tags to define the procedure. Attributes:

• menu (The text displayed in the context menu for this action.)
• shortcut (The shortcut key to directly execute the action.)
• default (If set to true double clicking the card or group will execute this action. Defaults to false if not specified.)
• execute or batchExecute (The name of the Python function to call when this action is invoked. See remarks below.)

Additionally there are separators which are a 3rd kind of tag you can place inside groups. The and simply add a separator between the actions defined for card or group actions respectively. They currently support no attributes or children.

Python Function Signature

Each action should have either the execute attribute defined or the batchExecute attribute. Note that only can use batchExecute.

For a Group Action, OCTGN will call the function specified and pass the group as its only parameter. Here's an example of a correct group function and the way the action is declared in XML:

     def randomDiscard(group):
       mute()
       card = group.random()
       if card == None: return
       notify("{} randomly discards a card.".format(me))
       card.moveTo(me.graveyard)

     <groupaction menu="Random Discard" shortcut="ctrl+D" execute="randomDiscard" />

If the group is the Table, the function may be passed the mouse coordinates where the action was invoked. Note that depending on how the action is invoked there may NOT be any coordinates, so you should declare these x,y parameters optional, with a default value (probably 0,0). Here's an example of a correct table action:

     def token(group, x = 0, y = 0):
       card, quantity = askCard("[Rarity] = 'Token'")
       if quantity == 0: return
       table.create(card, x, y, quantity)

For a Card Action, let's consider execute first. OCTGN will call the function with the card as first parameter. Again if it's on the table, optional x,y parameters are passed in addition to the card:

     def rotate(card, x = 0, y = 0):
       mute()
       card.orientation ^= Rot90
       if card.orientation & Rot90 == Rot90:
         notify('{} turns {} sideways'.format(me, card))
       else:
         notify('{} turns {} upright'.format(me, card))

     <cardaction menu="Rotate Card" shortcut="ctrl+T" default="true" execute="rotate" />

An action may be executed on several cards at the same time, in the case of a multiple selection. In this situation, OCTGN calls the execute function once for each card in the selection. This is usually the most convenient way to write a function because you don't have to iterate the cards in the selection. But sometimes you need more control over the selection. Maybe... The action is influenced by the size of the selection (E.g. add as many markers as there are cards in the selection.) You need to keep track of some variable during the execution on all cards (E.g. you want to lay out the cards on the table in a nice rectangular array) You want to ask for a choice once and apply it to all cards (E.g. choose a marker type to add on all cards)

For those situations, batchExecute should be used instead of execute. OCTGN will call this only once, with an array of cards as the first parameter. For example:

     def addMarker(cards, x = 0, y = 0):
       marker, quantity = askMarker()
       if quantity == 0: return
       for c in cards:
         c.markers[marker] += quantity

     <cardaction menu="Add Marker..." shortcut="ctrl+M" batchExecute="addMarker" />