Nif Format/NifTools XML Format

From NifTools
Revision as of 22:18, 8 September 2006 by Shon (Talk | contribs)
Jump to: navigation, search

The NifTools XML format is used to describe the NIF, KF, and KFM file formats. NifSkope uses this file directly and almost any new discoveries about the format can be enabled in NifSkope by editing the nif.xml file included in its install directory. Niflib uses the XML file as well; Python scripts read the XML file and generate some of the source code used by Niflib to read and write NIF files. The XML files also contain our human-readable documentation of the format, and will eventually serve as the source for a new HTML version of the file format specification. Thus, these XML files are central to our efforts to understand the file formats and create tools that support as many games as possible.

Contents

The Basics

If you've never heard of XML before, you may want to check out a few of these informational links borrowed from Wikipedia:

If you've ever worked with HTML, XML will look very familiar to you. Basically, instead of working with tags like <B>, <IMG>, and <TABLE>, you will be working with special tags designed to describe the NIF file format such as <basic>, <compound>, and <niobject>.

Every XML file starts with a basic heading. Following is the heading for the NifTools XML format. It doesn't really do anything important other than tell you that this document is in the NifTools XML format, and it has to be there:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE niftoolsxml>
<niftoolsxml version="0.7.0.0">

   XML File contents go here

</niftoolsxml>

Also, like in HTML, plain text can appear between the start and end version of a tag. Similarly, plain text enclosed in NifTools XML tags contains the human readable documentation about what this NIF structure does. This is completely plain text... no HTML tags are allowed. Here's an example:

<add name="Name" type="string">
  Name of this object. This is also the name of the action associated with this file.
  For instance, if the original NIF file is called &quot;demon.nif&quot; and this
  animation file contains an attack sequence, then the file would be called
  &quot;demon_attack1.kf&quot; and this field would contain the string &quot;attack1&quot;.
</add>

There are also certain characters which are not allowed in XML plain text. These must be replaced with special codes. Some examples:

Character Replace with this
" &quot;
< &lt;
> &gt;
& &amp;

Organization

The NIF XML file is divided into sections based around the five main tags. These are; <version>, <basic>, <enum>, <compound>, and <niobject>. At the top of each section is an XML comment. Just like in HTML, a comment is text that is ignored by the program reading the XML file. For example:

<!--This text is for informational use and will be ignored by NifSkope-->

Tags

This section will introduce each tag and explain how to use it. Tags which appear inside other tags will be grouped under the tag which they are most likely to appear inside of

<niftoolsxml>

The <niftoolsxml> tag is the root tag, and everything else in the file goes inside it. There is exactly one of these tags in a NifTools XML document. This is similar to the way the <HTML> tag works for HTML documents.

Attributes:

Name Format Description
version #.#.#.# Used to specify the version of the NifTools XML format being used.

Tags Which can appear inside this one:

<version>, <basic>, <enum>, <compound>, and <niobject>

Example:

<niftoolsxml version="0.7.0.0"></niftoolsxml>

<version>

<basic>

The <basic> tag specifies a new simple data type, one that holds just one piece of data. For example, a number, a string, etc. The main reason to add a new basic data type would be to allow NifSkope or Niflib to treat it differently. At this point most basic data types that you need should already have been created and it's probably best to ask if it's necessary to create a new one. You should know what the basic data types are, however, because you will refer to them often in other tags.

Attributes:

Name Format Description
name text This is the name of this basic data type. It is used to refer to this type in other tags.
count integer This determines whether a basic data type can be used as a count. Only data types that store integers can be used as a count. 1 is true, 0 is false.
niflibtype text This is the name of the type in Niflib that this basic data type will be mapped to. Usually it is the same as the name. It doesn't have to exist as a basic tag.
nifskopetype text This is the name of the type in NifSkope that this basic data type will be mapped to. Usually it is the same as the name. It must be the name of an existing basic tag.

Tags Which can appear inside this one:

None.

Example:

<basic name="short" count="1" niflibtype="short" nifskopetype="short">
  A signed 16-bit integer.
</basic>

<enum>

The <enum> tag specifies a data type which consists of a list of options. Each <enum> tag will contain two or more <option> tags which specify the choices available in this collection. Each option corresponds to an integer value which is given a name and can have a description.

Attributes:

Name Format Description
name text This is the name of this enum data type. It is used to refer to this type in other tags and will be the name of the C++ enum in Niflib.
storage text This specifies the data type used to store the enum value in the NIF file. Generally, this will be uint, ushort, or byte. It must exist as the name of a <basic> tag somewhere else in the file.

Tags Which can appear inside this one:

<choice>

Example:

<enum name="ChoiceType" storage="uint">
  Specifies a type of choice.
  <option value="0" name="CHOICE_YES">An affirmative choice.</option>
  <option value="1" name="CHOICE_NO">A negative choice.</option>
  <option value="1" name="CHOICE_MAYBE">A noncommittal choice.</option>
</enum>
<choice>

The <choice> tag describes a choice that is part of an enum data type. Enums store the choice as a number, so each <choice> tag contains that number and a name so people can understand what the number means. It can also contain descriptive text explaining what the option is for. The name should be in all capital letters with spaces replaced by underscores(_) because it will be used as a constant name in Niflib.

Attributes:

Name Format Description
value integer This is the number that is stored in the NIF file when this choice is selected. There should be only one <choice> tag per number.
name text This is the short name of this choice. It should be in all capital letters with no spaces and should start with an abbreviated form of the enum name. It must be unique; no choice name can be the same as any other choice name anywhere in the XML file.

Tags Which can appear inside this one:

None.

Example:

<option value="0" name="ANIMAL_DRAGON">Indicates that this object is a dragon.</option>

<compound>

The <compound> tag defines a new data type which contains several instances of other data types. Compounds are analogous to C/C++ structs or classes in that they contain several variables in a certain order. These other data types can be specified in preceding <basic>, <enum>, or other <compound> tags. Basically, a compound data type is like a list of data that will be found in a NIF file in the order given. It is useful to create a compound when a complex part of another data type is repeated many times, such as in an array. The compound tag should contain a plain text description in addition to any <add> tags to document its purpose.

Attributes:

Name Format Description
name text This is the name of this compound data type. It is used to refer to this type in other tags and will be used for the name of the C++ struct for Niflib. The first letter of each word should be capitalized and it should contain no spaces or underscores.
niflibtype text This is optional. Some special types are implemented by hand in Niflib to give them extra features. If this is the case, the name of the C++ class or struct is specified here. Normally you can ignore this.

Tags Which can appear inside this one:

<add>

Example:

<compound name="LODRange">
  The distance range where a specific level of detail applies.
  <add name="Near Extent" type="float">Beginning of range.</add>
  <add name="Far Extent" type="float">End of Range.</add>
</compound>

<niobject>

<add>
Personal tools