Table of Contents

• Catastrophic Errors
  • Blocktype Impossible
  • Vertex/Face Count Overflow
  • UV Layers Missing:
  • Skeleton Root Error:
• Recoverable Errors:
  • Property Error Level - Missing and Duplicated Header Properties.
  • Blocktype Error Level - Conflicting Blocktype Declarations.
  • Loops Error Level - Redundant, Mismatched and Missing Normals
  • UV Error - UV Map Incompatibilities
  • Colour Error Level - Colour Map Incompatibilities
  • Weighting Error Level -Vertex Weight Groups Irregularities
  • Weight Count Error Level - Weight Count Errors
  • Faces Error Level - Non Triangular Faces
• Plugin Errors

Introduction

Asterisk's Importer-Exporter plugin comes with extended error handling and reporting capabilities. Most notably errors don't immediately halt execution of the process but are instead logged and only raised until the end of section.

To access the warnings and errors log open the Windows' Console through Window > Toggle_System_Console.

[]

The plugin makes a difference between 3 types of errors. Catastrophic Errors, Recoverable Errors and Plugin Errors.

Catastrophic Errors

Catastrophic errors are errors which the plugin will not recover from that are found in the model. Catastrophic errors by their very definition cannot be turned off.

Blocktype Impossible

Indicates that the mesh properties cannot be satisfied by any MTFramework Blocktype as such it requires removing elements so it fits within one of them. Fixed by editing the mesh to remove the properties listed on the error so that they fall within the ranges of the MTFramework Blocktypes.

Vertex/Face Count Overflow

Indicates a mesh has over 65535 vertices/faces (the limit of a short which the VertexCount and FaceCount variable are). Fixed by splitting a mesh into multiple parts or simplifying the mesh.

UV Layers Missing:

Indicates a mesh is completely lacking a UV Map. Fixed by UV Mapping the mesh, either manually or through unwrapping.

Skeleton Root Error:

Indicates there is no skeleton-hint-Empty. This does not mean that models without a skeleton are not possible. However because of the exporter design there has to be at least one Empty to represent an Empty-skeleton-tree. Skeletons are read from the children of an unparented Empty. There can only be one unparented Empty object on the scene as a result. This error is fixed by adding a parentless empty if 0 candidates are found, and grouping all unparented empties under a single dummy one if multiple are found.

Recoverable Errors:

This are error classes that the plugin can patch. Some are mostly innocuous and bare extreme circumstance are unnoticeable when patched. Recoverable errors can level of alarm can be toggled on the exporter settings ranging from Ignore which will not log occurrences of the incident, Warning which will add a log entry but otherwise continue and Error which will make the exporter stop at the end of section.

A section corresponds to an entire coherent structure on the mod3 format. The sections are Header (containing file wide metadata and properties), Skeleton (containing the Skeleton, LMatrices, AMatrices and the BoneMap) and Meshes (containing each individual mesh and each of their header data). Additionally each mesh is it's own subsection but while errors and warnings are tagged with what mesh they belong to, the exporter won't stop if an error is found until it finishes analyzing all of the meshes.

The default settings for error reporting are generally suitable for most purposes and should be left alone barring specific use cases. The settings are structured to preserve original game model's data. However in certain cases, particularly whole model importing, it might be better to change specific settings; this are noted under each error level.

Property Error Level - Missing and Duplicated Header Properties.

Default Level: Warning

Indicates that a metadata property is missing or repeated from the scene or mesh header. If the property is missing it's set to a default value. The default value is in most cases incorrect and may have impact on the result. This properties are set by the Header Import for the scene and by the meshparts themselves for meshparts. If a meshpart was not imported it's recommended to transfer the properties already in a mod3 file the mimics the desired end result. A guide on how to can be found here.

For the header it's recommended to import the header of a close enough mod3 (only the header is strictly necessary).

While the results might be major, the fix is simple and can be applied retroactively by reloading the mod3 and adding the needed properties, as a result while significant it's fixable even after export.

[]

The fall through behaviour is to set the property to it's default value.

Blocktype Error Level - Conflicting Blocktype Declarations.

Default Level: Error
Suggested Level: Warning

Indicates that the mesh's custom property "blockLabel" is in conflict with the data in the actual mesh. The importer will prioritize the explicit mesh property over the blockLabel it calculates as the minimum. To fix it simply set the block label to that of the recommended label, remove blockLabel as a custom property for that mesh (if none is given it will be calculated and autoset) or deal with the extraneous properties that are forcing a higher classification.

The logging level is set to error as there is a functionality detail involved. Any level below the maximum will instead simply overwrite the property with the optimal suggestion in case of mismatch. The exporter assumes blocktype level is only stated when it's intended to be kept at said level. As the fix is simple but an incorrect export would semi-irreversible lose the original level it's set as an error.

The fall through behaviour is to set it to the suggested minimum blocktype level.

Loops Error Level - Redundant, Mismatched and Missing Normals

Default Level: Ignore

