definition.xml

Game Definition XML: definition.xml

This is the only file found in the root directory of the Game Package. It is an XML file which contains all of the data and properties that OCTGN requires to locate the game on a feed, play the game, or use the deck editor. This page outlines and documents the structure of the XML.

NOTE: ALL files, images, and other assets used by the game definition must be placed in folders, as only the only file allowed in the root directory is this XML (definition.xml). When defining the source URL links to these files, use the relative path from the root directory. For example, if you have a Python file called scripts.py in the Scripts folder, use Scripts/scripts.py as the src. (Case-sensitive, note that there is no slash at the beginning of the URL)

XML Structure

o8build requires the child elements of <game> to be in a specific order as listed below. Child elements that are mandatory will have a * denoting so.

<game>*

<scripts>
<events>
<sounds>
<fonts>
<symbols>
<markers>
<proxygen>*
<phases>
<documents>
<gameModes>
<globalvariables>
<card>*
<gameboards>
<table>*
<player>*
<shared>
<deck>
<sharedDeck>

</game>

`<game>`

Every game must have a root xml element called game. These are the following attributes for game.

name - This is the name of your game
id - This is a GUID used to uniquely identify this game. Every game must have a unique GUID.
octgnVersion - This is the minimum version of OCTGN that your game is compatible with. You must use OCTGN's 4 digit versioning system, i.e. 3.1.70.0
version - This is the version of your game. You must use the 4 digit versioning system, i.e. 3.1.70.0. OCTGN will always install/update the largest game version it can find within its installed feeds. It is recommended that you increase the version number every time you put out a new release, otherwise some players may not receive the update. Note that players will not be able to play together if their game's versions differ by the first two digits.
scriptVersion - This is the specific version of the Python API version that your game scripts will use. You can see which versions are available here and which events each version supports here. If the version number you use does not exist (for example, if that version has expired from OCTGN), OCTGN will default to the oldest version available.
markersize - The height value that markers will size to on cards. The value is the same unit as the defined height of the card, and all marker images will resize to the same height value.
setsurl - This is a URL where users can go to find available [image packages](Card package) for the game. It is not currently used by OCTGN.
gameurl - This is the main URL for your game, and will appear in the game' information panel in the game feeds. It provides a useful link for the user to find more information online about the game. It is also the link that OCTGN will provide the user if there is an error with the game definition.
authors - This is a comma separated list of authors of a game, for example Joe, Jim. It is displayed in the information panel on the game feed.
description - This is a short description of your game that appears in the information panel on the game feed. This will give users a taste of what your game is about before they download it.
tags - This is a space separated list of searchable tags that will help users find your game. It currently has no functionality in OCTGN.
iconurl - This is a URL to an image file on the internet, to be displayed as the game icon in the game feeds. OCTGN fits the icon into a 64x64 space, so a square-shaped image is recommended.
usetwosidedtable - Optional, defaults to True. This sets the default setting for whether or not the table will be two-sided. Users can change this value while in the pre-game lobby.
noteBackgroundColor - Optional - Sets the background color for notes. Uses hex values, with the first value pair being the transparency value. Ex. #AAFF0000 . Solid red background that's not completely opaque.
noteForegroundColor - Optional - Sets the foreground color for notes. Uses hex values, with the first value pair being the transparency value. Ex. #AAFF0000 . Solid red background that's not completely opaque.

`<scripts>`

Defines any Python scripting files used by the game. See [Scripting in Python](scripting in python) for more information on the Python scripting engine.

Each script file has its own <script> tag, and contains the following attributes:

src (The relative path of the script file)

An example of the <scripts> tag:

<scripts>
    <script src="Scripts/scripts.py"/>
    <script src="Scripts/actions.py"/>
</scripts>

`<events>`

OCTGN can call specific Python script functions when certain in-game events are triggered, such as a player ending their turn, loading a deck, restarting the game, or moving a card. This allows a game's Python scripting to provide customized functionality to in-game events.

The events are associated with a specific Python API version, as declared in the <game>'s scriptVersion. The events may behave differently depending on the API version.

Each game event may pass specific parameters, such as the card objects, player triggering the event, or various properties of the card, to the assigned python function. It is important that your python function includes the correct parameters for the given event, otherwise you will receive errors. To view a list of all the available events for a given API version, as well as the required parameters, CLICK HERE.

Each event has its own <event> tag, and contains the following attributes:

name (The exact name of the event to be triggered)
action (The name of the Python function to pass the event's parameters to)

NOTE: You may use the same event more than once, if you wish to pass the parameters to more than one python function.

Here's a practical example of implementing an OnChangeCounter event into a game:

<events>
    <event name="OnMoveCards" action="moveCardEvent"/>
    <event name="OnMoveCards" action="anotherMoveCardEvent"/>
    <event name="OnChangeCounter" action="counterChangeEvent"/>`
</events>

This is what the parameters for the OnChangeCounter event looks like (from Game Events Reference):

<event name="OnChangeCounter">
    <param name="player" type="Player"/>
    <param name="counter" type="Counter"/>
    <param name="oldValue" type="int"/>
</event>

When the event is triggered, OCTGN will will pass the (player, counter, oldValue) parameters to the counterChangeEvent function defined in your Python script file(s):

NOTE: If using Script version 3.1.0.2 or above, the arguments will be passed in a single table. That is to say, instead of it passing you player, counter, and oldValue, it'll pass you one object (args) and you can get the parameters by doing args.player, args.counter, and args.oldValue respectively.

#script version 3.1.0.0 or 3.1.0.1
def counterChangeEvent(player,counter,oldValue):
    notify("{} changes {} counter from {} to {}".format(player,counter,oldValue,counter.value))

#script version 3.1.0.2
def counterChangeEvent(args):
    notify("{} changes {} counter from {} to {}".format(args.player,args.counter,args.oldValue,args.counter.value))

`<sounds>`

Defines sound files which are available to use in-game via the playSound() python API function.

The supported sound files are .wav, .mp3 or .ogg.

XML example:

<sounds>
    <sound name="doorbell" src="Sounds/doorbell.wav"/>
</sounds>

`<fonts>`

You can include multiple fonts in your game definition, which some games have used to include game-specific symbols or styles to their games. The fonts must be included in the game definition, so you cannot reference fonts which may be installed on the user's computer. Only TrueType fonts, .ttf are allowed.

The following attributes are used in the <font> tags:

src (the relative path to the font file)
size (the size of the font to display)
target (the area within OCTGN to apply the font to)

There are four areas within OCTGN that you can apply custom fonts to, as specified by the target attribute (Note that each target can only be assigned once):

context (the input section of the in-game chat box)
chat (the logged chat messages in the in-game chat box)
notes (the game notes functionality)
deckeditor (the text displayed within the deck editor's card database)

  <fonts>
    <font src="fonts/Western-Regular.ttf" size="11" target="context" />
    <font src="fonts/Western-Regular.ttf" size="11" target="chat" />
    <font src="fonts/Western-Regular.ttf" size="11" target="notes"/>
    <font src="fonts/Western-Regular.ttf" size="11" target="deckeditor" />
  </fonts>

`<symbols>`

See set.xml for further information on symbols.

Defines the location and properties of symbol icons which can be inserted into a card's custom property text. Symbol icons must be saved and referenced inside the game package as image files.

The following attributes are used in the <symbol> tags:

name (the name of the symbol, which appears whenever you hover the image)
src (the relative path to the image file)
id (an identifier to reference the image in the custom property text)

<symbols>
    <symbol name="Military" id="military" src="symbols/military.png" />
</symbols>

`<markers>`

Contains any number of child <marker> elements, each one representing a single marker object. Markers are OCTGN's term for the counters (beads, indicators, coins, dice, etc) that players can place onto cards to indicate certain traits or quantities.

Markers were originally defined in the set XML files, but as of OCTGN version 3.4.240, they are now defined in the game definition XML.

The <marker> child elements must each contain the following attributes:

name - the name of the marker, which will appear when you hover the marker. It will also be used as the label in the askMarker python API dialog window.
id - the unique identifier assigned to this marker. Python scripts use this to reference the marker. (NOTE: This is the equivalent to the GUID identifier used for the old set markers format)
src - the relative file path to the image file for this marker

`<proxygen>`

Defines the location of the proxy template XML definition. See See [proxy Generator] (proxyGenerator) for more detailed explanation of this functionality.

The following attributes are used:

definitionsrc (the relative path of the proxy template XML definition)

NOTE: the definitionsrc attribute is within the <proxygen> tag; there are no child elements.

`<phases>`

Phases define the different parts that make up a turn of a game. They allow players to communicate what part of the turn they are currently on.

OCTGN implements Phases via a toolbar that appears on the top-right corner of the game table. As long as the <phases> section is defined in your game definition, it will show. Hovering over the Phases toolbar will display a graphical list of all phases available in the game, which the user can click to interact with. Its functionality changes depending on who is the active turn player -- Only the active turn player is allowed to actually change the current phase. All other players can place "Pauses" on the turn. When the active player attempts to switch to a different phase, if the current phase has a pause on it, it will prevent the passing of that phase and notify all players. This works similar to the "Pass Turn" arrow buttons on the player tabs.

OCTGN creates the Phase Toolbar based on the phases defined within <phases>. They will appear in the order listed and according to the defined icon image supplied. The following

The following attributes are REQUIRED for each <phase> child element:

name (the name of the phase)
icon (the relative path of an icon used to represent the phase on the Phase Toolbar)

  <phases>
    <phase name="Draw Step" icon="icon/mypic.jpg" />
    <phase name="Action Phase" icon="icon/mypic2.jpg" />
  </phases>

`<documents>`

The game definition can include documents to serve various uses in-game, such as a a game rulebook or user guide. Each document will be listed inside the documents menu of the game table.

Documents can be in .pdf, .txt, .html formats. Other format types may be supported depending on a user's system. If you use HTML documents, you can do any complex function that HTML supports, for example hyperlinking or redirecting. You can even use it to include images in your documentation. The default width of the documents window will be 800px.

The following attributes are used:

name (the label name of the document item in the menu)
icon (the relative path of an icon used to identify the document)
src (the relative path of the document file)

NOTE: The icon attribute is REQUIRED, however OCTGN does not currently have a use for it yet.

  <documents>
    <document name="Game Rules" icon="icon/mypic.jpg" src="documents/rules.pdf" />
    <document name="Plugin Guide" icon="icon/mypic2.jpg" src="documents/guide.txt" />
  </documents>

`<gameModes>`

Defines all of the available game modes that are available for the game. These appear in the Matchmaking mode of game hosting, and users can choose a specific game type to join.

The following attributes are used:

name (The name of the game mode. Can be anything you want. (ex: Texas Holdem, Go Fish, Blackjack) )
shortDescription (A short description of the game mode. Lets the user know more information about the game mode.)
image (Relative path to an image used for the game mode button. OCTGN will resize to 64x64px, so a square-shaped image works best)
playerCount (The number of players required to start the game. Must be specific integer values, cannot use a range or minimum/maximum)
usetwosidedtable (Optional, defaults to True. This sets the default setting for whether or not the table will be two-sided. Users can change this value while in the pre-game lobby.)

8. `<globalvariables>`

Defines all of the global variables that the game's Python scripting can read and write from. These are different from Python's built-in global variable methods, as OCTGN's global variables will be shared among all players in the game. (Python's global variables, by contrast, are only stored locally)

The pros of using OCTGN's global variables over Python's global variables:

They are readable and writable by all players in the game, thus are shared.
They will not reset when a player is temporarily disconnected.
They will only reset to their default values when a player resets the game.

The cons:

They are networked methods, thus they can potentially slow down the performance of the game's scripting or cause some lag to the player.
They must be stored as STRING values. If other datatypes are being used by the variable (integer, list, dictionary, etc), you MUST convert them to strings before setting them.

The following attributes are used:

name (the STRING name assigned to the variable)
value (the default STRING value for the variable)

<globalvariables>
    <globalvariable name="dealer" value="1" /> 
</globalvariables>

in Python, use [getGlobalVariable()](OCTGN python api reference#getGlobalVariable) to retrieve a global variable, and [setGlobalVariable()](OCTGN python api reference#setGlobalVariable). All players are able to read and write to the OCTGN global variables, so be wary of this while designing more complicated Python scripts using Global Variables.

9. `<card>`

Contains all the data relevant for defining the behavior and appearance of cards in the game.

The following attributes are allowed within the tag, which define the properties of the DEFAULT card size:

front (the relative path of the default image for the card's front face, used when the identity of the card is not known to the player)
height (the unit height of the card's front face)
width (the unit width of the card's front face)
cornerRadius (the unit radius of the circle used to round the corners of the card. DEFAULTS to 0)
back (the relative path of the default image for the card's back/facedown face, used when the identity of the card is not known to the player)
backHeight (the height of the card's back/facedown face)
backWidth (the width of the card's back/facedown face)
backCornerRadius (the unit radius of the circle used to round the corners of the card. DEFAULTS to 0)

<card> also contains the <property> and <size> child tags

`<property>`

These define all of the different properties that are available to a card, for example "Cost", "Collector Number", "Type", "Rules Text". The property values provided by the [set definitions](Set Definition) will require these.

The following attributes are used:

name (The name of the property, i.e. "Cost" )
type (The dataType of the property. Accepted values are String, Integer, and RichText. These change how OCTGN handles the property's values for the deck editor grid, search filters, python, etc)
ignoreText (Boolean, if True, the property will be ignored by text searches within the View Piles and Python askCard() game windows)
textKind (Defines how the sealed editor will manipulate the property's values in its filters.) Accepted values are:
- Tokens (Property contains space-separated values and will be split apart for filters. Example, "Human Warrior" will be split into "Human" and "Warrior" filter values)
- Enum (Property value is treated as a complete string and will be filtered exactly as-is.)
- Free (DEFAULT, property is ignored by the sealed editor)
hidden (Boolean, if True the property column is hidden from the deck editor. Defaults False)

IMPORTANT: Certain property names are reserved in OCTGN for specific usage, and cannot be used as a custom property name: name, set, id, size.

`<size>`

Defines custom card sizes used by the game, which allows your cards to be different sizes in a game. These will override the default values assigned in the <card> tag. These custom sizes can be assigned to cards in the Set Definition XML.

The following attributes are used:

name (the name assigned to identify this custom size. The set definition will use the name value to associate a card with this size. See HERE for more information on how to assign a custom size to a card.)
front (the relative path of the default image for the card's front face, used when the identity of the card is not known to the player)
height (the unit height of the card's front face)
width (the unit width of the card's front face)
cornerRadius (the unit radius of the circle used to round the corners of the card. DEFAULTS to 0)
back (the relative path of the default image for the card's back/facedown face, used when the identity of the card is not known to the player)
backHeight (the height of the card's back/facedown face)
backWidth (the width of the card's back/facedown face)
backCornerRadius (the unit radius of the circle used to round the corners of the card. DEFAULTS to 0)

  <card back="cards/back.jpg" front="cards/front.jpg" width="63" height="88" cornerRadius="2">
    <property name="Cost" type="String" />
    <property name="Type" type="String" textKind="Tokens" />
    <property name="Rarity" type="String" ignoreText="True" textKind="Enum" />
    <property name="Number" type="Integer" />
	<size name="Wide Card" width="126" height="88" back="cards/backwide.jpg" front="cards/frontwide.jpg" cornerRadius="14"/>
  </card>

`<gameboards>`

Defines the default game board that OCTGN places over the table. The image will be re-sized proportionally to fit inside the rectangle drawn by the given attributes.

The following attributes are required:

src (The relative path of the image)
x (The Leftmost x coordinate of the image to be placed on the table)
y (The Topmost y coordinate of the image to be placed on the table)
width (The horizontal unit width of the image's boundary)
height (The vertical unit height of the image's boundary)

You can also define any number of additional game boards within <gameboard> child elements. The Python API will be able to switch between game boards.

<gameboard> share the same attributes as <gameboards>, with the addition of:

name (The identifying name used by the Python API to switch between boards. Note that the default game board has the name Default, and cannot be used as a name by alternate boards)

NOTE: The default game board used to be defined within the <table> element, which is still supported to provide backwards-compatibility but won't be documented anymore.

  <gameboards src="board/playmat2.png" x="-601" y="-214" width="1078" height="429">
    <gameboard name="newboard" src="board/playmat.png" x="-300" y="-200" width="600" height="400"/>

`<table>`

Defines the characteristics of the Play Table, and the game actions that are available to the Table.

The following attributes are available:

name (A custom name to give to the Table)
visibility (The initial visibility of cards on the table. Players not included in the visibility will only see the face-down image of the card, but can peek at them. While customizeable, it is recommended to keep this at "undefined" or "all" due to the nature of the table.) Accepted values:
- none (Default, nobody has visibility)
- me (only the owner has visiblity. Nobody owns the table, so this is functionally identical to none)
- all (forces everyone to have visibility)
- undefined (no visibility assigned, all players will have visibility)
width (Sets the minimum viewable unit width of the table)
height (Sets the minimum viewable unit height of the table)
background (The relative path to an image file, which sets the wallpaper background of the table)
backgroundStyle (Sets the rendering style of the background image) Accepted values:
- tile (tiles the image to fill the entire table area, does not resize or stretch)
- uniform (Resizes to fill the table dimensions while preserving its aspect ratio. Will leave black space if the aspect ratio of the table is different from the image)
- uniformToFill (Resizes to fill the table dimensions while preserving its aspect ratio. If the aspect ratio of the table is different from the image, the image will clipped to fit in the destination dimensions.)
- stretch (will stretch the dimensions of the image to fit the entire table area. Does not maintain the aspect ratio of the image.

NOTE: The height and width values of the table are used to define the visible ranges of the coordinate grid at the 1X zoom level, based on the pixel length and width of the table when the play window is first loaded. The width unit, height unit, and (x,y) position of cards on the table will be with respect to this grid.

The <table> tag can include any number of <action> child tags. See the Action Definition article for documentation.

`<player>`

This defines the characteristics of the Player, and includes counters, global variables, the hand group, and custom pile groups.

The only attribute used in <player> is summary. This is a string which is displayed next to the player's name in each player tab. You can include references to a player's counter values, or the number of cards in their hand or piles. The syntax for this is {#VALUE}, where value is the full name of the pile, hand, or counter. For example: summary="Hand:{#Hand}|Score:{#Score}"

The <player> tag supports the following children tags: <counter>, <globalvariable>, <hand>, <group>.

`<counter>`

Defines the counters that appear in the player tab, which can keep track of values (such as a player's score or health value). These are editable integer values, and include buttons to manually increment or decrease the value.

The following attributes are used:

name (the name of the counter)
icon (the relative path of the icon used for the counter)
default (an integer, default is 0. The initial value for the counter)
reset (a boolean, default is True. If True, it will reset the counter's to the default value when the game gets reset)

`<globalvariable>`

These function similarly to the global variables defined in the <globalvariables> tag. Each player will receive their own named global variable, which can be get or set independent of those from other players.

`<group>`

Defines a pile, or a deck of cards. The visibility of a pile determines which players are able to see the top card in the players tab, otherwise it'll appear face-down.

The following attributes are used:

name (the name of the pile)
icon (the relative path of an icon image to associate with that pile)
visibility (The initial visibility of cards in the pile. Players not included in the visibility will only see the face-down image of the card, but can peek at them. For piles, only the top card of the pile is shown in the player tab.) Accepted values:
- none (Default, nobody has visibility)
- me (only the owner has visiblity.)
- all (everyone has visibility)
- undefined (no visibility assigned, all players will have visibility)
ordered (Boolean, True if the order of the cards in the pile are important. If True, a message will be sent to the chat log indicating that the player has reordered the contents of that pile)
collapsed (Boolean, True will collapse the pile. Collapsed piles are listed on the right side, and will take up less space in the player tab.)
shortcut (An optional hotkey value to assign to this group. When assigned, the CTRL+hotkey will move a hovered card to the top of this group, and CTRL+ALT+hotkey will move it to the bottom.)

The <group> tag can include any number of <action> child tags. See the Action Definition article for documentation.

`<hand>`

The Hand group is a specialized group, which displays the cards from left-to-right instead of in a traditional pile. You may only have 1 <hand> tag included, but it is not required.

<hand> uses the same attributes and child tags as <group>.

The <hand> tag can include any number of <action> child tags. See the Action Definition article for documentation.

`<shared>`

The <shared> tag defines the global player, which is a player controlled by the "server". It shares the same attributes and child tags as <player>, except no global variables.

`<deck>`

Defines the deck sections used in the deck editor to organize deck contents. Each deck section has a target group that it will add the cards into when you load a deck in-game. Multiple deck sections can load their cards into the same group.

The <section> child tags contain the following attributes:

name (The name of the deck section that is displayed in the deck editor)
group (The name of the defined pile (or Hand) that cards in this section should be loaded into when a player loads the deck in a game)

`<sharedDeck>`

Works the same as the <deck> tag, except these deck sections will load the cards into the global player's piles instead of local player piles.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

definition.xml

Game Definition XML: definition.xml

XML Structure

`<game>`

`<scripts>`

`<events>`

`<sounds>`

`<fonts>`

`<symbols>`

`<markers>`

`<proxygen>`

`<phases>`

`<documents>`

`<gameModes>`

8. `<globalvariables>`

9. `<card>`

`<property>`

`<size>`

`<gameboards>`

`<table>`

`<player>`

`<counter>`

`<globalvariable>`

`<group>`

`<hand>`

`<shared>`

`<deck>`

`<sharedDeck>`

Clone this wiki locally

definition.xml

Game Definition XML: definition.xml

XML Structure

8. <globalvariables>

9. <card>

<property>

<size>

<counter>

<globalvariable>

<group>

<hand>

Clone this wiki locally

8. `<globalvariables>`

9. `<card>`

`<property>`

`<size>`

`<counter>`

`<globalvariable>`

`<group>`

`<hand>`