.gls file format specs

Rev.: 1.01
Written by: Mikkel Fredborg
For more information visit: www.frecle.net/giles
For technical assistance contact: giles@frecle.net

Introduction

The .gls file format is gile[s] custom file format. It contains model, material, texture and lighting data. The reason gile[s] has it's own file format, is that it needs information not stored in any other file format.

Chunk Layout

A .gls file contains chunks with relevant information about the different properties of the scene. Chunks are hierarchical or nested, with a parent chunk containing all child chunks relating to the parent.

All chunks follow this layout: 

Chunk ID

Integer

A unique ID that indicates the data stored in the chunk

Size

Integer

The size (excluding the chunk header) of the chunk

Data

Mixed

The actual data

Materials, lightmaps and textures are referenced by index. Index numbers start from 0 and go to the amount present in the file. Materials, lightmaps and textures have different indexes, so that the first lightmap in the file has index 0, and the first material in the file has index 0 as well.

Chunks referenced by index must come before the first time they are referenced.

Generally chunks are optional. If a chunk is not present, default values are used. A few chunks must be present, but unless otherwise indicated a chunk is optional.

Data Types

The following data types are used in the gls file format:

Byte

1 byte

When used as a flag, a byte should be 0 for off and 1 for on.

Short

2 bytes

-

Integer

4 bytes

-

Float

4 bytes

-

String

X bytes

Strings in the gls file format are zero terminated.

Chunk Descriptions

The following chunks are reserved in the gls file format:

Chunk Name

Chunk ID

Data Type

Parent Chunk

GLS_HEADER

$FFFF

String + Float + Sub Chunks

-

The gls file header, contains all chunks in the file.

This must be the first chunk in the file, it contains the string: "gile[s]" and the file version number as a float. After this, the remaining data in the file is stored as sub chunks.

The current file version is 1.01

 

Chunk Name

Chunk ID

Data Type

Parent Chunk

GLS_AUTHOR

$F000

String

GLS_HEADER

Information about who saved the file, using which version of gile[s], and when.

 

Chunk Name

Chunk ID

Data Type

Parent Chunk

GLS_MODELS

$1000

Sub Chunks

GLS_HEADER

Contains all models in the file.

GLS_MODEL

$1001

Sub Chunks

GLS_MODELS /
GLS_MODEL

Contains a single model. Please note that a model chunk must contain either a GLS_MESH, GLS_PIVOT, or GLS_LIGHT chunk!

Models may be linked by placing a GLS_MODEL within another GLS_MODEL chunk.

GLS_MODEL_NAME

$1002

String

GLS_MODEL

Model Name.

GLS_MODEL_POSITION

$1003

3 Floats

GLS_MODEL

The position of the model, in local coordinate space. (X, Y, Z)

GLS_MODEL_ROTATION

$1004

3 Floats

GLS_MODEL

The rotation of the model, in local coordinate space. Stored as Euler angles. (Pitch, Yaw, Roll)

GLS_MODEL_SCALE

$1005

3 Floats

GLS_MODEL

The scale of the model, in local coordinate space. (X, Y, Z)

GLS_MODEL_CUSTOMPROPS

$1006

String

GLS_MODEL

The custom properties of the model.

GLS_MODEL_FILE

$1007

String

GLS_MODEL

The name of the file this model originates from.

GLS_MODEL_HIDDEN

$1008

Byte

GLS_MODEL

Flag indicating whether the model is hidden.

 

Chunk Name

Chunk ID

Data Type

Parent Chunk

GLS_MESH

$2000

Sub Chunks

GLS_MODEL

Indicates that this model is a mesh, and contains all data specific to a mesh.

GLS_MESH_OVERRIDE

$2001

Byte

GLS_MESH

Flag indicating whether the mesh's lighting properties should override, the materials assigned to the mesh.

GLS_MESH_BACKLIGHT

$2002

Byte

GLS_MESH

Receive Back Light Flag.

GLS_MESH_RECEIVESHADOW

$2003

Byte

GLS_MESH

Receive Shadows Flag.

GLS_MESH_CASTSHADOW

$2004

Byte

GLS_MESH

Cast Shadows Flag.

GLS_MESH_RECEIVEGI

$2005

Byte

GLS_MESH

Receive Global Illumination Flag.

GLS_MESH_AFFECTGI

$2006

Byte

GLS_MESH

Affect Global Illumination Flag.

 

Chunk Name

Chunk ID

Data Type

Parent Chunk

GLS_MESH_SURFACES

$2100

Sub Chunks

GLS_MESH

