DPRSim file formats.


OVERVIEW
-------------------
There are three file types:

  .world
  .state
  .experiment

World is a strict subset of a State file; they may contain the same content, and 
exist as a convention for designating intermediate (State) and significant (World)
DPRSim environments.  DPRSim initiates from a World file, and outputs State files.

The Experiment file is undocumented, but is a simple ASCII Key-Pair file to 
establish the variable and one-time conditions of a particular World/Experiment.

The World/State file (hereon, State) is written in binary mode for speed and size 
efficiency.  A C++ library for reading and writing is provided (StateFile/); an 
independent implementation in perl provides sample utilities for translating from
older formats and "understanding" the contents of a World and State file.


STATE FORMAT (Version 1)
-------------------
The State format starts with a 32-bit Magic Number, an 8-bit Version Number, 
followed by two or more "chunks".  All 32-bit numbers are written in Network
Byte Order.  8-bit values and strings are not altered.

The Magic Number is 0x434C4159, the meaning of which is left as an assignment
to the reader.

Chunks follow the form of:

  id (8-bit)
  length (32-bit)
  content

A "body" chunk has a length of -1 (0xFFFFFF), is of variable length, and must be 
the last chunk.

A valid state file contains at least one "module" chunk and one "body" chunk.
There may eventually exist multiple chunk ids that satisfy each of these 
requirements.


CHUNK ID -- Desc IMPLEMENTS
===========================

1 -- Chunk Id 1 is not used.
===========================

2 -- Basic Module MODULE
===========================
A first-generation "module" chunk has the form:
  length A (8-bit)
  string A (8-bit string of length A)
  version number (32-bit)
  length B (8-bit)
  string B (8-bit string of length B)
  length C (8-bit)
  string C (8-bit string of length C)
  length D (8-bit)
  string D (8-bit string of length D)

Where C is an ordered string of the datatypes in the module's per-catom
state stored within the body, and D is a ':' deliminated ordered string
of field names.  Providing D in D is optional, with per-field assignments 
made in-order("x:y:z::r:g:b" gives names to the first three variables, 
skips the next one, names the next three, and skips any remaining).

Implementation Statements:
---
* For a State file, there is at least one module to be listed,
	"_sim"

  Versions:
    #1 (Simple Cubic):
      ( 4, "_sim", 1, 8, "cccCCCCCC", 17, "x:y:z:r:g:b:a:bat",0,"" )

* '_sim' is a reserved module name for simulator state.  
  By convention, '_sim' should be the first listing in the module chunk.

* Module names should be at least 3 characters long.

* string C datatypes should use perl 'pack' notation

* The minimum fixed length overhead for a Simple Cubic represented world
  file (world files only contain _sim information) is 52 bytes. 

3 -- Basic Body BODY 
===========================
A first generation "body" chunk has the form:
  catom id (32-bit)
  total length (32-bit)

 ...followed by one or more module states:
  length N (32-bit)
  data N (8-bit string on length N)

The ordering of the modules is based on the order of the modules as
defined in the module header.  

Implementation Requirements:
---
* By convention, the first module is simulator state, but this must be interpreted 
  from the module header.  

* '_sim' is the only module required for a valid World file.

* A minimal World file in Simple Cubic(_sim:1) is 20 bytes per catom.
  4 bytes for id, 4 bytes for total length (12), 4 bytes for _sim length (8 bytes)
  and 8 bytes representing x,y,z as signed bytes and r,g,b,a and bat as unsigned.
  This also limits the World to 2^24 possible catoms or catom positions.


EXPERIMENT FILE FORMAT (Version 2)
----------------------------------

Experiment files are plain ASCII text.  It consists of a series of key/value pairs separated with an equals ('=') sign.  Special characters are "=", ",", and "#"  (equals, comma and pound).  Any line that starts with a "#" is considered a comment and will not be parsed by the simulator.

Sample Experiment file:

WORLD=small_tower.dpr
TIMESTEPS=2000
SAVE=0
VISUALIZE=false
MODULES=Flicker
RESOLUTIONX=640
RESOLUTIONY=480
CAMERA=10,40,-50
CAMERALOOK=10,0,5
USE_PHYSICS=true
BOUNCE=0.80
GRAVITY=10
PHYSICS_TIME_STEP=0.05
SIM_TIME_STEP=0.1
CATOM_RADIUS=1.0
CATOM_MASS=1.0
MAGNET_DEPTH=0.1
MAGNET_MAX_FORCE=100
MAGNET_MAX_RADIUS=3
SHOW_FEATURES=true
FRICTION=infinity
GROUND_FRICTION=1
LATTICE=cube
OBJECT=SPHERE,0,0,5,0,0,0,0,255,0,0,100,5
OBJECT=CCYL,15,3,3,0,-20,0,0,255,0,0,100,1,10
OBJECT=BOX,20,20,0,0,90,0,0,255,0,0,100,30,2,5
OBJECT=CYL,0,0,10,0,0,0,255,255,255,0,100,1,35
#OBJECT=PLANE,10,0,0,0,45,0,0,255,0,0,100,10,10,20,20  <-- sample comment

End Sample Experiment File.

Object format is as follows:

OBJECT=   <-- OBJECT KEYWORD, activated static object parser.

OBJECT_TYPE,x,y,z,yaw,pitch,roll,r,g,b,alpha,mass  <-- same for all objects

Then there are extra object specific data:

SHPERE: add a value for "radius" on the end of the line
CYL: add values for "radius" and "length"
CCYL: add values for "radius" and "length"
BOX: add values for "length", "width" and "depth" (x,y,z)
PLANE: add values for a,b,c,d that define the plane
