definition.xml

This page outlines the full structure of the XML game definition.

XML Structure

root: <game>

1. <scripts>
2. <events>
3. <sounds
4. <fonts>
5. <proxygen>
6. <documents>
7. <gameModes>
8. <globalvariables>
9. <card>
10. <table>
11. <player>
12. <shared>
13. <deck>
14. <sharedDeck>

<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. Every game must have a unique guid id.
• octgnVersion - This is the minimum version of OCTGN your game can run on. It can be denoted by 1.2.3 or(3 digits instead of 4 is no longer valid) 1.2.3.4(More info on versioning)
• version - This is the version of your game. It is recommended that you increase the version number every time you put out a new release, otherwise it may no install properly. It can be denoted by 1.2.3 or(3 digits instead of 4 is no longer valid) 1.2.3.4(More info on versioning)
• scriptVersion - Sets the API version your game is going 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 lowest version available.
• markersize - The size of your markers. 25 seems like a good default if you're not sure.
• setsurl - This is a url where users can go to download [Card packages](Card package).
• gameurl - This is the main url for your game. If users want to download the latest version, get in contact with you, or anything else related to your game, this is the link they will use to do so.
• authors - This is a comma separated list of authors of a game, for example Joe, Jim.
• description - This is a short description of your game. This will give users a taste of what your game is about before they download it.
• tags - This is a space separated list of tags that will help users find your game, for example cards chicken. If a user searches for either, your game will show up somewhere in the list.
• iconurl - This is a url to an image file on the web, so that your game can have an associated icon. A good size is 64x64 or more, as long as it's square(preferably not to big, or whenever someone finds your game it may take awhile to download the image).
• usetwosidedtable - Optional - Default: True - If this is true any game played with this definition will use a two sided table, otherwise it won't.
• noteBackgroundColor - Optional - Sets the background color for notes. Uses hex values, with the first value pair being opacity. 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 opacity. Ex. #AAFF0000 . Solid red background that's not completely opaque.

1. <scripts>

One can load several Python files. Function that are declared inside those files can then be used by game actions (see Action Definition).

Scripts are referenced inside a scripts tag, which contains a collection of script tags. Each tag has the following attributes:

• src (The id of the relationship defined in game.xml.rels pointing to the Python script file.)

A relationship to a Python script should have the http://schemas.octgn.org/script type. Here's an example of a correct relationship:

<Relationship Target="scripts/actions.py" Id="r10" Type="http://schemas.octgn.org/script" />

2. <events>

You can hook on to specific OCTGN game events by declaring them in the events section here. You can also hook up multiple event hooks to a single event, allowing for more specialized functions.

You can view a list of all the available events for Test and Live

Each event hook is registered with the following syntax

