Halo Wars Model Editing

Anders

Import, edit, transfer, and export Halo Wars UGX models and UAX animations with Blender.

Anders is New Arcadia's Halo Wars toolkit for Blender. It preserves imported retail models while you edit them, builds new UGX files from Blender meshes, transfers Halo Wars 2 meshes between imported files, edits material metadata and texture paths, and imports and exports UAX animations on compatible armatures.

The safest model-editing loop is:

1. keep an untouched copy of the original game files;
2. import the correct UGX version;
3. make one controlled change in Blender;
4. export to a new filename;
5. reimport the exported file before testing it in game;
6. replace the loose game file only after the reimport succeeds.

Unit models are strict

A UGX can be structurally valid enough to open in Blender and still crash the game when a match starts. Skinned units depend on their skeleton, section table, material table, mesh bindings, LODs, and sometimes a paired damage document. Start from the retail unit UGX whenever possible and keep backups of every source file.

What The Addon Supports

Workflow	Halo Wars DE	Halo Wars 2
Import UGX	v4	v6
Re-export an imported UGX	Yes	Yes
Export a new Blender mesh	v4	v6
Static and skinned meshes	Yes	Yes
Material and texture-path editing	HW1 material values	HW2 UFX values
DDS/DDX texture preview and export	Yes	Yes
Multiple imported LOD objects	Basic section preservation	Yes
Cross-file mesh adoption	No	Yes
Paired damage-document update	No	Yes, when detected
Import UAX animation	Yes	Yes
Export UAX animation	Yes	Yes

The native extension repository requires Blender 4.2 or newer. The legacy single-file addon declares Blender 4.0 as its minimum. Current development and validation use Blender 5.0.

Install And Update The Extension

Blender 4.2 or newer can install Anders from New Arcadia's extension repository and receive updates through Blender:

https://new-arcadia.net/blender/extensions/anders/

1. Open Edit > Preferences > Get Extensions.
2. Open the repository menu in the upper-right corner and choose Repositories.
3. Add a remote repository and paste the New Arcadia URL above.
4. Allow Blender to synchronize the repository.
5. Search for Anders: Halo Wars Tools and choose Install.
6. Check Blender's File > Import and File > Export menus.

The import menu should contain:

• Halo Wars: Definitive Edition UGX (v4);
• Halo Wars 2 UGX (v6);
• Halo Wars UAX Animation.

The export menu should contain the two versioned UGX exporters and Halo Wars UAX Animation.

Updating the extension

Use Get Extensions, synchronize the New Arcadia repository, and apply the available Anders update. Blender verifies the package hash published by the repository index before installing it.

Manual And Legacy Installation

The current extension package can also be downloaded and installed with Get Extensions > Install from Disk:

https://new-arcadia.net/blender/extensions/anders/anders_ugx_tools-2026.8.31.zip

Blender 4.0 and 4.1 require the legacy single-file addon from an HWEK checkout:

components\anders\anders.py

Close Blender before replacing a legacy copy. Remove any older Anders installation, install the current anders.py, restart Blender, and confirm that only one copy is enabled. Keeping multiple copies can register duplicate menus or leave an older implementation active.

Built-In Shader Previews

The addon includes its Halo Wars DE and Halo Wars 2 shader node groups. Enabling the addon creates both groups automatically, and importing a UGX connects the material textures to the appropriate one. You do not need a separate .blend file, shader script, environment variable, or manual setup.

The built-in nodes approximate the games' material appearance inside Blender. The UGX material paths, flags, and parameters remain the source of truth for export; Blender's viewport is not an exact reproduction of either game renderer.

If an open Blender file already contains an older node group named Halo Wars DE or Halo Wars 2, the addon preserves it under a name ending in [Legacy] and creates the current built-in group for newly imported materials.

Import A UGX

Choose the importer that matches the game:

• File > Import > Halo Wars: Definitive Edition UGX (v4) for Halo Wars DE;
• File > Import > Halo Wars 2 UGX (v6) for Halo Wars 2.

The version check is intentional. Selecting the wrong importer produces an error instead of silently creating a mismatched scene.

An import can create:

