Unreal Model Utility v1.15a Documentation
-----------------------------------------------------------------------------------------------------------

(* = Sections updated as of v1.15)
(If nothing else, it is worth skimming over section 07 to read up on V/F-count uniformity and the <-128,+128> bounds. These
two things are demanded by the Unreal engine of all Models.)

Table of Contents:
01) Introduction
02) The painful History
03) *The Creation Process
04) *Preliminary Steps
05) *The SequenceCompilation Directory
06) *Materials
07) *Errors and Warnings
08) *Miscellaneous Bits
09) Contacting the author
10) Distribution Sites
11) Upcoming Versions
12) Revision History



01) Introduction
-----------------------------------------------------------------------------------------------------------
eerok's Unreal Model Utility, or UMU as it will be called from here on, is a plugin designed for
3D Studio Max 2.x    The idea behind it is to remove all the tedium from an Unreal artist's life, so he/she can concentrate
on what really matters: the art. This plugin improves upon the very useful "3ds2unr", which to my knowledge was the only way
to get 3D Studio data into Unreal format until now.

Quickie definition of terms:
Throughout this document i will try to keep a steady definition of the terms "Model", "Sequence", and
"Frame". A Frame is of course the atomic unit of character animation. If you don't know what a frame is,
you've got a long road ahead of you grasshoppah. :)  A Sequence is the collection of one or more frames that
makes up a continuous motion. A series of frames that defines a character saluting, running, jumping, or
doing a roundhouse kick... all of these are examples of Sequences. A Model is the collection of one or more
sequences, with the assumption that all of the sequences are of the same mesh... The vertex/face count must
be the same amongst all the sequences in a Model. So a Model cannot contain a Human Running Sequence alongside a Skaarj
Backflipping Sequence. One has to go into a Human Model, and the other into a Skaarj Model. Not trying to put anyone to
sleep here. Just wanted to be sure that was cleared up first. :)



02) The painful History
-----------------------------------------------------------------------------------------------------------
The main shortcoming of 3ds2unr, was that one had to export sequences one frame at a time, maintaining a certain name
structure. I personally found this frustrating with even small 15-frame single-sequences, so i don't even want to imagine
what 180+ frame single-sequence exports are like. Consider that for character models, you are dealing with perhaps 8-10
SEPERATE sequences (8-10 is more or less what it was in Quake1... take a look at how many Unreal has per character to get a
REAL idea of the pain level i'm talking about :)). Then factor in that many revisions may occur, and you are easily looking
at DAYS of tedious clicking,scrolling,renaming...clicking,scrolling,renaming... over and over until your head explodes. :)
As if this wasn't bad enough, any texture art applied to your Max2 models had to be exported into 8bit PCX files with power
of 2 resolutions. (The size not being the bad part, but the additional tool loading/directory managing)



03) The Creation Process
-----------------------------------------------------------------------------------------------------------
UMU seeks to free the artist from all this by automating the entire export process, from frames to textures. Yes, soon EVEN
procedural texture support will be in UMU. I will first more or less generalize the process, and then follow it up with the
vital details:

1) Create a mesh using the standard mesh-oriented primitives. (no NURBS unless you collapse to mesh)

2) Create/apply the materials/textures for it.

3) Go about animating and saving (as .max files) the various sequences (running, walking, skating, whatever).

4) Come up with a name for your Model and fill it in at the appropriate editbox on the UMU panel (or click the Modelname
browse button if you wish to view the list of Models you've worked on with the utility)

5) Load a sequence you wish to export, select the relevant nodes, go to the UMU panel and click on
"Save Sequence". You are then asked to provide a name for the sequence. After being named, all the desired frames of the
animation sequence are exported, along with any Materials that were applied to the selected nodes. UMU determines which
frames you desired based on the Time Range. The lower/upper bounds of which can be set from the Time Configuration
menu.

6) Step 5 is repeated for each sequence that is supposed to go into the Model. Once all the sequences have been exported,
decide upon a Scale for your model (default is 100.0 "Unreal Units"), decide what the model's Superclass should be
(default is 'Actor'), and click on "Compile Model". If the defaults are appropriate for your model, you can click on
"Compile Model" right away of course. After a brief delay as UMU unifies all the sequences, out pops a .uc file, two .3d
files, and however many .PCX files as there were materials. All these files go into the appropriate directories.