Contains all surfaces of the mesh.

GLS_MESH_SURF

$2101

Sub Chunks

GLS_MESH_SURFACES

Contains a single surface of the mesh.

GLS_MESH_SURFVERTS

$2102

Short

GLS_MESH_SURF

The number of vertices in this surface.

GLS_MESH_SURFPOLYS

$2103

Short

GLS_MESH_SURF

The number of polygons in this surface.

GLS_MESH_SURFMATERIAL

$2104

Integer

GLS_MESH_SURF

The index of the material assigned to this surface.

GLS_MESH_SURFVERTFORMAT

$2105

Integer

GLS_MESH_SURF

Indicates what types of vertex data are present for this surface.

Any combination of the following is allowed:

0 - Position
1 - Vertex Normals
2 - Base Vertex Color + Alpha
4 - Vertex Light
8 - Lightmap Coordinates
16 - Texture Coordinates 0

A surface that has a lightmap, texture and vertex colors assigned, would have this vertex format:

0 + 2 + 8 + 16 = 26

It is advised that vertex normals are present, but it's not needed.

GLS_MESH_SURFVERTDATA

$2106

Vertex Data

GLS_MESH_SURF

Vertices are stored in sequence. Vertex data is stored in the following order:

Position - 3 Floats (X, Y, Z)
Normals - 3 Floats (NX, NY, NZ)
Base Vertex Color+Alpha - 4 Bytes (R,G,B,A)
Vertex Light - 3 Bytes (R, G, B)
Lightmap Coords - 2 Floats (U, V)
Tex Coords 0 - 2 Floats (U, V)

Depending on the Vertex Fomat, the size of each vertex will vary.

GLS_MESH_SURFPOLYDATA

$2107

Polygon Data

GLS_MESH_SURF

The vertex connection data for each polygon in the surface. Each polygon contains:

V index 0, V index 1, V index 2

Each V index is a short.

 

Chunk Name

Chunk ID

Data Type

Parent Chunk

GLS_PIVOT

$3000

Sub Chunks

GLS_MODEL

Indicates that the model is a pivot. Currently pivots do not contain specific data.

 

Chunk Name

Chunk ID

Data Type

Parent Chunk

GLS_LIGHT

$4000

Sub Chunks

GLS_MODEL

Indicates that the model is a light. All light properties are stored within this chunk.

GLS_LIGHT_TYPE

$4001

Byte

GLS_LIGHT

The Light type. Possible values are:

1 - Directional
2 - Omni
3 - Spot
4 - Ambient

GLS_LIGHT_ACTIVE

$4002

Byte

GLS_LIGHT

Light Active Flag

GLS_LIGHT_CASTSHADOWS

$4003

Byte

GLS_LIGHT

Light Cast Shadows Flag

GLS_LIGHT_INFINITE

$4004

Byte

GLS_LIGHT

Light Infinite Flag

GLS_LIGHT_OVERSHOOT

$4005

Byte

GLS_LIGHT

Light Overshoot Flag

GLS_LIGHT_RADIUS

$4006

Float

GLS_LIGHT

Light Radius

GLS_LIGHT_RED

$4007

Float

GLS_LIGHT

Light Color Red. Range 0.0-1.0

GLS_LIGHT_GREEN

$4008

Float

GLS_LIGHT

Light Color Green. Range 0.0-1.0

GLS_LIGHT_BLUE

$4009

Float

GLS_LIGHT

Light Color Blue. Range 0.0-1.0

GLS_LIGHT_INTENSITY

$400A

Float

GLS_LIGHT

Light Intensity

GLS_LIGHT_NEAR

$400B

Float

GLS_LIGHT

Light Near Range

GLS_LIGHT_FAR

$400C

Float

GLS_LIGHT

Light Far Range

GLS_LIGHT_INNER

$400D

Float

GLS_LIGHT

Light Inner Cone

GLS_LIGHT_OUTER

$400E

Float

GLS_LIGHT

Light Outer Cone

GLS_LIGHT_TOON $400F Byte GLS_LIGHT
Light Toon Shading Flag
GLS_LIGHT_TOONLEVELS $4010 Byte GLS_LIGHT
Light Toon Shading Levels

 

Chunk Name

Chunk ID

Data Type

Parent Chunk

GLS_MATERIALS

$5000

Sub Chunks

GLS_HEADER

Contains all materials in the file

GLS_MAT

$5001

Sub Chunks

GLS_MATERIALS

Contains data for a single material

GLS_MAT_NAME

$5002

String

GLS_MAT

The name of the material

