x2bc - X2 BOD Compiler/BOB Decompiler

Contetnt:
=========

- Introduction
- The compiler
	- Usage
	- Flags and Switches
	- Decompiling
	- Compiling
	- Limitations
	- Performance
	- Error detection in BOD files
- INI file

Introduction:
=============

x2bc is program for conversion between two data formats used in X2 - The Threat
and X3 Reunion.

Those two data formats are "plain text" and "binary".
Plain text files have extension "BOD" and binaries use extension "BOB".

Furthermore X2 stores two types of data in these files: bodies and scenes.

A body file contains one or more "bodies" - meshes consisting of vertices and
faces.

A scene file contains one scene. A scene defines body placement in space: its
coordinates and rotation. Sometimes body data are stored directly in scene files
instead of being in separate file.

The compiler:
=============

x2bc can convert (decompile) binary encoded scene and body files to text format
and convert (compile) text encoded scene and body files to binary format.

Usage:
------

x2bc is a console program (it's invoked from command line)
run:

x2bc /?

to get list of supported options

Flags and Switches:
-------------------
There are 2 types of flags: short (1 letter) and long (multiple characters)
Short flags are preceded by hyphen '-' and long flags are preceded by two
hyphens '--'

Short flags can be combined in such way:
-cs
is the same as
-c -s

Switches are special case of long flags. They can be followed by plus '+' or
minus sign '-'. If sign is ommited, plus sign is assumed.

Example:

--xpinfo
is same as
--xpinfo+

and it will turn on Extra point informations.

--xpinfo-

will turn them off.

Switches always override settings from INI file.

Decompiling (BOB to BOD):
-------------------------

x2bc -d "some file.bob"
OR
x2bc --decompile "some file.bob"

This is the shortest way to decompile a file. It will output the result to file
"some file.bod" in the same directory where is the input file. The extension can
be changed in INI file - see section INI file.

x2bc -d "some file.bob" "output file.test.bod"

this will output the results to file "output file.test.bod"

Switches:
---------
--xpinfo            Extra point informations - see file extra_bob_data.txt
--frame_warnings    frame format warnings - see INI file
--x3info            X3 specific informations - see file extra_bob_data.txt

Compiling (BOD to BOB):
-----------------------

x2bc -c --cut "source.bod"
OR
x2bc --compile --cut "source.bod"

This is the shortest way to compile BOD file. You must tell the compiler what
data the input file contains via the --cut or --bob flag.

x2bc -c --bob "source.bod" "c:\target.bob"

Will compile the file (here we are telling that it contains BOB1 data) to
"c:\target.bob"

X3 CUT (scene) files:
---------------------

X3 is using strings instead of numbers to indentify a body. To be able to
compile such scene files, the cut version must be set to 6 or greater, otherwise
the compiler will detect invalid data type.

Error detection in BOD files:
-----------------------------

I did my best to match the parsing of BOD files with X2, so I will recognize
(all?) errors which will cause X2 to crash/not show body or scene. If BOD file
can be compiled with x2bc w/o errors it will work in X2 as well. If x2bc detects
errors in BOD file, it will show error message containing line and column where
the error is.
Note that the "coordinates" of error are sometimes shifted by 1 token so you
must not blindly rely on the column number and you may have to look on the
preceding text to find the error. Like in C, sometimes if the source code is
"well" malformed it will confuse x2bc to such level that the error coordinates
will be incorrect at all.

Limitations:
------------

- The BOB file created by compiling BOB1 source will almost never be identical
to the original BOB file. That's because x2bc writes the points in different
order than Egosoft. Also the size of files may differ.
If you compile plain CUT1 source (without embedded BOB1) the resulting BOB file
will be binary identical with original BOB file.

- Because floating points are stored as integers in BOB format, there is lost of
precision when compiling BOD file to BOD and back. However the numbers will not
degrade any further if you comiple / decompile.

- When compiling BOD file, whole file is loaded into memory at once.

- Even if compilation fails, the output BOB file is still created and can
possibly contain data.

- When you compile body files with material 3 into BOB format, you may notice
loose of details. That's because when X2 loads material 3 definition it adds
some hardcoded effects (such as bump maps). But materials stored in binary
BOB files are stored as material 5, and these materials are treated exactly as
they are defined and X2 will not add any additional detail to them.

Performance:
------------

x2bc decompiles 06070.bob (46.7 MB) in 38 seconds. The output file has size of
90 MB. The memory allocation vary - peak is around 19 MB.

x2bc compiles 06070.bod (90 MB) in 1 minute 35 seconds. The memory allocation is
roughly
size of file + ~10MB. That is 90 MB + 10 MB.

x2bc decompiles 10205.bob (3.47 MB, 47 000 points) in 3 seconds

x2bc compiles 10205.bod (7.42 MB) in 6 seconds

Tested on Intel P4 1.5 GHz, 512 MB RAM

Decompiling performance of x2bc is better than performance of DeBOB from
CheckerTwo, but only because x2bc is using better algorithm for "packing of
points". When x2bc use them same linear search for "point packing" as DeBOB
does, then DeBOB is slightly better.

INI file:
=========

INI file consists of two main sections: "program" and "library".
Section "program" is used by x2bc while section "library" is used by library
libx2bc.

See the ini file itself for more info.