• a collection named after the UGX;
• one armature containing the UGX skeleton;
• one or more mesh objects;
• separate Halo Wars 2 objects for mesh bindings and LOD ranges;
• Blender materials carrying the source material data;
• UV0, UV1, and UV2 layers when the source uses them;
• preserved normals, tangents, section assignments, bone indices, weights, bounds, and source metadata.

Select an imported mesh and open Object Properties > New Arcadia UGX. The panel identifies the game version and reports the section, bone, accessory, and material counts. Halo Wars 2 imports also show the mesh name, LOD index, and detected paired damage file.

Bones that have no geometry use the games' empty-bound sentinel values. Anders reports these as No geometry uses this bone instead of displaying the very large raw sentinel numbers as editable bounds.

Do not delete the import metadata

Imported mesh objects contain custom properties and a UGX_Section face attribute that connect Blender geometry back to the source file. Do not copy only the visible mesh into a clean scene and expect it to remain linked to the original UGX. Keep the imported objects, or use the addon's cross-file adoption command for Halo Wars 2.

Remove UGX Data For A Cross-Game Port

Use the cleanup command when you deliberately want to detach imported geometry and its rig from the source game's UGX contract before preparing it for the other game.

1. Select an imported mesh or armature.
2. Open Object Properties > New Arcadia UGX.
3. Under Cross-game port, choose Remove UGX Data for Cross-Game Port.
4. Confirm the removal.

The command processes the selected rig and its imported mesh group together. It removes Anders custom properties and helper mesh attributes from the objects, object data, bones, pose bones, materials, texture nodes, and imported images. Geometry, the armature, vertex weights, material appearance, texture pixels, and Blender actions are preserved. When a material or image is also used by an object outside the cleanup scope, Anders makes a scoped copy before removing its UGX data.

This intentionally breaks source-linked UGX export

Cleanup does not convert one game's material, skeleton, or runtime rules into the other game's format. It produces clean Blender content for a deliberate port. Reimport the original UGX if you need its source metadata again, then assign the target game's material data before exporting.

Make A Safe First Round-Trip

Before changing geometry, prove that the source model can make a clean round-trip.

1. Import a retail UGX with the correct versioned importer.
2. Leave the mesh, armature, materials, names, and custom properties unchanged.
3. Keep an imported mesh active.
4. Choose the matching version under File > Export.
5. Save under a new filename, such as model_roundtrip.ugx.
6. Start a new Blender scene and import model_roundtrip.ugx.
7. Confirm that the expected meshes, armature, materials, and LODs appear.
8. Test the exported copy as a loose replacement in game.

This separates an addon or format problem from a later modeling change. If the untouched round-trip works, add one change at a time and repeat the test.

Edit An Imported Model

Imported export is the recommended path for retail units and other complex assets. The exporter uses the original UGX as its structural base and updates the parts represented in Blender.

You can edit:

• vertex positions and supported UV layers;
• topology, when the source layout can be rebuilt safely;
• mesh and material assignments;
• imported bone transforms, names, and bounds;
• section material, accessory, rigid-bone, LOD-distance, and sorting values;
• material names, texture paths, HW1 material values, and HW2 UFX values;
• Halo Wars 2 mesh bindings through the adoption workflow.

The object panel exposes section metadata one section at a time. These controls are advanced. Keep their retail values unless you know which runtime contract the asset expects.

Edit Geometry

Edit the imported mesh normally in Object or Edit Mode. The exporter synchronizes Edit Mode before reading the mesh.

Useful rules:

• keep at least one complete triangle in every exported section;
• do not leave material indices pointing at an empty material slot;
• preserve vertex groups on skinned meshes;
• keep the armature modifier connected to the intended armature;
• keep UGX_Section unless you deliberately rebuild the topology;
• triangulate unusual topology yourself when you need exact control over the result.

Halo Wars stores supported UV channels per exported vertex. The addon can rebuild split UV topology, but a large UV or topology change is more invasive than moving existing vertices. Reimport and retest after either change.

Edit The Imported Skeleton

The imported armature is already connected to the UGX. Keep its hierarchy and names unless the change requires otherwise.

