Halo Asset Blender Development Toolset — TzeentchNet Fork

A fork of General_101/Halo-Asset-Blender-Development-Toolset, the seminal Blender add-on for authoring assets across the Halo title family. All of the upstream import/export surface (JMS, JMA, ASS, QUA, JMI, WRL, H1/H2 tag imports, cinematic cameras) is preserved — please support General_101 on Ko-Fi if this work is useful to you.

This README documents what's new in the fork. For the full baseline feature matrix, upstream credits, and per-game support table, see the upstream README.

Why this fork exists

The fork focuses on four themes the upstream add-on does not cover (or treats as partial):

1. Halo 3 scenario import end-to-end — upstream lists Halo 3 structure_bsp / scenario tag import as "No Support". This fork ships a working H3 .scenario importer, plus every tag adapter the scenario walker needs.
2. Blender 5.0 compatibility — silent regressions on Blender 5 (all-black materials, icon changes, auto-smooth API removal) are patched.
3. Headless testing & regression coverage — a subprocess-based Blender harness plus a pytest suite exercises real shipping H3EK scenarios on every change.
4. Reliability over silence — silent decode failures in H3 geometry and tag-layout parsing now surface as warnings instead of producing invisible meshes.

Highlights over upstream

Halo 3 .scenario import (new)

• New H3 tag adapters under io_scene_halo/file_tag/h3/: file_scenario, file_scenario_structure_bsp, file_scenario_structure_lighting_info (stli), file_scenario_lightmap_bsp_data (Lbsp), plus object palette parsers for scenery, bipeds, vehicles, machines, controls, sound scenery, equipment, weapons, and crates.
• BSP cluster + instanced-geometry decode (compressed vertices, strip indices, winding fix-up by axis_flips bucket), cluster portals, decal palette with tag-driven world radius, Tier 1 blocks (player starting profiles, editor folders, cubemaps, airprobes, soft ceilings/surfaces, effect scenery, decorators, flocks, recorded animations), Tier 2 MP sandbox blocks (mv * equipment/weapons/vehicles/scenery/goals/spawners/teleporters, spawn data, zone sets, scenario cluster data), and opt-in HSC script import.
• Real-scenario verified: guardian (MP) and 130_epilogue (campaign) land in Blender with thousands of objects, per-BSP collections, proper decal orientation, and object hierarchies from the H3 hlmt → render_model pipeline.

Halo 3 shader & material pipeline (new)

• Native H3 shader-tag parameter resolution (shad, stem, rmfl, rmhg, rmtr, rmcs, rmcu, rmd , rmdc, rmfo, rmsk, rmw , rmwt) bypassing upstream's H2-only shader codepath.
• tool.exe export-bitmap-tga routing with result caching, shader-collection prefix map driven by levels\shader_collections.txt.
• Halogram materials detected and wired through the Principled BSDF Emission socket so holograms read as self-lit.

Halo 1 / 2 / 3 reflection cube-map rendering (new)

• H1: shader_environment and shader_model reflection cube-map bitmaps are now unfolded into an equirectangular panorama at import in io_scene_halo/global_functions/shader_generation/shader_helper.py. All three Halo color-plate cube layouts are supported (4×3 horizontal cross, 6×1 horizontal strip, 1×6 vertical strip), projected with standard DirectX cube-map math and cached as <bitmap>_equirect in bpy.data.images. The ShaderNodeTexEnvironment feeding the reflection input is now driven by ShaderNodeTexCoord.Reflection in shader_environment.py (matching shader_model.py), so the cube map samples as a real reflection vector instead of a flat lookup. Upstream produced a smeared/averaged tint because the raw cross plate was interpreted as an equirectangular image with no reflection direction.
• H2: halo_2_shader.py now detects bitmap parameters whose backing .bitmap tag has bitmap_type == cube_map and routes them through the same equirectangular unfold + TexEnvironment + reflection-vector path. When the shader's env_tint_color / env_glancing_tint_color (+ env_brightness / env_glancing_brightness) parameters are present the sample is modulated by the existing Reflection Tint Logic fresnel group, matching H1's perpendicular/parallel tint shape. Non-cube bitmaps keep their existing UV-scaled path unchanged.
• H3 (opt-in): a new add-on preference h3_import_reflection_cubemaps drives shader_processing.py to resolve each material's environment_map / env_map / reflection_map / reflection_cube_map parameter via io_scene_halo/file_tag/h3/container.py, export all six cube faces through tool.exe export-bitmap-tga, stitch them into an equirect image (Pillow + numpy), and wire the sample into Principled BSDF Base Color via an additive mix after the existing base-map chain. Fresnel tint uses env_tint_color / env_glancing_tint_color with env_brightness / env_glancing_brightness. Materials whose .bitmap tag isn't a cube-map type, or whose TGA export returns fewer than six faces, silently skip reflection wiring with a print log.
• H3 caveats:
  • Off by default because it is slow. tool.exe export-bitmap-tga is invoked once per environment-mapped material and writes six DXT-decoded TGAs per cube map. On a full scenario import with many reflective shaders the first run can add tens of seconds to minutes; the _run_tool_export_cached wrapper skips re-export on subsequent imports when the source .bitmap tag hasn't changed, so steady-state cost is low.
  • Real-time Blender light probes are not used. The empties spawned by generate_h3_cubemaps at cubemap position in the scenario remain decorative — they are not converted to Blender LIGHT_PROBE_CUBE objects and Eevee/Cycles do not sample them. Every H3 reflection is instead a per-material baked equirect of the shader's tag-referenced cube bitmap, which gives a consistent look across Eevee and Cycles but loses the game's per-cluster probe placement. Converting those empties to real light probes (Eevee Next only) is tracked in backlog.md as a future pass.

