Nif Format/NifTools XML Format

From NifTools
Revision as of 21:59, 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.


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="">

   XML File contents go here


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;.

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;


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-->


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


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.


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>


<niftoolsxml version=""></niftoolsxml>



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.


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:



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


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.


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:



<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>



Personal tools