This error mostly occurs because of blender's inadequate handling of normals. If set to warning it will give a count of the number of split normals, meaning normals of a vertex that are different depending on what face a vertex lies on. Blender allows a vertex one normal for each face it's part of, the mod3 format only has a normal per vertex. As a result in cases where the normals for a vertex for each face are different the exporter must calculate a single value to save to the file. Because of blender's inadequacy with normal manipulations and preservation this will generate warnings even for untouched models and is only significant in niche cases involving the creation of seams on solid meshes in which case the fix is to use normal editing plugins like Y.A.V.N.E..

In some cases it will also occur due to orphaned vertices, vertices without a face. The fix for this cases is outlined in the section regarding UV Errors.

As blender utterly incompetent normal handling causes irregularities to happen on in-game models it's recommended to keep this on ignore or disable the use of split normals (even when disabled this error might happen because blender can fail to meet expectations even when one has none).

[]

The fall through behaviour is to set the vertex normal to the first per-face-normal found. The reason more complex operations are not performed is because each normal has a corresponding tangent and bitangent. Because arithmetic operations on normals do not hold invariants such as orthogonality when mirrored on their tangents and bitangents this have to be recalculated. Because of blender inexistant competency in this regard this have to be calculated at mesh level and as a result cannot be handled on vertex per vertex and since the difference will be indistinguishable, and would require considerable amounts of coding effort and exponentially increase export time it's not done.

UV Error - UV Map Incompatibilities

Default Level: Error

Includes the common error of a vertex missing a UV coordinate. Often the result of it not being part of any face. This is fixed by selecting all faces of a mesh (setting the select mode to faces and pressing A), hiding them (pressing H), selecting all unhidden vertices of a mesh (setting the select mode to vertices and pressing A), deleting them (pressing del) and restoring visibility to the faces (Alt+H).

Also corresponds to a vertex having multiple UV points assigned to it, which frequently leads to UV distortions. This are fixed by following the tutorial on seams.

It also includes the error of a mesh having over 4 UV Maps which is solved by removing UV Layers over the fourth as the MTFramework doesn't have any blocktype capable of handling this many.

The default level is set at error as orphaned vertices are a bad practice, multiple UV points result in VERY undesirable results that cannot be fixed once already exported without redoing the model from the original and the last case requires manual handling to pick the extraneous uv maps.

The fall through behaviour is to set the UV coordinates to (0,1) when no uv data exists for the point, to set the uv coordinate to the first found when multiple exist for the same point and to drop any uv layer after the fourth for the case where more than 4 uv maps are present.

Colour Error Level - Colour Map Incompatibilities

Default Level: Ignore

Indicates if there's an excess of colour layers (more than 1), if a vertex has multiple colours assigned to it (blender allows one per face touching the vertex, mod3 only one per vertex) or if the vertex is missing colour data (orphaned vertices).

The default level is set to ignore as colour editing is not something usually done at model level.

The fall through behaviour is to only take the first colour layer, take the first colour in the vertex when multiple are present for a given one and to set the colour to (0,0,0,255) which corresponds to no coloring and full alpha.

Weighting Error Level -Vertex Weight Groups Irregularities

Default Level: Warning

Happens when a vertex group has a name that doesn't correspond to any bone (Member of the Empty Tree). The fix is to remove weight groups that aren't tied to an existing bone.

The fall through behaviour is to simply ignore this weight.

Weight Count Error Level - Weight Count Errors

Default Level: Warning
Suggested Level: Error (when Coerce Fourth Negative Weight is disabled)

Occurs when a vertex is weighted to more than 8 vertices, exactly to 8 vertices but Split Weight Notation is not used or to 4 vertices with Coerce Fourth Negative Weight enabled. It indicates that a weight will not be faithfully stored on the mod3.

Split weight notation is explained in detail in here. It specifies a special weight group that will be set to occupy the weight complement id (the weight that is calculated from the other weights). Without it vertex group 0 is given priority and barring that a group with weight 0, failing both it's the lowest weighted vertex group. This vertex group's weight value is ignored and is instead calculated from the other 3 or 7 weights depending on the case.

The exporter will, unless forced by the option Coerce Fourth Negative Weight, simply set the blocktype as 8 weights when this happens for a 4 weight vertex (because this behaviour would result in changes to the mod3 file when importing and exporting a base game file it's not part of the default options).

The fix for 8 weights is to use less weights as there is no workaround (or use explicit negative weight notation). For 4 weights removing the mesh's blockLabel or disabling Fourth Weight Coercion solves the issue.

When 8 weights are exceeded the exporter simply takes the first 8 weights sorted from highest to lowest weight value.

Faces Error Level - Non Triangular Faces

Default Level: Error

Occurs when non triangular faces are found. The fix is to apply blender's triangulation operator to the mesh.

The fall through is to convert the multi sided face into tris by fixing a vertex and doing a triangle with each pair of remaining vertices. This solution however is inferior to simply using blender's triangulate operator. In particular the case of nonconvex faces has degenerate results. []

Plugin Errors

This are errors from code execution that are not directly caused by the mesh or models but by the programming behind the addon. Nobody is perfect and this are bound to happen. If you happen to catch an error that's not logged as one of the above or abnormal behaviour log them in the issues tracker section of the plugin's github page.