----------------------------------------------------------------------------
- Orbiter Mesh (*.msh) Export and Import Script for gmax and 3DSMax        -
- Version 1.3                                                            -
- by Alexander Blass (mindblast@gmx.de) 2003 - 2009                        -
- Thanx to Swatch (Jason Nimersheim) for LABEL tag support code and        -
- Tschachim for error tolerance improvements                               -
----------------------------------------------------------------------------

Version History

v1.3

- removed the size conversion introduced in 1.29b as it is not needed
  using the unit setup and system unit setup in gmax/3DSMax the user has all
  the tools needed to get the export to orbiter right (set system units to 
  meters and display units to whatever you like to work with)
- Bugfix: on import there was a bug that was introduced with the LABEL tag 
  support that lead to neither the labels nor the semicolon separated group 
  name being recognized so the groups where all labeled Group <nr> 
  This is now fixed. If there is a LABEL tag then that name is used otherwise 
  the semicolon separated groupname from the GROUP tag, if both are not present
  the group is named Group <nr>
- Bugfix: fixed some minor bugs on import of meshfiles that use tabs for 
  separation of numbers instead of spaces


v1.29b

- Bugfix: splitting up of vertices with multiple normals and multiple 
  associated texturevertices should now work correctly, this should fix the 
  problem with the crease that sometimes appeared on exported meshes, where 
  there should be a smoothed surface
- Bugfix: in import script, the normal vectors where not rotated if the 
  Rotate 90 option was chosen
- Bugfix: in import script, fixed error when texture mapping coordinates 
  were missing (contributed by Tschachim)
- Mesh Names are now exported to the LABEL call as well as the original. 
  (contributed by Swatch)
  On Import the Meshes are named by the LABEL tags if present otherwise 
  by the usual colon seperated Name following the GEOM tag. 
- export and import will now do a conversion from the units configured 
  in gmax/3DSMax to meters. 
  >>> Note that this will lead to a size reduction by 39.370079 of your 
  mesh when exporting a mesh that uses the generic units of gmax/3DSMax 
  as these correspond to inches internally. Just convert your mesh accordingly
  by scaling it by 39.370079 (3937.0079%) in all axes and switch units to 
  meters or any other unit you like to work with. <<<


v1.2: 

- reorganised the 3 scripts into one script defining 2 utilities with 
  their own rollouts, feature for saving to a file or dumping to Listener
  is now selectable through radio buttons, the script should now be placed
  in the scripts\startup directory of gmax/3DSMax and can then be used
  via the MAXScript rollout in the Utilities tab
- grouped objects are now exported correctly, group objects are skipped,
  also nested groups should work
- all objects with transparent materials assigned (opacity < 100) are now
  placed at the end of the mesh file
- new feature for rotating the mesh by 90 degrees around x on import/export
  this makes it easier to edit models in gmax, especially ground scenes
- fixed a problem on importing meshes that don't specify normal vectors
- made import more stable towards meshes that don't 100% conform to 
  the .msh format
- external tool "GMaxMshGrabber" for grabbing the .msh file output from the 
  MAXScript Listener window to a file is now part of the package 


v1.11

- Bugfix: generation of texture mapping coordinates fixed 


v1.1 

- Improved import/export of texture coordinates, no unwrap_UVW modifiers 
  are needed anymore, the texture coordinates are stored/read directly  
  to/from the mesh instead.
- The bLoadTextureData Variable removed since loading with textures is 
  now lightning fast. :)
- All Faces are now created with smoothing group 1 only, otherwise gmax
  automatically assigns groups wich leads to vertices with multiple normal
  vectors and thus to inconsistencies with the export script (files would
  get larger and larger with each import/export cycle). 
- All scene objects are now copied and the copies automatically converted
  to Editable_Mesh, meaning the scene can contain any kind of objects
  (non geometry objects i.e lightsources and the like will be skipped)
- Multiple normal vectors on a vertex (because of smoothing groups) 
  are now exported correctly to orbiter by splitting the vertex up. 
- Export scripts for gmax and 3DSMax are now separate with 3DSMax version
  saving to a file and gmax version dumping the .msh file contents
  to the Maxscript Listener Window

v1.0 Initial version 


Known problems:

- Whenever a script error occured during import/export, you will have to close
  and reopen the respective rollout before you can start the script again. 
- Mirrored copies of objects sometimes appear as inverted meshes in orbiter
  (vertex normals turned to inside), this is due to a problem with the mirror 
  function in gmax, use the mirror modifier instead.  