Halo 3 lightmap integration (opt-in, new)

• Lbsp (.scenario_lightmap_bsp_data) parsing: lightprobe texture + dominant-light-intensity bitmap export via tool.exe, plus per-cluster and per-instance atlas-slice indices.
• UVMap_Lightmap UV layer built on cluster and instanced-geometry meshes (1:1 by index when vertex counts match, otherwise KDTree nearest-neighbor remap to handle lightmap-unwrap seam splits).
• Per-cluster material variants splicing a ShaderNodeMixRGB(MULTIPLY) between the base color and the Principled BSDF, keyed on (bsp, slice) so clusters sharing a slice reuse one variant.
• Gated behind a h3_import_lightmap_textures add-on preference; default is off because tool.exe DXT5-array export is slow.

Halo 3 generic lights (new)

• stli (.scenario_structure_lighting_info) parsing drives Blender Point / Spot / Sun lights with correct axis remap (Halo +X → Blender −Z, Halo +Z → Blender +Y, Halo +Y → Blender +X) and world-scale parity with the sbsp pipeline.
• Spot cone angle and blend derived from falloff / hotspot; per-BSP *_stli_lights collections keep the outliner organized.

Blender 5.0 compatibility

• Image pack/colorspace ordering fix in io_scene_halo/global_functions/shader_generation/shader_helper.py — on Blender 5, setting colorspace_settings.name before image.pack() silently discards the pixel buffer and produces all-black H1/H2 materials. Fixed by packing first.
• mesh.use_auto_smooth access is hasattr-gated on the H3 build-mesh path; custom split normals are still applied via normals_split_custom_set_from_vertices.
• Deprecated icon='SEARCH' migrated to icon='VIEWZOOM' in add-on preferences.

Vendored pytagfilelayout fix

• Patched io_scene_halo/_vendor/pytagfilelayout/tag_data_reader.py to deep-merge inline-parsed scalars with chunked sub-struct results. The upstream vendored library silently clobbered inline fields whenever a struct declared both inline scalars and chunked children — which is every H3 scenario_object_datum_struct (position, rotation, placement flags, scale). Without this fix, H3 object transforms decode as zeros everywhere.

Silent-failure surfacing

• io_scene_halo/file_tag/h3/file_scenario_structure_bsp/ and the shared mesh decoder now emit WARNING reports (with cluster / IGD / instance context) for empty render geometry, missing mesh indices, or instance definitions that point out of range, instead of silently dropping geometry.
• io_scene_halo/file_tag/build_scene/build_bsp.py bounds-checks mesh lookups before indexing (Python negative indexing used to silently wrap).

Headless regression harness & pytest suite

• tests/headless_import_harness.py + tests/blender_headless_import_runner.py launch Blender in background mode, run an import, and stream WARNING / ERROR / HEADLESS_HARNESS signal lines plus per-collection object counts.
• tests/test_h3_scenario_import.py parametrizes regression cases across guardian.scenario (MP) and 130_epilogue.scenario (campaign), auto-locates H3EK under the default Steam path (or via H3EK_ROOT), and gates lightmap / scripts tests on the corresponding prefs.
• JMS parser unit tests, sorting tests, and integration smoke tests run through pytest via run_tests.py; see tests/README.md.

Generate Level cross-platform fixes

• Cross-platform path joins in io_scene_halo/misc/generate_level.py (was hard-coded to Windows separators).
• Missing-asset paths now raise an explanatory FileNotFoundError listing which games ship blend assets and what to add, instead of Blender's cryptic failed to open blend file.

Add-on preferences UX

• A labelled Halo 3 Import Options section in the add-on preferences surfaces h3_import_lightmap_textures and h3_import_scripts toggles, instead of burying them under the MCC tag-path block.

Performance: numpy-backed geometry build

The shared mesh-construction paths in io_scene_halo/global_functions/mesh_processing.py and io_scene_halo/file_tag/build_scene/generate_h3_scenario.py were rewritten around numpy + Blender's foreach_get / foreach_set bulk-transfer API:

