Created by John Wharton (aka. Solstice245), with credits to the contributors of m3addon for making this project possible.
This addon adds the following operations to Blender:
- Imports the selected .m3 file into your scene. An armature is created to represent the root of the model, and to contain all of the M3 specific data for the model.
- Meshes are parented to the armature. Then they can reference M3 materials which are defined by the parent armature.
- While importing, you can select an existing armature to import M3 data and mesh objects into, rather than creating a new armature. This feature is primarily intended for importing
.m3a
data into an.m3
model.
- Requires that there be an active or selected armature object.
- The data inside the armature defines the properties of the
.m3
or.m3a
file. Only mesh objects parented to the armature will be exported as the mesh data of the.m3
file. - Includes an option to disable the export of animation data to the
.m3
file. (This option is overriden in the case of exporting.m3a
.)
This addon adds the following panels to the Object tab of the properties editor for armature objects:
- Contains the same import/export operators as the main import/export operators, as well as model specific export settings.
- Import will default the
Armature Object
property to the selected armature. - Export will default to the last file export location of the specific M3 model, rather than the last export operation in general.
- Versions of various M3 data structures can be configured here. More information on this can be found in the Advanced Topic Explainers section.
- Contains various flags for the purpose of adjusting the workflow in the Blender interface.
- Contains properties relating to the bounding box of the M3 model. Includes a preview toggle.
- Lists the animation groups of the M3 model. Each animation group should have at least one sub-animation, which can each be assigned an action.
- Animation group names should only contain words from a specific dictionary. This dictionary is defined in the
bl_enum.py
file. - Actions are referenced, but are not automatically generated when a new sub-animation is added to a group. Take care to create new actions rather than referencing an action from multiple sub-animations unless this is strictly intended.
- Lists the M3 material layers that are defined for the M3 model.
- Material layers define the texture mappings or colors of materials.
- Material layers can be referenced by multiple materials.
- Lists the M3 materials of the M3 model. The material type is displayed on the right side of each list item.
- Layer slots are listed, with the option to assign an existing layer, create a new one, or duplicate the layer currently in the slot, if applicable.
- Materials are assigned to meshes via the M3 Properties panel when a mesh object is selected.
- Lists the attachment points of the M3 model.
- Attachment points are used in the game to position effect models such as weapon launches or impacts.
- Attachment point names must be picked from a dictionary, and should be unique from each other.
- The Volume sub list allows definition of areas, generally used by Target and Shield attachments. It is recommended to only ever have 1 volume defined in this list for a given attachment point.
- Contains the definition for the model's tight hit test volume, and lists the model's fuzzy hit test volumes.
- "Tight" hit test volume determines the area by which an in-game unit can be selected via operations such as drag select or screen wide select.
- "Fuzzy" hit test volumes determine which areas the mouse must hover over to allow a click based selection. If no fuzzy hit test volumes are defined, the entire unit model is used for click hit testing.
- NOTE: Do not use the "Cylinder" volume shape for hit test volumes. While technically allowed by the game renderer, they will not function properly in-game.
- TODO
- TODO
- TODO
- TODO
- TODO
- TODO
- TODO
- TODO
- TODO
- TODO
- A list of bone names to be enlisted by the engine as billboards.
- The given bones are aligned to the camera based on the type of alignment assiged.
- Intended for elements where you want a consistent appearance from varying model angles and/or camera perspectives.
- TODO
- TODO
- TODO
- TODO
- A list of bone names, which are the target bones of engine driven inverse kinematics.
- The target bone should be parented to the end point of a chain of bones which you wish to have procedurally transformed, so that the end is positioned on the terrain. (Such as Collosus legs while cliff walking.)
- The "Joint Length" property should match the number of bones in the chain which you wish to be affected by the repositioning of the target bone.
- Lists the vertex warpers of the M3 model.
- An experimental feature that was used exclusively for the Mothership Black Hole spell, where the mesh of units in the area are distorted based on proximity to the center. This visual effect applies only to the model of units with a behavior that enables the "Warpable" Modify Flag.
- Lists the shadow boxes of the M3 model.
- Niche feature that affects how shadows are rendered on screen. When visible, shadows are rendered only in the box's defined area, and at a relatively higher quality. There should probably only be one shadow box in a given scene.
- TODO
- Bind scale is an M3 specific property that exists on bones, and is accessible in the M3 Properties panel of the Bone Properties tab, or in the Item tab of the Context Menu while in Pose mode.
- Affects the scaling of M3 defined elements such as attachment/hit test volumes, particles, ribbons, etc.
- The scaling factor is applied as a denominator, rather than as a multiplier.
0.5
means twice as large,2.0
means half as large. - When applied to attachment points that are used as turrets, it also influences the scale of any mesh which is weighted to a bone that is parented to the attachment point's bone.
- All M3 properties which can be animated have an animation header.
- Animation headers have 3 components:
Animation ID
: An essentially random integer, represented as a hex string. Must be unique from all other IDs within the modelInterpolation
: Can be set toLinear
,Constant
orAutomatic
.Automatic
is converted toLinear
orConstant
when exported, according to convention for a given property.Flags
: The functionality of this field is unknown
- Animation headers should have an exact match between an M3 file and any M3A file applied to the model.
- In the case you need to change an animation header ID, set the ID value to an empty string and a new random integer will be assigned.
- To access animation IDs for bones, use the "Edit M3 Animation Headers" button in the Bone Properties tab, or in the Item tab of the Context Menu while in Pose mode.