Skip to content

set.xml

Jump to bottom Edit New page
brine edited this page May 12, 2020 · 6 revisions

The Set Definition (also called as Set Def, set xml, set.xml) is an .xml file which defines a single set (or expansion) of the game. It originates from the modular nature of collectible card games, where new cards are periodically released in groups referred to as "sets" or "expansions".

The Set Definition contains the raw data for the cards used in a game, including all custom properties (defined in definition.xml) of the card. It can also define specific properties of the set itself, such as the "booster pack" information required to generate card pools for Limited Game play.

Set XML Structure

<set>

</set>

<set>

Every set.xml file must have a root element called set. This contains all the child elements as well as the special properties of the set. These are the following attributes for set.

  • name - The name of the set.
  • id - The GUID associated with the set.
  • gameId - The GUID of the game this set belongs to.
  • version - The version of this set.
  • gameVersion - The minimum version of the game definition required to use this set.
  • hidden - OPTIONAL A Boolean value, if True, the set and its cards will be hidden from the deck editor.

<packaging>

Defines the contents of the "booster" packs associated with this set, to be used by OCTGN's Limited Game functionality. Any number of <pack> child elements can be included, each one representing a different type of pack. The following is a sample of a set with two defined packaging options:

  <packaging>
    <pack name="Booster" id="68a6bf36-13df-4b77-82fb-a20864043e59">
      <include id="06c3c25f-9417-8c1d-80ae-2032154385b2" set="06da10cc-273a-4898-89c5-fa7e2269c8b0" >
        <property name="Rarity" value="Common" />
        <property name="Type" value="Resource" />
      </include>
      <options>
        <option probability="0.25">
          <pick qty="1" key="Rarity" value="Super Rare" />
        </option>
        <option probability="0.75">
          <pick qty="1" key="Rarity" value="Rare" />
        </option>
      </options>
      <pick qty="2" key="Rarity" value="Uncommon" />
         <property name
      <pick qty="5" key="Rarity" value="Common" />
      <pick qty="1" key="Rarity" value="Common" >
        <property key="Type" value="Resource" />
      </pick>
    </pack>
    <pack name="Resource Pack" id="eb05cd61-ce9d-441d-9d41-738409f9b22a">
      <pick qty="unlimited" key="Rarity" value="Basic Resource" />
    </pack>
  </packaging>

<pack>

This element defines the properties of a single pack. It must include the following attributes:

  • name - the descriptive name of this pack. This will be used to identify the pack when players are choosing the packs they wish to use when they start a limited game.
  • id - a GUID identifier for this pack. OCTGN requires this to be unique so that it can network the chosen packs to the other players.

The <pack> element can also include any number of <include>, <pick> and <options> child elements.

<include>

Links to an existing card from a different set, adding it to the pool of possible cards to select from in this pack. It must include the following attributes:

  • id - The GUID of the card to link. Note that this card's GUID must exist in a different set.
  • set - The GUID of the set that the card belongs to. Necessary for OCTGN to locate the card, and the set GUID must exist.

<include> may contain any number of additional <property> child elements. These tags will OVERRIDE the existing property values defined from the original card, allowing you to customize how it gets selected from the pack generator. It requires the following attributes:

  • name - The name of the card's Custom Property to override. Note that this custom property's name must match one of the game's defined Custom Properties (see definition.xml <card><property>)
  • value - The new value for the specified Custom Property. Note that this will override the card's property value in the sealed deck editor's filter as well

<pick>

Defines the subsection of cards in the set that should be considered to add to the contents of the pack. It must include the following attributes:

  • key - The custom property to be filtering by when selecting cards to add to the pool
  • value - The property value from the specified key that must be matched by the filter
  • qty - The number of unique cards to be selected from the filtered list of matching cards. If "unlimited" is used for the qty attribute, then the entire filtered selection of cards in this pick will be added to the pack, and players can an unlimited amount of those cards to their decks.

Note that the pack generator will add a _unique _selection of cards for each individual instance of <pick> -- it will never duplicate them. If the filtered selection of cards is less than the defined qty value, then the generated pack will be less than expected.

For example, if a pack should contain 5 different cards where the "Rarity" value is equal to "Common", you would define it as:

 <pick qty="5" key="Rarity" value="Common" />

<pick> can include any number of additional <property> child elements. Each <property> tag represents an additional Custom Property value to filter by, providing a more defined card selection. Each <property> element requires the same key and value attributes as used by <pick>.