• Per-loop UV, lightmap UV, vertex color, material-index, and region-attribute buffers are allocated as contiguous np.zeros / np.empty arrays (float32 / int32) and streamed into mesh datablocks in a single C-level call per layer. The previous per-loop / per-polygon Python attribute assignment — the dominant cost on large H3 BSPs — is gone.
• mesh.from_pydata(...) is followed by a single polygons.foreach_set("use_smooth", ...) and, when normals are authored, normals_split_custom_set_from_vertices fed from numpy. No per-polygon Python loops.
• H3 lightmap UV remap uses numpy-backed KDTree inputs (mesh.vertices.foreach_get("co", ...) → reshape → query) instead of Python-side vector lists, so seam-split cluster meshes process in one pass.
• Shader pixel buffers in io_scene_halo/global_functions/shader_generation/shader_helper.py convert PIL images via np.asarray(...).ravel() and hand the flat float32 buffer directly to image.pixels.foreach_set, avoiding the Python-level row-by-row copy.

Net effect on a real H3EK guardian.scenario import (thousands of clusters + instanced geometry + object palette meshes): BSP mesh construction is the fast path, no longer the bottleneck. Scenario walk + shader resolution now dominate the profile.

What hasn't changed

Everything upstream continues to work: JMS / JMA / ASS / QUA / JMI export and import for Halo CE, Halo 2, and the MCC classic variants; WRL importing; H1 and H2 tag importers for models, collision, physics, animations, camera tracks, BSPs, lightmaps, scenarios, and selected shader groups; Halo Reach and Halo 4 cinematic cameras. Refer to the upstream README for the authoritative per-game feature matrix and the upstream contributor credits.

Out of scope for this fork (see backlog.md for details): H3 animation (antr / jmad) import, H3 physics (phmo) import, and animation inside H3 .scenario import.

Documentation & testing

• backlog.md — deferred items with scope notes (H2 scenario material dedup, H3 JMS+JMA import gaps).
• tests/README.md — test layout and how to invoke the headless harness.
• run_tests.py — top-level pytest entry point.

Installation (Blender 4.2+ / 5.x extension)

Important — migrating from the upstream legacy add-on. This fork is repackaged as a Blender 4.2+ extension, not a legacy scripts/addons add-on. If you previously installed the upstream io_scene_halo by dropping its folder into %APPDATA%\Blender Foundation\Blender\<version>\scripts\addons\ (or the equivalent on macOS / Linux), you must remove that copy before installing the extension. Leaving it in place produces Add-on not loaded: "io_scene_halo", cause: No module named 'io_scene_halo' errors at startup and can shadow preferences lookups.

Locations to clear (per Blender version directory):

• Windows: %APPDATA%\Blender Foundation\Blender\<version>\scripts\addons\io_scene_halo
• macOS: ~/Library/Application Support/Blender/<version>/scripts/addons/io_scene_halo
• Linux: ~/.config/blender/<version>/scripts/addons/io_scene_halo

Also open Edit → Preferences → Add-ons, search for halo, and click Remove on any legacy entries shown as "Add-on not loaded".

Install the extension zip

1. Grab dist/io_scene_halo-<version>.zip from this repo (or build it — see below).
2. In Blender, open Edit → Preferences → Get Extensions.
3. Click the dropdown arrow next to the "Get Extensions" heading → Install from Disk… and pick the zip.
   • Alternatively: drag the zip directly onto a running Blender 4.2+ window.
4. Blender installs under %APPDATA%\Blender Foundation\Blender\<version>\extensions\user_default\io_scene_halo\ (or the OS equivalent). Pillow and lxml wheels bundled in the zip are unpacked automatically.
5. Open Edit → Preferences → Add-ons, find Halo Asset Blender Development Toolset, expand it, and set your tag/data paths (or click the per-game Auto-Detect buttons for MCC / Halo 2 Vista / H1 CE installs under Steam).

Uninstall or upgrade

• Edit → Preferences → Get Extensions → (find the entry) → dropdown → Uninstall, then reinstall the new zip.
• The extension's preferences (tag paths, H3 import toggles) are stored per-Blender-version; reinstalling the same major version preserves them.

Building the extension zip

Run build_extension.py from the repo root to produce a Blender 4.2+/5 extension zip at dist/io_scene_halo-<version>.zip:

python build_extension.py --clean

The script reads the version from bl_info, downloads Pillow and lxml wheels for Windows / macOS / Linux into build/wheels/, writes a blender_manifest.toml at the zip root, and packages everything in extension format. Pass --skip-wheels to re-use the wheel cache between builds and --no-wheels to omit dependency bundling entirely.

• External references preserved from upstream: C20 docs and H2Codez docs.

Attribution

This repository is a fork of General_101's Halo-Asset-Blender-Development-Toolset. The upstream add-on is the foundation for everything here — JMS/JMA/ASS/QUA toolchains, H1/H2 tag import infrastructure, the build-scene pipeline this fork extends to H3. Please support General_101 at ko-fi.com/general101. The full contributor list (Cyboryxmen, Aerial Dave, conscars, MercyMoon, Fulsy, mosesofegypt, num0005, kornman00, the Sigmmma crew, chiefster_4014, dogbrainludus, meowsandstuff, JackOfChaos, and general_101 himself) is preserved in the upstream README credits section.

License

GPL, unchanged from upstream — see the upstream LICENSE.