As of OCTGN 0.9, the Python scripts do not enforce controlship on the object they manipulate. It is not safe to change the state of cards or groups you don't control, even though the script would let you do that. The only functions that are safe to use on elements you don't control are target, highlight, counters and markers manipulations. Of course you can read the state of any element. So be very careful to always filter the cards you touch. DO NOT use (c for c in table); DO use (c for c in table if c.controller == me).

In general you want to use OCTGN-provided rnd(min, max) function to randomly choose a number rather than Python's built-in functions. This is because rnd() is a distributed operation and other players can check that you don't cheat when choosing the number.

Avoid keeping references to cards in the game. Remember that between script executions, or even during asynchronous operations such as shuffle(), rnd() or reveal(), the game state may change and cards may be destroyed, moved, and so on. Not following this guideline may lead to your script crashing.

Python has nice comprehensions to select objects. Here's a way to get all Land cards you control on the table:

      cards = (card for card in table
                    if card.controller == me
                    and re.search(r'\bLand\b', card.type))

re is the Regular Expression engine built-into Python, which is very useful to perform text matching. You need to import it first:

    import re

The expression above: re.search(r'\bHero\b', card.type) checks whether the word 'Hero' (\b are marking word boundaries in a RegExp) appears into card.type.

Stops OCTGN from automatically logging messages. This only applies to the context of the executed action and OCTGN is automatically "unmuted" when it ends. If you want to "unmute" during the execution of the action, mute() returns a context manager usable in with statement:

      with mute()
        pass # Here OCTGN is muted
      pass # Here it isn't

Writes message in the chat log. If you use the built-in format function to create your message, Players are automatically replaced by their nicknames and Cards are replaced by their name, in a "hoverable" way.

      notify("{} plays {} from his hand.".format(me, card))

Writes message in the chat log of the local player only. See also notify.

Returns a random number between min and max inclusive. This method is generally better than Python's built-in functions because it is distributed. Other players can check that you don't cheat while choosing the number.

NEW IN 3.0.1.25: a timeout period, in milliseconds, can now be included.

This method reads the contents of a web page at the specified url and returns a tuple (contents, code), where code is HTTP status code for that page (404, 403, 500 and 200 are currently supported).

The intended purpose of this method is to allow python to read .txt files hosted online, to allow more dynamic scripting without having to force game definition updates. There may be many other uses as well.

NOTE: Only .txt files are recommended to be used with webRead.

New in Octgn 3

Opens the user's default web browser to the specified URL. It asks the user's permission first to allow for URL verification. Please be responsible when using this method.

New in Octgn 3

Read-only: Returns the current turn number as an integer (from the internal turn counter)

Asks the user a confirmation, displaying message in a dialog box. Returns True if the user answers Yes, False otherwise.

Shows a dialog box with question and defaultAnswer. The user must provide a positive integer. Returns the provided integer, or None if the user closes the window instead.

      count = askInteger("Draw how many cards?", 7)
      if count == None: return
      for c in me.Deck.top(count): c.moveTo(me.hand)

Shows a dialog box so that the user can choose a marker type and quantity. Returns a couple (marker, quantity) or (None, 0) if the user doesn't choose any marker (closes the window).

      marker, qty = askMarker()
      if qty == 0: return
      card.markers[marker] += qty

Shows a dialog so that the user can choose a card type and quantity. restriction limits the choice of cards available. Valid syntax is "[property name]", "'string constants'", "numbers", common operators "+, -, *, /, >, >=, <, <=, <>, =" and logic operators "and, or, not". Returns a couple (card, quantity) or (None, 0) if the user doesn't choose any card (closes the window).

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

New in Octgn 3

Returns the version of OCTGN that the user is using.

New in Octgn 3

Returns the version of the game definition that the user is using.

New in Octgn 3

returns the variable stored in the server's globalVariables.

NOTE: The global variables are stored as strings and must be converted to the data type you require (int, dict, list, etc.) after calling this function.

New in Octgn 3

stores the value into the variable defined in the server's globalVariables.