An example of a pack that should contain 3 different cards with a "Rarity" of "Uncommon" and a "Type" of "Resource":

 <pick qty="3" key="Rarity" value="Uncommon" >
     <property key="Type" value="Resource" />
 </pick>

<options>

This is used when certain slots of a pack has a probability of containing a different subset of cards. For example, many games have booster packs which contain one "Rare" card, but there is a smaller probability that the card can be replaced by one of a higher rarity.

The <options> element has no attributes and contains any number of <option> child elements.

Each <option> element must include the probability attribute, which defines the decimal probability of selecting that option. It can also include any number of <pick> child elements.

All probability values MUST add together to equal 1.

<cards>

  <cards>
    <card id="50d634aa-9aed-4583-81d6-c3097c090271" name="jim" size="Wide" >
        <property name="fruit" value="banana"/>
        <property name="stamina" value="1"/>
    </card>
    <card id="92abea24-1caa-49ee-bfbf-f696d64b20d3" name="joe">
        <property name="fruit" value="pear"/>
        <property name="stamina" value="12"/>
        <alternate name="joe apple" type="altfruit1">
            <property name="fruit" value="apple"/>
        </alternate>
        <alternate name="joe orange" type="altfruit2">
            <property name="fruit" value="orange"/>
            <property name="stamina" value="15"/>
        </alternate>
    </card>
  <cards>

Contains any number of child <card> elements, each one representing a single card.

<card>

Contains all data assigned to a specific card in the game. This includes all custom properties of that card (card data such as its Type, Cost, Rules Text, Collector Number, etc), as well as any "alternate" versions of that card.

The <card> element contains the following attributes:

  • name - the name of the card. This is used in various locations within OCTGN as a way to identify the card for players (deck lists, python, chat logs, deck editor, etc)
  • id - the GUID assigned to this card. This is the GUID that you want image files to be linked to in order to match the image to the card.
  • size - OPTIONAL, the size identifier for the card, if you want the card to use a custom card size.

The <card> element can also contain any number of <property> and <alternate> child elements.

<property>

Defines the value of a specific custom property for the card. The custom properties are defined in the <card> element of definition.xml. Only one entry for each property can be defined.

Here are the required attributes for <property>:

  • name - The name of the property. This name must match one of the custom properties defined in the game definition.
  • value - The value you want to assign to the property. (NOTE: RichText properties do not include this attribute. See the section on Rich Text properties below.

You do not need to include all game-defined custom properties in each card element. If you choose to omit certain properties, then OCTGN will consider the missing property's value to be null.

Rich Text properties

This is a specialized text format for custom properties defined in the game definition to have the RichText Type attribute. It allows for advanced XML syntax to add text formatting such as bold, italics, colored font, and symbol icons.

The following example highlights the syntax used for RichText properties:

<property name="Rules Text">This card has <b>BOLD</b> text and the <s value="thumbsup">[Thumbs Up!]</s> icon.</property>

The following elements can be used:

  • <b> (Bold Text)
  • <i> (Italicized Text)
  • <u> (Underline Text)
  • <c value="#RRGGBB"> (Colored Text, using #HEX color codes)
  • <s value="symbolid"> (Symbol Icon, symbolid being the symbol's id as defined in the game definition. NOTE: The inner text will replace the symbol icon for search filters and python functions)

You can nest some elements inside of others, however you cannot overlap them.

Valid:

<property name="Rules Text"> This <b>is <u>valid</u> syntax</b> </property>

Invalid:

<property name="Rules Text"> This <b>is <u>invalid</b> syntax</u> so you can't use it. </property>

<alternate>

Some cards may have "alternate" forms to them. These are a different set of properties and images that are assigned to the same card object, which can be "swapped" back and forth in-game. An example of this is a card with two faces, or a card which can "transform". All alternates of a given card share the same GUID, since they are still the same card.

The attributes and child elements of <alternate> are the same as for <card>, with one exception. Instead of the id attribute for the GUID, an alternate uses the type attribute. This is a identifier name associated with the specific alternate, which is used by python to switch back and forth between alternates. It is also used to match alternates to different image files, using the filename syntax {cardGUID}.{type}.{img}. The type identifier is unique within a card, but can be reused between multiple cards. Only alphanumerical characters are allowed.

Add a custom footer
Add a custom sidebar
Clone this wiki locally