7) The End. You may now exit 3D Studio Max 2.x, and invoke unreal with the -make parameter to assemble the
package which will have your new Model in it.



04) Preliminary Steps
-----------------------------------------------------------------------------------------------------------
As you can see, this is a hell of a lot less time consuming and painful than the old way of doing it.
Now onto those details i promised...
Above i said step #1 is to create the mesh. There are actually three preliminary steps prior to mesh
creation that have to be performed once per package/project. First, create a subdirectory under your Unreal directory named
after the package you wish to assemble. Say for example, "UnrealTeamFortress". You would end up with:
C:/Unreal/UnrealTeamFortress, or whatever variant thereof, depending on where you installed Unreal.
The next step is to edit your Unreal.INI file and add the entry "UnrealTeamFortress" to the end of your EditPackages list.
It would end up looking something like this:
EditPackages[4]=IpDrv
EditPackages[5]=UnrealI
EditPackages[6]=UnrealTeamFortress
(In my UNREAL.INI, the EditPackages start on line #576)
The final preliminary step is to load up Max2.x, go into the UMU panel, and click on the
"Set Project Directory" button.
*IMPORTANT NOTE* All UMU functionality is disabled until the Project Directory is set. This is simply because the project
directory is essential to the entire export process. Once the project directory has been set, an entry is stored in the
Windows Registry, so that it is remembered between power-cycles/resets. The only time you'll need to change the project
directory is when you change projects.
Pretty many functions, if not all, are suspended until you select a ModelName. This wasn't the case in the older versions
of UMU, but is so as of v1.15+ because it relies on the ModelName to determine the name of the directory that will hold
all the exported sequences and textures, as well as where to look during compiles/deletes and such.



05) The SequenceCompilation Directory
-----------------------------------------------------------------------------------------------------------
The SequenceCompilation directory behaviour has been changed a bit from previous versions. No more is there a need to
flush it when you switch to work on another model. Now all exported sequences reside in subdirectories of the
SequenceCompilation directory named after the Model they are a part of. There are also code safeguards that prevent one
from saving sequences to the wrong directory. A big benefit of having a subdirectory for each model is that sequences
exported in the past are not lost. Its a sort of work history. For example, say you model a Riot Gun...you export say
5 sequences...tweak it all out....and compile. Thinking your done you move on to the Mortar. In the past, you would have
had to flush out all exported Riot Gun sequences before starting on the Mortar. So if yer project leader told you he was
unhappy with some aspect of the Riot Gun or whatever, you'd have to re-export the whole mess... the whole time trying to
be careful not to mix meshes which would screw up the plugin.



06) Materials
-----------------------------------------------------------------------------------------------------------
UMU looks to the Diffuse property of materials to determine how a material looks. It ignores the Specular, Ambient,
Bump maps and all that. The Diffuse property can be one of three possibilities:
1) A uniform color
2) A Bitmap
3) A Procedural TextureMap  (Perlin Marble, Wood, Camoflauge, etc.. as well as the special maps like Mix, Checker, etc..)
If it is a uniform color, UMU generates a PCX file at the texture rez you have set, where each pixel is the color.
For a bitmap, UMU resizes it to the chosen texture rez. The PCX files are of the paletted variety, so any truecolor bitmaps
are quantized down. Don't worry, this is using MAX2's internal histogram which is the BEST histogram/quantizer
i've encountered in my life! It works in 16bits per color channel (48bpp) and just all around it rux!
/*NOTE*/ Procedural Texturemaps are still unsupported as of v1.15.

The other material property UMU recognizes is the material's name. Its pretty much an exact clone of 3ds2unr in this
respect. :)  Materials named after 4 special keywords generate polygons with special behaviour in the Unreal engine.
Any other name is just a normal polygon. The keywords recognized are: SKIN, WEAPON, TRANSLUCENT, TWOSIDED
UMU does a case-insensitive string comparison, so whether you type "SKIN", "skin", or "SKiN" its all the same thing.
Here's pretty much a cut and paste of 3ds2unr's dox on the subject:

SKIN:
This texture will be assigned as the models Skin property in Unreal.   Skin textures can be replaced easily at runtime (to
show increasing damage, for example) and are the basis for Unreals corona effects.

TRANSLUCENT:
The polygons mapped with this texture will be marked as translucent, and can have their transparency set by the program.

TWOSIDED:
The polygons mapped with this texture will be marked as two-sided, so the texture mapping will show up on both sides of the
polygon.

WEAPON:
The polygon (there should be only one!) mapped with this texture will be marked as the weapon triangle.  Weapon polys
are not visible.

UMU has a safeguarding feature concerning the WEAPON poly which is present during Model Compiles. If it finds that the mesh
has more than 1 poly assigned this material, it validates only the first. The first being the first it encounters in the
mesh face list. Any subsequent polys assigned the WEAPON material are treated as if they are normal polys, and derive their
appearance from the WEAPON material's diffuse property. In addition to this auto-guard, the user is also informed with a
warning messagebox. Reason being, I figure if there's more than one WEAPON, which one ends up being the first in the face
list is pretty much anyone's guess. So it would be some pretty unpredictable behaviour, and a warning lets ya know it might
happen.

The one thing I still have not figured out is how the WEAPON poly's orientation is interpreted by the Unreal engine to
determine which way the weapon points. I did some experiments for like 1.5 hours and still couldn't figure it out. This
ain't a shortcoming of UMU, but just an aspect of Unreal that isn't well documented (or at least I didn't see anything
about it). If I do learn how it works, the documentation will be updated.



07) Errors and Warnings
-----------------------------------------------------------------------------------------------------------
Save Sequence can generate an error if the sequence you are trying to save conflicts in vertex/face counts with
sequences saved previously in that Model directory. Scenarios where this can come up could be something like...
Say you model a human soldier... you do a bunch of sequences and save them... suddenly you realize you forgot to give him a
weapon poly... so you quickly append one... he now has 3 vertices and 1 face more than the sequences already saved.. there
is gonna be a conflict... unfortunately a conflict that can only be resolved by re-saving the prior sequences with the
higher V/F count. This is the only way. The V/F counts MUST be uniform across all sequences, because Unreal itself expects
this. Furthermore its not something UMU can just "fix" for you, because that would entail coming up with information out
of its ass. :)  I do all my animating in Character Studio v2.0, so it is extremely trivial for me to resave sequences where
the basic model has been appended to. (OK, maybe not extremely trivial, but pretty durn trivial :))   Its conceivable that
methods that don't involve CS2.0 would entail a great deal of pain. So I say all this stuff strongly only so people don't
run into any situations where they realize too late that Unreal demands a uniform vertex/face count. There are two reasons
UMU enforces V/F uniformity within a Model:
1) Sweeney's engine demands it.
2) It prevents people from accidentally saving a Skaarj sequence into a Human Model, or something along those lines.

Save Sequence will generate an error if one of the selected nodes is not mesh-based (NURBS, camera objects, etc..)

As stated in the Materials section, Compile Model can generate a warning if you have more than one WEAPON poly in yer mesh.
See the above section for the details on this.

Both the Delete Sequence and Save Sequence buttons popup with a file system browser that allows the user to go up
the directory tree, which is undesirable as far as UMU is concerned. Reason being if you save sequences in other Model
directories, the vertex/face count may not match, which is a requirement for even being a Model in a fixed-V/F count game.
Deleting outside of the Model directory is a bad idea cos who knows what .3ds file you end up deleting. :)   So both
functions will generate a warning and reset the popup if this happens.

Compile Model can generate a warning if any coordinates exceed the <-128, +128> bounds imposed by the Unreal engine. This
can come up if you turn off the Auto-Center/Scale checkbox, and your mesh steps out of this boundary in the MAX2
worldspace. Unlike the uniform V/F-count which is absolutely required by Unreal, the boundary issue can be ignored, but
animations violating bounds will visually have a silly wraparound effect going on.

There's a handful more little warnings that can pop up, but they are extremely self-explanatory and trivial.