NOTE: setGlobalVariable stores the variable as a string.

Player variable representing the local player. You should not overwrite its value.

Table variable representing the table. You should not overwrite its value.

An array of type Player representing an unordered list of all players in the game.

The Player class provides dynamic properties to easily access game-defined piles and counters, e.g. me.Deck or me.Score. Those dynamic properties are case-insensitive. If the pile or counter name can't be used that way (i.e. it contains some invalid symbol such as a dot or a space), use the long syntax instead: me.piles["Discard Pile"] or me.counters["Victory Points"] . Note that the hand is a regular property, hence it IS case-sensitive. Always use: me.hand.

Read-only; nickname of this player.

New in Octgn 3

Read-only; a string representing the color assigned to the player. Returns a color formated in html notation: #000000.

Read-only; instance of Hand, or None if this game doesn't use hands.

Read-only; dictionnary containing this player's counters. Keys are names (case-insensitive); Values are Counter object, that have two properties: name and value (settable). If the counter name is a valid Python identifier, its value can be accessed directly from the Player object.

      me.Score = 10
      me.counters['Score'].value += 1

Read-only; dictionnary containing this player's piles. Keys are names (case-insensitive); Values are Pile instances.

New in Octgn 3

Read-only; a boolean value determining if the player has an inverted table.

NOTE:Will return TRUE if the player is on the "inverted side" (side B)of a two-sided table.

New in Octgn 3

Read-only; a boolean value determining if it is the player's turn.

New in Octgn 3

Will pass the turn to the indicated player. This function works identically to clicking the green "end turn" buttons on the player tabs, and will do nothing if you try to pass to the player who is already the active player.

NOTE: This function is used to PASS THE TURN only! You cannot use it to take control of the turn, so me.setActivePlayer() will NEVER DO ANYTHING!