GLS_MAT_RED

$5003

Float

GLS_MAT

Material Red Color. Range 0.0-1.0

GLS_MAT_GREEN

$5004

Float

GLS_MAT

Material Green Color. Range 0.0-1.0

GLS_MAT_BLUE

$5005

Float

GLS_MAT

Material Blue Color. Range 0.0-1.0

GLS_MAT_ALPHA

$5006

Float

GLS_MAT

Material Alpha. Range 0.0-1.0

GLS_MAT_SELFILLUMINATION

$5007

Float

GLS_MAT

Material Self-Illumination. Range 0.0-1.0

GLS_MAT_SHININESS

$5008

Float

GLS_MAT

Material Shininess. Range 0.0-1.0

GLS_MAT_FX

$5009

Integer

GLS_MAT

Material Effects, contains a combination of the following flags:

1 - Full Bright
2 - Vertex Color
4 - Flat Shade
8 - No Fog
16 - Two Sided
32 - Vertex Alpha

GLS_MAT_BLEND

$500A

Integer

GLS_MAT

Material Blend Mode. Possible Values:

1 - Alpha
2 - Multiply
3 - Additive

GLS_MAT_LIGHTMETHOD

$500B

Byte

GLS_MAT

Material Lighting Method. Possible Values:

0 - No Lighting
1 - Vertex Lighting
2 - Lightmap

GLS_MAT_LIGHTMAP

$500C

Short

GLS_MAT

Material Lightmap Index.

GLS_MAT_RECEIVEBACK

$500D

Byte

GLS_MAT

Material Receive Back Light Flag.

GLS_MAT_RECEIVESHADOW

$500E

Byte

GLS_MAT

Material Receive Shadows Flag.

GLS_MAT_CASTSHADOW

$500F

Byte

GLS_MAT

Material Cast Shadow Flag.

GLS_MAT_RECEIVEGI

$5010

Byte

GLS_MAT

Material Receive Global Illumination Flag.

GLS_MAT_AFFECTGI

$5011

Byte

GLS_MAT

Material Affect Global Illumination Flag.

GLS_MAT_TEXLAYER

$5012

Byte+Short

GLS_MAT

Material Texture Layer. Stored as a byte indicating the texture layer, and then a short that indicates the texture index.

 

Chunk Name

Chunk ID

Data Type

Parent Chunk

GLS_TEXTURES

$6000

Sub Chunks

GLS_HEADER

Contains all textures in the file.

GLS_TEX

$6001

Sub Chunks

GLS_TEXTURES

Contains data for a single texture.

GLS_TEX_FILE

$6002

String

GLS_TEX

The filename, with or without path, of the texture.

GLS_TEX_SCALEU

$6003

Float

GLS_TEX

The texture scale u.

GLS_TEX_SCALEV

$6004

Float

GLS_TEX

The texture scale v.

GLS_TEX_OFFSETU

$6005

Float

GLS_TEX

The texture offset u.

GLS_TEX_OFFSETV

$6006

Float

GLS_TEX

The texture offset v.

GLS_TEX_ANGLE

$6007

Float

GLS_TEX

The texture angle in degrees.

GLS_TEX_FLAGS

$6008

Integer

GLS_TEX

The texture flags. Can contain a combination of any of the following values:

1 - Color
2 - Alpha
4 - Masked
8 - Mip Map
16 - Clamp U
32 - Clamp V
64 - Spherical Reflection
128 - Cube Map
256 - V Ram
512 - Hi Color

GLS_TEX_BLEND

$6009

Integer

GLS_TEX

The texture blend. Possible values are:

1 - Alpha
2 - Multiply
3 - Additive
4 - Dot3

GLS_TEX_COORDSET

$600A

Byte

GLS_TEX

The textures coordinate set. Currently only coordinate set 0 is supported.

 

Chunk Name

Chunk ID

Data Type

Parent Chunk

GLS_LIGHTMAPS

$7000

Sub Chunks

GLS_HEADER

Contains all lightmaps in the file.

GLS_LMAP

$7001

Sub Chunks

GLS_LIGHTMAPS

Contains a single lightmap.

GLS_LMAP_NAME

$7002

String

GLS_LMAP

Lightmap Name

GLS_LMAP_FILE

$7003

String

GLS_LMAP

The lightmap export file name.

GLS_LMAP_WIDTH

$7004

Short

GLS_LMAP

The width of the lightmap. The following sizes are supported: 256, 512, 1024, 2048, 4096

GLS_LMAP_HEIGHT

$7005

Short

GLS_LMAP

