Developer Guide

This guide will walk you through the process of creating your own custom set of cards for use in LOTR. A “Set” in OCTGN terms is simply an .xml file full of card data, placed within it’s own Set folder. As an example, open up windows explorer and navigate to:

MyDocuments\OCTGN\GameDatabase\a21af4e8-be4b-4cda-a6b6-534f9717391f\Sets\

That long string of letters and numbers is the GUID for the LOTR game. Inside the Sets folder, you’ll see a bunch of folders, each named their own GUID. And within each of those folders, there is a “set.xml” which defines all the cards included in that Set. So, all we need to do to create a new Set is to create a new folder with it’s own GUID, and create a new set.xml for our new cards. To generate your own GUIDs, go to a site such as:

http://www.guidgen.com/

Create a new folder within \Sets\ and give it a new GUID for a name. Download the following set_template.xml file and copy it to your new folder, then re-name it to “set.xml”

set_template.xml

Open up this .xml using Windows Notepad, or better yet a program that is designed to work with code, such as Notepad++ (do not use a word processor such as Word). On line 2, you’ll see a <set> tag with some properties. Enter the name of your Set into name=””, and copy your set’s GUID into id=”” (this must match the GUID of the folder you created). Do not change the gameID property, since that is already pointing to LOTR. gameVersion should be the current version of the LOTR game (you can check in OCTGN what the current version is, but it’s okay if the version you list here is a little outdated). version=”” is the version of your own Set, which should probably start at 1.0.

Now you’ll see a couple of empty card templates. The first one will be used for the vast majority of your cards, and the second one is set up for a two-sided quest card (which is why it includes the <alternate> tag and more properties to define the back side). Copy the first <card> definition and make as many copies as needed to fit all your new cards. You can do the same for the quest card definition for all your desired quest cards.

 

Card Data Entry

Now it’s time for data entry. You should be as complete as possible with your information, since the new version of OCTGN will generate proxy card images from this data.

Card id=””
Each card needs its own unique GUID. So generate one and enter that here.

Name
The name of the card

Unique
If a card is unique, then enter just the following symbol in this field:   ‰

Type
Should be one of Enemy, Treachery, Location, Hero, Ally, Event, Objective, Attachment, Treasure, Quest or Nightmare

Sphere
For player cards this should be one of

  • Leadership
  • Tactics
  • Spirit
  • Lore
  • Neutral
  • Baggins
  • Fellowship
  • Boon

For cards in the encounter deck this should be one of

  • Burden
  • Boon
  • Special (for cards that shuffle back into the Special deck like Sack cards or Smaug)
  • or left blank for all other encounter cards

Cost
For heroes this is the starting threat of the hero, for other player cards, the number of resources needed to play the card

Engagement Cost
Only used for enemies

Traits
These are the bold-italicized words on the card, such as Gondor, Rohan, Orc, etc.

Keywords
This spot can be used for things like “Ranged.”, “Attach to a hero.”, etc.

Text
The main card text

Shadow
Any shadow text here should actually start with “Shadow: ”

Encounter Set
The name of the Encounter Set this card belongs to, if any

Victory Points
A numerical value equal to the number of victory points granted by the card

Quantity
The number of copies this card should have

Setup
You can leave this blank. The only time it is used is for Quest Stage 1A. When you play an existing Quest in OCTGN, you may notice that using the Set Up Game function will pull select cards out of the encounter deck and put them on the table, in the staging area, or in the active location slot as instructed by Stage 1A’s card text. This setup field is where you can define where cards are supposed to go. (explained further below). Some cards have a setup effect written into the card text (such as boons).

  • ‘s’ – place the card in the staging area (i.e. Gandalf’s Delay)
  • ‘t’ – place the card on the table for user setup (i.e. Skilled Healer)

Symbols Guide

The following symbols have been added to the in game fonts. Simply copy and paste the appropriate character, and it will be properly converted in game.

  • Willpower – Ò
  • Threat – $
  • Attack – Û
  • Defense – Ú
  • Leadership – Ì
  • Spirit – Ê
  • Tactics – Ï
  • Lore – Î
  • Baggins – Í
  • Fellowship – ☺
  • Unique – ‰

 

Newlines and Quotations

If you want to add in newlines or quotation marks, you can’t simply hit [Return] or type “, since that will break the .xml document. So you need to enter a code that the XML will pick up on.

To make a newline, enter the following:                &#10;
To make a quotation mark, enter the following:    &quot;

You don’t need to worry about what comes immediately before or after these characters, and I often use two newlines right in a row to make the text skip a line.

 

Quest Cards

