Repository navigation
mw5 model extraction
Research into extracting 3D mech models from MechWarrior 5: Mercenaries and turning them into the 2D sprites (and eventual spritesheet animations) that MakaMek's board renders today.
Date: 2026-10-25 · Scope: research only, no code changes.
The pipeline these techniques feed into is designed in ../architecture/asset-pipeline.md (stage 1 = canonical model import, stage 2 = sprite rendering). This document covers the extraction fact base and the sprite-format details that design builds on.
-
Extraction is a solved, well-trodden problem. MW5 is Unreal Engine 4.26; every base-game asset lives in
MW5Mercs-WindowsNoEditor.pak, and DLC/mods ship as additional.pakfiles that must be loaded too (see §2.1). Three working routes exist: FModel (browse/preview/export), UE Viewer/umodel (viewer + batch export), and the official MW5 Mod Editor (FBX export with real materials and skeletons). -
There are 199 unit variants in
data/units/mechsbut only 76 distinct chassis. MW5 meshes are per-chassis, so the render workload is 76 model sets, not 199 (see §2.3). -
Current unit art is a single 84×72 top-down silhouette (
unit.pnginside the.mmuxzip) drawn at 0.84 × the 100×86.6 hex. A re-render pipeline only needs to replace one PNG per unit at first — no format change is required to prove the idea. -
Animation needs a format change (
.mmuxv2: sprite atlas + metadata), but the runtime already has a sprite engine:MonacoLabs.Presto.AvaloniaexposesSpriteSheet/ImageSequence/PlayFrames(see presto-animation-capabilities.md §3.6). - Walking/idle/run exist in MW5; prone and stand-up do not. MW5 has no knockdown mechanic, so no fall/getup animation was ever shipped. Those two clips must be authored in Blender (cheap for a top-down camera) or approximated from the shutdown/collapse and jump-jet clips.
-
Legal: renders of MW5 models are derivative works of PGI/Microsoft IP. They cannot be committed to this repo or shipped as downloadable content. The tooling can be; the output must stay a user-generated local asset pack (which the existing
LocalFolderResourceStreamProvideralready supports).
| Item | Value |
|---|---|
| Engine | Unreal Engine 4.26 (older builds 4.23) |
| Install root | …\MechWarrior 5 Mercenaries\MW5Mercs\Content\Paks\ |
| Main archive |
MW5Mercs-WindowsNoEditor.pak (plus DLC/mods as additional paks) |
| Asset types | Cooked .uasset (skeletal meshes, textures, material instances, data assets) |
| AES | Base-game paks are not encrypted as a rule; mod paks occasionally are. If a tool reports the archive as encrypted you need the game's AES key. |
UE5 mappings (.usmap) |
Not needed — 4.26 assets are versioned |
-
MW5Mercs/Content/Objects/Mechs/<Chassis>/…— one skeletal mesh per chassis (rig + hardpoint sockets as bones), plus animation assets, material instances, textures andAnimBlueprints. - Variant data lives in data assets (
…Data,.hpshardpoint sets, loadouts); the mesh is shared across variants of a chassis. - Weapons/arms are separate meshes attached to sockets — an extracted mech body may be missing arms or weapons.
- Materials are custom UE4 material graphs (paint-scheme composition, camo masks), not plain PBR — expect flat/grey previews from
umodel/FModel.
2.2.1 Verified against the pak (2026-10-27, MW5Extractor)
The statements above are directionally right but the real tree is messier; measured on a full base + DLC install (285,997 virtual files):
| Reality | Consequence |
|---|---|
104 mech folders, not 76: Clan chassis live one level deeper, Objects/Mechs/CLANS/<Chassis>/, and DLC content is nested inside the single base pak (MW5Mercs/Content/DLC7/...) |
Chassis identity must be resolved from the chassis' own child folders, not from the segment after Mechs
|
102 chassis are monolithic (Model/Body/<Chassis>_SKM); Atlas II is modular: it has no <Chassis>_SKM, but it does have a body mesh at Model/Body/AS7II plus separate part meshes; Blackhawk KU ships no body mesh at all (its weapons use the Nova code) |
"One skeletal mesh per chassis" is false for newer DLC chassis, and a missing <Chassis>_SKM does not mean a missing body |
Body meshes carry no sockets; the shared Mech_SKL carries 47 (Torso_Weapon, Forearm_Left_Weapon, Weapon_Melee_*, WeldTarget_*) |
Mount transforms exist, but at torso/arm granularity — not per hardpoint |
| 101 cockpit meshes, 90 cockpit glass meshes; 14 chassis ship no glass | Glass is per chassis and sometimes absent |
104 <Chassis>_HPS hardpoint sets, 686 variant (_MDA/_Loadout/_UnitCard) assets, 12,541 weapon meshes, 10,978 animation assets |
Everything the assembly step needs is present |
MWMechHardpointAsset/MWMechDataAsset/MWMechLoadoutAsset are custom classes CUE4Parse leaves as UObject, but JsonPropertiesExporter dumps them fully: Atlas_HPS.json lists HardpointSlotID (Torso_Left_MH1_lrm10), MechSkeletonSocketID (Torso_Weapon), MechPart, and HardpointVisuals (weapon tag → weapon Blueprint); AS7-D_Loadout.json lists InstalledWeapons[] as HardpointSlotID → weapon data asset |
Hardpoint topology, mount socket and the equipment→asset mapping are machine-readable headlessly — no hand-written deserialiser, no hand-curated weapon table |
The MW5 layout is therefore "body + cockpit + glass + weapon meshes + data assets", with two body layouts to support. Filenames remain the cheapest discovery index (Weapon_Mech_AS7_Torso_Right_BH1_AC20_SKM encodes chassis, location, hardpoint and weapon), and the <Chassis>_HPS/_MDA/_Loadout JSON is the authoritative assembly data.
MW5Extractor assemble now builds a full variant from the pak and produces one renderable glTF (AS7-D.glb, ~50k triangles): body (Atlas_SKM) + third-person cockpit (AS7_TP_Cockpit_DM0_STM, named by <Chassis>_MDL, parented to the Cockpit bone) + the loadout's weapon meshes, each placed by its slot's skeleton bone. The loadout → weapon-data-asset → WeaponType tag → <Chassis>_HPS visual → _SKM mesh chain is fully data-driven; the only manual knowledge left is which MakaMek equipment corresponds to which MW5 weapon tag. The first-person cockpit (Atlas_Cockpit_SKM/_CockpitGlass_STM) is an interior asset and must not be used as the visible head. Output is byte-identical across runs.
MW5Extractor clips AS7-D --probe decodes each candidate and reports what is really there. The Atlas folder
ships 91 animation assets; only six canonical slots exist and three of them are empty:
| Canonical | Source asset | Keys | fps | Duration | Animated bones | Root travel | Loop closure |
|---|---|---|---|---|---|---|---|
Idle |
AS7_Stand_ANI |
31 | 30 | 1.0 s | 39 | 0 m | 0° |
Walk |
AS7_WalkForward_Straight_ANI |
61 (60 sampled) | 30 | 2.0 s | 39 | 8.61 m | 0° |
Run |
AS7_RunForward_Straight_ANI |
31 (30 sampled) | 30 | 1.0 s | 39 | 18.45 m | 7.9° |
Jump |
— | — | — | — | — | — | chassis-dependent |
Shutdown |
— | — | — | — | — | — | chassis-dependent |
Destroyed |
AS7_Falling_ANI |
91 | 30 | 3.0 s | 39 | 0 m | 0.4° |
ProneEnter / ProneIdle / StandUp
|
— | — | — | — | — | — | absent everywhere |
Findings that shaped the tooling:
-
Aliases are data. First-person (
_FP_), injury (_Limp), turn (_Turn_/_Turning_), reverse (_Backward_), aim/melee and BlendSpace (_BLS) clips are excluded by an ordered pattern list inclip-map.json;_WalkForward_Straight_ANIoutranks_WalkForward_Left_ANI/_Right_ANI. - 30 fps, N+1 keys. A 2 s walk has 61 keys at 30 fps; the closing key duplicates the first pose. Sampling every key and dropping the last gives 60 shipped poses (the loop wraps 60 → 1).
-
bForceRootLockdoes not mean no root motion. The walk still translatesRootby 8.6 m and the run by 18.45 m; stage 1 zeroes the horizontal root translation and reports the stripped distance. The sprite is board-anchored. -
Indexes do not line up.
Mech_SKLhas 272 bones,Atlas_SKMreferences 110, and a walk track animates only 39. Tracks are mapped to joints by bone name; index-based mapping silently animates the wrong limb. -
Idleis a static stance, not a breathing loop.AS7_Stand_ANIhas 31 keys, but every key is identical: the clip only holds the pose (34 constant channels, one key each after collapsing). Rendering it produces pixel-identical frames, even at 4× supersampling. Ship the pose for completeness, but do not count on idle motion at board size; the walk/run leg cycle is the motion that reads. -
Runis not perfectly closed (7.9° on one bone). The loop still ships, with the closure error recorded inclips.jsonrather than hidden. -
Not every chassis has every clip.
JumpandShutdownare chassis-dependent and reportedmissing; only prone/stand-up areabsentby design (MW5 never shipped knockdown). -
CUE4Parse cannot write animated glTF.
AnimationExporteronly offers ActorX (.psa), UEFormat and USD.MW5Extractortherefore readsUAnimSequence → ConvertAnims()tracks and writes the glTF animation itself with SharpGLTF (UAnimSequence.ConvertAnims,CAnimTrack.GetBoneTransform, y/z swap + cm→m). -
Blender drops an armature-level transform on skinned meshes. Baking the canonical rotation into the
armature moved the body but not its attachments; the animated model therefore stays in MW5 source space and
the driver applies
--model-yaw 90. See../architecture/blender-render-driver.md§3.3.
data/units/mechs/*.mmux → 199 variants
distinct chassis prefixes → 76: ARC AS7 ASN AWS BJ BL BLR BMB BNC CDA CGR CHP
CLNT CN9 COM CP CPLT CRB CRD CRK CTF DRG DV ENF FLC FLE FLS FS9 GHR GLT GRF HBK HER
HGN HNT HSR JM6 JR7 JVN KTO LCT LGB LNC25 MAD MCY MON ON1 OSR OTL OTT PNT PXH QKD RFL
RVN SDR SHD STG STK STN TBT TDR THE THG UM VL VLK VND VTR WHM WLF WSP WTH WVE WVR ZEU
A chassis map (AS7 → Atlas, CPLT → Catapult, …) must be maintained as a small JSON file in the tooling; MW5 folder names are chassis names, MegaMek/MakaMek codes are CHASSIS-VARIANT.
Open-source UE datamining frontend. Reads .pak directly, renders static/skeletal meshes with animations in-app, exports .psk/.pskx, .gltf, PNG/TGA textures and raw .uasset/JSON.
Setup:
-
Directory → Selector → Add Undetected Game→ point at…\MW5Mercs\Content\Paks, pick UE 4.26, press +. - Settings → Output Directory, Texture Platform = Desktop.
- Loading mode All → Load (merges base + DLC + installed mods).
- Browse
MW5Mercs/Objects/Mechs/…, double-click a mesh to preview, right-click → Save Model (.psk) / Save Texture.
Strengths: fastest to a preview; per-asset graph navigation (jump from mesh → material → texture); exports both PSK and glTF. Weaknesses: no batch/batch-CLI; custom materials render grey.
Gildor's UE Viewer is confirmed working for MW5 ("meshes, textures and animations", build 1590). It is a real-time viewer with animation playback and a scriptable CLI exporter.
umodel.exe -path="…\MechWarrior 5 Mercenaries" -export -out=out MW5Mercs-WindowsNoEditor.pak
Keys worth knowing: PgUp/PgDn cycle objects, [/] cycle animations, Space play, Ctrl+A animation sets, Ctrl+X export current object, Ctrl+S screenshot.
Caveat: custom materials render grey; spiritovod's custom "materials" build (linked from the MW5 forum topic) improves preview and fixes some static meshes in newer game versions.
The official Mod Editor is a complete UE 4.26 editor, free in the Epic launcher for game owners. In it: select asset → Asset Actions → Export → FBX.
This is the only route that preserves:
- real materials and texture references,
- the real skeleton (hardpoint sockets are bones — useful later),
- LODs, collision, correct scale/pivot.
Skeletal-mesh export options that work: FBX 2013/2014 binary, Vertex Color on, Level of Detail off, Export Morph Targets on, Map Skeletal Motion to Root on.
Cost: a multi-GB editor install and a slow first load.
If the pipeline needs to run for 76 chassis repeatedly, write it as a scripted tool rather than clicking:
| Layer | Library |
|---|---|
| Pak read/decrypt |
repak (CLI) or CUE4Parse (the library FModel is built on) |
| Asset parse | CUE4Parse (meshes, textures) / UAssetAPI (property-level) |
| Mesh → file | CUE4Parse exporters (PSK/glTF), or shell out to umodel -export
|
| Render |
blender -b -P tools/blender/render.py — this is the pipeline's renderer (see ../architecture/blender-render-driver.md); the same install also covers PSK/PSA round-tripping |
A C# tool on CUE4Parse fits this repo's stack (net10.0, no Python build step needed for extraction) and can emit the .mmux packages directly.
This now exists: src/MakaMek.Tools/MW5Extractor mounts the paks, enumerates and classifies all 104 chassis into discovery-report.json, reads meshes/skeletons/sockets, exports glTF/PSK/JSON, and dumps the custom hardpoint/loadout data assets — headless, read-only, no GUI. It is the intended unreal adapter of MakaMek.Pipeline.Import.
| Gotcha | Handling |
|---|---|
| LODs |
Save Model writes _LOD0.._LODn — use LOD0 only |
| Duplicate material slots | merge duplicates in Blender, or shading looks wrong |
| PSK has no vertex normals | work from .pskx/glTF when normals matter |
| Custom materials | expect grey; rebuild base colour/normal/mask manually |
| Paint schemes | MW5 composes camo from mask textures — extracted albedo is a plain base colour |
| Scale | PSK carries no unit system; UE is cm/Z-up, models import ~100× too big |
| Missing limbs | weapons/arms are separate meshes on sockets; decide per-chassis what to include |
| Mod paks | load All in FModel or you may pick a modded override |
| Thing | Current state |
|---|---|
| Package |
.mmux = zip with unit.json, unit.png, manifest.json
|
| Image | single 84×72 ARGB PNG, transparent, top-down silhouette, ~1:1 to logical pixels |
| Drawing |
UnitControl → Image at 0.84 × Width/Height of a 100 × 86.6 hex, Stretch = Fill, rotated by torso facing |
| Loading |
IImageService.GetImage("units/mechs", model) → CachedImageService → UnitCachingService (ImageCache) |
| Animation runtime |
MonacoLabs.Presto.Avalonia SpriteSheet / ImageSequence / PlayFrames (pinned preview dependency) |
| Unit states available |
UnitStatus.Prone, MovementType (Walk/Run/Jump/Prone), IsOutOfCommission, shutdown/heat, Mech.IsProne
|
So: P0 changes nothing but the PNG. Animation later needs a v2 package + a state→clip resolver.
Verified against the Atlas pak on 2026-10-27 — real asset names, key counts and root motion are in §2.2.3.
The mapping is data (src/MakaMek.Tools/MW5Extractor/clip-map.json), not a per-chassis assumption.
| Clip | Source in MW5 | Notes |
|---|---|---|
Idle |
✅ chassis idle (<Chassis>_Stand_ANI) |
static stance; holds the pose |
Walk |
✅ locomotion (<Chassis>_WalkForward_Straight_ANI) |
loop; leg cycle reads top-down, 2 s at 30 fps |
Run |
✅ locomotion (<Chassis>_RunForward_Straight_ANI) |
longer stride, faster; 1 s at 30 fps |
Jump |
useful for MovementType.Jump
|
|
Shutdown / PowerUp
|
good for UnitStatus.Shutdown
|
|
Destroyed |
✅ destruction/collapse (<Chassis>_Falling_ANI) |
good for IsOutOfCommission
|
ProneEnter |
❌ does not exist | MW5 has no knockdown mechanic |
ProneIdle |
❌ does not exist | author |
StandUp |
❌ does not exist | author |
MW5 never shipped fall/getup animations (knockdown was a MWO feature, removed early and never per-mech; the MercTech 1.0 mod had to author four new clips to add knockdown). Treat prone/standup as new animation work, not extraction.
Because the board is top-down, lying down is a silhouette problem, not a rig problem — cheat aggressively:
- ProneEnter (4–6 frames): rotate the root/hips 80–90° about the mech's forward axis while dropping the pelvis; splay arms. At 256 px and 12 fps this reads as "falling over".
- ProneIdle (2–4 frames): settled pose, tiny breathing offset.
- StandUp (5–7 frames): reverse with a push-up beat — arms plant, torso rises, legs gather under.
- Reuse one authored set across chassis via retargeting (skeletons are per-chassis but humanoid-ish; MercTech reports cross-chassis animation reuse works after rig surgery). Fallback: 3–4 body-plan variants (biped, reverse-joint, quadruped) instead of 76 bespoke sets.
The current art is top-down and the UnitControl rotates sprites for facing, so the camera and lights must be facing-independent:
| Parameter | Recommendation |
|---|---|
| Projection | Orthographic, ortho_scale fixed to the hex footprint (100 u) — every mech shares one scale |
| Pitch |
90° (decided) — matches the current art, so sprite replacement never changes how the board reads. The tilted alternative was rejected; see ../architecture/asset-pipeline.md §4.2 for the consequences (facing is the only depth cue; prone needs a marker) |
| Yaw | 0° (mech faces "north"); rotation happens at runtime |
| Framing | mech footprint centre at frame centre, not bounding-box centre — keeps position stable in the hex across frames |
| Lights | key + fill + rim parented to the camera, fixed intensity, neutral white — identical lighting on every mech and every frame (colour would break the luminance contract) |
| Background |
film_transparent = True, RGBA output |
| Renderer | Headless Blender (blender -b -P tools/blender/render.py), Cycles CPU — see ../architecture/blender-render-driver.md. Blender is also the tool for the manual extraction route above (FBX export, PSK/PSA import), so one dependency covers both ends |
- The fitted per-model canvas supersedes the legacy fixed 84 × 72 cell (spikes #1642/#1653): render at the
model's plan-view projection + 2 px margin (
render.py --fit), box-downsample 4× frames to 1×, and draw the result 1:1 centred in the 100 × 86.6 hex. Every unit therefore ships its owncellWidth/cellHeight, carried inunit-sprites.json. The old84 × 72size (0.84 × hex) remains the fallback for existing art only. - Sprite size is not chosen here: it comes from the tonnage-volume scale chain in
../architecture/asset-pipeline.md§4.3, with per-chassis overrides inscale-overrides.json. - Keep the 84:72 aspect inside the cell, or switch
UnitControltoStretch = Uniform;Stretch = Fillon a square frame would squash the mech. -
Luminance only, no hue. The shipped sprites are tinted at runtime (
UnitControlcomposites the owner colour over the sprite with the sprite's alpha as anOpacityMask), so they must be a white→dark-grey ramp: near-white base, darker creases and outline. Measured on the current art: ~98% of opaque pixels are neutral (R≈G≈B) across a full 4…255 range — the tint path already assumes exactly this. Details in../architecture/blender-render-driver.md§3.1. - One atlas per chassis, one row per clip, fixed cell size → trivial slicing and a trivial Presto
SpriteSheetmapping.
Proposed .mmux v2 additions (backwards compatible — unit.png stays as the static/reduced-motion fallback):
Suggested clip costs at 12 fps: walk 10 frames ≈ 0.83 s loop; prone transition 6 frames = 0.5 s (matches a tabletop "falls this turn" beat); stand-up 7 frames ≈ 0.6 s.
Measured on the assembled, animated Atlas (spike #1653): the fitted 1× cell for Walk is 91 × 63
(the union of every sampled frame at 5.098 px/m, +2 px margin), the atlas is 1024 × 128 with one row, and
sheet.py writes unit-sprites.png/unit-sprites.json, a labelled contact-sheet.png (1× frames at 2× zoom
on neutral and hex backgrounds), clips.csv/clips.json and preview-Walk.gif. The source is 60 poses at
30 fps, shipped as 10 at 12 fps; frames re-render pixel-identically (max channel delta 0).
| Concern | File | Change |
|---|---|---|
| Package read | src/MakaMek.Assets/Services/PackageReaders/MmuxUnitPackageReader.cs |
parse unit-sprites.json (+ optional sheet bytes) into UnitPackage
|
| Package record | same file, UnitPackage
|
add SpriteSheetData? Sprites
|
| Cache | src/MakaMek.Assets/Services/UnitCachingService.cs |
second dictionary SpriteCache; keep atomic commit under SyncRoot
|
| Image access |
src/MakaMek.Avalonia/MakaMek.Services.Avalonia/AvaloniaAssetImageService.cs, CachedImageService.cs, HybridImageService.cs
|
new GetSpriteSheet(assetType, assetName) returning a decoded atlas + metadata |
| Render | src/MakaMek.Avalonia/MakaMek.Avalonia/Controls/UnitControl.cs |
swap Image for a Presto SpriteSheet visual; play clip from state |
| Clip resolution (pure, testable) | new src/MakaMek.Presentation/UiStates/UnitAnimationResolver.cs
|
(UnitStatus, MovementType, isMoving, isDestroyed) → clip name — unit-testable, keeps UI thin |
| Reduced motion | UnitControl |
fall back to static unit.png frame 0 (Presto WhenReduced) |
UnitAnimationResolver is where the value is: it belongs in Presentation (tested, coverage-tracked), not in the control.
| Phase | Scope | Estimate |
|---|---|---|
| P0 spike | 3 chassis (e.g. AS7 Atlas, COM Commando, LCT Locust), static top-down re-render, drop into .mmux, eyeball in game |
1–2 days |
| P1 | all 76 chassis static renders; camera/lighting settled; render script + atlas-less unit.png swap |
3–5 days (mostly unattended render time) |
| P2 |
.mmux v2 + UnitAnimationResolver + UnitControl sprite playback; Idle/Walk/Run for the 3 pilot chassis |
3–4 days |
| P3 | prone/stand-up authored (4 body plans), full 76-chassis rollout | 1–2 weeks, dominated by animation authoring + review |
Per-chassis render time is minutes, not hours, if the scene is a template with linked meshes.
| Risk | Impact | Mitigation |
|---|---|---|
| Licensing | Renders are derivative works — cannot be committed or published | Ship the generator, not the output; user runs it against their own game copy into a local pack |
| Silhouette readability | MW5 mechs are busy; top-down may read worse than the clean MegaMek line art | Pilot side-by-side at 84×72 before committing; mitigate with outline/posterize post-process rather than changing the camera pitch (locked at 90° — see ../architecture/asset-pipeline.md §4.2) |
| Missing arms/weapons | Extracted body may look "stripped" | Decide a canonical loadout per chassis; attach socket meshes |
| Skeleton variance | Retargeting prone clips across 76 rigs | Author per body plan, not per chassis |
| Asset size | 76 × 9 clips × 10 frames × 84×72 × 4 B ≈ 160 MiB uncompressed (≈ 24 KiB/frame) | PNG on a grey ramp compresses this heavily, so it is not a packaging problem at 1×; if clips grow, cut frame counts or trim cells before raising resolution |
| Soft raster at zoom | 1× is as soft as the current art when zoomed or on high-DPI | Accepted for parity with existing assets; resolution is a preset value, so a high-DPI pass is a later cellWidth/cellHeight change, not a format change |
| Custom materials | Grey renders from FModel/umodel | Export via Mod Editor FBX, or author a simple 3-tone material (base/shadow/highlight) — arguably better for board readability |
| Format churn |
.mmux v2 breaks readers |
Keep unit.png authoritative; sprites optional; bump manifest.json version |
Not legal advice. The statements below are engineering constraints we choose to honour, not a legal interpretation of any agreement. Verify against the current EULA before relying on them.
MW5 assets and any render derived from them are PGI/Microsoft IP. Quoting the MechWarrior 5: Mercenaries EULA directly (26 July 2021 text):
- License Grant — "a non-exclusive, non-transferable, non-sublicensable worldwide license to install and use the Product … solely for your personal and non-commercial use".
- Restrictions / Code of Conduct (pursuant to Article 3) — the licensee shall not "(c) copy, reproduce, display, perform, or otherwise use the Product in a way that is not expressly authorized in this EULA" or "(d) sell, rent, lease, license, distribute, or otherwise transfer the Product".
- Derivative works — "You shall not reverse engineer, derive source code from, modify, adapt, translate, decompile, or disassemble the Product or create derivative works based on the Product, except as set forth in Article 7 with respect to User Generated Content". A rendered sprite of a game mesh is a derivative of the Product under that reading.
- Ownership — "Any reproduction or representation of these licensed materials in any way and for any reason is prohibited without Piranha Games' prior permission".
The User-Generated-Content carve-out is real, and narrower than "modding is allowed". Article 7 permits creating and distributing your own additions/mods; the separate MW5 Mod Editor EULA then scopes "Licensed Materials" (software + content) separately from the Editor (Epic-licensed) and permits Licensed Materials inside a compliant, free Mod used with the game. That does not make standalone redistribution of extracted assets — or of renders produced from them — a "mod": the carve-out is about shipping content that extends the game, under its conditions, not about publishing the game's art as an independent asset pack.
This is the same constraint that shaped the current asset story: data/ art comes from the MegaMek Data Repository (CC BY-NC-SA 4.0) and is distributed separately as downloadable content.
Working rules we apply:
- ✅ May ship: the extraction/render tooling, the
.mmuxv2 format, the runtime sprite support, documentation. - ❌ May not ship: rendered sprite atlases, or the extracted meshes, in the repo or in a downloadable pack.
⚠️ A mod is a different act: a free, game-integrated mod built with the Mod Editor may include Licensed Materials under that EULA's conditions. That does not license this repository to ship MW5-derived sprites, and it does not turn an asset pack into a mod.- ✅ Users may: run the tool against their own licensed copy and load the result through
LocalFolderResourceStreamProvider(which already exists precisely for "assets not published to GitHub"). - Alternative for a shippable art pass: run the same pipeline against commissioned or CC-licensed mech models, or trace silhouettes into original vector art.
- The pipeline enforces the first two mechanically with a closed
licenseStatus(redistributable/not-redistributable/unknown, default-deny) — see../architecture/asset-pipeline.md§8.
-
P0 first, nothing else. Render the 3 pilot chassis top-down at 84×72 (the same size as the existing art), drop them into
.mmux, and judge them against the MegaMek sprites in-game. If the silhouette doesn't read at board size, the whole pipeline is the wrong investment and no format work is justified. - If P0 passes, P1 is a pure asset job — no code — and can run in parallel with everything else.
- Only then design
.mmuxv2 andUnitAnimationResolver, and start with Idle/Walk/Run. Prone/stand-up are authored content, so schedule them last and per body plan, not per chassis. - Keep the generator under
tools/with a gitignored output folder; never point CI at it.
- Gildor's forum, MechWarrior 5: Mercenaries topic (UE 4.26, umodel 1590 works for meshes/textures/animations): https://www.gildor.org/smf/index.php/topic,7536.0.html
- Gildor's UE Viewer documentation: https://www.gildor.org/projects/umodel
- FModel: https://fmodel.app/ · wiki: https://github.com/4sval/FModel/wiki
- MW5 Mod Editor guide (asset workflow, Save To Mod, packaging): https://static.mw5mercs.com/docs/MW5Mercs_Mod_Editor_Guide_(v2.3).pdf
- Mechwarrior Foundry wiki, Modding Mechs (chassis = skeletal mesh + animations + data assets): https://mechwarrior5modding.fandom.com/wiki/Modding_Mechs
- Blender PSK/PSA extension (imports umodel/FModel
.psk/.pskx/.psa): https://extensions.blender.org/add-ons/io-scene-psk-psa/ - Knockdown/fall animations do not exist in MW5; MercTech 1.0 authored them: https://www.reddit.com/r/Mechwarrior5/comments/1tns9sz/knockdowns_merctech_10_feature_preview/
- In-repo: presto-animation-capabilities.md §3.6 (sprite sheet runtime),
src/MakaMek.Assets/Services/PackageReaders/MmuxUnitPackageReader.cs,src/MakaMek.Avalonia/MakaMek.Avalonia/Controls/UnitControl.cs