Exported sequence bounding spheres are always zero; model bounding radius is not preserved on round trip

[Talvbot]

TL;DR: Importing a stock Blizzard .m3 and re-exporting it silently degrades its bounding data in two independent ways: every per-sequence SEQS.bounding_sphere is written as all zeros (the exporter never assigns the field), and the model-level MODL.boundings.radius is dropped on import and recomputed on export as half the bounding-box diagonal, which inflates it by up to √3 on the (large) class of stock models that store a max-half-extent radius instead. Both reproduce headlessly on Blender 4.5.4 LTS at 52e9b92. A small two-commit fix is proposed in #14; alternatives are listed at the end since the right target value for the sequence spheres is a design call.

Symptom

Round-tripping Carrier_Taldarim.m3 (liberty.sc2mod, base.sc2assets/Assets/Units/Protoss/Carrier_Taldarim/; the standard Carrier.m3 carries identical bounds) through import → export, with no edits in between:

Field	Stock value	After round-trip
SEQS.bounding_sphere (all 9 sequences)	min(-2.60467, -2.51439, -2.60467) max(2.60467, 2.69495, 2.60467) radius 2.60467	min(0,0,0) max(0,0,0) radius 0
MODL.boundings min/max	as above	unchanged (correct)
MODL.boundings.radius	2.60467	4.51142

The radius inflation is exactly the half-extent → half-diagonal substitution: the model box extents are 5.20934 on all three axes, and 5.20934 × √3 / 2 = 4.51142.

Reproduction

Blender 4.5.4 LTS, addon at 52e9b92, headless:

blender --factory-startup --background --python roundtrip.py -- Carrier_Taldarim.m3 out.m3

where roundtrip.py enables the addon, runs bpy.ops.m3.import (defaults, new object), selects the resulting armature, and runs bpy.ops.m3.export (defaults). One headless-only caveat: bl_graphics_draw.py calls gpu.shader.from_builtin(...) at module import time, which raises SystemError in --background; stubbing gpu.shader.from_builtin before enabling the addon works around it (the viewport draw handler never runs headless). In a GUI session the same round trip via the UI reproduces identically.

Then compare SEQS/MODL BNDS values of input vs output with any independent M3 parser.

Root cause

1. SEQS.bounding_sphere is never assigned

bounding_sphere is declared in structures.xml#L660 — and that declaration is the only occurrence of the string in the repository. No importer, exporter, or Blender property reads or writes it (checked for dynamic access too: the export processor only touches the fields listed in io_shared.py#L32-L38).

