166 lines
7.3 KiB
Plaintext
Executable File
166 lines
7.3 KiB
Plaintext
Executable File
==============================================================================
|
|
|
|
This is the exporter DLL for the MilkShape 3D modeler available
|
|
from chUmbaLum sOft : //www.swissquake.ch/chumbalum-soft/
|
|
|
|
The original version of this code was written be José Luis Cebrián who
|
|
has graciously allowed us to integrate his code into the Torque SDK.
|
|
José did an awesome job of putting this tool together and the GG staff
|
|
is very gratefull for the work he's put in to it.
|
|
|
|
If you look through the code, you'll notice a little complexity in the
|
|
DTS file format. A little background is in order... the dts format was
|
|
originally designed to reduce load time processing. This means that the
|
|
DTS format is almost a direct representation of how the TS engine stores
|
|
data in memory. This does reduce load times, but also ties the file
|
|
format to the run-time implementation, which is not really a good idea.
|
|
Changes in run-time implementation, and the pre-processing needed for
|
|
the run-time data, resulted in un-planned changes and re-structuring of
|
|
the DTS file format. These changes leave us with a file format which
|
|
leaves much to be desired.
|
|
|
|
To help reduce the complications involved in writing new exporters,
|
|
the MilkShape exporter is divided into a base DTS "SDK", which provides
|
|
the core support needed to deal with DTS files, and a small set of
|
|
MilkShape specific files which do the actual conversion. The long term
|
|
goal is split this DTS SDK into a seperate library to be shared between
|
|
exporter projects.
|
|
|
|
|
|
Current Functionality
|
|
---------------------
|
|
|
|
The exporter is currently in it's 1.0 "beta" phase. Which means it's
|
|
usable. Though there is much functinality to add, and several outstanding
|
|
issues. Maybe "alpha" might be more appropriate :)
|
|
|
|
- The exporter only exports diffuse texture materials.
|
|
- Multi-sequence animations
|
|
- Animation only supports bone animation (no texture, texture coor,
|
|
vertex morphing or mesh visibility)
|
|
- Support for single collision mesh
|
|
- Named nodes.
|
|
|
|
|
|
Exporter Flags & Animation Sequences
|
|
------------------------------------
|
|
|
|
Since MilkShape does not directly support a number of Torque engine features
|
|
so the tool has been extended through the use of "hacks". These are described
|
|
more fully below but essentially fall into two categories: mesh flags embeded
|
|
in the mesh's name, and specially named materials which are used to declare
|
|
animation sequences and exporter options.
|
|
|
|
|
|
Multi-Sequence Animations
|
|
-------------------------
|
|
|
|
Material with special names can be used to declare sequence information.
|
|
These materials are ignored during export and are solely used to declare
|
|
animation sequences. Sequence materials are named as follows:
|
|
|
|
seq: option, option, ...
|
|
|
|
All other properties of the material are ignored. The following options are recognized:
|
|
|
|
name=start-end This declares the name of the sequence followed by
|
|
the starting and ending key frames. This option must
|
|
exist for the sequence declaration to be valid.
|
|
fps=n The number of frames/second. This value affects the
|
|
duration and playback speed of the sequence.
|
|
cyclic Sequences are non-cyclic by default. Cyclic animations
|
|
automatically loop back to the start and never end.
|
|
|
|
Examples of valid sequence declarations:
|
|
|
|
"seq: fire=1-4"
|
|
"seq: rotate=5-8, cyclic, fps=2"
|
|
"seq: reload=9-12, fps=5"
|
|
|
|
|
|
Setting Export Options
|
|
----------------------
|
|
|
|
Materials with special names can be used to set several export options.
|
|
These materials are ignored during export and are solely used to set otoins. Option materials are named as follows:
|
|
|
|
opt: option, option, ...
|
|
|
|
All other properties of the material are ignored. The following options are recognized:
|
|
|
|
scale=n Shape scale factor, where n is a floating point value.
|
|
The default scale value is 0.1
|
|
size=n The minimum visible pixel size, default is 0
|
|
fps=n The default frames/second value for animations. Each
|
|
animation sequence may set this value, but if it's
|
|
not defined by the sequence, this default value is used.
|
|
cyclic The default animation looping flag. Each animation
|
|
sequence may set this value, but if it's not defined
|
|
by the sequence, this default value is used.
|
|
|
|
There may be more than one option material. If the same options are set on mulitple materials, then the last one in the material list is the value used.
|
|
Examples of valid material names:
|
|
|
|
"opt: fps=10, cyclic"
|
|
"opt: scale=1"
|
|
|
|
|
|
Mesh Option Flags
|
|
-----------------
|
|
|
|
Mesh may have additional flags embedded in the mesh (or group) name. The mesh name follows the following format:
|
|
|
|
name: flag, flag, ...
|
|
|
|
where the : and flags are optional. The following flags are recognized:
|
|
|
|
Billboard The mesh always faces the viewer
|
|
BillboardZ The mesh faces the viewer but is only rotated around
|
|
the mesh's Z axis.
|
|
ENormals Encodes vertex normals. This flag is deprecated and
|
|
should not be used, unless you know what your doing.
|
|
|
|
Examples of legal mesh/group names:
|
|
"box" Just called box
|
|
"leaf: Billboard" Leaf that always faces the viewer
|
|
"leaf: BillboardZ" Z axis rotated facing leaf
|
|
|
|
Meshes by defualt do not have any of these flags set.
|
|
|
|
|
|
Issues & Future Developement
|
|
----------------------------
|
|
|
|
- Split off the DTS SDK into it's own library and continue to refine
|
|
it's functionality and API.
|
|
|
|
- Triangle strips. This is probably the biggest outstanding issue.
|
|
Every mesh triangle is emitted as it's own triangle strip. This is
|
|
very bad :( Triangles need to be stripped by material. Support
|
|
should be added to the DTSMesh class.
|
|
|
|
- Detail support. Need to add support for progressive meshes. The
|
|
DTSMesh class should automatically produce decimated sub-details
|
|
based off the original art.
|
|
|
|
- DSQ exporting. DSQ files are essentially animation sequence files.
|
|
They only contain animation sequence information and can be loaded into
|
|
a shape at run-time. The same DSQ can be loaded into multiple shapes
|
|
allowing animations to be shared.
|
|
|
|
- Multiple collision meshes. The exporter currently selects the first
|
|
mesh named "collision" as a collision mesh. The torque engine actually
|
|
allows multiple collision meshes per shape and the exporter should
|
|
export all meshes named "collision" as collision meshes.
|
|
|
|
- Billboard meshes are mesh which the Torque engine automatically
|
|
rotates at run time to face the camera. There needs to be some way
|
|
of marking meshes. This could be as simple as naming them "billboard".
|
|
|
|
- Alpha BSP (or ordered) meshes. Alpha textured triangles need to be
|
|
rendered in back to front order at run-time for them to render correctly.
|
|
The dts file can contain BSP tree meshes used for this purpose.
|
|
|
|
- Better material support. There are number of material features (besides
|
|
animation) which MS doesn't support, these include multiple UV mapping
|
|
options, environment mapping flags, addative vs. blended alpha, etc. |