<events>
    <event name="eventName" action="pythonFunctionToCall"/>
    <event name="eventName" action="pythonFunctionToCall2"/>
    <event name="eventName2" action="pythonFunctionToCall3"/>`
</events>

• name (The name of the event(which you can find in the Test and Live lists.

• action (the python function to call when the event happens. You can find a list of parameters you can use for Test and Live

A simple example using the event by using an event to catch when someone changes a Counter value

In the Live you can see the following xml

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

this would coorilate to the following event attribute in your game definition file

<event name="OnChangeCounter" action="onTheCounterChanges"/>

and the following python function

def onTheCounterChanges(player,theCounter,theOldValue):
    notify("{} changes {}={} to equal {}".format(player,theCounter,theOldValue,theCounter.value))

Which if our nickname was "bob" and we changed the Counter "faceCount" from 1 to 2 would write

bob changes faceCount=1 to equal 2

3. <sounds>

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

You can use .wav, .mp3 or .ogg files.

<sounds>
    <sound name="tim" src="sounds/soundfile.wav"/>
</sounds>

4. <fonts>

You can add up to two custom fonts to include with your game definition. One font affects the context menu (right click menu) the other will affect the chat window. The fonts must be included in your game definition, and cannot simply reference fonts already installed on a user's computer. Both fonts need to be TrueType (file extension is .ttf). Both fonts can be named anything you want. Preferably they should keep the original filename. In order for the game to see these fonts you must do the following.

  <fonts>
    <!-- Sets the font for the chat input in game -->
    <font src="fonts/Western-Regular.ttf" size="11" target="context" />
    <!-- Sets the font for the chat in game -->
    <font src="fonts/Western-Regular.ttf" size="11" target="chat" />
    <!-- Sets the font for the notes in game -->
    <font src="fonts/Western-Regular.ttf" size="11" target="notes"/>
    <!-- Sets the font for the deck editor -->
    <font src="fonts/Western-Regular.ttf" size="11" target="deckeditor" />
  </fonts>

5. <proxygen>

See [proxy Generator] (proxyGenerator)

6. <documents>

The Game Definition can define plain text or html documents to serve various functions in-game, such as "Game Rulebook" and/or "Game Help". These are specialized buttons that appears under the "Help" tab of the in-game ribbon.

For each button, you MUST define the label name, icon image, and source path. The XML tags look like this:

    <documents>
        <document name="{Label}" icon="icon/mypic.jpg" src="documents/thedoc.txt" />
        <document name="document name2" icon="icon/mypic2.jpg" src="documents/thedoc2.txt" />
    </documents> 

Documents will appear in a window width of 800px.

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 icon won't appear, but it's still required (see #876

7. <gameModes>

The gameModes tag lists the different gameMode's available for your game.

###gameMode

• 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 what it means.)
• image (Relative path to an image for the game mode.)
• playerCount (The number of players required to start the game. Can be less/more in custom, but must be exact in matchmaking)

8. <globalvariables>

OCTGN maintains its own type of Global Variables, which are truly global as all players are able to read and write them. This differs from Python's own Global Variable system, which are only stored locally and do not broadcast to other players.

This is used to assign initial conditions to the global variables are readable and writable by all players. The variables are referenced in globalvariable tags, and are written as such:

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

in Python, use [getGlobalVariable(name)](OCTGN python api reference#getGlobalVariable) to retrieve a global variable, and [setGlobalVariable(name, value)](OCTGN python api reference#setGlobalVariable) to store one. 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.

Global Variables will all reset to their default values when a game is restarted.

NOTE: The global variables are always stored as a string, and must be converted via python if you wish to treat them as another variable type such as a dictionary. Use str(variable) to convert to a string, then eval(string) to convert back to the original type.

9. <card>

  <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>

The <card> tag defines the appearance and content fields of the game cards. The following attributes are available:

Attribute	Description	Accepted Values
width	The width in mm of the card	any INTEGER value
height	The height in mm of the cad	any INTEGER value
front	the image resource for the unloaded front of the card	root filepath to the image
back	the image resource for the back of the card	root filepath to the image
cornerRadius	The rounded corners radius of the card, in mm. Optional and defaults to 0 - square corners	any INTEGER value

<card> also includes the <property> and <size> child tags:

<property>

Each custom card property used in the set definitions require a <property> tag to define them. The following attributes

which contain information like cost to play, rules, rarity, or anything else the game needs are defined by tags. A field "name" is always implicitly defined by OCTGN. The following attributes are used:

Attribute	Description	Accepted Values
name	The name of the property, i.e. "Cost", "Rules"	any String value; a-z A-Z 0-9 - _
type	The datatype of the property	"String" , "Integer"
ignoreText	Boolean; if True the property is hidden from python searches	"True" , "False" (default)
textKind	Defines how string properties are sorted in the Sealed deck editor	"Free" (default), "Tokens", "Enum"
hidden	Boolean; if True the property column is hidden from the deck editor	"True", "False" (default)

NOTES:

• ignoreText will only hide String properties from python functions such as askCard() textKind="Tokens"

• textKind="Free" is any text, and will not appear as a filter in the sealed deck editor.

• textKind="Tokens" means that the property contains space-separated values (e.g. card type may be "Human Warrior", or color may be "Blue Yellow"). Each individual value will be its own searchable item.

• textKind="Enum" means the string is a restricted set of possible values (e.g. rarity is "Rare", "Common" or "Uncommon"). The whole string will be a searchable item.

<size>

Defines all custom card sizes used by the game, which allows your cards to be different sizes in a game. The attributes are similar to those in the <card> tag

Attribute	Description	Accepted Values
name	the name identifier used to flag cards with this custom size	any STRING value; a-z A-Z 0-9 - _
width	The width in mm of the card	any INTEGER value
height	The height in mm of the cad	any INTEGER value
front	the image resource for the unloaded front of the card	root filepath to the image
back	the image resource for the back of the card	root filepath to the image
cornerRadius	The rounded corners radius of the card, in mm. Optional and defaults to 0 - square corners	any INTEGER value

10. <table>

The table tag defines the characteristics of the virtual card table and the actions that are available from it. The following attributes are available:

• visibility (The default visibility of cards in this group. Usually "undefined")
• ordered (True if the order of the cards in the group is important, false otherwise.)
• width (The width of the group in mm.)
• height (The height of the group in mm.)
• hidden (When true, this property should never be displayed to the user. Isn't 100% working right now, e.g. it still appears in the deck builder.)

Defining the Group and Card actions is explained in the Action Definition article.

11. <player>

The tag defines the Hand, Counters, player-specific Global Variables and Groups available to each individual player. For details on Counter definitions, consult the Counter Definitionarticle.

The player specific Global Variables are used to set initial values to the player's personal set of global variables. These are writable only by the player but are still readable to other players. They are defined as such:

<globalvariable name="standing" value="1" /> 

The details on the Hand and Group definitions are explained in the Group Definition article. It also accepts the following attribute:

• summary which describes the key indicators displayed inside the player tabs. Text is free, but {#name} placeholders are replaced by either the card count or the counter value of the corresponding object. E.g. {#Score}/{#Hand} may display 5/2 meaning a score of 5 and a hand count of 2 (if the Score counter and the Hand group are defined).

12. <shared>

The <shared> tag defines common elements all players share among each other. It contains Counter Definition and Group Definition.

13. <deck>

The tag defines the deck format. It consists of one or more <section> child-tags that structure the deck into multiple parts like "Main Deck" and "Side Deck". The <section> tags require the following attributes:

• name (The name of the deck section.)
• group (The name of the group into which the sections should be moved when a deck is loaded.)

14. <sharedDeck>

The <sharedDeck> tag uses exactly the same format as the <deck> tag.