On export, create_sequences (io_m3_export.py#L1163) assigns only the name, the io_anim_group fields, and anim_ms_start/anim_ms_end (io_m3_export.py#L1177-L1185). The record comes from content_add() (io_m3.py#L740-L743), which default-initialises every field (M3StructureData.__init__ → field.default_set, io_m3.py#L319-L326); for the embedded BNDS struct that recurses into float fields whose default is 0.0 (io_m3.py#L467-L470). So every sequence in every exported model gets an all-zero bounding sphere — unconditionally, not as a result of any user choice.

2. MODL.boundings.radius is dropped on import and re-derived differently on export

Import (create_bounding, io_m3_import.py#L1242-L1246) reads only min/max into ob.m3_bounds; BoundingProperties (m3_object_armature.py#L122-L129) has the six box faces and no radius, so the stored radius is discarded. Export then recomputes radius = (max - min).length / 2 (to_m3_bnds, io_m3_export.py#L114-L120) — half the box diagonal. Some stock models do store exactly that; a larger class stores something smaller (see below), and for those no recomputation from min/max recovers the original value.

What Blizzard's own files contain

Surveying 13 varied stock models from liberty.sc2mod (Carrier, Carrier_Taldarim, Marine, Battlecruiser, SiegeTank, Zealot, Colossus, Zergling, Ultralisk, Mutalisk, Overlord, UrsadakFemale, SnowBeast; 176 sequences total):

• No stock sequence or model has a zero bounding sphere anywhere.
• In 10 of 13 models, every sequence's BNDS is byte-identical to MODL.boundings.
• In the other 3 (Marine, UrsadakFemale, SnowBeast), sequences carry genuinely per-sequence values — animated-bounds unions that differ per animation — and MODL.boundings min/max is their union.
• The stored radius follows two distinct conventions. The 3 per-sequence models store exactly the half-diagonal — the same formula to_m3_bnds uses (Marine: box extents 3.27367 × 2.84584 × 4.05959, radius 2.97052 = half-diagonal; its per-sequence radii are likewise the half-diagonals of their own boxes). The other 10 store the maximum half-extent instead, with a box that is (near-)cubic — a sphere-first convention where the box is the sphere's bounding cube (Carrier: extents 5.20934 on all axes, radius 2.60467 = half-extent, while the half-diagonal is 4.51142). So recomputing the half-diagonal happens to reproduce the first class but inflates the second by up to √3, and no single formula from min/max covers both — only carrying the imported value through does.

Why it matters

This is round-trip data loss: a model that merely passes through the addon comes out with different (degraded) data than it went in with, which also makes binary before/after comparisons noisy for unrelated edits.

In-game impact, honestly scoped:

• The model-level radius is consumed by the engine: the CModel field Art: Visual Radius is documented as "If set to 0 or greater, this overrides the radius of the model's bounding sphere. The model becomes visible when its radius touches the edge of the Fog of War…" (SC2Mapster wiki, Data/Models/Generic) — i.e. unless a data override is set, the stored radius drives fog-of-war visibility, and a ~√3-inflated radius means models render sooner/appear inside fog. The predecessor addon likewise exposes exactly this field as its "visibility test" (below).
• What the engine does with the per-sequence spheres specifically I have not established; I did not observe a concrete in-game symptom from the zeros, and I'd rather not speculate here. The report's claim is fidelity, not observed breakage.

Prior art: m3addon

The predecessor addon (SC2Mapster/m3addon, at SC2Mapster/m3addon@5893500) handles both fields: it writes a per-sequence sphere on every export (hardcoded radius 2.0 — m3export.py:1289, m3Sequence.boundingSphere = self.createAlmostEmptyBoundingsWithRadius(2)), and round-trips the model radius through a dedicated scene property (m3import.py:782 m3_visibility_test.radius = self.model.boundings.radius → m3export.py:541 model.boundings.radius = self.scene.m3_visibility_test.radius). So models passing through m3addon are never radius-0, and the model radius survives intact.

Proposed fix

Two commits, kept separable (#14):

1. Round-trip the model radius: add a radius float property to BoundingProperties, read it in create_bounding, and write it back on export — keeping the computed half-diagonal as the fallback when the stored radius is 0, so scenes authored from scratch (and every existing user scene, where the property deserialises to 0) export byte-identically to today.
2. Populate SEQS.bounding_sphere: assign model.boundings to each sequence in create_sequences. This reproduces Blizzard's layout exactly for the 10-of-13 class of models above, and is a conservative over-approximation for models with genuinely per-sequence bounds.

Verified on Blender 4.5.4 LTS: with both changes, round-tripping the Carrier fixture yields all 9 sequence spheres and the model sphere byte-equal to stock (radius 2.60467 in and out); Marine/Battlecruiser/SiegeTank/Zergling round-trips preserve the model BNDS exactly; and a from-scratch scene (no import) exports byte-identical output before vs after the change.

Alternatives considered, in case you'd rather go another way:

• Full per-sequence round-trip — per-sequence min/max/radius properties (+ optional UI) on GroupProperties; faithful for the Marine-class models, but new surface, and from-scratch sequences still need a default.
• Compute per-sequence bounds — reuse the animated-bounds data finalize_anim_data already builds for MSEC/SDMB; most correct, but that path is conditional and heavier.
• m3addon parity (hardcoded 2.0) — only defensible as "better than 0".

Aside, noticed while reading but left untouched: SDMB animated-bounds import is a stub (m3_key_collect_bnds is pass, io_m3_import.py#L258-L259) — harmless today since export recomputes them, just related to this area.

[Talvbot]

Supplementary material, so this can be checked independently without setting anything up. Files are hosted on a scratch host of mine — grab copies rather than deep-linking; if a link is dead by the time you read this, ask here and I'll re-upload.

Base URL: https://tmp.talv.space/sbr/scratchpad/m3studio-bnds/

File	md5	What it is
Carrier_Taldarim.stock.m3	92039c760dea327a64dc5960ab2c1a67	The fixture exactly as shipped by the game (liberty.sc2mod, base.sc2assets/Assets/Units/Protoss/Carrier_Taldarim/)
Carrier_Taldarim.roundtrip-pre.m3	72e00143d2da9cce21f3636aa39449c6	That file imported → exported at 52e9b92 — shows the defect: all SEQS spheres zero, MODL radius 4.51142
Carrier_Taldarim.roundtrip-post.m3	e90552c7b043f8396ede9649a8c48d29	Same round trip with #14 applied (sc2-arcade-watcher/m3studio@e565149) — SEQS and MODL spheres match stock
fromscratch-pre.m3 / fromscratch-post.m3	63722955511343f7c8587e4772a405d0 (both)	A from-scratch scene (armature + one animation group, no import) exported before/after #14 — byte-identical, demonstrating the radius-0 fallback keeps existing behaviour
roundtrip.py / fromscratch.py	—	The headless harnesses used for everything above (inlined below too)
bnds-survey.txt	—	Full output of the 13-model survey backing the numbers in the issue (inlined below)

To run the harnesses: put (or symlink) the addon checkout at <some-dir>/addons/m3studio, then

BLENDER_USER_SCRIPTS=<some-dir> blender --factory-startup --background --python roundtrip.py -- <input.m3> <output.m3>
BLENDER_USER_SCRIPTS=<some-dir> blender --factory-startup --background --python fromscratch.py -- <output.m3>

The BNDS values quoted in the issue and in bnds-survey.txt were read with an M3 parser that is independent of m3studio (its own structure definitions, not this repo's structures.xml), so the 28-byte min/max/radius layout is cross-confirmed rather than assumed.

One note for anyone diffing the two round-trip outputs byte-for-byte: the exporter embeds the output filename in the file, so exports written under different names shift all subsequent offsets — compare parsed values (or export under identical basenames), not raw offsets. The fromscratch-pre/post pair above was produced with identical basenames for exactly that reason.

roundtrip.py

# Headless m3studio round-trip harness.
# Usage: BLENDER_USER_SCRIPTS=<scripts-dir-with-addons/m3studio> \
#   blender --factory-startup --background --python roundtrip.py -- <input.m3> <output.m3>
import sys

import addon_utils
import bpy
import gpu

argv = sys.argv[sys.argv.index('--') + 1:]
src, dst = argv

# bl_graphics_draw builds a GPU shader at module import time, which raises
# SystemError in --background; stub it out (the viewport draw handler never
# runs headless, so the dummy is never used).
if bpy.app.background:
    class _DummyShader:
        def __getattr__(self, name):
            return lambda *a, **k: None
    gpu.shader.from_builtin = lambda *a, **k: _DummyShader()

loaded = addon_utils.enable('m3studio', default_set=False, persistent=False)
if loaded is None:
    print('RT_FAIL: addon did not enable (see traceback above)')
    sys.exit(2)
print(f'RT_OK: addon enabled, blender {bpy.app.version_string}')

# clean slate: remove default scene objects so only the import result remains
for ob in list(bpy.data.objects):
    bpy.data.objects.remove(ob, do_unlink=True)

op_import = getattr(bpy.ops.m3, 'import')
res = op_import(filepath=src)
print(f'RT_IMPORT: {res}')

armatures = [ob for ob in bpy.data.objects if ob.type == 'ARMATURE']
if len(armatures) != 1:
    print(f'RT_FAIL: expected 1 armature after import, got {len(armatures)}')
    sys.exit(2)
ob = armatures[0]
bpy.context.view_layer.objects.active = ob
ob.select_set(True)
print(f'RT_ARMATURE: {ob.name} anim_groups={len(ob.m3_animation_groups)} '
      f'bounds l={ob.m3_bounds.left} r={ob.m3_bounds.right} '
      f'b={ob.m3_bounds.back} f={ob.m3_bounds.front} '
      f'bot={ob.m3_bounds.bottom} top={ob.m3_bounds.top}')

res = bpy.ops.m3.export(filepath=dst)
print(f'RT_EXPORT: {res}')
print('RT_DONE')

fromscratch.py

# From-scratch export regression harness (no import): armature + one anim
# group with default m3_bounds, exported to m3. Compare output across addon
# versions — the radius fallback must keep pre-fix behaviour for such scenes.
# Usage: BLENDER_USER_SCRIPTS=<scripts-dir> \
#   blender --factory-startup --background --python fromscratch.py -- <output.m3>
import sys

import addon_utils
import bpy
import gpu

argv = sys.argv[sys.argv.index('--') + 1:]
dst = argv[0]

if bpy.app.background:
    class _DummyShader:
        def __getattr__(self, name):
            return lambda *a, **k: None
    gpu.shader.from_builtin = lambda *a, **k: _DummyShader()

loaded = addon_utils.enable('m3studio', default_set=False, persistent=False)
if loaded is None:
    print('FS_FAIL: addon did not enable')
    sys.exit(2)

for ob in list(bpy.data.objects):
    bpy.data.objects.remove(ob, do_unlink=True)

bpy.ops.object.armature_add()
ob = bpy.context.view_layer.objects.active
assert ob and ob.type == 'ARMATURE'

from m3studio import shared  # noqa: E402
grp = shared.m3_item_add(ob.m3_animation_groups, 'Stand')
grp.frame_start = 0
grp.frame_end = 30

print(f'FS_BOUNDS: l={ob.m3_bounds.left} r={ob.m3_bounds.right} radius={getattr(ob.m3_bounds, "radius", None)}')
res = bpy.ops.m3.export(filepath=dst)
print(f'FS_EXPORT: {res}')
print('FS_DONE')

bnds-survey.txt — 13 stock models, 176 sequences

Protoss/Carrier_Taldarim/Carrier_Taldarim.m3  SEQSv2  nSeq=9
  MODL.boundings: min(-2.60467,-2.514388,-2.60467) max(2.60467,2.694952,2.60467) r=2.60467
  seq radii distinct: [2.60467]  allEqModelRadius=true  boxEqModel=9/9  anyZero=false

Terran/Marine/Marine.m3  SEQSv1  nSeq=24
  MODL.boundings: min(-1.860982,-1.543236,-0.635442) max(1.412684,1.302605,3.42415) r=2.970521
  seq radii distinct: [1.553998, 1.78402, 1.525278, 1.125773, 1.536682, 1.624375, 1.550433, 1.185117, 1.54751, 1.623925, 1.570589, 1.26832, 1.996965, 2.147059, 2.383025, 2.237153, 2.01066, 2.044275, 1.103333, 1.10559, 1.526897, 2.296351, 1.514701, 1.095882]  allEqModelRadius=false  boxEqModel=0/24  anyZero=false
    "Walk": min(-0.397655,-1.091082,-0.442024) max(1.112876,0.871533,1.435763) r=1.553998
    "Fidget": min(-0.548835,-1.251283,-0.221668) max(1.412684,1.146107,1.549172) r=1.78402
    "Stand": min(-0.559372,-1.253729,-0.208611) max(1.157483,0.675677,1.414871) r=1.525278
    "Attack": min(-0.679773,-0.969804,-0.075498) max(0.606567,0.415532,1.147465) r=1.125773
    "Stand 01": min(-0.529712,-1.237036,-0.21449) max(1.154383,0.685319,1.492535) r=1.536682
    "Stand Left": min(-0.711926,-1.283088,-0.239688) max(1.176588,0.729941,1.473672) r=1.624375
    "Stand Right": min(-0.561622,-1.239473,-0.225741) max(1.161952,0.743537,1.421177) r=1.550433
    "Attack 01": min(-0.686843,-1.038182,-0.074256) max(0.592597,0.415437,1.292505) r=1.185117
    "Walk Slow": min(-0.498172,-1.23049,-0.243989) max(1.162411,0.711439,1.502588) r=1.54751
    "Cover": min(-0.7756,-1.304539,-0.180382) max(1.135796,0.521776,1.706326) r=1.623925
    "Attack Superior": min(-0.808772,-1.1172,-0.102167) max(0.789089,0.769956,1.834964) r=1.570589
    "Attack Inferior": min(-0.769844,-1.056605,-0.198023) max(0.572309,0.464472,1.324964) r=1.26832
    "Stand Dance": min(-1.204887,-1.299004,-0.207325) max(1.162685,1.008243,2.033814) r=1.996965
    "Stand Dance 01": min(-1.336905,-1.300582,-0.16438) max(1.31309,1.302605,1.989777) r=2.147059
    "Stand Dance 02": min(-1.563398,-1.543236,-0.635442) max(1.244852,1.196959,2.070163) r=2.383025
    "Stand Dance 03": min(-1.860982,-1.254966,-0.36962) max(1.264825,1.232313,1.645863) r=2.237153
    "Stand Victory": min(-1.013931,-1.411859,-0.390029) max(1.190675,0.826411,2.120126) r=2.01066
    "Stand Victory 01": min(-1.089642,-1.430777,-0.183656) max(1.139571,1.227103,1.980256) r=2.044275
    "Stand Right Ready": min(-0.665687,-0.948986,-0.036495) max(0.584365,0.423537,1.15637) r=1.103333
    "Stand Left Ready": min(-0.665313,-0.954356,-0.04947) max(0.583923,0.423454,1.146508) r=1.10559
    "Spell": min(-0.564044,-1.246777,-0.201168) max(1.152797,0.683644,1.427202) r=1.526897
    "Unload End": min(-0.539147,-1.304179,-0.3322) max(1.157044,0.722069,3.42415) r=2.296351
    "Unload": min(-0.525464,-0.903502,1.491879) max(1.14932,0.720908,3.42415) r=1.514701
    "Stand Ready": min(-0.663663,-0.953127,-0.066957) max(0.563538,0.415504,1.126634) r=1.095882

Terran/Battlecruiser/Battlecruiser.m3  SEQSv1  nSeq=12
  MODL.boundings: min(-2.337904,-2.178133,-2.326937) max(2.337903,2.497675,2.34887) r=2.337903
  seq radii distinct: [2.337903]  allEqModelRadius=true  boxEqModel=12/12  anyZero=false

Terran/SiegeTank/SiegeTank.m3  SEQSv1  nSeq=2
  MODL.boundings: min(-1.861641,-1.882105,-1.16868) max(1.86164,1.825293,2.586572) r=1.877626
  seq radii distinct: [1.877626]  allEqModelRadius=true  boxEqModel=2/2  anyZero=false

Protoss/Zealot/Zealot.m3  SEQSv1  nSeq=20
  MODL.boundings: min(-0.771242,-0.793948,-0.231491) max(0.815681,0.792975,1.355432) r=0.793462
  seq radii distinct: [0.793462]  allEqModelRadius=true  boxEqModel=20/20  anyZero=false

Protoss/Carrier/Carrier.m3  SEQSv1  nSeq=9
  MODL.boundings: min(-2.60467,-2.514388,-2.60467) max(2.60467,2.694952,2.60467) r=2.60467
  seq radii distinct: [2.60467]  allEqModelRadius=true  boxEqModel=9/9  anyZero=false

Protoss/Colossus/Colossus.m3  SEQSv1  nSeq=26
  MODL.boundings: min(-3.462959,-3.268638,-0.426832) max(3.462959,3.657279,6.499085) r=3.462959
  seq radii distinct: [3.462959]  allEqModelRadius=true  boxEqModel=26/26  anyZero=false

Zerg/Zergling/Zergling.m3  SEQSv1  nSeq=16
  MODL.boundings: min(-1.029533,-1.155501,-0.700484) max(1.029533,0.903564,1.358581) r=1.029533
  seq radii distinct: [1.029533]  allEqModelRadius=true  boxEqModel=16/16  anyZero=false

Zerg/Ultralisk/Ultralisk.m3  SEQSv1  nSeq=23
  MODL.boundings: min(-2.792943,-3.661338,-1.432903) max(2.92089,2.052495,4.28093) r=2.856916
  seq radii distinct: [2.856916]  allEqModelRadius=true  boxEqModel=23/23  anyZero=false

Zerg/Mutalisk/Mutalisk.m3  SEQSv1  nSeq=12
  MODL.boundings: min(-1.828813,-1.619072,-1.257236) max(1.828813,2.038554,2.40039) r=1.828813
  seq radii distinct: [1.828813]  allEqModelRadius=true  boxEqModel=12/12  anyZero=false

Zerg/Overlord/Overlord.m3  SEQSv1  nSeq=5
  MODL.boundings: min(-1.445861,-1.501821,-1.370683) max(1.510086,1.454126,1.585263) r=1.477973
  seq radii distinct: [1.477973]  allEqModelRadius=true  boxEqModel=5/5  anyZero=false

Critters/UrsadakFemale/UrsadakFemale.m3  SEQSv1  nSeq=5
  MODL.boundings: min(-0.830121,-1.529723,-0.087929) max(0.864202,1.643489,2.061771) r=2.095305
  seq radii distinct: [1.90988, 1.943582, 1.902931, 2.088474, 1.901908]  allEqModelRadius=false  boxEqModel=0/5  anyZero=false
    "Stand": min(-0.830121,-1.445293,-0.004302) max(0.830121,1.456125,1.843921) r=1.90988
    "Walk": min(-0.792918,-1.45334,-0.078722) max(0.864202,1.537226,1.770739) r=1.943582
    "Stand 01": min(-0.830121,-1.427329,-0.004302) max(0.830121,1.45577,1.843919) r=1.902931
    "Fidget": min(-0.830121,-1.529723,-0.087929) max(0.830121,1.643489,2.061771) r=2.088474
    "Stand 02": min(-0.830121,-1.444443,-0.004302) max(0.830121,1.437951,1.840805) r=1.901908

Neutral/SnowBeast/SnowBeast.m3  SEQSv2  nSeq=13
  MODL.boundings: min(-1.756002,-2.769073,-0.718449) max(2.882499,2.92776,4.540112) r=4.517246
  seq radii distinct: [2.495095, 2.248723, 2.519782, 2.639526, 2.940518, 3.412686, 3.730091, 2.891114, 2.483541, 2.844646, 3.200547, 3.205466, 2.808715]  allEqModelRadius=false  boxEqModel=0/13  anyZero=false
    "Stand": min(-1.254582,-1.546314,-0.099472) max(1.46226,1.814213,2.396049) r=2.495095
    "Stand 01": min(-1.197957,-1.285246,-0.059202) max(1.402389,1.627223,2.173003) r=2.248723
    "Walk Spell": min(-1.025744,-1.748352,-0.12985) max(1.079381,2.028587,2.45866) r=2.519782
    "Walk": min(-1.372702,-1.652178,-0.07672) max(1.501115,1.956904,2.489227) r=2.639526
    "Attack": min(-1.368603,-2.219455,-0.293519) max(1.385779,1.65253,3.171692) r=2.940518
    "Attack 01": min(-1.19607,-2.769073,-0.318538) max(2.882499,1.989182,2.385161) r=3.412686
    "Attack 02": min(-1.547825,-2.56414,-0.429217) max(1.677552,1.969846,4.540112) r=3.730091
    "Jump Start": min(-1.461406,-1.873884,-0.18389) max(1.619308,2.081569,2.69669) r=2.891114
    "Jump": min(-1.328068,-1.893069,-0.091877) max(1.638028,1.175785,2.449053) r=2.483541
    "Jump End": min(-1.393435,-2.089107,-0.342174) max(1.496663,1.969478,2.404325) r=2.844646
    "Death 02": min(-1.468533,-1.247678,-0.718449) max(1.963755,2.92776,2.710706) r=3.200547
    "Death 03": min(-1.756002,-2.220698,-0.458389) max(1.707576,2.274343,2.524611) r=3.205466
    "Stand Angry": min(-1.50201,-1.703169,-0.071464) max(1.658149,1.985162,2.75079) r=2.808715

=== TOTALS: models=13 sequences=176 radius==model: 134 box==model: 134 anyZeroSeen=false

[Talv]

• The 1st one from the left is pre-export
• The two at the right after export.

(This is before the fix ofc)

[Solstice245]

My thoughts as to the "right way" to go about fixing this are that getting correct bounding boxes should not require any manual input from users and it should not make any assumptions about the model data. Roundtripping the MODL bound radius value in all cases from the imported model is making assumptions about the model in its exported form which may not be accurate. Maybe better than how its currently handled in some circumstances, but still not ideal.

From my standpoint there are essentially 3 classes of bounding boxes that a user should be selecting from rather than the current situation where they have manual access to each component of the bounding box.

1. Min/max bounding box values derived from the model, with a radius that reaches to the extent of the furthest edge of the box.
2. Min/max bounding box values derived from the model, with a radius that encapsulates the entire box, notably the corners.
3. Bounding box specially suited to beam attack models. The center of the bounding box is biased towards the Attacher bone, and an arbitrary radius is given by the user according to the use case of beam model. The calculated min/max values of the bounding box are encapsulated by the radius, as in option 2.

Only in the 3rd case should the original radius necessarily be retained exactly. The main challenge to this approach I think is detecting which of these options best matches an imported model. Distinguishing between options 1 and 2 is easy enough logically, but detecting option 3 will likely involve holistically analyzing the overall model. The presence of the "Attacher" bone could be leveraged as a quick filter though.

[Talvbot]

Generated by an LLM (Claude) with access to: a purpose-written M3 parser (independent of this repo's structures.xml); 1772 .m3 files from the public dist.sc2arcade.com asset mirror; an IDA Pro disassembly of the retail SC2 client (build 5.0.15.96921); Blizzard's shipped catalog XML (ModelData.xml across 79 mods) and EditorCatalogStrings.txt; and the sources of this repo at 52e9b92, PR #14, and m3addon. Every number below is reproducible from the linked gist — please treat the claims as checkable rather than authoritative, and the disassembly caveat in the engine section is stated explicitly.

TL;DR — I surveyed 1772 real .m3 files to answer your detection question. Four findings:

1. You don't need to detect "beam" to route class 3. Compare the stored radius against the box: r/hdiag > 10 ⇒ arbitrary radius on an almost-empty box; else r ≈ hmax ⇒ class 1, r ≈ hdiag ⇒ class 2; anything left ⇒ arbitrary radius on a real box. That assigns all 1772 models with no residue, and the tolerance isn't a tuning knob.
2. Don't test the box for zero. m3addon's "almost empty" bounds are extent 9.54e-07, not 0, and two models use 0.005 — so an epsilon test on the box either misses cases or eats real geometry. The ratio test has a ~400× margin.
3. Class 3 is an effects phenomenon, not a beam one — 36% of FX models vs 1.4% of units and 19% of beam-named files. A beam-shaped detector would miss most of it.
4. The Attacher bone is 97.6% precise but only 67% recall. Great as corroboration, wrong as the primary gate. Your "box is biased toward the Attacher" premise holds as a bias (bone inside the box 96%) but is looser than it looks at small sample — median 11% of box diagonal, not ~1%.

On severity, to be straight about it: the round-trip bug itself is minor. The √3 error inflates the cull sphere, which is the safe direction — models un-cull early, costing a little performance; the damaging direction would be an undersized radius, giving pop-in and stalled emitters. And the zero SEQS spheres turn out to be inert, since they aren't the cull source. What's actually worth your time is (a) round-trip integrity as a property — passthrough shouldn't alter data, or diffs stop being trustworthy — and (b) point 2 above: a naive implementation of the three-class plan would mangle ~36% of effect models, because their "empty" box isn't empty.

Sections below have the numbers, plus where the engine actually consumes the radius and how this composes with #14.

To put numbers behind the detection question, I parsed 1772 real .m3 files with an M3 reader independent of this repo's structures.xml, and checked the retail client and the shipped catalogs alongside. Three populations, deliberately including the awkward one: a seeded random sample of 1000 models (mostly units/doodads), the 47 *beam*-named models, and 762 effect/FX models (impacts, missiles, deaths, ribbons) — the FX set matters because it's where the hard cases actually live. Findings below; they support your three-class plan, and I think they simplify the detector and substantially reframe class 3.

Parser, per-model CSVs and the sample list are here so none of this has to be taken on trust: https://gist.github.com/Talvbot/476c8717bcef458dca0f375fd85231cb

The "Attacher" bone: high precision, mediocre recall — and you may not need it

Your instinct on the Attacher bone is right, and it survives the adversarial test. Across all 1772 models, 164 carry an M3 bone named Attacher — and 160 of those are beam-named (97.6% precision). The false-positive rate is 4 in 1533 non-beam-named models (0.26%), and the four are amonshard_aoeradius_impact, bioplasmamissileimpact, tripwire_effect, xelnagashielddomeimpact — all beam-adjacent projected effects rather than ordinary models. That precision holds inside the FX set specifically (149 carriers, 145 beam-named), which is the population most likely to fool it. Three caveats from the data:

• Key on the M3 bone, not the Ref_Attacher/KeyAttacher attach-point in the catalogs — those are generic (they sit alongside Ref_Back/Ref_Center and are used by ordinary hosted/segmented models), so an attach-point check would over-match.
• Recall is the weak side, not precision. Only 160 of 239 beam-named models (67%) have the bone. In the 47-file beam set, 11 files carry neither a ribbon nor an Attacher — they're PAR_-only impact/launch/charge effects or a static prop (beam rifle); of the 36 that are structurally beam-like, Attacher catches 33 (92%) and the 3 misses all carry a RIB_ section instead.
• RIB_ is the weaker signal — it appears in 145 of 1533 non-beam-named models (9.5%), and 21% of non-beam FX (trails, capes, death ribbons), versus 0.26% for the Attacher bone. Use Attacher as the quick filter; RIB_ only as a recall top-up if you want it.

I also tested your stated premise that the box is "biased towards the Attacher bone", using the IREF inverse-bind matrices (row-major, translation in the last row). Over the 148 beam-named models that have an Attacher bone and a real box, the box center sits a median 11% of the box diagonal from that bone, the bone is inside the box in 142 (96%), and 88% are within 25%. So the premise is sound as a bias — but it's a loose one, not a centering: it was much tighter (median 1%) on the 47-file beam set alone, and widens over the full population. Worth knowing if you intend to place the box from the Attacher rather than merely detect with it.

For classes 1 vs 2, key off the stored radius — and class 3 is self-identifying

You don't actually need to detect "beam" first to route class 3. Compute hmax = max axis half-extent and hdiag = |max-min|/2 from the box, then look at the stored radius:

1. r / hdiag > 10 → class 3a: the box is m3addon's "almost empty" bounds and r is arbitrary. Retain both verbatim.
2. r ≈ hmax → class 1 (half-extent)
3. r ≈ hdiag → class 2 (half-diagonal)
4. anything left → class 3b: arbitrary radius on a real box. Retain r, regenerate the box.

That assigns all 1772 models, no residue:

	class 1 (hmax)	class 2 (hdiag)	class 3a (almost-empty)	class 3b (arbitrary)
random (1000)	108	876	14	2
beam-named (47)	17	21	9	0
FX / effects (762)	140	346	276	0
all unique (1772)	261 (14.7%)	1218 (68.7%)	291 (16.4%)	2 (0.1%)

Three things worth pulling out of that table:

The "empty" box is not empty, so don't test for zero. m3addon's createAlmostEmptyBoundingsWithRadius(2) writes a box with extent 9.54e-07, not 0 — only a handful of files are exactly zero. And two models (disruptor_purificationnova_impact, disruptor_zeratul_coop_purificationnova_impact) carry extent 0.005 with r=2.0, so a max_extent < 1e-6 test misses them while a < 1e-2 test would start eating real geometry. The ratio test sidesteps the threshold problem entirely, and there's a wide gap to hide in: across all 1772 models the only r/hdiag values between 1.05 and 1000 are 1.39 (blitzer.m3) and 566 (those two disruptor impacts). Every single class-3a model has r exactly 2.0.

Class 3 is an effects phenomenon, not a beam one. It's 36% of FX models versus 1.4% of random units — and only 19% of beam-named files. So framing class 3 as "the beam case" undersells it: impacts, deaths and ribbon effects are the bulk of it, and any beam-shaped detector would miss most of them. Detecting from the bounds gets them all for free.

Classes 1 vs 2 are cleanly separable, and tolerance is not a tuning knob. Excluding class 3, hmax/hdiag matching gives an identical partition anywhere from 1e-4 to 1e-3. At a loose 1e-2, 23 models match both, but those are needle boxes (two smaller extents ≤10% of the longest) where the formulas differ by under 1% anyway, so either label reproduces the file. The overall split is 82/18 in favour of half-diagonal, and it varies a lot by population — random units 89/11, FX 71/29 — so don't hard-code a prior.

One consequence worth stating outright, since it departs from "beams → class 3": under this rule most beams route to classes 1/2 — 38 of the 47 beam-named files match a formula (21 hdiag, 17 hmax), and only the 9 almost-empty ones are class 3. I'd argue that's correct rather than a detector miss: a radius that matches a standard formula wasn't arbitrary to begin with, recomputing it reproduces the stored value on a pure round trip, and it then follows the user's geometry edits — exact retention is only needed where the value is genuinely underivable.

The upshot for your objection to round-tripping: at import, measure which case applies and store it as a per-model mode. On export, classes 1/2 recompute from the current box (no stale assumption carried through edits); class 3b keeps the radius but regenerates the box; class 3a keeps both, since regenerating an almost-empty box from geometry would diverge from what those 291 files ship. That derives from the model for the common cases and keeps exact fidelity only where it's genuinely required. Concretely, this composes with #14 as it stands: the radius property it adds is the storage, plus one enum on BoundingProperties (half-extent / half-diagonal / arbitrary / almost-empty) that create_bounding sets from the comparison above — export then switches on the mode instead of the current if radius: retention.

On the "min/max derived from the model" half of your plan: the machinery already exists in the exporter — the MSEC path computes per-frame pose-space boxes from the bones (bounding_vectors_from_bones over bone_bound_vecs), and in the stock data the static MODL box is exactly the union of the per-sequence boxes (identical in 10 of the 13 models surveyed in the issue, the union in the other 3). So the static box can be derived by unioning what that path already computes, rather than writing new geometry code.

(One wording note: the stock "class 1" radius is the furthest face/axis half-extent — max((max-min)/2) — not the furthest edge; an edge distance would be √2× larger. The 10 cubic-box stock units, e.g. carrier_taldarim r=2.60467, are all this convention.)

Does the beam's arbitrary radius even reach the engine? Sometimes — so class 3 still needs it

I wondered whether the RadiusLoose ("Visual Radius") data override made the baked beam radius moot. In SC2GameData it's set on 23 of the 57 beam-named CModels in liberty.sc2mod's ModelData.xml — 23 of 49 once the *Impact/*Rocks/*Debris/*Cage variants are excluded, so about half of actual beam models. Against a baseline of 197/8382 (2.35%) of all CModels in liberty.sc2mod (and 481/32795 ≈ 1.5% across all 109 ModelData.xml files in the game data), that's roughly a 20× enrichment — beams really are the population that tends to carry the override. It's hand-set per model, not inherited: none of the shared FX templates in core.sc2mod (FX, MissileFX, PersistentSpellFX, ImpactFX, OneShotSpellFX, RaceMissileFX, …) sets it. But the other half sets no override, so for those the baked M3 radius is what the engine uses. "Beams override it anyway" is therefore only half-true, and class-3 exact retention is still the right call — you can't assume a data override exists.

liberty.sc2mod beam CModels — with vs without RadiusLoose

Sets RadiusLoose (23, all 1.0): ArchonAttackBeam, ArchonAttackBeamLow, BypassArmorDroneAttackBeam, CarrierBeamAttackBeam, ColossusAttackBeam, ColossusAttackBeam_Upgrade, DisruptorBeam, GravitonBeam, HellionAttackBeam, HellionAttackBeamLow, HellionUpgradeAttackBeam, MedivacHealBeam, MedivacHealBeamUpgrade, MothershipAttackBeam, MothershipAttackBeamLow, RavenRepairDroneHealBeam, RipFieldAttackBeam, SentryAttackBeam, SentryAttackBeamLow, ThermalBeam, VoidRayAttackBeam, VoidRayAttackBeamLow, VoidRayCenterBeam

Does not (34): ChannelSnipeBeam, ChannelSnipeTrackingBeam, ColossusAttackBeamImpact, ColossusAttackBeamImpact_Upgrade, Cybros_Beam, CycloneTargetingBeam, CycloneUpgradeBeam, DOM_CeilingDebris_Beams, ForceAwayBeam, GhostSnipeAttackBeam, GhostSnipeDoTAttackBeam, GrappleBeam, GravitonBeamImpact, GravitonBeamRocks, HunterSeekerTrackingBeam, InterceptorAttackBeam, InterceptorAttackBeam2, LiberatorAttackBeam, MothershipCoreEnergizeBeam, OracleStasisTrapBuildBeam, PenetratingShotBeam, PointDefenseBeamImpact, PointDefenseDroneAttackBeam, PointDefenseDroneAttackBeamImpact, ProbeAttackBeam, Sentry_Purifier_EnergyBeam, ShieldBatteryRechargeChanneledBeam, SiegeTankLoadBeam, SiphonAttackBeam, SlaynElementalBeamCage, SOA_Beam, TargetingDroneAttackBeam, WarHoundBeam, WidowMineTargetingBeam

(One inheritance wrinkle: Sentry_Purifier_EnergyBeam sets no value of its own but is parented off SentryAttackBeam, which does — so it inherits one. The shared FX templates still set nothing.)

Why the class-1 √3 error matters at all (engine grounding)

From the retail client plus Blizzard's own editor docs: the model BNDS radius becomes the view-frustum cull sphere (a static sphere cached when the model is attached), and — this part I verified in the disassembly — a frustum-culled model skips its entire per-frame update, not just its draw (build 5.0.15.96921, imagebase 0x140000000: the RenderSync per-listener updater at 0x14122DA40 sets a visibility bit from the frustum test at 0x1401A01A0, then test dl,1 ; jz gates all the update/tick/emitter calls). That's why a wrong radius has visible consequences: emitters on a culled model stop emitting. RadiusLoose overrides that radius when non-zero, else the file's BNDS radius is used — this is Blizzard's editor-string description of the field (EDSTR_FIELDHINT_CModel_RadiusLoose: "If this value is not 0, it will override data that is normally queried from the model file… the model will only update its state when this sphere is within the camera's FOV… typically needs to be larger than the actual radius so the model will not pop in the fog of war"). I confirmed both Radius and RadiusLoose are parsed into CModel, but I did not extract the exact RadiusLoose ? : file_radius branch, so that one step rests on the editor docs, not the disassembly. Net effect of the √3 inflation: an oversized cull sphere, so the model un-culls early — resumes emitting / leaves fog sooner and simulates over a wider camera range. Conservative against pop-in, wrong for performance, not what shipped.

Two smaller things

• collision_boundings is a non-issue. The MODL struct has a second inline BNDS (collision_boundings, right after boundings — it's in this repo's structures.xml too), and it is all-zero in 1771 of the 1772 models I parsed, across every MODL version present (23, 24, 25, 26, 28, 29). The single exception (cf_apcupgraded.m3) doesn't hold a box either — its bytes decode to two denormal floats (~6.5e-43, the integer 462 reinterpreted), i.e. stray data rather than geometry. Writing zero is correct; no round-trip concern there.
• Per-sequence SEQS.bounding_sphere isn't the cull sphere. The engine culls each model against a single static bounding sphere cached when the model is attached (derived from MODL.boundings); I traced the per-frame cull path and it uses that static sphere — not the per-sequence SEQS sphere. (Animated MSEC/SDMB bounds are computed only after a model passes the cull, for update/deformation, so they don't feed the cull decision either.) The loader also only validates each SEQS record's name and bone-anim-set references. So the zero SEQS spheres have no effect on culling, and Preserve model bounding radius and write sequence bounding spheres on export #14's "copy MODL boundings into each sequence" is a safe, conservative choice that also byte-matches the sphere-cube unit models.