To change a bone's exported name or bounds:

1. Select the imported armature.
2. Select the bone.
3. Open Object Properties > New Arcadia UGX.
4. Edit UGX name or the exposed bound values.

Changing a bone used by vertex weights or animation tracks can break those bindings. Update matching vertex-group and animation names together.

Export A Completely New Model

You can export a Blender mesh that was not imported from a UGX.

1. Select the mesh object that should become the UGX.
2. Add at least one material.
3. Assign UGX data to every new material as described in Materials.
4. For a skinned model, connect a valid armature and finish all vertex weights.
5. Choose the correct version under File > Export.

When the selected mesh has no imported UGX metadata, the versioned exporter builds a new file instead of trying to patch a source UGX. It creates a minimal section table, material table, skeleton, bounds, vertex buffer, and index buffer.

Use new export for simple assets first

A new export is suitable for a simple static prop or a controlled custom rig. A retail-template import is still safer for a playable unit with multiple meshes, LODs, damage bindings, unusual shaders, or game-specific section settings.

Static Models

A mesh without an armature exports as a static model. The addon creates a minimal skeleton containing GrannyRootBone because Halo Wars UGX files still require at least one bone record.

Completely New Armatures

For a new skinned model, GrannyRootBone should be the top-level root bone. It is not the only requirement.

The complete contract is:

• the mesh is parented to the armature or has an Armature modifier that targets it;
• the armature contains at least one bone;
• the top-level root is named GrannyRootBone;
• child-bone parenting matches the intended hierarchy;
• mesh vertex-group names exactly match armature bone names;
• every exported vertex has a non-zero weight on at least one matching bone;
• no vertex depends on a group that is absent from the export armature;
• use no more than four meaningful influences per vertex;
• the armature contains no more than 255 bones.

The addon normalizes and encodes the strongest supported influences. It rejects unweighted vertices and bones that cannot be represented by the format.

An example hierarchy is:

GrannyRootBone
  pelvis
    spine
      chest
        head
    thigh_l
    thigh_r

An armature with only GrannyRootBone is valid for a rigid or single-bone mesh if every vertex is weighted to that group. A multi-bone unit needs the rest of its hierarchy and matching weights as well.

Materials

Imported materials already contain UGX metadata. New Blender materials do not.

Select a mesh material and open Material Properties > New Arcadia UGX Material. For a new material, choose one of:

• Halo Wars DE (v4);
• Halo Wars 2 (v6).

This creates the material fields and texture slots expected by the selected game. Assign the correct version before exporting a new mesh.

What Carries Into The UGX

Use the New Arcadia material panel to edit data that should be exported:

• UGX name changes the exported material name;
• texture-slot fields change resource paths stored in the UGX;
• the folder button applies a matching DDS/DDX texture set;
• reset restores a slot to its imported source value;
• HW1 material values expose v4 flags, blend type, opacity, specular values, environment values, and related fields;
• HW2 UFX exposes UFX mode values, shader passes, permutation status, and constant-buffer values.

Changing only a Principled BSDF value does not automatically create equivalent Halo Wars material data. Treat the node graph as a preview and the New Arcadia panel as the export contract.

Change A Halo Wars 2 UFX Shader

For a v6 material, expand HW2 UFX > Shader passes. Each pass exposes the actual permutation name and unsigned UFX header hash written to the exported material table.

1. Select the mesh and the intended Halo Wars 2 material.
2. Open Material Properties > New Arcadia UGX Material.
3. Click the folder icon beside the pass you want to replace.
4. Choose the target .ufx file.
5. Confirm that the panel shows the selected permutation name and its header hash.
6. Export the v6 UGX, reimport it into a new scene, and verify the pass again.

The addon derives the permutation name from the .ufx filename and reads the hash from its UFXS header. You can edit both fields directly when reproducing known values, but choosing the file keeps them paired and avoids a stale hash.

The UGX does not embed the shader file or an absolute Windows path. The game resolves the permutation by name, so deploy the matching .ufx under data\shaders\dx12\asset_shaders in the game or mod data layout. UFX ok means the addon found a matching deployed file and hash. Selected UFX; deploy it means the chosen file is internally valid but was not found in that runtime shader directory.

