Guide: Siege University - 201: Templates

Fellow adventurers! This guide is a direct upload from the original author and is no longer supported by Microsoft or Gas Powered Games. It is also not supported by the wikia's administration or members. Any errors encountered are a result of the original publication.

Introduction

At the most basic level, a template tells the game engine how to use certain game resources - such as art, sound, and physics properties - to create (instantiate) a game object (rock, tree, sword, a Krug, etc.) in the world. A template is simply a block of text that defines the characteristics of a game object.

When modding a game, one can either modify the content already included in the game, add completely new content, and most often a combination of the two. The need to create a template arises when a mod developer wishes to add content to the game or use the existing content in new ways, without losing any functionality of the existing content. For instance, if you would like to create a new sword with completely new art, you should create a new template for it. In the same vein, if you wish to create a new sword just with new stats, you should create a new template so as to preserve all of the already defined swords in the game. These are not laws, of course, but rather guidelines as to the purpose of creating your own templates.

What You Need For This Tutorial

• Dungeon Siege, updated to version 1.09B or later
• A text editor. Notepad will work fine; UltraEdit-32 offers advanced functionality.
• Untanked resource files.

What This Tutorial Assumes You Have Already Learned

• Siege U: 100 - The Basics of the Siege Editor, specifically sections regarding tanking/untanking maps.
• Siege U: 200 - Dungeon Siege Concepts and Terminology

What This Tutorial Will Teach You

• Definition of a template
• Why templates are used
• Template structure
• Template specializations
• Naming conventions
• Sorting templates within Siege Editor

Untank Logic.dsres

To untank the Logic.dsres into its editable components, follow these steps:

1. Start the Siege Editor.
2. Select Convert .dsmap to Files... from the File Menu.
3. For the Source File, browse to Dungeon Siege\Resources.
4. Under "Files of type:", switch to Dungeon Siege Resource Files (*.dsres)
5. Select Logic.dsres and click Open.
6. For the Destination Folder, leave it at its default setting (My Documents\Dungeon Siege\Bits).
7. Click OK.
8. Once the untanking is completed, exit the Siege Editor.

You have now untanked the Logic.dsres file into My Documents\Dungeon Siege\Bits. File paths listed in this tutorial can be found in this directory. If you untanked to a non-default directory, you will have to look there to find the files referenced below.

Show me a Template!

Templates reside in GAS files and can range from as few as four lines of text to as many as a hundred or more. A GAS file can contain one or one thousand templates - the game engine does not care (for your own sanity, however, a good guideline is under 100 templates per file). The following code shows an example of a template that actually resides in a file in the Logic.dsres tank located in the \Resources directory of your installation of Dungeon Siege.

[t:template,n:blacksmith_hammer]
{
    specializes = base_misc_fs1;
    category_name = "other";
    doc = "blacksmith hammer";
    [aspect] { model=m_w_hmr_004; }
    [attack]
    {
        damage_max = 2;
        damage_min = 1;
    }
    [common]
    {
        screen_name = "Blacksmith Hammer";
    }
    [gui]
    {
        active_icon = b_gui_ig_i_ic_hmr_001;
        inventory_height = 2;
        inventory_icon = b_gui_ig_i_w_hmr_004;
        inventory_width = 1;
    }
} 

(taken from world\contentdb\templates\regular\interactive\wpn_misc.gas)

One of the great things about Dungeon Siege is the large amount of documentation included in the game files themselves. Much of the following can also be found in - and is, in fact, taken from - the various files touched upon below. This documentation may appear in the form of comments at the beginning of the file or in-line with the data. See templates.gas and components.gas (discussed below) for some good examples of this.

One thing to keep in mind, however, is that some of the commented documentation in these files may be out of date as they were written during the initial implementation of a feature or system. It's possible (and often likely) that the operation of the feature or system documented has since mutated between the initial implementation and the final release version of Dungeon Siege. The information within this document should therefore be used in conjunction with the information in these files, with the data here taking precedence over file documentation.

Template Structure

Templates are made up of 3 types of data:

• Components
• Fields
• Values
• "Blocks"

OK, that's four, but a block is really just the collection of the first three.

A template is made up of blocks which contain a component, one or more of the component's fields, and those fields' values. Let's look at the [common] block in the above template:

