U3D v.1.0 Unreal model conversion tool.
(c) 2000 Thomas B. Beard

Yet another Unreal model converter...


  Presently there are at least four other unreal model 
converters out there but as you may know, each one has it's 
own set of limitations that either make the conversion 
process a pain in the rear, or plug in to a specific 
version of 3D StudioMAX. 

  This release of U3D only supports conversion from
3DStudioMAX .3DS files and I have only tested it on .3DS
files generated by version 3 so you may run into problems
with older or converted .3DS formats. I may add other 3D
input formats in the future such as .DXF and .ASC assuming 
they can supply all required mesh and texture data. This is 
the first release of the U3D conversion tool, so if you 
spot a bug or find a way to consistently crash it :) just 
send me an e-mail, my address is listed below.

-- U3D Options --------------------------------------------

Input Field
  Type in the name of the source .3DS file or click on the
  '...' button for a file selection dialog.

Output Field
  Type in the name of the output .3D file or click on the
  '...' button for a file selection dialog. If you are
  overwriting or appending animations to an existing file,
  you can select either the <name>_a.3D or <name>_d.3D
  file.

Vertex Conversion
  Unreal .3D model format requires all vertex points in
  your mesh to be located inside of the (-128 to 128)
  range. When converting the mesh, you will lose a little
  precision as the vertex points are snapped to fit a
  .3D model grid. This is why it's a good idea to make
  your models fit as closely as possible to the (-128 to
  128) boundaries. To simplify your work, U3D will
  automatically correct points outside of the (-280
  to 128) range by one of these methods:

- Uniform Scale
  If your model(s) have any points outside of the (-128 to
  128) bounding cube, they will automatically be scaled on
  all axis to fit and the uniform scale value will be
  displayed in the status log. If all of the models points
  reside inside of the (-128 to 128) range, a uniform scale
  will not be applied. The same uniform scale will be
  applied to all models imported.

- X,Y,Z Scale
  Similar to the uniform scale, however each axis may be
  scaled differently depending on how far points extend
  past the (-128 to 128) bounding planes on each axis.

- Clip Bounds
  Any points that extend past the (-128 to 128) range will
  be capped. This may distort your model quite severely but
  it is useful for hand animations where the maximum range
  may not be visible.

Animation

- Append Frames
  Checking this box will append all converted frames to the
  end of the selected output file. This may cause problems
  if you rely on U3D to scale any out of bounds meshes
  because U3D will not remember what scale factors were
  applied to the previously converted frames. You can
  avoid this problem by ensuring your model and all frames
  do not extend past the (-128 to 128) limit.

- Convert by object name
  When this option is selected, every mesh object in the
  .3DS file will become a separate animation frame, and
  will be converted from it's first keyframe position. All
  other keyframes will be ignored. You should choose a
  different name for each object, numbering them is
  probably the easiest to manage. While converting, the
  sorting order of the names will determine the animation
  sequence.

- Convert by key frame
  This option is by far the easiest way to convert an
  animation sequence because it will use the animation as
  it appears in the 3DS file (by keyframe). You may have
  multiple mesh objects in the scene and they will be
  combined to form the final .3D mesh. Please note that
  converting by keyframe does impose limitations as
  described below.


Alternative command line interface

  Useage: 

  U3D <Input file> <output file> [-append -xyx -clip -byname]

  -append is the same as the 'Append Fames' option
  -xyz    is the same as the 'X,Y,Z Scale' option
  -clip   is the same as the 'Clip Bounds' option
  -byname is the same as the 'Convert by object name' option

  By default U3D will use the 'Convert by key frame' and
  'Uniform Scale' options.



-- Before you begin... ------------------------------------

Please be aware of the limitations placed upon .3DS files
and their conversion to the Unreal .3D format.

1 - When using 'Convert by keyframe', each mesh object must
  exist in every animation frame and can not be modified
  between animation frames at a sub object level (Points,
  Edges, Faces, UVW Mappings), you can only change the
  entire objects translation, rotation and scale. This is a
  limitation of the .3DS file format as of 3DStudio MAX R3.
  If you need to make changes to the sub object geometry,
  you must use the 'Convert by object name' option which
  takes a bit more work to prepare. MAKE SURE you are on
  the first keyframe (frame 0) before you export, or the
  converted animation sequence will be hosed :) .
  There also seems to be a bug in 3DMax where it will drop
  the final keyframe scale information, so you may need to
  manually fix your .3DS file. As you may have guessed,
  pulling keyframes from a .3DS file is HIGHLY experimental
  at the moment so you may run into situations where U3D
  does not produce the expected results. First try filling
  in any keyframe gaps (translation, rotation and scale)
  and as a last resort you can use the
  'Convert by object name' option which is quite a bit more
  reliable but a lot less fun to use.

2 - The total number of points and faces in each
  animation frame must be the same. This applies to both
  'convert by keyframe' and 'Convert by object name'.

3 - When using the 'Convert by object name' option, you
  may only have a single object mesh per animation frame.
  If you have two object meshes with the same name, they
  will still be converted as separate frames but may not
  be placed in the correct order so numbering them is
  usually a good idea. Keep your object names no greater
  than 10 characters in length (another .3DS limitation).

