gameplay-bundle.txt

gameplay Bundle File Format (.gpb)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

File Description
================
A simple binary bundle file format supporting definition of primitive and built-in objects.

File Extension and Mime Type
============================
File extension is '.gpb' and the mime type is 'application/gpb'

File Structure
==============

Section      Name            Type
------------------------------------------------------------------------------------------------------
Header
             Identifier      byte[9]     = { '\xAB', 'G', 'P', 'B', '\xBB', '\r', '\n', '\x1A', '\n' } 
             Version         byte[2]     = { 1, 1 }
             References      Reference[]
Data
             Objects         Object[]

Objects
=======
Supported object types are defined in the table below. Object with unique ids are included
in the Reference table (see below).

References
==========
A Reference is an Object that has a unique id. The Reference contains the unique id of the
object, a uint for the TypeID a uint for the offset into the package for the object definition.

ID's
====
Object ID's are represented as a string which is guaranteed to be unique per file.
Any object which host an object id should be added to the header Reference table so that it can
be consumed by reference internally and externally.

Xrefs
=====
Xrefs are string with a specific format used for referencing objects internal and external to
a package. An xref with the format "#id" references an object within the current package with
the given ID. Xrefs can also have the format "file#id", where "file" is the name of package file
(relative to the location of the current package) and "id" is the unique identifier of an object
in that bundle.

Primitives
==========

Name            Description
------------------------------------------------------------------------------------------------------
string          8-bit char array prefixed by unint for length encoding.
bool            8-bit unsigned char   false=0, true=1.
byte            8-bit unsigned char
uint            32-bit unsigned int, stored as four bytes, lowest byte first.
int             32-bit signed int, stored as four bytes, lowest byte first.
float           32-bit float, stored as four bytes, with the least significant 
                    byte of the mantissa first, and the exponent byte last.
enum X          A uint which is restricted to values from the given enum name "X".

Arrays
======
Arrays of constant length are simply the array of data for the expected type. 
Arrays of dynamic size length(uint) encoded followed by expected type of data.
Notation:   byte[3]  - constant length notation = byte[3]
            int[]    - dynamic length notation = length+int[count]
            Mesh[]   - dynamic length notation = length+Mesh[count]

Enums
=====

enum VertexUsage
{
    POSITION = 1,
    NORMAL = 2,
    COLOR = 3,
    TANGENT = 4,
    BINORMAL = 5,
    BLENDWEIGHTS = 6,
    BLENDINDICES = 7,
    TEXCOORD0 = 8,
    TEXCOORD1 = 9,
    TEXCOORD2 = 10,
    TEXCOORD3 = 11,
    TEXCOORD4 = 12,
    TEXCOORD5 = 13,
    TEXCOORD6 = 14,
    TEXCOORD7 = 15
}

enum FontStyle
{
    PLAIN = 0,
    BOLD = 1,
    ITALIC = 2,
    BOLD_ITALIC = 4
}

enum FontFormat
{
    BITMAP = 0,
    DISTANCE_FIELD = 1
}

enum PrimitiveType
{
    TRIANGLES = GL_TRIANGLES (4),
    TRIANGLE_STRIP = GL_TRIANGLE_STRIP (5),
    LINES = GL_LINES (1),
    LINE_STRIP = GL_LINE_STRIP (3),
    POINTS = GL_POINTS (0)
}

enum IndexFormat
{
    INDEX8 = GL_UNSIGNED_BYTE (0x1401),
    INDEX16 = GL_UNSIGNED_SHORT (0x1403),
    INDEX32 = GL_UNSIGNED_INT (0x1405)
}

enum NodeType
{
    NODE = 1,
    JOINT = 2
}


Object Definitions
==================
TypeID->Name    Member                  Type
------------------------------------------------------------------------------------------------------
Reference
                id                      string
                type                    uint
                offset                  uint
------------------------------------------------------------------------------------------------------
1->Scene
                nodes                   Node[]
                activeCameraNode        xref:Node
                ambientColor            float[3]
------------------------------------------------------------------------------------------------------
2->Node
                type                    enum NodeType
                transform               float[16]
                parent_id               string
                children                Node[]
                camera                  Camera
                light                   Light
                model                   Model
------------------------------------------------------------------------------------------------------
3->Animations
                animations              Animation[]
------------------------------------------------------------------------------------------------------
4->Animation
                id                      string
                channels                AnimationChannel[]
-----------------------------------------------------------------------------------------------------
5->AnimationChannel
                targetId                string
                targetAttribute         uint
                keyTimes                uint[]  (milliseconds)
                values                  float[]
                tangents_in             float[]
                tangents_out            float[]
                interpolation           uint[]
------------------------------------------------------------------------------------------------------
11->Model
                mesh                    xref:Mesh
                meshSkin                MeshSkin
                materials               Material[]
------------------------------------------------------------------------------------------------------
16->Material
                parameters              MaterialParameter[] { string name, float[] value, uint type }
                effect                  xref:Effect
------------------------------------------------------------------------------------------------------
17->Effect
                vertexShader            string
                fragmentShader          string
------------------------------------------------------------------------------------------------------
32->Camera
                cameraType              byte {perspective|orthographic}
                aspectRatio             float
                nearPlane               float
                farPlane                float
                [ cameraType : perspective
                  fieldOfView           float
                ]
                [ cameraType : orthographic
                  magnification         float[2]
                ]
------------------------------------------------------------------------------------------------------
33->Light
                lightType               byte {directional|point|spot}
                color                   float[3]
                [ lightType : point
                  range                 float
                ]
                [ lightType : spot
                  range                 float 
                  innerAngle            float (in radians)
                  outerAngle            float (in radians)
                ]
------------------------------------------------------------------------------------------------------
34->Mesh
                vertexFormat            VertexElement[] { enum VertexUsage usage, unint size }
                vertices                byte[]
                boundingBox             BoundingBox { float[3] min, float[3] max }
                boundingSphere          BoundingSphere { float[3] center, float radius }
                parts                   MeshPart[]
------------------------------------------------------------------------------------------------------
35->MeshPart
                primitiveType           enum PrimitiveType
                indexFormat             enum IndexFormat
                indices                 byte[]
------------------------------------------------------------------------------------------------------
36->MeshSkin
                bindShape               float[16]
                joints                  xref:Node[]
                jointsBindPoses         float[] // 16 * joints.length
                boundingBox             BoundingBox { float[3] min, float[3] max }
                boundingSphere          BoundingSphere { float[3] center, float radius }
------------------------------------------------------------------------------------------------------
128->Font
                family                  string
                style                   enum FontStyle
                size                    uint
                charset                 string
                glyphs                  Glyph[] { uint index, uint width, float[4] uvCoords }
                texMapWidth             uint
                texMapHeight            uint
                texMap                  byte[]
                format                  enum FontFormat      @since version [1,3]