[common]
{
    screen_name = "Blacksmith Hammer";
}

We can see that this block contains a single field - screen_name, and that field's value - "Blacksmith Hammer". A block is considered to include the declaration of the component (in this case [common]) and everything between the open and close braces. The field lines contained in a block are terminated by semicolons. Anyone familiar with C, C++, Java or similar languages will recognize these syntax conventions, which, incidentally, must be followed exactly or your object will fail to load into the game engine.

All of the templates in the game can be found in the GAS files in Logic.DSRES, under world\contentdb\templates.

All of the base templates including the core templates in templates.gas (discussed later) can be found in the \regular subdirectory. The \veteran and \elite directories contain the templates that have been tuned for the other two difficulty levels. It's recommended that after you've read this document and become familiar with templates and the template structure, you look through the veteran and elite files and templates to gain an understanding of how these are used by the engine to create alternate difficulty levels. Basically, the templates within \veteran and \elite are mirrors of their \regular counterparts, with increased stats and pcontent ("parameterized content") ranges. Parameterized content is the system by which the engine creates dynamic content based on ranges of values. While pcontent is outside the scope of this document, more information can be found in components.gas (see below).

Components

A component is a basic building block of a game object. Various components are defined that implement certain tasks in the game engine. Within templates, components appear inside square brackets ([]). For example, the [common] component in the above template contains one field (the 'screen_name' field) that tells the engine what to display on screen when the item is picked up or moused-over.

One of the most valuable files with regards to learning about templates is components.gas, located in world\contentdb\components\.

This is your Secret Decoder Sheet for deciphering all of the components and their fields in the game. I would recommend having this file open while you look through some of the templates to familiarize yourself with the various components and their myriad fields. As you discover a new component in a template, you can refer back to components.gas to find out just what it does.

Fields

For example, if you were unsure as to the purpose of the "screen_name" field in the above template's [common] component, just crack open components.gas and do a search on 'screen_name'. This should yield a hit on the following line, just under the [t:component,n:common] heading:

[screen_name] 
{  
    type = string; 
    flags = LOCALIZE; 
    doc = "Text seen in-game upon mouse over";  
}

The two most important parts of any field's line in components.gas is the default= and the doc=. Just about every field will have a default (there are exceptions, as in this case), and the doc will (usually) tell you exactly what that field's purpose is. Although this field of the common component doesn't have a default, we'll talk more about defaults later when we get into specialization.

Values

The values are pretty self-explanatory. Each field specified in a component block of a template must have a value. In the above example template, the value of the screen_name field is "Blacksmith Hammer"...

Specialization

Specialization is one of the most important aspects of the template system. It is the process by which templates inherit properties (components, fields, and values) from other templates. In the simplest terms, templates lower in the tree that specialize templates higher in the tree inherit all of components and fields that appear in that specialized template.

All of the templates in the game (over 7,300) are arranged in a logical tree, with the core templates (see templates.gas) making up the trunk of the tree, base templates as the branches of the tree, and the leaf templates as the final extension of the tree's branches. The fourth type of template, the instance, is not often (if ever) edited by hand and is created by the Siege Editor when saving out a region of a map in which you've placed content. The four types of templates are discussed briefly below.

• Core templates Core templates, also called root templates, are the foundation templates that the rest of the templates in the game are built from. Every other template in the game eventually inherits information from one of the core templates (if not overridden…more on that later). All of the core templates can be found in templates.gas, located here: world\contentdb\templates\regular\_core\templates.gas Many of the base templates in the game specialize a core template in templates.gas. This is not a global rule, however, as there are also many base templates that specialize other base templates.

• Base templates The base templates reside in the various GAS files under the world\contentdb\templates\ directory structure, often as the first template listed in a particular GAS file. These templates are often named in the format of "base_templatetype", e.g. [t:template,n:base_container_barrel] in ctn_container.gas. All of the leaf templates in the game specialize a base template.
• Leaf templates Leaf templates are at the end of the specialization chain, and actually define the only objects that may be added via Siege Editor or instantiated by the game engine. In other words, as soon as any template B specializes template A, template A can no longer be added to a region with SE or at the console. Instance templates specialize leaf templates, although instances do not have a "specialize" field - it's an implicit specialization.

