definition.xml

This is the only file found in the root directory of the Game Definition. 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>
<proxygen>
<documents>
<gameModes>
<globalvariables>
<card>*
<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.

1. `<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>

2. `<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):

def counterChangeEvent(player,counter,oldValue):
    notify("{} changes {} counter from {} to {}".format(player,counter,oldValue,counter.value))

3. `<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>

4. `<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>

5. `<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.

6. `<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>

7. `<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)

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" and "Integer", and changes how OCTGN handles the property values)
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.

The following attributes are used:

name (the name assigned to this custom size. The set definition will use this value to associate a card with a specific custom 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 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>

10. `<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.
board (The relative path of an image to be used as a game board, which locks to the table's coordinate grid)
boardPosition (defines the X, Y, Width, and Height values of the game board as a tuple)

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.

11. `<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)

`<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.)

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.

12. `<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 , except no global variables.

13. `<deck>`

Defines the deck sections used in the deck editor to organize deck contents. 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)

14. `<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

XML Structure

`<game>`

1. `<scripts>`

2. `<events>`

3. `<sounds>`

4. `<fonts>`

5. `<proxygen>`

6. `<documents>`

7. `<gameModes>`

8. `<globalvariables>`

9. `<card>`

`<property>`

`<size>`

10. `<table>`

11. `<player>`

`<counter>`

`<globalvariable>`

`<group>`

`<hand>`

12. `<shared>`

13. `<deck>`

14. `<sharedDeck>`

Clone this wiki locally

definition.xml

XML Structure

<game>

1. <scripts>

2. <events>

3. <sounds>

4. <fonts>

5. <proxygen>

6. <documents>

7. <gameModes>

8. <globalvariables>

9. <card>

<property>

<size>

10. <table>

11. <player>

<counter>

<globalvariable>

<group>

<hand>

12. <shared>

13. <deck>

14. <sharedDeck>

Clone this wiki locally

`<game>`

1. `<scripts>`

2. `<events>`

3. `<sounds>`

4. `<fonts>`

5. `<proxygen>`

6. `<documents>`

7. `<gameModes>`

8. `<globalvariables>`

9. `<card>`

`<property>`

`<size>`

10. `<table>`

11. `<player>`

`<counter>`

`<globalvariable>`

`<group>`

`<hand>`

12. `<shared>`

13. `<deck>`

14. `<sharedDeck>`