Quest Cards deserve some special attention because we are now trying to emulate a two-sided quest card. So we make use of the <alternate> property to define the back side of the card, which essentially has you define 2 cards within one <card> tag. Fill in the fields like normal for Side A of the card, then within the <alternate> section, fill in the fields for Side B. Note that Side B of the card does not get it’s own GUID, since it’s inherently linked to Side A. Now, in the Side A section, you can choose to use the “Setup” property if you want to start the quest with certain cards picked out of the Encounter deck and placed on the table somewhere. This is completely optional, and if you’d like to implement it, here’s how it works:

We have designated 3 spots where cards can be placed during Setup:

  • ‘s’ – the card is moved to the staging area
  • ‘l’ – the card is moved to the active location area
  • ‘t’ – the card is moved to the table (under the quest cards)

I’ll use the Escape from Dol Guldur quest as an example as I explain how Setup works. The setup instructions on stage 1A instruct you to put the 3 objective cards in the staging area, and the Nazgul of Dol Guldur aside and out of play. So, I would make the value=”ssst”, since the first three cards should be added to the staging area, and the fourth card should be placed on the table. Make a note of this value somewhere because you’ll need it when it comes time to build your scenario deck (.o8d).

 

Testing

When you’ve filled out all your card data, now it’s time to test it out. As long as your Set folder is sitting alongside the rest of the Set folders on your hard drive, then you’ve already got it installed. Load up OCTGN, open up the Deck Editor, and create a new Lord of the Rings deck. Click the Set filter, then use the pull-down menu to select your new Set. If your Set is not listed here, that means there’s an issue with your xml file and it didn’t compile correctly. The most common problem I’ve run into is a break in one of my fields (perhaps a ” mark is missing, or some data exists outside the ” “).

If the cards are working properly, but you’d like to alter the card data (if you notice a typo or something), then simply edit and save your xml file. However, you’ll also need to delete the old proxy card image so that OCTGN knows to generate a new image (otherwise it’ll simply display the existing card image, and your change won’t be seen). Navigate to:

MyDocuments\OCTGN\ImageDatabase\a21af4e8-be4b-4cda-a6b6-534f9717391f\Sets\

And simply delete your Set folder that was generated here. If you close and re-open OCTGN, it will once again generate new card images here as you view them in the Deck Editor.

 

Adding Card Images

At this point, all your cards should be completely playable with the proxy images. If you want to go the extra mile, you can now you can add in your own images for the cards. This section of the guide is also applicable to those who wish to replace the proxy card images of public releases with their own scans (when the Image Pack has yet to be released).

There are 3 ways to do this:

1) Drag and drop your images into the Deck Editor
2) Manually add your images into the proper folder in the ImageDatabase
3) Create an .o8c Image Pack that you can install within OCTGN

Option 1 is definitely the easiest, but it’s for OCTGN subscribers only. Simply open up the Deck Editor, highlight a card, then drag a card image from windows explorer onto the card image in the Deck Editor to replace it. Options 2 & 3 are basically the same, with the latter involving an extra step to package it up. In all cases, you’ll need to format your card images to be either .jpgs or .pngs with a height of about 600px (anything below around 500px can become hard to read, and bigger than 600 is really unnecessary). Quest cards should instead be 600px wide.

The filenames of each of these images needs to match the GUIDs of the cards in your xml file. So you’ll need to copy the GUID of each card from the xml file and re-name each image accordingly.

Quest Cards again deserve a special note. If you recall, Side A and Side B of a quest card share the same GUID since one is an ‘alternate’ of the other. So, for your two quest card images, Side A should be named the GUID, and Side B should be named GUID.B.png (or .jpg)
Example:
Side A image: 00b143f4-fbcc-4959-b03b-dd3fe7f2420f.png
Side B image: 00b143f4-fbcc-4959-b03b-dd3fe7f2420f.B.png

Once your images are properly named, you’ll just need to put them in the following folder:
MyDocuments\OCTGN\ImageDatabase\{lotr_GUID}\Sets\{your_set’s_GUID}\Cards\

You might also see a sub-folder called “Proxies”, which is where the proxy card images are generated.

Creating an Image Pack (.o8c file)
If you want to share your custom card images with others, this is the best way to go about it. Create a .zip file with the following folders/sub-folders inside:

a21af4e8-be4b-4cda-a6b6-534f9717391f\Sets\{your_set’s_GUID}\Cards\

Now copy all your card images into this folder. Now re-name the .zip into .o8c and your Image Pack is now ready to install within OCTGN.

 

Building the Scenario Deck (.08d file)