• Instance templates (or instances) The fourth type of template, called an instance, is created only while using the Siege Editor to place content. These instances appear in the various GAS files in a map's region after placing objects or actors and saving out that region. These instances possess the properties of their leaf templates - the engine treats this specialization in exactly the same way the leaf and higher templates are specialized even though there is no specializes= field. In addition, you will almost never manipulate these instance templates by hand, and the practice is in fact discouraged.

Specialization Example

Given the above, you can think of specialization as a snowball effect. Consider the following hypothetical example:

1. Core template "core_template" defines A, B, and C in file templates_hypothetical.gas.
2. In stuff.gas (somewhere down the directory tree), base template "base_template" specializes "core_template", and additionally defines D and E.
3. Two leaf templates "leaf_template_01" and "leaf_template_02" specialize "base_template".
4. leaf_template_01 defines BOB
5. leaf_template_02 defines SALLY

Now, through specialization, the leaf templates actually possess much more than just BOB and SALLY even though this is the only component that appears in their templates:

leaf_template_01	leaf_template_02
A	A
B	B
C	C
D	D
E	E
BOB	SALLY

This is why leaf templates often appear so small, when in fact they may have inherited a whole slew of components, fields, and values from multiple levels of specialization.

For an actual example, let's look at a very small leaf template and trace its specialization trail back to one of the core templates. The following leaf template can be found in world\contentdb\templates\regular\non_interactive\signs_directional.gas:

[t:template,n:sign_cav_glitterdelve]
{
    doc = "directional_glitterdelve";
    specializes = base_sign_directional;
    [aspect]
    {
        model = m_i_cav_sign-glitterdelve;
    }
    [common]
    {
        screen_name = "Glitterdelve";
    }
}

This template, sign_cav_glitterdelve, specializes base_sign_directional. If we look at the top of the base_sign_directional.gas file we see the base template base_sign_directional that this template specializes. We can also see the two components and their fields that all other signs in this file that specialize base_sign_directional inherit:

[t:template,n:base_sign_directional]
{
    category_name = "sign";
    doc = "base template for directional signs";
    specializes = interactive;
    [aspect]
    {
        draw_selection_indicator = false;
        is_selectable = true;
        lodfi_lower = 0;
        lodfi_upper = 0;
        megamap_icon = b_gui_ig_mnu_arrow;
        megamap_orient = true;
        megamap_override = true;
    }
    [common]
    {
        auto_expiration_class = immediate;
        forced_expiration_class = immediate;
        rollover_display = true;
    }
}

As you can see, this base template specifies much more than the leaf templates that specialize it. This is an excellent example of the power of specialization - instead of having the large amount of identical data in each and every leaf template, all of the common component field values have been put in the base template. All of the other signs in this file then inherit these values. Not only does this speed up the GAS parser on game load, it's also easier on the eyes when working with the templates in this file. This is GOOD PRACTICE™ - try to have as much as possible in your base templates, and make your common leaf templates as small as possible. Alright, on with the specialization trail…

This base template - base_sign_directional - in turn specializes the interactive core template. This template resides in templates.gas:

[t:template,n:interactive]
{
    doc = "An interactive item or object";
    
    aspect:is_selectable = true;
    aspect:megamap_icon	= b_gui_ig_mnu_dropped_item;
    aspect:use_range = 2;
    
    [common]
    {
        forced_expiration_class = normal;
        auto_expiration_class = normal;
    }
    
    [placement]	{  }
}

All of the components here in the interactive template eventually get inherited by the sign leaf templates in world\contentdb\templates\regular\non_interactive\signs_directional.gas.

Two things appear in this template, however, that are a bit different from the aforementioned conventions. The first is the colons appearing between multiple lines of the aspect component and its fields, as well as an empty [placement] block.

The first we call the "shorthand" form of a component block, and it's usually used when there are only 1 or 2 fields to appear in a component block. This:

    aspect:is_selectable = true;
    aspect:megamap_icon	= b_gui_ig_mnu_dropped_item;
    aspect:use_range = 2;

is exactly the same as this:

[aspect]
{
    is_selectable = true;
    megamap_icon = b_gui_ig_mnu_dropped_item;
    use_range = 2;
}

as far as the engine is concerned. You may use either convention as the GAS parser reads these in similarly.

The empty component (in this case the [placement] block) often appears in core templates, and simply states that this component must appear somewhere in a template before it can be instantiated by the engine to appear in the world. The [placement] component really doesn't appear in any templates further down in the chain, but is added to the instance of a template when that object is placed via the Siege Editor; SE automatically adds the placement component and its relevant fields. Although this component in this template appears empty, it does in fact have some default values as defined in components.gas (see [t:component,n:placement] in components.gas).

Overriding A Specialized Component Or Field

Overriding occurs when a template lower down in the tree explicitly overrides a component field value that was specified in the specialized template higher in the tree. For example, if a base template for trees (say, "base_tree") specifies a screen_name of "Tree" and a tree leaf template (say "tree_oak_01") specifies a screen_name of "Oak Tree", that leaf template's screen_name is said to override the base template's screen_name field.

Naming Conventions

Naming conventions are particularly important when dealing with templates. Two rules must be followed at all times - no two templates must have the same name, and template names must not contain spaces. As far as the naming itself goes, in general names of templates should be least specific to most specific from left to right. Consider the following tree leaf template:

[t:template,n:tree_grs_apple_01]

This line tells the engine of the data type (template), and then specifies the template's name, "tree_grs_apple_01". Again, all templates must have a unique name, system-wide. No two templates may share the same name in any of the GAS files residing in any TANKs, otherwise you will receive duplicate template errors upon loading up the Siege Editor. The engine will read in the first template it finds while parsing the GAS files and simply ignore the next template it finds that shares the same name.

Back to the name of this template… First, its "tree" designation appears, then "grs" (which stands for "grass" - a world area type), then the exact type of tree - "apple" - and then the 'version' of that apple tree. If you had three different apple trees that only differ in size, you might name them thusly:

[t:template,n:tree_grs_apple_small]
[t:template,n:tree_grs_apple_medium]
[t:template,n:tree_grs_apple_large]

Or, they could be simply:

[t:template,n:tree_grs_apple_01]
[t:template,n:tree_grs_apple_02]
[t:template,n:tree_grs_apple_03]

It is up to you how you'd like to name your templates, but following a convention such as this is highly recommended, especially if you will be creating a large amount of templates. And remember, no two templates system-wide may share the same name. This includes templates between your mod and the retail version of the game, as well as other mod groups' templates.