For 2 player games, always use players[1].setActivePlayer() to pass the turn to your opponent (who is always at the [1] index of the players list.

New in Octgn 3

returns the variable stored in the player class's globalVariables. Python can read the variable stored by any player via:

    player.getGlobalVariable(variable)

NOTE: The global variables are stored as strings and must be converted to the data type you require (int, dict, list, etc.) after calling this function.

New in Octgn 3

stores the value into the variable defined in the player class's globalVariables.

NOTE: setGlobalVariable stores the variable as as string.

NOTE: You can only store or modify variables in your own class, i.e.

    me.setGlobalVariable(variable, value)

Group classes behave like read-only collections. You can count the number of cards len(table), access a specific card me.Deck[3], take a slice me.hand[2:5] or iterate them for c in table.

Note that you can't modify this collection directly, use card.moveTo() and card.moveToTable instead.

Read-only; the name of this group.

Read-only; the owner of this group.

Returns a random card inside the group, or None if the group is empty.

Creates quantity new cards on the table, at position (x, y). If persist is False, the cards vanish when they leave the table. Each card created is of type given by model, which is a guid (as string). You can either pass a constant, or ask the user to choose such a guid by using askCard(). This method returns the newly created cards for further manipulation by the script. If quantity is 1 the card is directly returned. Otherwise an array of Card is returned. If the model/guid doesn't exist in the database, this method will return None instead.

Returns a new couple (x,y) slightly offset with respect to the (x,y) input position. This method does a non-trivial work as it takes into account whether the table is two-sided, if y is in the inverted zone and the size of the cards.

New in Octgn 3

Returns true if the table is two-sided.

Returns true if the table is inverted at the y coordinated specified.

Hand doesn't add anything to Group.

If count is None returns the top card of the pile, or None if the pile is empty. Otherwise returns an array with the top count cards (as much as possible).

      me.Deck.top().moveTo(me.hand)
      for c in me.Deck.top(10): c.moveTo(me.Discard)

If count is None returns the bottom card of the pile, or None if the pile is empty. Otherwise returns an array with the bottom count cards (as much as possible). See "Top" for examples.

Securely shuffles the pile.

The Card class provides dynamic properties to easily access game-defined properties, e.g. card.Type or card.Cost. Those dynamic properties are case-insensitive. If the property name can't be used that way (i.e. it contains some invalid symbol such as a dot or a space), use the long syntax instead: card.properties["White Magic"].

Read-only; returns the GUID (as a string) of the card type.

Read-only; returns the name of the card.

Read-only; dictionnary of custom properties as defined by the game. Keys are property names (case-insensitive); Values are actual properties values.

Read-only; player who owns that card.

Read-only; player who currently controls that card.

Read-only; the group this card is currently in.

Note: use moveTo() or moveToTable to change group.

True if the card is face up, False otherwise. card.isFaceUp = not card.isFaceUp # Toggle the card face up / down

New in Octgn 3

Returns true if the alternate image is being displayed.

New in Octgn 3

Swaps between the normal and alternate images of the card.

NOTE: isAlternateImage() and switchImage() checks the set definition for an alternate image. For example, if "cardA.jpg" is the filename for the card, its alternate image must be indicated by the filename "cardA.b.jpg".

New in Octgn 3

Reveals the identity of the card to the local player. This is identical to manually right-clicking and selecting "Peek at Card"

New in Octgn 3

This function combines these built-in right-click actions: "pass control to --> player", and "take control" depending on who the current controller of the card is. Will do nothing if the specified player already controls the card.

examples:

• card.setController(me) #will take control of the card
• card.setController(players[1]) #will pass control to your opponent (in two-player games)

One of the four constants Rot0, Rot90, Rot180 and Rot270. Note that those constants combine: Rot270 = Rot180 | Rot90. card.orientation = Rot90 # Set orientation card.orientation ^= Rot90 # Toggle card.orientation |= Rot180 # Flip card card.orientation &= ~Rot180 # Unflip card

Read or write a color in format "#rrggbb" (hex) which is used to highlight the card, or None. It is advised to declare constants to ease using this property.

      AttackColor = "#ff0000" # Red
      card.highlight = AttackColor
      position

Read-only; couple (x, y) indicating the card's position on table. Use moveToTable(x,y) to move the card.

Only works on table. Sends the card behind all other cards on the table.

Only works on table. Sends the card on top of all other cards on the table.

Gets the index of the card in the pile or group. index is an integer value >=0.

NOTE: This can change after getting the index if a card is moved, added or removed from the table in any fashion.

Only works on table. Moves the card to index index. Index is the z coordinate of the card, or how far from the top the card is located. 0 is the bottom of all cards.

Read-only; a dictionary containing all markers set on the card, and the quantity associated with them. Keys are a couple ("name", "guid") used to identify the specific marker; Values are the quantity of markers (can be set). To create a new key (adding a new marker to the card) you can either use askMarker() or create a constant.

      DamageMarker = ("Damage", "fabd2965-929e-4ee9-b69c-e278e3cd4098")
      card.markers[DamageMarker] += 1

The GUIDs for OCTGN's internal markers are "00000000-0000-0000-0000-00000000000#" where # is:

  1 - white
  2 - blue
  3 - black
  4 - red
  5 - green
  6 - orange
  7 - brown
  8 - yellow

Move the card to group or change index inside group. If index is None the card is moved to the top of piles, and to the end of hands.

Move the card to the bottom of pile.

Move the card to the table at position (x, y). faceDown can be used to move a card to the table face down.

       #moves the card facedown to the table at (300,-150).
       card.moveToTable(300,-150,True)

Adds the card to current selection.

Targets the card. If active is False remove all targets from the card.

This read-only property contains the player targeting this card, or None if the card is not targeted.

  if card.targetedBy == me:
    card.markers[ChargeMarker] += 1

Static method; returns the card width as defined by the game.

Static method; returns the card height as defined by the game.

This will switch a card with some predefined alternate version. Please see the SwitchWithAlternate README for more details.

This will return false, unless a card has been through one or more switchWithAlternate() calls, and is not currently the original version. Please see the [SwitchWithAlternate README] (https://github.com/MagnusVortex/Standard-Playing-Cards---OCTGN/blob/Alternate/SwitchWithAlternate_README.txt) for more details.