The height of the lightmap. The following sizes are supported: 256, 512, 1024, 2048, 4096. Please note that at present the lightmap height must be the same as the lightmap width!

GLS_LMAP_NONUNIFORM

$7006

Byte

GLS_LMAP

Maximise Lightmap Usage/Non Uniform Scaling Flag.

GLS_LMAP_USECUSTOMTEXEL

$7007

Byte

GLS_LMAP

Use Custom texels/meter Flag.

GLS_LMAP_CUSTOMTEXEL

$7008

Float

GLS_LMAP

Lightmap Custom texels/meter size.

GLS_LMAP_REPACK

$7009

Byte

GLS_LMAP

Lightmap needs re-packaging flag.

GLS_LMAP_DATA

$700A

Lightmap Color

GLS_LMAP

The lightmap color data. Stored as a sequence of pixels in the RGB format. Each color channel uses 1 byte. The size of the chunk is width*height*3. The data is saved one row at a time.

 

Chunk Name

Chunk ID

Data Type

Parent Chunk

GLS_RENDER

$8000

Sub Chunks

GLS_HEADER

Contains the render settings for the scene.

GLS_RENDER_CLEARBEFORERENDER

$8001

Byte

GLS_RENDER

Clear Before Rendering Flag.

GLS_RENDER_DIRENABLE

$8002

Byte

GLS_RENDER

Enable Direct Illumination Flag.

GLS_RENDER_GIENABLE

$8003

Byte

GLS_RENDER

Enable Global Illumination Flag.

GLS_RENDER_RAYBIAS

$8004

Float

GLS_RENDER

Ray Bias.

GLS_RENDER_DIRMULTIPLY

$8005

Float

GLS_RENDER

Direct Illumination Multiplier.

GLS_RENDER_DIRBACKSHAD

$8006

Byte

GLS_RENDER

Back Faces Cast Shadows Flag.

GLS_RENDER_DIRSHADOWS

$8007

Byte

GLS_RENDER

Enable Shadows.

GLS_RENDER_DIRSOFT

$8008

Byte

GLS_RENDER

Enable Soft Shadows Flag.

GLS_RENDER_DIRSOFTSAMPLES

$8009

Byte

GLS_RENDER

Soft Shadow Samples. Possible values are 1-32.

GLS_RENDER_GIIGNORETEX

$800A

Byte

GLS_RENDER

Global Illumination Ignore Textures Flag.

GLS_RENDER_GIITERATIONS

$800B

Byte

GLS_RENDER

Global Illumination Iterations.

GLS_RENDER_GIDENSITY

$800C

Float

GLS_RENDER

Global Illumination Sample Density. Possible values are 1.0-100.0

GLS_RENDER_GISAMPLES

$800D

Integer

GLS_RENDER

Global Illumination Rays per Sample.

GLS_RENDER_GIMULTIPLY

$800E

Float

GLS_RENDER

Global Illumination Multiplier.

GLS_RENDER_SKYENABLE

$800F

Byte

GLS_RENDER

Enable GI Sky Flag.

GLS_RENDER_SKYRED

$8010

Float

GLS_RENDER

GI Sky Color Red. Range 0.0-1.0

GLS_RENDER_SKYGREEN

$8011

Float

GLS_RENDER

GI Sky Color Green. Range 0.0-1.0

GLS_RENDER_SKYBLUE

$8012

Float

GLS_RENDER

GI Sky Color Blue. Range 0.0-1.0

GLS_RENDER_SKYMULTIPLY

$8013

Float

GLS_RENDER

GI Sky Multiplier. Currently not used.

GLS_RENDER_AUTOBLUR

$8014

Byte

GLS_RENDER

Auto Blur Flag.

GLS_RENDER_AUTOEXPAND

$8015

Byte

GLS_RENDER

Auto Expand Flag.

GLS_RENDER_AUTOBLURRADIUS

$8016

Byte

GLS_RENDER

Auto Blur Radius.

 

Example Layout

A simple .gls file might have a layout as follows (only main chunks shown):

GLS_HEADER
   GLS_LIGHTMAPS
      GLS_LMAP
   GLS_TEXTURES
      GLS_TEX
      GLS_TEX
   GLS_MATERIALS
      GLS_MAT
      GLS_MAT
   GLS_MODELS
      GLS_MODEL
         GLS_MESH
            GLS_MESH_SURFACES
               GLS_MESH_SURF
               GLS_MESH_SURF
      GLS_MODEL
         GLS_PIVOT
         GLS_MODEL
            GLS_LIGHT
   GLS_RENDER