One of the other things that we are highly recommending to modders is, when you create new templates, preface the template name with your (or your group's) initials. For example, if we here at GPG were to create our own "mod" and were adding three totally new apple trees, we would name our three templates in the following fashion:

[t:template,n:gpg_tree_grs_apple_01]
[t:template,n:gpg_tree_grs_apple_02]
[t:template,n:gpg_tree_grs_apple_03]

Again, this is not a requirement per-se, but is strongly, highly, hugely recommended to avoid conflicting data between mods created by other members of the community. Another point to note is that the engine does not care about the naming of the GAS files that reside under the world\contentdb\templates directory. You may create as many new files named however you wish, and of course a good practice would be to preface your filenames with your initials (e.g. gpg_wpn_sword.GAS).

For more information on naming conventions and the Siege Editor, including ensuring your new templates (or rather, the game objects they define) are available for placement, please see "Appendix A: Naming Conventions & Siege Editor: Template Sorting" below.

Art Assets: Placement and Naming

In contrast to the lack of template and template file naming restrictions (besides duplicates and spaces), art resources referenced by your templates MUST follow the established conventions. The engine utilizes the art resources based on location within the art directory structure and the filenames themselves. The art files residing in the following directories:

\art\Animations
\art\Bitmaps
\art\Meshes
\art\Terrain

are named as they are for two reasons - asset management (there's a ton of 'em) and engine use. The engine uses a "Naming Key" in order to know how to parse and use the art files. Please take a moment to look at the NamingKey.NNK file located here:

\art\NamingKey.NNK

The naming key is the engine's Secret Decoder File to know where and how to reference all of the art files in the game, based on the name of the files. Each file type has a prefix that must be defined in the naming key for the engine to know where to find it. Explaining each type of art file and the various sections within the naming key is beyond the scope of this document; however, it's fairly easy to decipher using the NNK and perusing the art files. Although at first glance the naming key and it's naming conventions may appear to be nonsensical, a naming system had to be developed in order to keep track of the many thousands of art files in Dungeon Siege.

Conclusion

A template defines an object that may be placed using the Siege Editor, or instantiated by the game engine at run-time. Templates reside in a tree hierarchy, with templates lower in the tree specializing - and therefore inheriting the properties of - templates higher in the tree. Templates contain component blocks made up of fields and values. These values can be overridden by templates lower in the tree. Templates can be named in any way you like, as long as there are no spaces and no two templates are named the same. It's recommended also that template names are prefaced with a modder's or group's initials (e.g. gpg_tree_grs_apple_03).

Beyond The ScopeOf...

In writing this, it became apparent that there was far more information and intricacies within the topic of templates that would fit within a single 200-level document. As you've read, the "beyond the scope of" phrase was used a couple of times - I hate that too. If enough demand (and time) is there, a 300-level document may be called for and created. Some of the topics that may be covered in such a document:

• pcontent
• Veteran & Elite templates - Difficulty Levels
• Armor - how it works
• Performance optimization
• Game Console Command Reference

Although these things are in fact beyond the scope of this first course and are not discussed here, much of the information can be gleaned from the game files themselves. With the base of knowledge learned here, a modder should be able to piece together much of what was not discussed. The modding of games with no documentation whatsoever is testament to the abilities of the mod community!

Have fun, and happy templating!
The Gas Powered Team

Appendix A: Naming Conventions and Siege Editor: Template Sorting

In addition to the naming of the actual templates being important to avoid conflicts with other modders' templates, some naming conventions are important within the templates themselves, within certain fields. The Siege Editor is what we're concerned with here, and these fields will be discussed below.

Category Names

Game Object content (rocks, bushes, trees, a Krug, a bed, etc.) is viewed within the Siege Editor via the Category Name structure. Category names determine the location of objects within the file tree. For example, if you wished to place a bed object in a region, you'd look under Game Objects/furnishings/indoor/, as beds have a category name of "indoor." When creating new object templates, it's highly recommended that you add your object to an existing category. You do this by editing the category_name field within your template.

For example, let's look at the following tree template:

[t:template,n:tree_des_02]
{
   category_name = "trees";
   doc = "des_bamboo_tan";
   specializes = base_tree;
   [aspect]
   {
      lodfi_lower = 0.15;
      lodfi_upper = 0.3;
      model = m_i_des_tree-02;
   }
}

(taken from world\contentdb\templates\regular\non_interactive\natural_trees.gas)

As you can see, this template has a category_name of "trees". This makes it available for placement in the Siege Editor by browsing the tree and opening the Game Objects/landscape/trees/ directory.

NOTE: The category_name field is very important - if an object does not have a category name, it will not be available for placement in the Siege Editor except by doing a content search.

Available Category Names
Generally, when looking at the object tree within the Siege Editor (SE), the subfolder names are the same as the category names for those directories. The various subfolders and their categorized objects are listed below as reference:

Landscape
The following categories sort objects within the Landscape subfolders:

• dead (all bones, bodies, carcasses)
• foliage (shrubs, flowers, grass, misc plants)
• trees (all trees)
• rocks (all rocks, crystals, ore, gems)
• misc (all miscellaneous natural items like brush, dirt, logs, branches, etc)

Furnishings
The following categories sort objects within the Furnishings subfolders:

• indoor (all indoor furnishings like tables, paintings, beds, etc)
• statue (all statues)
• outdoor (all outdoor furnishings like carts, tents, tombstones)
• sign (all signs)
• container (all nonregion-specific containers like base barrels, crates, jugs, sarcophagi, etc)
• lighting (all light fixtures like lamps, torches, candles, etc)

Treasure
The following categories sort objects within the Treasure subfolders:

• treasure (all inventory treasure like gold, gems, jewelry)
• magic (all magic spells)
• mbook (all magic books)
• potions (all potions)
• quest (all quest related objects)
• lorebook (all lore books)

Gizmos
The following categories sort objects within the Gizmos subfolders:

• levers (all levers, buttons, etc)
• interactive (all interactive objects like health fountains)
• trigger (all triggers)
• catalyst (all catalyst type AI commands)
• target (all target type AI commands)
• zurb (specialized commands that don't use normal jat/next scid
• skrev (skrit event specialized commands)
• effect (all effect commands like camera shakes)
• nis (all NIS commands)
• emitter (sound and SFX emitters like fire and smoke)
• special (misc special features like shrine effects, use points, etc)
• traps (SFX traps like fireballs)
• elevator (all elevator gizmos)
• 1w_generator (all regular world base generators and spawners)
• 1w_automated (all regular world automated generators and spawners)

Doors
The following categories sort objects within the Doors subfolders:

• doors (all normal doors)
• use_toggle (use toggle doors that require an activate to become unlocked)

Actors
The following categories sort objects within the Actors subfolders:

• 1w_ambients (neutrally aligned creatures like deer, cows, gremals)
• 1w_evil_a (Primary evil races of Krug, Seck, Droog, and Goblins
• 1w_evil_b (evil boss monsters like the dragon, fury, giant spider, etc)
• 1w_evil_c (lesser evil races like skeltons, trog, braak, etc)
• 1w_evil_d (individual evil monsters like golems, spiders, googore, etc)
• 1w_character (good NPC's like guards and possible party members)
• 1w_townsperson (good NPC townspeople)
• 1w_shopkeep (good NPC shopkeeps)

Nodes
The following categories sort objects within the Node folder:

• node (all node specific objects like windows, waterwheels, mill vanes, etc)

All category names that begin with "1w" also have "2w" and "3w" versions for the Veteran and Elite types of the same objects.

You might notice that weapons and armor do not have category names at all, and are missing from the above lists. The display of those objects is based solely on their template names, so when creating new templates for these types of objects it's highly recommended you either:

1. devise (and stick to) your own template naming convention, or
2. stay within the current naming scheme and use a naming convention similar the existing type of content.

Method 2, staying within current naming scheme, is the recommended route here. Staying within the current naming scheme confines will aid greatly in the ease with which your new objects will show up in SE's template view. When in doubt, you may use the category name of "pending" which sorts objects into the "unsorted" folder. (there is a way to add your own categories by editing se_view_db.gas, but this is beyond the scope of this document)

Doc Names

The doc value (a.k.a. "doc name" or "Development name"), is another very important template field. The value that's entered here is what is seen as the name of the object when in the Development name content display in the Siege Editor. The aim when creating a doc name is to make it as descriptive and as user-friendly as possible. Let's go back to our tree template from above:

[t:template,n:tree_des_02]
{
   category_name = "trees";
   doc = "des_bamboo_tan";
   specializes = base_tree;
   [aspect]
   {
      lodfi_lower = 0.15;
      lodfi_upper = 0.3;
      model = m_i_des_tree-02;
   }
}

As you can see, the doc field value (or "doc name", as it's commonly referred to around here) "des_bamboo_tan" is more descriptive than the template name, "tree_des_02". The doc field must always be present in your templates. If a template is missing the doc field and its value, the object will simply not have a name when you look for it within SE while in Development names content display. With some interactive objects or actors, it is preferable to use the Screen Name (field screen_name) as the Doc Name (field doc), which is generally fine. Your doc names do not have to be named uniquely, but it is generally a good idea to do so.

At times, you may create a template for an object that is intended for use in very specific situations. In this case, it's possible the object requires more information (or even instructions) on how it should be used or where it should be placed. In this case, there is an additional informational field you can use called extra_doc. If we add this field to the tree_des_02 template, it would appear as such:

[t:template,n:tree_des_02]
{
   category_name = "trees";
   doc = "des_bamboo_tan";
   extra_doc = "Only place me in dry, deserty areas";
   specializes = base_tree;
   [aspect]
   {
      lodfi_lower = 0.15;
      lodfi_upper = 0.3;
      model = m_i_des_tree-02;
   }
}

If you open the template properties of tree_des_02 within SE, you will find the extra_doc string displayed in the Documentation field, directly below the Template name. In this way you are providing more information for others who may be placing your content - either on your team, or even other modders.