4 - Only UVW texture mapping is supported. See the UVW
  walkthrough below. Unfortunately .3DS files save UV
  mappings by vertex, not face so if you place multiple
  UV mappings to a mesh you will run into problems any
  place two textures connect. You can fix this by splitting
  apart you model by texture in effect duplicating all
  previously shared points or you could design a texture
  that seamlessly wraps around your model which takes a
  bit more planning.

6 - Lights cameras and other goodies will be ignored when
  converting.


-- Special names ------------------------------------------

U3D supports special object and material names that will
translate into Unreals .3D functionality.

!<objectname> - Any mesh Object with a name beginning with
  an '!' will be ignored.

skin# - Denotes a skin texture that will be used in the UVW
  mapping conversion. '#' denotes a number from 1 to 9 You
  may have up to 9 skins, but try to use as few as
  possible. The number you choose here will be the same
  number you give the .UC #exec command used to import the
  texture into unreal. Ex:
  #exec MESHMAP SETTEXTURE MESHMAP=SRifle NUM=1 TEXTURE=SRiflea

<materialname>*W* - A triangle with this material
  mapped to it will become the weapon triangle used to
  align player and weapon models. You should only have
  one weapon triangle for a character model.

<materialname>*M* - Polygons mapped with this material
  will become mask polygons.

<materialname>*O* - Polygons mapped with this material will
  become modulated polygons.

<materialname>*F* - Polygons mapped with this material
  will become flat polygons.

<materialname>*T* - Polygons mapped with this material will
  become translucent polygons. You can adjust their alpha
  values in Unreal.

<materialname>*2* - Polygons mapped with this material will
  be flagged as two sided.

<materialname>*E* - Polygons mapped with this material will
  be environmentally mapped.

<materialname>*N* - Polygons mapped with this material will
  use the nofilter setting.

<materialname>*C##* - You can adjust the color value of
  polygons where ## denotes two hex numbers 00-FF.

<materialname>*X##* - You can set the extended polygon flags
  where ## denotes two hex numbers 00-FF. I am not sure
  if these are actually used by unreal but they may be in
  the future.

  Any of the trailing letter materialname formats may be
combined for multiple effects. You may also use two or more
materials that start with the same 'skin#' which will allow
you to place different effects on polygons mapped to the
same texture.
Here are a few examples of valid material names:
'skin1 TC04'
'skin1N2'
'skin2 X56E'

-- Textures -----------------------------------------------
  I generally use large true color image textures while
modeling, Photoshop layered images are invaluable here.
The models textures usually take more revisions than
the model itself so a high end image editor is best.
  Keep in mind that you will eventually be scaling your
texture down to a 256x256 pixel, 8 bits per pixel
(256 color) .PCX file. You may need to make use of
multiple textures to achieve a wide amount of color
variation.

-- Texturing using 3D Studio MAX R3 -----------------------

  U3D currently only supports UVW mapping of textures. UVW
mapping is highly flexible, allowing you to place different
portions of a bitmap texture on specific faces of a mesh.
You can cut down on the number of textures used by dividing
your bitmap up and applying it to multiple locations.

  Here are some quick 3DStudioMAX R3 step by step
instructions to get you started.

1 - Import your bitmap. Open the Material editor (the icon
  with the 4 spheres). Select the first material
  (upper left) and make sure it's type is set to
  'standard'. Now scroll down and open up the 'Maps'
  rollout. Check the 'Diffuse Color' box and click on the
  button to it's right. Select 'Bitmap' from the list that
  pops up (Make sure the 'New' radio button on the left
  is selected). Click on 'Ok' and you will be prompted to
  select an image to use. You should now see the image
  applied to the first material and the 'Coordinates'
  rollout should be opened below. Make sure 'Texture'
  is selected and 'Explicit Map Channel' is selected
  in the dropdown. All other parameters should be left
  to their default values. While you are here make sure
  to select the blue and white checkered box in the
  horizontal toolbar. This will force 3DMax to display
  the texture when you apply it.

2 - Rename the material. To get back to the top level
  material properties, you must click on the up arrow
  (sort of a return arrow pointing up located between the
  materials and the 'coordinates' rollout). Change the name
  in the text field to 'skin0'.

3 - Apply the texture. You can either apply the texture to
  an entire mesh or to just a few selected faces, simply
  drag the material from the material edit window and
  drop it on to the mesh.

4 - Align the texture. Click on the modify tab (should be
  the second tab over on the right panel of the
  application). Press the 'UVW Map' button and the
  'Parameters' rollout will open. Play around with the
  settings here until you get the texture lined up
  properly. If this is your first time UVW mapping, spend
  some extra time exploring the parameters here.

5 - Collapse the UVW mapping. In the 'Modifier Stack'
  rollout, just above the 'Parameters' rollout, you will
  need to click on the little box toolbar button to open
  the 'Edit Modifier Stack' Dialog. Click on the
  'Collapse All' button and choose yes. Now your texture
  mapping will stick and your model should be ready to
  convert.


For more info or help with model conversion, check out the
Unreal fan sites and message boards. PlanetUnreal.com has
quit a few top notch hosted sites with tons of information.


Thomas B. Beard (Macabre)
Email: tbeard@carolina.rr.com
Homepage: http://home.carolina.rr.com/dhmtb
