----------------------------------------------------------------------------
- Orbiter Mesh (*.msh) Export and Import Script for gmax and 3DSMax        -
- Version 1.2                                                              -
- by Alexander Blass (mindblast@gmx.de) - 2003                             -
----------------------------------------------------------------------------

New in 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 



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. 
- Sometimes sharp edges are exported between faces, that share a smooth group
  and should therefore have a smoothed edge. This happens if one of the faces 
  vertices has different texture vertices assigned for each of the faces. 
  If the corresponding texture faces share the same edge as the geometry faces 
  you should try remapping them with the unwrap_UVW modifier, if they don't 
  there is currently no way for exporting a smoothed edge. The solution would 
  be somewhat complex to program, so i will only do it, if people ask for it. 
- 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 directory
  make sure you restart gmax afterwards or manually execute the max2msh.ms once
- 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 and choose MAXScript to open the MAXScript rollout.
In the rollout in the Utilities combobox choose either the export or import utility. 
In the rollout of the utility choose your preferences and click the start button. 
You can also open the MAXScript Listener Window from the MAXScript rollout or by 
pressing F11.


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. 
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. 
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 ! :)
