Skylord123============================================================================== 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.