Now it’s time to finally construct the quest deck and encounter deck for your scenario. Open up the Deck Editor in OCTGN and load up your new Set. Add the Quest Cards to the Quest section of the deck, and the Encounter Cards to the Encounter section. Be sure to include the proper quantities of each card.There are two more sections that I should point out. The Special section and the Setup section.

The Special section is used for quests that implement some sort of second encounter deck. The Foundations of Stone is a perfect example of this. The encounter set from this adventure pack is put in this Special section, which exists as a secondary encounter deck within OCTGN (which starts minimized on the Global Tab). There are special right-click commands on this deck, such as moving all the cards into the normal encounter deck, or swapping this 2nd deck with the normal encounter deck.

The Setup section in the deck builder is tied in with the “Setup” field we defined on Quest Stage 1A in the xml file. If you recall from our Escape from Dol Guldur example, we made the value=”ssst” (for the 3 objective cards and the Nazgul). So, I’d add Gandalf’s Map, Dungeon Torch, Shadow Key, and Nazgul of Dol Guldur to the Setup section, and remove those cards from the Encounter section to avoid duplicates. Note that the order I put these cards in matches the order of the letters in the Setup field.

Save the file and your deck is now ready to go. To finish off, start a new game and load up your scenario deck. Right-click the table and choose Set Up Game, and the first quest card should pop out on the table, along with all the setup cards you defined going to their proper places.

Your new Set is now complete!

To share your set with others, create a .zip with the following:
– Your Set folder (with the set.xml inside)
– Your .o8d scenario deck
– Your .o8c Image Pack if you created one

7 thoughts on “Developer Guide

  1. The set_template.xml link doesn’t seem to work. Could you update it or provide a different link to download the template?

  2. I’m trying to add new set to octgn, but it still fails. I have this in OCTGN log:

    ERROR 2014-10-20 18:36:20,322 3.1.153.338 [9] Octgn.DataNew.FileDB.CollectionQuery`1 [(null)] – Error desterilizing D:\OCTGN\GameDatabase\a21af4e8-be4b-4cda-a6b6-534f9717391f\Sets\a42ab73f-36f6-4e37-ac3f-8187c53adc6b\set.xml for collection Set
    System.FormatException: Unrecognized Guid format.
    in System.Guid.GuidResult.SetFailure(ParseFailureKind failure, String failureMessageID, Object failureMessageFormatArgument, String failureArgumentName, Exception innerException)

    Could you suggest anything?

  3. my code is not working and the OCTGON Log is giving me this error:

    ERROR 2014-10-26 19:35:17,399 3.1.153.338 [12] Octgn.DataNew.FileDB.CollectionQuery`1 [(null)] – Error desterilizing C:\Users\Jonah\Documents\Octgn\GameDatabase\a21af4e8-be4b-4cda-a6b6-534f9717391f\Sets\ba06c67b-fcb2-4b5e-a458-6a706640df8c\set.xml for collection Set
    System.Xml.XmlException: Invalid character in the given encoding. Line 5, position 50.
    at System.Xml.XmlTextReaderImpl.Throw(String res, String arg)
    at System.Xml.XmlTextReaderImpl.InvalidCharRecovery(Int32& bytesCount, Int32& charsCount)
    at System.Xml.XmlTextReaderImpl.GetChars(Int32 maxCharsCount)
    at System.Xml.XmlTextReaderImpl.ReadData()
    at System.Xml.XmlTextReaderImpl.ParseAttributeValueSlow(Int32 curPos, Char quoteChar, NodeData attr)
    at System.Xml.XmlTextReaderImpl.ParseAttributes()
    at System.Xml.XmlTextReaderImpl.ParseElement()
    at System.Xml.XmlTextReaderImpl.ParseElementContent()
    at System.Xml.Linq.XContainer.ReadContentFrom(XmlReader r)
    at System.Xml.Linq.XContainer.ReadContentFrom(XmlReader r, LoadOptions o)
    at System.Xml.Linq.XDocument.Load(XmlReader reader, LoadOptions options)
    at System.Xml.Linq.XDocument.Load(Stream stream, LoadOptions options)
    at Octgn.DataNew.SetSerializer.Deserialize(String fileName) in c:\Program Files (x86)\Jenkins\workspace\OCTGN-Release\octgnFX\Octgn.DataNew\GameSerializer.cs:line 923
    at Octgn.DataNew.FileDB.CollectionQuery`1.GenerateObjects() in c:\Program Files (x86)\Jenkins\workspace\OCTGN-Release\octgnFX\Octgn.DataNew\FileDB\CollectionQuery.cs:line 148

    the 5th line is:

  4. In OCTGN, my custom encounter deck has the player deck back (the gold ring) instead of the encounter deck back (the lidless eye). How do I change it so that they have the proper back?

Leave a Reply