- Multi-Materials are not supported, the export script will stop with an error
  message when it encounters any object with a Multi-Material assigned.
- When exporting meshes that were imported with version 1.0 of the scripts
  sometimes the export script stops with an error. This seems to be because
  the old import script generated lots of smoothing groups on a Mesh. 
  In this case you should just import the mesh again using the v1.1 import 
  script. You may also try reducing the number of smoothing groups in the 
  meshobject that caused the problem.
- Sometimes the file is dumped multiple times to the listener window, not 
  sure why. I never had this right after starting gmax though. So if you're 
  experiencing this, just save your scene, restart gmax and try again. 

  !!! It is generally a good idea to save your scene before starting the 
  export script !!! :)



Installing the package

- unzip the max2msh.ms to the directory scripts\startup\ in your gmax/3DSMax directory
  make sure you restart gmax/3DSMax afterwards or manually execute the max2msh.ms once
- if you are using gmax: 
  unzip the GMaxMshGrabber.exe and GMaxMshGrabHook.dll to a directory of your choice
  the dll should be placed in the same directory as the exe


Using the script

In gmax/3DSMax open the Utilities tab (usually on the right side of your screen, 
the tab with the hammer symbol) and choose MAXScript to open the MAXScript rollout.
In the rollout in the Utilities combobox choose either "Export *.msh file" or 
"Import *.msh file". 
A rollout for the selected utility (import or export) will open. Choose your 
preferences and click the start button. 
You can also open the MAXScript Listener Window from the MAXScript rollout or by 
pressing F11 to have a better view of the messages output by the script.


The import utility

You may choose to rotate the imported mesh by 90 degrees around the X-Axis. 
This makes editing a bit easier, especially with ground sceneries. 
Once you start the import you will be prompted to choose the .msh 
file to load. When you have chosen the file the utility will start working
and output status messages for every meshgroup read from the file. 
On bigger meshes and slow computers the import might take a few minutes and 
sometimes the 3DSMax/gmax window is not updated while the import script works. 
So be patient.. usually if something goes wrong the script stops with an error 
but i never had it hang up in an endless loop. 
Due to the fact that in gmax a texture is always a part of a material the utility
may create more materials in gmax than there are in the .msh file. This is 
because the material may be used in the mesh file multiple times but always together 
with different textures, so in gmax a new material with the same properties 
will be created for every material/texture pair. 


The export utility

Choose wether you want to rotate the mesh -90 degrees around the X-Axis. (see import)
Choose wether you want to write the output directly to a file (works only in 3DSMax) or
dump the .msh file contents to the MAXScript Listener window.
The export utility will generate the complete .msh file format from the current 
gmax/3DSMax scene including materials and texture filenames. 
Texture filenames are exported from the gmax/3DSMax materials diffuse map. All other 
maps that you have used in your material will be ignored.


The GMaxMshGrabber tool

In gmax all the file creation functions are disabled so this little tool will let you
grab an orbiter .msh file from the gmax MAXScript Listener window as it is output by 
the export utility. 
Here is how it works:
- start GMaxMshGrabber.exe
- make sure gmax is running and then click the "Grab to File ..." button in
  GmaxMshGrabber
- choose or enter the file to write your .msh data to
- the grabber will now wait until the start of the .msh file is detected in the 
  MAXScript Listener window 
- start the export in gmax
- as soon as the actual .msh file is being output, the Grabber will show a status 
  message and begin writing data to the file you chose
- go get some tea/coffee... :)
- just wait until the output from the gmax script is finished, the grabber should say
  "Done" and your file should be ready


Textures

gmax doesn't seem to support .dds files in materials. So they have to be 
converted to .bmp format manually.
The import script will create materials in gmax with the
given texture filenames from the .msh file but with the extension .bmp instead
of .dds. They should be in the directory "..\textures" relative to the dir of 
the imported .msh file. 
The export script will create texture names from the filename of the diffusemap
with the .dds extension. So if you created your model in gmax you will have to 
convert your textures also manually to .dds files and place them in the 
orbiter\textures\ dir. 


The scripts have been tested with gmax 1.2 and 3DSMax9. 
If you find any bugs, oddities or just have suggestions or questions feel free 
to mail me at mindblast@gmx.de. 

However i don't take any responsibility for any problems that may arise when 
using these scripts. 


Now have fun and go create some good stuff for orbiter ! :)