Keep The Pass Set Compatible

Skinned and specialized materials can use separate surface, surface-variant, depth/shadow, and constant-color permutations. Replacing only the surface pass is valid only when the remaining passes are compatible with it. When copying a shader setup from another asset, copy all populated passes and the related UFX mode and constant-buffer values.

Replace One Texture Slot

1. Select the mesh and the intended material.
2. Open Material Properties > New Arcadia UGX Material.
3. Click the folder icon beside the slot.
4. Choose a .ddx or .dds file.
5. Confirm or edit the exported UGX Texture Path in the file-browser options.

Normal, specular, packed-map, and mask slots are loaded as non-color data automatically.

Apply A Texture Folder

Use Folder in the material panel to apply a full texture set. The addon matches recognized filename suffixes to diffuse/albedo, normal, specular, gloss, opacity, emissive, packed-map, ambient-occlusion, and related slots.

This is useful when several materials share the same base name and all map files are stored together.

Texture Paths And Texture Pixels Are Separate

The UGX stores texture resource paths. It does not embed your edited image pixels.

If you edit an image in Blender, you must export the texture file as well:

• choose Export Active Texture DDS for the selected image node; or
• use Export Loaded UGX Textures from Object Properties > New Arcadia UGX.

Deploy the exported .dds or .ddx files at the loose path referenced by the material. Exporting only the UGX changes the path or material metadata; it does not publish the modified texture image.

Why material edits can appear to disappear

For imported materials, edit the fields in New Arcadia UGX Material or replace the indexed image node through that panel. For a completely new Blender material, use Assign UGX Material Data first. Then export both the UGX and any changed texture files.

Transfer A Halo Wars 2 Mesh Between UGX Files

Cross-file mesh adoption links one imported Halo Wars 2 mesh to another imported Halo Wars 2 UGX. Use it instead of manually copying a donor object, its armature, or its custom properties.

This is the correct workflow for adding a demo Flood mesh to a retail unit UGX.

1. Import the retail target with Halo Wars 2 UGX (v6).
2. Import the demo or donor UGX into the same Blender scene.
3. Select exactly one donor mesh object.
4. Shift-select a mesh from the retail target last, so the retail target is the active object.
5. Open Object Properties > New Arcadia UGX on the active target.
6. Click Adopt Other Selected UGX Mesh.
7. Inspect the newly adopted object in the target collection.
8. Export while any mesh belonging to the target UGX is active.

The command:

• copies the donor mesh and its section metadata;
• attaches the copy to the target UGX import group;
• copies and remaps the donor materials into the target material table;
• maps donor vertex weights to target bones by bone name;
• connects the adopted object to the target armature;
• adds a target mesh binding and preserves the donor LOD range;
• rebuilds the Halo Wars 2 structure during export.

The donor's original UGX does not need to remain the export target after adoption. The adopted copy is linked to the retail target's UGX data.

Skeleton Requirements For Adoption

Every donor bone used by a weighted vertex must also exist in the target skeleton. Matching is name-based. If a required donor bone is absent, adoption stops with an error instead of exporting a corrupt skin.

If the donor mesh is rigid to GrannyRootBone, a target with the same root can accept it. If the donor uses additional Flood bones, add compatible target bones and weights before adoption or use a target template that already contains them.

Use Retail Materials On The Adopted Mesh

Adoption initially copies the donor material definitions. To use an existing retail target shader instead:

1. Select the adopted mesh.
2. Open its material slots.
3. Replace the donor material in a slot with the intended material from the imported retail target.
4. Confirm the chosen retail material still shows New Arcadia UGX Material data.
5. Export and reimport the result.

Do not create an ordinary Blender material with the same visible name and assume it contains the retail UFX data. Reuse the actual imported retail material or assign fresh Halo Wars 2 data in the addon panel.

Multiple Donor LODs Or Meshes

The adoption command accepts one donor object at a time. Repeat the workflow for each donor mesh or LOD that belongs in the target. Keep the same retail target active for every adoption.

Paired Damage Documents

