************************************
* GeomAdd Technology Preview v0.04 *
************************************
Date: 2002-08-03

Contents:
* Usage
* Restrictions
* Level Verification
* 3ds Import
* SWP Update
* Release History (See for list of new features)


Usage
=====
Place one or more new models in .3ds format into a directory along with
all the texture files. Run GeomAdd and follow the instructions.

Common problems:
- Model too big. One trespasser unit is about one meter/yard, however
  modelling programs often use centimeters/inches. So if the models
  are not rescaled (either in the modelling program, or using the
  GeomAdd import options) then they will turn out very large.


Restrictions and known problems:
================================
- Opacity maps are actually not loaded, and instead palette entry
  zero of the texture map is made transparent.
- Type1 geometry objects often don't import properly (they usually
  crash Trespasser).
- Limit of around 90 different palettes.
- The total size of the smallest texture mipmaps plus the size of all
  textures without mipmaps must be less than about 6Mb.
  As an example, the largest Trespasser level 'it' uses about 4Mb.
- Currently each time a level is saved, about 128Kb of the 6Mb is
  wasted, which implies that GeomAdd can only be used to add textures
  to a level about 30 times. Also, this wasted space will result in a
  (possible small) performance loss in Trespasser.
  To remedy this, replace the PID/SWP with the original ones, and run
  the SWP Update feature, which will add all new textures at once,
  which works much better.
- Similar problem occurs if textures are replaced - the original space
  is lost, even if the new texture is identical size to the old one.
  Run SWP Update on the original PID/SWP to recover the wasted space.


Level Verification
==================
  GeomAdd attempts to verify a level, looking for problems that are known
to crash Trespasser, however it is not perfect.
  The list of valid value names is stored in a text file called
"GeomAdd.knownvalues.txt" in the startup directory.
  For reasons I cannot determine, some textures in the original
Trespasser levels are reported as missing even though they are obviously
there. To minimize this annoyance, there is a text file called
"GeomAdd.ignoretextures.txt" in the startup directory. Any texture names
listed in this will not be reported as missing.


3DS Import
==========
  Trespasser data files store geometry in two slightly different formats,
we call them type1 and type2. There's not much difference between them,
except that all visible geometry except dinos must be type2, eg. invisible
geometry (like physics, triggers and occlusion objects) can be type1, but
if Class = "CInstance" or there's no Class, the model name must begin with
'$', or the values must contain "Visible = false"
  By default, all geometry is imported as type2. To force the geometry
to be a specific type, set a model's TScript to include the value
"int ext_GeometryType = <1 or 2>".
NOTE: Type1 import does not work properly at the moment, and often importing
a model as type1 will cause Trespasser to crash (perhaps only if textured
type1)

Things that are imported:
- TScript from corresponding .values.txt file.
- If there's a .names.txt file, object, mesh and texture names are
  replaced by the ones in that file (each line has "oldname newname" pair).
  Note that names are case sensitive.
- Triangle mesh:
  - Vertices, texture coords, faces
  - Smoothing groups are used to generate the normals
  - Mesh is scaled to fit into a unit cube [-1,-1,-1]-[1,1,1]
  - Mesh is translated so that it's centered in the cube. This is so
    that Trespasser generates the bounding box correctly. Thus the
	local coordinates of the mesh are lost. It still appears in
	the correct location (and rotates around the pivot offset? check)
- Instances from first keyframe:
  - Position, rotation, scale (pivot offset?)
- Materials: texture1 and opacity maps only, no parameters
  - Currently the actual opacity map file is ignored, and palette entry
    zero of the texture map is made transparent
- Occlusion texture. Any texture with name "SOccludet2.bmp" is marked as an
  occlusion texture. For occlusion textures to work, the model mesh must
  be type1 geometry (see ext_GeometryType above), and can't be Moveable.
  (If model is Moveable, or type2, texture will be transparent, but won't
  occlude anything).

Things that are not imported include:
- Dummy objects
- Lights, cameras, etc.


SWP Update
==========
This is useful for sharing new levels, only the SCN, GRF, and new .bmp
textures need to be downloaded. The SWP Update function will then take
the original Trespasser PID and SWP for the level, and add the new
textures to it. This is done by searching through all the textures used
by models in the GRF, throwing away the directory part of the texture
name, then loading the texture from the import directory and adding
it to the PID/SWP. Existing textures are not replaced.


Release History
===============
2002-08-03
 * Auto-correct case of imported TScript value names if it makes them
   valid (eg. changes "viSible" to "Visible"). Valid value names are
   stored in the "GeomAdd.knownvalues.txt" file (see Level Verification,
   above).
 * Custom TScript values now begin with "ext_" instead of just "_"
   (eg. "ext_GeometryType").
 * New value "float ext_ImportScale". If it appears in the TScript of
   an object being imported, that scale is used instead of the scale
   shown in the import dialog box. If ext_ImportScale does not appear
   in the TScript of the new object, but the new object is replacing
   an existing object that does have an ext_ImportScale, the import
   scale of that existing object is used. There is also an option
   to automatically add the import scale shown in the import dialog
   box to the script of all objects being imported.
 - Warn if texture .BMP files are not in 8bit palette format.

2002-06-08
 * Added option to export a model and its sub-objects as a grf.
   This may be useful for transferring objects between levels
   that don't import correctly from .3ds format (eg. Dinos).
   This option doesn't extract textures, so you will need to extract
   the objects with TresEd too to get the textures.
 
2002-05-27
 * Initial public release