08) Miscellaneous Bits
-----------------------------------------------------------------------------------------------------------
The Texture Size radio buttons are only read during the Saving of a Sequence.... So if you save at 128x128, and then
later decide you wanted 256x256, you need to resave the sequence at 256x256. Compile Model just reads in the textures at
whatever rez they were saved and makes em PCX files of that rez. I thought about having it resize to the current selected
rez, but this approach suffers from the same issues that Photoshop users are aware of... "scaling up".. Information was lost
in the initial scaling down, and cannot be retrieved simply by scaling up the scaled down image.

Sequence files (*.3DS) exported with versions prior to v1.15 probably will not work correctly with v1.15+ because of a
little bit of hidden data that v1.15 relies on that wasn't exported with priors. Apologies for any inconvenience a
re-export causes.

BTW, some of you have wondered why when you save a sequence, the status bar says calculating scale, and then proceeds to
do so, even when Autoscale is unchecked. This has to do with how I save certain data in the 3DS file. Its nothing unusual,
even though it may at first appear to be.



09) Contacting the author
-----------------------------------------------------------------------------------------------------------
I can be reached at eerok@elp.rr.com
Don't hesitate to send complaints, suggestions, bug reports...whatever..

In addition to this, my good friend Jason is hosting a forum for this plugin at:
Forum:  http://teamanarchy.com/Usk8/eeindex.htm

While your there, be sure to check out the USK8 TC he's part of. Its not out yet, but when it gets released
will be one helluva mod!
USK8:   http://teamanarchy.com/Usk8/



10) Distribution Sites
-----------------------------------------------------------------------------------------------------------
http://teamanarchy.com/Usk8/		Under the Tools section
http://www.motornerve.com/		Click on the "Unreal" link, and then "Utilities"
http://www.unrealized.com/		Click on the "Modelling" link, and then "Tools"
ftp://pub:pub@24.92.101.192:28000	AKA   24.92.101.192  port 28000   login: pub   password: pub  (under UMU directory)

The FTP site will always be the most up to date since that's at my house :)



11) Upcoming Versions
-----------------------------------------------------------------------------------------------------------
Here's a short list of some of the bugfixes/features i got planned for the future:
1) Unreal Model Import - This feature will allow an artist to browse the packages in his Unreal/System
	directory, and pull in frames of a model. Most likely it will only be single frame support. But
	we will see. The point of this is to have a sort of template to work with.
2) Properly handle Procedural Texturemaps and generate PCX files for them like bitmaps.
3) Add a radio button to automatically handle Tiling UVcoords/bitmaps by generating a PCX that has tiling
	within it (Only possible way, because Unreal only supports 0.0 -> 1.0 domain)
4) Perhaps a seperate checkbox for Autocenter and one for Autoscale instead of the merged one present now.
5) MAYBE something to add faces with a NULL area to resolve V/F conflicts... tho this is extremely doubtful due to
	the can of worms it would open.



12) Revision History
-----------------------------------------------------------------------------------------------------------
Version v1.15a - December 4th, 1998
	-Fixed a small math bug with the percentage of bounds calculation (divide by zero in rare instances)


Version v1.15 - December 3rd, 1998
	-Fixed Autocenter bug that caused jerking/leaping meshes
	-Made Autocenter/Scale an option
	-Changed the way SequenceCompilation works to keep a work history and keep models seperate
	-Fixed input-focus bug that allowed users to click on functions while warnings were displayed
	-Added support for special materials (WEAPON, 2-SIDED, SKIN, TRANSLUCENT)
	-Supported checkboxes to allow user to choose texture resolution (all kinks worked out)


Version v1.13 - October 23rd, 1998
	-Worked out the UV coordinate problems


Version v1.12 - October 16th, 1998
	-Fixed up the PCX palette export; now uses internal histogram for impeccable quality


Version v1.10 - October 15th, 1998
	-Added near-full Texture map support (.PCX)
	-Added .UC/.3D support
	-Added Model Compilation functions
	-Optimized Mesh Export to toss extraneous vertices
	-Added Scale/Superclass edit boxes
	-Improved Cosmetics


Version v1.02 - Early October, 1998
	-Autoscale/Autocenter on sequences
	-Fixed fusing bug
	-Fixed mirror bug


Version v1.00 - Mid-September, 1998
	-Very basic .3DS export of sequences