When importing a Halo Wars 2 UGX, the addon looks in the same folder for exactly one file ending in .dmg.xmb, or exactly one .dmg file.

If an adoption changes mesh bindings and a paired damage document was detected, export writes an updated copy beside the new UGX. Keep the source UGX and its paired damage file together before import, and deploy the updated pair together.

After a structural Halo Wars 2 export, the object panel displays:

Mesh structure changed; reimport the exported UGX before editing again.

This is expected. Start a new scene, import the exported UGX, and continue from that new source. Do not export the stale pre-rebuild scene a second time.

Import And Export UAX Animation

The addon imports Halo Wars UAX animation data into Blender actions.

1. Import the matching UGX first so its armature exists.
2. Select the armature, or select a mesh connected to it by parenting or an Armature modifier.
3. Choose File > Import > Halo Wars UAX Animation.
4. Select one or more .uax files.

The addon matches animation tracks to pose bones by name, creates editable actions, assigns the first imported action to the armature, and adjusts the scene timeline to the animation duration. Each action is named after its UAX filename rather than any internal authoring path. Imported actions have a fake user so they remain in the .blend file even when they are not currently active.

Enable Keep Matrix Source Action only when debugging the importer or comparing exact baked matrices. It creates an additional action and is slower than the normal editable import.

If no compatible armature is selected, the addon can still create an action containing source metadata, but it cannot create usable pose curves for the missing skeleton.

Export The Active Action

1. Select the armature whose animation you want to export.
2. Make the intended action active in the Dope Sheet or Action Editor.
3. Choose File > Export > Halo Wars UAX Animation.
4. Save to a new .uax filename.

The exporter samples the action across its frame range, converts each pose bone back to its source game transform, writes position, rotation, and scale-shear tracks, and reparses the completed file before reporting success. The curves are stored uncompressed for a predictable authoring round-trip, so an edited export may be larger than a retail UAX.

Validate animation exports in game

Blender import/export/reimport tests verify the file structure and reproduced bone poses. They do not prove every runtime animation rule used by every unit. Keep the retail UAX, export under a new name, reimport the result, and test it in the target game before distribution.

Object Panel Reference

Open Object Properties > New Arcadia UGX on an imported mesh or its armature.

Control	Purpose
Version and counts	Shows UGX version, sections, bones, accessories, and materials.
Mesh and LOD	Identifies the active Halo Wars 2 mesh binding and LOD range.
Damage	Shows the detected paired damage document.
Adopt Other Selected UGX Mesh	Adds one selected donor v6 mesh to the active target v6 UGX.
Export Loaded UGX Textures	Writes all loaded material images to a selected folder.
Remove UGX Data for Cross-Game Port	Detaches the selected imported rig and mesh group from source UGX metadata while preserving the Blender content.
Bone UGX name	Changes the exported name of the active imported bone.
Bone bounds	Changes low and high bounds stored for that bone; empty sentinels are shown as an informational message.
Section index	Selects which imported section metadata to edit.
Accessory index	Changes the mesh/accessory binding used by the section.
Max bones	Changes the section's declared maximum influences.
Rigid bone / Rigid only	Controls rigid-section skinning metadata.
LOD min / LOD max	Changes the section's visibility range.
Sorting bias	Changes the section sorting value.

Material Panel Reference

Open Material Properties > New Arcadia UGX Material.

Control	Purpose
Assign Halo Wars DE / Halo Wars 2 data	Initializes an ordinary Blender material for new UGX export.
Texture path	Changes the resource path written into the UGX material.
Folder icon	Replaces one texture slot with a selected DDS/DDX file.
Reset	Restores the imported texture path and preview.
Folder	Matches a directory of textures to the current material's slots.
Export Active Texture DDS	Writes the active loaded image as a texture file.
UGX name	Changes the material name written to the UGX.
HW1 material values	Edits v4 blend, opacity, specular, environment, and flag values.
HW2 UFX	Edits v6 UFX properties, shader passes, and constant-buffer values; the pass folder button reads a .ufx permutation name and header hash.

Export Validation

Before writing a new or rebuilt file, the addon verifies that the UGX has:

