=============================
Piece Model File (PMF) Format
=============================

Contents
--------
1. Introduction
2. File structure
3. Pieces
4. Animations


1. Introduction
---------------
  PMF is a simple model file format used by the Piece Model Editor originally
written for the MS-DOS game Post Apocalyptic Petra.  PMF files contain a
hierarchy of meshes and rotation-based animations, making it ideal for retro
styled 3D character models whose individual parts (head, torso, legs, arms, etc)
are made out of rigid meshes.

  One important aspect to keep in mind about PMF files is that they only
contain geometry and animations can only use rotations (with the exception of
the root node which can also be translated).  The file does not contain texture
or material information and animations do not contain translation (aside from
the root node) or scaling.

  The Piece Model Editor can be found at:

    http://runtimeterror.com/tools/piecemod/


2. File structure
-----------------
  A PMF file has the following structure:

    * 4 bytes for the four-character sequence 'PMF1'
    * Piece hierarchy
    * Animations

  All values use little-endian byte order.  Vector components for position,
translation, rotation, etc are stored in X, Y, Z order as floats.


3. Pieces
---------
  The first part of a PMF file, after the four-character sequence that
identifies the file as a Piece Model Format file, contains the piece hierarchy.
The hierarchy is made up of a single piece node - the root piece node - and
optionally its children and grandchildren (the children of a piece node
immediately follow the parent node).  The data for a piece node contain the
piece's name (up to 31 characters), its position in local space (that is,
relative to its parent piece node) and the mesh geometry for the node.

  A single piece has the following structure:

    * 32 bytes for the name.  The name is encoded as a Pascal shortstring,
      meaning that the first byte is the name's length, followed by the name's
      characters.
    * 12 bytes for the node's translation in local space as 3 32bit floats.
    * 4 bytes for a 32bit integer for the number of mesh vertices.  Note that
      this number will always be divisible by 3 as the pieces are made up of
      triangles.
    * Vertex data (see below) - the number of bytes varies.
    * 4 bytes for a 32bit integer for the number of children piece nodes.
    * Children pieces - number of bytes varies.

  A single vertex has the following structure:

    * 12 bytes for the vertex position as 3 32bit floats.
    * 12 bytes for the vertex normal as 3 32bit floats.
    * 8 bytes for the normalized texture coordinates as 2 32bit floats.


4. Animations
-------------
  Immediately after the piece hiearchy a PMF file contais the animation data
using the following structure:

    * 4 bytes for a 32bit integer for the number of animations in the file.
    * Data for each animation - number of bytes varies.

  Each animation has the following structure:

    * 32 bytes for the name.  The name is encoded as a Pascal shortstring,
      meaning that the first byte is the name's length, followed by the name's
      characters.
    * 1 byte for animation flags.  Currently only bit 0 is used and if the bit
      is set, the animation is meant to loop.
    * 1 byte for the playback speed in frames per second.
    * 2 bytes for a 16bit integer for the number of frames.
    * Data for each frame - number of bytes varies.

  Each frame has the following structure:

    * 1 byte for frame flags.  If bit 0 is set, the frame is a keyframe.  If
      bit 1 is set the frame is an event frame.  See below for an explanation.
    * 12 bytes for the root piece node position as 3 32bit floats.
    * Rotation data for each piece node stored in the same order as the piece
      nodes are stored in the pieces hiearchy previously.
      - Each rotation is stored as 12 bytes for 3 32bit floats.

  Keyframes (bit 0 is set) are used to calculate the in-between frames (bit 0 is
not set) using Catmull-Rom interpolation for the rotations and linear
interpolation for the root node position.  Note that this is used for the editor
and the frame data stored in the file contain the interpolated frames so a
game or viewer does not need to do the interpolation manually.

  Event frames (bit 1 is set) are meant to be used by the game for
animation-specific purposes (for example playing a sound, spawning some effect,
triggering some event like a hazard, etc).


Kostas "Bad Sector" Michalopoulos
badsector@runtimeterror.com