SIEGE UNIVERSITY 1 |
|||||||||||||||
Siege University II Tutorials Modding FAQ 095: Upgrading DSII 100: The Basics of Siege Editor 201: Compass Map Radar 202: Conversations 203: Journal 204: Quest Indicator Icons 205: Start Positions 206: Teleporters 207: Town Portal Restrictions 208: Weapon Effects 209: Flick 210: Tuning Grids 211: Setting Up Good Map Lighting 212: Setting Up Simple Node Fading 215: Building Data Tables Siege University I Tutorials 200: Concepts and Terminology 201: Templates 203: Triggers 204: Moods 205: Fades 206: Elevators 211: Naming Key 213: Dungeon Siege Resource System 301: Introduction to Dungeon Siege Architecture Third Party Tutorials A Simple Mod Part One - Armor Textures A Simple Mod Part Two - A New Armor Beginners Guide to Stitching Regions How to Open and Create Tanks Making Chants Work in a New Map Ornaments Understanding the NKK Useful Links Siegetheday.org Dungeon Siege Outpost Dungeon Raider Kdawg.org - List of useful Links MCarp DS Nodes Dungeon Siege 2 at Gamefront Broken World at Gamefront |
Templates
·
What
You Need For This Tutorial ·
What
This Tutorial Assumes You Have Already Learned ·
What
This Tutorial Will Teach You ·
Untank
Logic.dsres ·
Components
·
Fields
·
Values ·
Core
Templates ·
Base
Templates ·
Leaf
Templates ·
Instance
Templates ·
Overriding
a Specialized Component or Field ·
Art
Assets: Placing and Naming Appendix A: Naming Conventions
& Siege Editor: Template
Sorting ·
Category
Names ·
Doc
Names 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. 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: Start
the Siege
Editor. Select
Convert
.dsmap to Files... from the File Menu. For
the Source
File, browse to Dungeon Siege\Resources. Under
"Files of type:", switch to Dungeon Siege Resource Files
(*.dsres) Select
Logic.dsres
and click Open. For
the
Destination Folder, leave it at its default setting (My
Documents\Dungeon
Siege\Bits). Click
OK.
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. 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. [common] 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.
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. 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]
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. ·
Core
templates ·
Base
templates ·
Leaf
templates ·
Instance
templates
(or instances) Specialization
Example Given
the above, you can think of specialization as a snowball effect.
Consider the
following hypothetical example: Core
template
"core_template" defines A, B, and C in file
templates_hypothetical.gas. In
stuff.gas
(somewhere down the directory tree), base template
"base_template" specializes "core_template", and
additionally defines D and E. Two
leaf
templates "leaf_template_01" and "leaf_template_02"
specialize "base_template". leaf_template_01
defines BOB 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:
[t:template,n:sign_cav_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] 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? [t:template,n:interactive] 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.
aspect:is_selectable = true; is
exactly the same as this: [aspect] as
far as the engine is concerned. You may use either convention as the
GAS parser
reads these in similarly. 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. [t:template,n:tree_grs_apple_small] Or,
they could be simply: [t:template,n:tree_grs_apple_01] 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. [t:template,n:gpg_tree_grs_apple_01] 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). Art
Assets: Placement & 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: 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 Scope Of... 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! Appendix
A: Naming Conventions &
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. [t:template,n:tree_des_02] (taken
from
world\contentdb\templates\regular\non_interactive\natural_trees.gas)
Landscape ·
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 ·
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 ·
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 ·
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 ·
doors
(all normal doors) ·
use_toggle
(use toggle doors that require an activate to become unlocked) Actors ·
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 ·
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. devise
(and
stick to) your own template naming convention, or 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] 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. [t:template,n:tree_des_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. |