H1A Editing Kit (343i)
After downloading the H1A-EK, please read
README_MODDING.txt. You must extract both
data.zip to the root of the mod tools folder.
The H1A Editing Kit (H1A-EK), also called Halo: CE Mod Tools, is the set of official modding tools used to create custom multiplayer and singleplayer maps targeting the PC MCC version of Halo: Combat Evolved Anniversary. It was first released by 343 Industries during Season 7 of MCC in 2021.
- Significant updates to the game engine and original tools, including bug fixes, quality of life improvements, extended limits, and new features.
- A complete source tag set for the game's stock campaign and multiplayer maps, plus source scripts for the campaign. This means that, unlike the original HEK, singleplayer maps are officially supported and you won't need to extract the stock tags anymore.
- A brand new tool, the H1A standalone build, which loads tags instead of maps (like Sapien) and supports all console commands unrestricted. It is intended for fast iteration and troubleshooting custom singleplayer maps and AI.
These tools are based on the original internal tools created by Bungie during the game's development. They have been updated over the years as Halo changed hands, and are now available again in a trimmed-down state for public use. You do NOT need to own MCC to install the H1A-EK.
Using the H1A-EK to create content for H1CE rather than H1A is not officially supported. For example, H1CE uses a different map version and won't load maps compiled for H1A. Taking advantage of many of the fixes and extended limits below will also result in your tags not being backwards compatible. Use at your own risk.
- Download the tools using Steam, you might need to install Steam first.
- Follow the on screen prompts to download the tools.
- Once the tools are done downloading you can find them in your library in the tools section.
- Right click the entry for the mod tools, select the "Manage" context menu entry then select the "Browse local files" subentry.
README_MODDING.txtand follow any further instructions contained within it. Extract both
data.zipto the root of the mod tools folder.
- (Optional) Check out the guides hub to learn more about modding or install a launcher like Osoyoos if you don't like using the command line.
If you're coming from the legacy HEK for Custom Edition or earlier versions of MCC you may be wondering what's new and great about the updated H1A tools and engine. Don't worry, we've got you covered!
The season 7 MCC update (patch notes) is a significant milestone for the Halo 1 engine. It represents the recombination of code and tags from Anniversary, Custom Edition, OG Xbox. Many aspects of Halo 2's tools or limits from later games have even been backported. Mod support is likely to continue beyond season 7 in a phased approach. The tools can receive updates over time owing to their distribution via Steam.
- Blitzkrieg was not rereleased. Use Jointed Model Blender Toolset or the new Tool commands for converting Autodesk FBX to JMS and JMA files.
- All the tags used in retail MCC plus the ones used for the old HEK tutorial are included alongside the tools, meaning tag extraction with Refinery or invader-extract or prebuilt tag sets are no longer required if someone wants to mod the stock maps. Note that these tags are partially incompatible with H1CE due to their use new flags, shader_transparent_generic, etc. The tags are intended for targeting H1A.
- The original source HSC scripts are included for all campaign missions.
- Stability improvements:
- Negative fog opaque distance and depth no longer causes a crash.
- Negative power values for skies no longer causes a radiosity crash.
- Fixed bitmap group sequence blocks crashing when crosshair overlay sequence index was out of bounds.
- Fixed exception when AI try to fire weapons without projectile references.
- Fixed a crash resulting from ejection from flipped vehicles not resetting unit animation state.
- Removed an incorrect assertion related to drawing HUD numbers and bitmap sequences.
- AI debug code now safely checks for an actor's secondary look direction prop index being NONE.
- Various buffer overflow, index out of range, and stale pointer fixes.
MAXIMUM_NUMBER_OF_BUILD_SPRITE_BITMAPSfrom 8 to 16 (renderer stability).
- The engine will now check and log when an invalid particle_system using rotational complex render mode has a particle state where the sprites bitmap does not include another "sideways" sequence after the given "forward" sequence index.
- The tools are in general faster and more responsive (in part due to manual optimizations, in part due to play builds built with a modern optimizing compiler being used instead of test builds).
- Asserts can be disabled using the
-noassertcommand line flag.
- The tags, data, and maps directories can now be set when running all tools. See custom content paths for more info. This makes it easier to work with different tag sets.
- All tools are still 32-bit but they are now large address aware (LAA). This allows them to use up to 4 GiB of virtual memory instead of 2, which prevents Sapien from running out of memory when editing scenarios with many large assets.
- Various cases of unnecessary/confusing logging in the tools have been removed, such as "Couldn't read map file toolbeta.map" and "Sound card doesn't meet minimum hardware requirements".
- The tools now use the modern DX11 graphics API instead of the obsolete D3D9 API. this should result in better performance and support on modern systems.
- First person models now use the highest LOD available instead of the lowest.
MAXIMUM_RENDERED_ENVIRONMENT_SURFACESfrom 16k to 32k. This means BSPs can now have more visible triangles without culling happening. It is still important to use portals to manage visible clusters.
- Many Gearbox visual bugs were fixed. Some examples are:
- Restoration of shader_transparent_generic and shader_transparent_plasma
- fog screen layers
- Fog planes draw over sky
- Environment bump mapping
- Interpolation on screen shake, antennas, flags, and some UI fading
- Water mipmap order
- Camo tint
- Glass with bumped reflections
- Flashlight distance
- Widget alignment in mirror reflections
- Lots of new verbs have been added. See the Tool page for details.
-verboseflag can be added to see additional logging.
- Lightmapping code has been optimized and is even faster with the
-noassertcommand line flag. Lightmapping now takes roughly a quarter of the time of legacy Tool and is even faster than LM tool. Additionally this code now only uses 32-bit integers instead of an unsafe mix with 16-bit ones, and 16 MiB stack reserve. This increases the crash stability of radiosity.
- Most logs (like
debug.txt) are now saved to a
reportssubfolder (similarly to Halo 2+).
- Bitmaps compilation
- Bitmap DXT1-3 (BC1-3) encoding now uses DirectXTex instead of some S3TC code. This should result in higher quality similar to the original XDK.
bitmapsverb now accepts both
- Map compilation (
- Script data is properly recompiled from source files when available now. A bug previously caused Tool to always fall back to sources stored in the scenario tag.
- Resource maps can optionally be updated to include all the resource data for the scenario being packaged.
- Maps can target "classic" or "remastered" mode.
loc.mapresource maps are no longer generated or used as they are not used by H1A (aside from H1CE backwards compatibility).
- Tool will now log errors when the user attempts to use swarm actors in firing-position based combat; always charge at enemies must be set to prevent runtime crashes.
- Model and structure compilation:
- The functionality used by phantom_tool to remove collision artifacts is now exposed as an argument for compiling BSPs (
structureverb) and model_collision_geometry (
- WRL files are saved alongside the JMS file being compiled rather than the HEK root. The user is now told that this file was generated.
- When compiling a structure BSP and shaders do not yet exist, the chosen types of shaders will now be generated in the level's
shadersdirectory instead of the tags root.
- Model compilation can now optionally use Halo 2's logic for LOD selection, which is more intuitive.
- Model and collision importing have more verbose output. Use
-verbosefor the most troubleshooting information.
- The functionality used by phantom_tool to remove collision artifacts is now exposed as an argument for compiling BSPs (
- Usage and feedback clarity:
- Argument parsing is now less primitive. Verbs can include optional arguments and flags and any unrecognized options are presented to the user.
- The usage printout when Tool is run without arguments is now sorted. The names and argument descriptions of some existing verbs have been updated for clarity and consistency.
stringsverbs have been removed since they weren't useful.
- Tool will now tell you if it couldn't find a directory rather than simply logging nothing like some verbs previously did (looking at you
- Verbs which accept a tag path as an argument will now automatically strip
tags\prefixes, allowing you to use tab completion on the command line (Halo 3 backport).
- Tool will no longer exception (but will log errors) when compiling a gbxmodel where the JMS has invalid node weights (two nodes where one has weight
- Tool supports a
-pauseflag which keeps the process running after completion until the user presses Enter. This was meant for community-made launchers like Osoyoos.
- Stability improvements:
- ogg/vorbis upgraded to to 1.3.5/1.3.7 which should improve sound compilation stability.
- Fixes for various unsafe code: uninitialized variables, bad
- When Sapien crashes it will attempt to autosave the scenario to a new file.
- The lightmap painting feature was fixed. The user can perform touchups to fix light leaks or add missing lights and save changes to the lightmap.
- Garbage collection now takes into account Sapien's 5x higher objects per map and object memory pool limits so Sapien no longer spams "garbage collection critical" errors after loading the c10 scenario.
- Multiple Sapien instances can now be launched at once using the
-multipleinstancecommand line flag.
- Game window improvements:
- Weather and particle effects like smoke and fire will now render.
- When the camera is outside the BSP, you will now see structure debug lines by default (
debug_structure_automatic) (like H2 Sapien). This helps you find the BSP if you get lost or the camera begins outside it, as with b40.
- Interpolation code from H1A is included and
framerate_throttleis disabled by default, allowing for smooth animation and movement.
- The camera speed can be temporarily boosted by holding Control.
- The Game window resolution has been increased from 800x600 to 1280x720 (widescreen).
- A gamepad can be used to control the camera, though this feature is experimental.
- User interface improvements:
- Sapien now features a modern Windows file open dialog which includes locations like quick access. This is also true for the Edit Types menu when finding new tags to add to a palette.
- Invalid block indices are now shown as
BAD: #rather than being set to
- UI has been cleaned up a bit with unsupported elements removed (e.g. File > New) and others renamed.
- Added "Clear" button to tag reference dialog.
- The View menu now includes ways to reopen the Output window and Tool window if they are closed.
- Widened layouts for strings, references, block indices, etc.
- When placing netgame flags, the Properties palette now includes explanations for how to set up each game mode.
- When placing netgame equipment the team index field also has a helpful reminder that 0=red and 1=blue.
- Stability improvement:
- Transparent shaders with no maps no longer cause Sapien to crash. The shader is simply not rendered.
- Objects with transparent self occlusion enabled while also referencing a transparent shader with extra layers will no longer cause a crash.
- Sapien no longer crashes if a BSP fog plane has a fog region set to NONE.
- The snap to normal hotkey, N, no longer puts the editor into a bad state.
- Detail object painting is possibly more stable now. More testing is needed to confirm.
- Sapien now supports
-nojoystickarguments as a mitigation for any device-related problems which need to be worked around.
- The New instance and Delete buttons in the hierarchy view are now properly disabled when not applicable.
- Recording and model view modes no longer cause a crash on closing Sapien.
- Closing the Output window now properly sets its handle to NULL.
- Fixed a crash related to selecting custom device_control names.
- Fixed issues with invalid platoon indices.
- Guerilla now features a modern Windows file open dialog which includes locations like quick access.
- H2 Guerilla backported features:
- Tag blocks can now be collapsed.
- UI elements have been upgraded to look more modern, with wider inputs.
- Expert mode, Show tag block sizes, and Copy tag name options.
- A zoom level feature has been added to the bitmap viewer. The alpha channel drop-down label has also been corrected.
- Fields which reference a block element by index, shown as a drop-down, now update their appearance in real time as the referenced block is edited. For example, when a referenced element is deleted the field will immediately show "BAD INDEX: #". When the name of a referenced block element is changed, the label in the drop-down is updated in real time too.
- Some unused UI options have been removed.
- Guerilla now enforces sound tag gain modifiers are within a valid
- When tags are loaded for editing, tag references with an unknown group ID are now clamped to NONE. This fixes cases like the leftover weapon_collection reference in the Bloodgulch scenario from causing downstream problems.
- Save as now makes copies of read-only tags editable without having to reopen the tag.
- Hover-over tooltips for flags after unused sections are no longer off-by-one, e.g. multiplayer spawn flags for vehicles.
- Fixed a crash from changing a "go to" command list atom modifier field in the scenario tag.
- The developer console now supports the Home and End keys to move the cursor to the start and end of the input line.
- Console history size has been increased from 8 to 16 entries.
- Many defunct globals and functions have been removed because they are not functioning or applicable to H1A (e.g. for troubleshooting Gearbox netcode).
- Built-in script docs:
script_docHSC function now includes external globals in the output file in addition to functions.
- Script docs and
helpoutput now show return value types for functions.
- Many instances of profanity in function descriptions have been cleaned up.
- The player is now referred to in a gender-neutral way.
- Custom Edition-specific functions like
multiplayer_draw_teammates_nameswere stubbed out for compatibility with CE maps (avoids crashes).
- Unrecognized script functions and globals will now cause script data to be dropped rather than crashing the game.
- Numerous new functions were added:
- Numeric functions:
- Logical functions:
- Listing players:
- Debug camera:
- Numeric functions:
- Changes to existing functions:
unit_kill_silentno longer crash the game if the given unit does not exist.
debug_camera_loadnow save and load
camera.txt. A console message is now logged when the camera file isn't found.
player_effect_set_max_rumbleis no longer a hard-coded alias for
player_effect_set_max_vibrate. Map scripts (like a10 and d40) were updated.
- H1A's versions of map scripts no longer use a repurposed
core_save_nameto signal mission segments. The function again behaves like legacy and a new
mcc_mission_segmentfunction was added instead.
- Globals and functions are no longer locked to specific contexts like server or multiplayer. For example, you can use
cheat_spawn_warthogin SP maps now when using H1A Standalone.
debug_structureshows invisible collision surfaces in semi-transparent red and includes a BSP bounding box now (Halo 2 Sapien backport).
debug_objectsbehavior has been changed. It no longer shows bounding spheres and collision geometry by default but these can still be toggled on their own.
cheat_jetpacknow works like it was intended to. Hold crouch to float and jump to fly.
- unit and actor_variant now each include the metagame type and metagame class fields for MCC's scoring system.
- shader_model received a new flag to use "OG Xbox" channel order for the multipurpose map. Guerilla's explanation of channel usage is now updated to explain both H1X and Gearbox+ channel orders.
- Some runtime tag fields have been made invisible, such as object, weapon, and scenario_structure_bsp predicted resources, some other BSP fields.
- Node limit was increased from 48 to 63 to match Custom Edition 1.10.
- The node count fields are now marked deprecated and are invisible in Guerilla. They are written to during postprocessing but never actually used by the game.
- The markers block is hidden in Guerilla since it is processed from permutation markers and not intended for editing.
- model_collision_geometry pathfinding sphere limit increased from 32 to 256.
- scenery received a new flags field which is unused in current versions of MCC.
- effect parts and particles each previously had two fields called create in. The second in each case has been corrected to violence mode.
- Unused fields have been marked deprecated and no longer appear in Guerilla and Sapien:
- The previously hidden cutscene title fields text style and text flags are now exposed.
- There is a new scenario flag disable color correction although it is unused at this time.
- Script source text is now visible in Guerilla and Sapien.
- Netgame flags team index was renamed to usage id and explanations were added in the tag for how to set this ID depending on the flag type.
- BSP switch trigger volumes source and destination BSPs are now typed as proper block indices rather than integers, which causes Guerilla to display them as drop-downs.
- The following blocks are now hidden by default unless Expert mode is enabled in the menu: BSP switch trigger volumes, scripts, globals, and references.
- Increased limits:
MAXIMUM_SCENARIO_OBJECT_PALETTE_ENTRIES_PER_BLOCKfrom 100 to 256.
MAXIMUM_VEHICLE_DATUMS_PER_SCENARIOfrom 80 to 256.
MAXIMUM_OBJECT_NAMES_PER_SCENARIOfrom 512 to 640.
MAXIMUM_HS_SCRIPTS_PER_SCENARIOfrom 512 to 1024.
MAXIMUM_HS_GLOBALS_PER_SCENARIOfrom 128 to 512.
MAXIMUM_HS_REFERENCES_PER_SCENARIOfrom 256 to 512.
MAXIMUM_HS_SOURCE_FILES_PER_SCENARIOfrom 8 to 16.
MAXIMUM_HS_STRING_DATA_PER_SCENARIOfrom 256kb to 800kb.
MAXIMUM_HS_SOURCE_DATA_PER_FILEfrom 256kb to 1MB.
MAXIMUM_HS_SYNTAX_NODES_PER_SCENARIOfrom 19001 to 32767 (SHORT_MAX).
- The unused spheroid tag has been removed.
- Custom maps compiled with H1A Tool are identified by having cache version
13in their header (H1CE is
- The map file size limit was increased to 2 GiB.
- Tag space is increased from 23 MiB to 64 MiB.
- A new flags field was added to the cache header for controlling H1A features.
- Tags, BSP verts (16 MiB), and game state are now stored in separate dedicated allocations rather than one giant one.
- Protected maps will be detected and force a crash because they are unsupported.
- H1CE's resource maps are now included in MCC and are used when playing a H1CE map.
Due to changes in the game state structure, savegames from before season 7 are invalidated.