• at least one section;
• at least one bone;
• at least one material;
• vertex-buffer data for every section;
• at least one complete triangle per section;
• indices that remain inside the section's vertex range;
• a position element in every vertex layout;
• valid material and accessory indices.

For a new skinned export it also checks that armature bones can be encoded and that every vertex has a non-zero weight on a matching bone.

Passing validation means the file satisfies the contracts the addon understands. It does not prove that every game-specific unit, damage, shader, or animation rule is correct. Reimport and test in game.

Troubleshooting

The export contains only the donor or Flood mesh

The copied mesh was exported as a new standalone UGX because it was no longer connected to the retail import metadata.

Reimport both files, select one donor mesh, make the retail mesh active, and use Adopt Other Selected UGX Mesh. Export the retail target group, not an ordinary copied donor object.

The game crashes when the match starts

Return to an untouched retail target and make a no-edit round-trip first. Then check:

• the retail armature and material table are still present;
• every exported section has triangles and a valid material;
• the donor's weighted bones exist in the target;
• all target and adopted objects still belong to the same imported target group;
• UGX_Section still exists on imported/adopted meshes;
• all required LODs were included;
• the paired .dmg.xmb or .dmg file was beside the target at import and deployed beside the export;
• a second export from the same scene preserves the rebuilt mesh, material, and damage bindings.

Material changes do not carry over

Check all three layers:

1. the material is an imported UGX material or has been initialized with Assign UGX Material Data;
2. the value was changed in New Arcadia UGX Material, or through its indexed texture node;
3. changed texture pixels were exported and deployed separately from the UGX.

For an adopted mesh that should use retail shading, assign the actual imported retail material, not a newly created material with a similar name.

Textures are missing or black

Keep the UGX near the extracted art or data\textures directory structure when importing. Check the texture path shown in the material panel. The addon creates the shader preview automatically, but it cannot display a texture file that is not present in the extracted data.

A missing preview does not always mean the texture path failed to export. Reimport the UGX and inspect its material path, then confirm the referenced texture exists in the loose mod.

Adoption says a donor bone is absent

The donor has a non-zero weight on a bone name that is not present in the target skeleton. Add a compatible bone to the target and update the skin deliberately, or choose a target skeleton that already contains the required bones. Do not rename unrelated target bones merely to bypass the check.

Export says the source changed since import

The UGX on disk was replaced or modified after Blender imported it, and the saved import snapshot is no longer compatible. Reimport the current source file and repeat the edit.

Export asks you to reimport

Current addon versions automatically refresh Blender's section, source-vertex, material, mesh-binding, and source-file metadata after a structural Halo Wars 2 export. You can continue editing and export again from the same scene.

Scenes saved by an older addon may still display Legacy rebuilt scene. Export once with the current addon to migrate that scene automatically. Reimport is required only if automatic matching reports that the rebuilt mesh attributes no longer correspond to the exported UGX.

A new skinned export reports unweighted vertices

At least one mesh vertex has no positive weight in a vertex group whose name matches an armature bone. In Weight Paint or Edit Mode, assign every vertex to one or more valid groups and normalize the weights.

Blender shows the wrong UGX version

Delete the failed import collection and import again through the correct versioned menu. Halo Wars DE uses v4; Halo Wars 2 uses v6.

Recommended Test Checklist

Before replacing a retail game file:

• keep the original UGX and any paired damage document untouched;
• export to a new working filename;
• reimport the result in a clean Blender scene;
• confirm mesh, LOD, armature, material, and section counts;
• inspect every adopted mesh and its material slots;
• scrub any imported UAX action if animation is involved;
• deploy the UGX and all changed texture/damage files together;
• test one unit or object in a controlled skirmish;
• keep the last known working export so you can isolate the next change.

Next Steps

Use Getting Started for Halo Wars DE loose-file setup or Halo Wars 2 Getting Started for PKG and Haruspis setup. For deeper scenario and terrain work, continue with Cutter.

If an export still fails, bring the source and exported filenames, game version, Blender version, exact error text, object-panel counts, and the last change that worked to the New Arcadia Discord.