Halo Engine Primer#

Hey there! If you're unfamiliar with either Blamite or the Halo engine and you need some help on how to start, what anything is, and so on, you've come to the right place.

First off - the to-do list. You'll find the current status of what is/isn't functional in the engine here. The list of things to do are ever-expanding.

Second - the issue tracker. You'll primarily be looking at the issue tracker on the repository itself, although every now and then you might find things on the website's job tracker as well (though those are mostly going to be for things not relating to the engine itself).

So, let's say you're brand new to all this. You've never touched the Halo engine in your entire life and, thus, the words "make it like the Halo engine" mean absolutely nothing to you. You, my friend, are the reason this page exists!

Let's start with the basics - tags.

Tags & Tag Classes#

Tags refer to primary content items within the engine. They can be anything from a weapon, projectile, 3D model, texture, shader, and so on. They serve the same function as content items in other engines, like Unity or Unreal.

Tag Classes refer to what a specific tag is. Think of it like a content type or file extension. Tag classes have both a "short" and a "long" class name. The short name can be up to 4 characters (and usually will be exactly 4, only some old classes from as far back as Halo CE are shorter). An example of this would be weap, referring to the Weapon tag class. The long name is a longer name - which in the case of a Weapon would plainly be weapon. Short classes generally should be a sort of shorthand for the long class name, but this isn't a hard and fast rule. Some tag classes have short names that, on the surface, make absolutely no sense - for example, the short name for the animation class is jmad. You'll most likely want to just keep things as a shorthand if you're adding brand-new tag classes, but it's not a mandatory rule.

If you're tasked with implementing a tag class, be sure to check the Tag Classes Reference page to see if the class already exists. Class layouts can be found within the plugins folder within the repository. Speaking of those...

Plugins#

Plugins are a creation of the Halo modding scene. They are used in programs like Alteration, Ascension, Adjutant, and most notably Assembly. Those programs all modify tag data directly within packaged levels, and as such have no way to natively read what the data is. Since the Halo engine also isn't well documented (or really at all past Halo CE, in terms of the public at least), modders used plugins as a way to easily define tag layouts and adjust them easily over time. Blamite will be utilizing them as well, for a similar purpose - since Blamite's tag structure may change often, plugins currently appear to be a nice, easy way to ensure existing tags don't break as we continue to build up the tag classes.

The files are stored as XML files, which define the layout and content of a tag. For more information on what kinds of fields a plugin can have, check the Tag Properties page.

Blam Cache Files#

Maps, or 'Cache Files' (.map) as the modding community has come to refer to them as, are what tags are packed up into for a shipping game. They have a header containing the scenario name, engine version, and several addresses and offsets for both security/integrity purposes as well as to tell the engine what's within a map. Most of the header data will come down to creative liberty, as most of those numbers are unknown (even still).

Most maps are simply actual levels, but there are several that are intended specifically for bulk asset/tag storage:

shared.map - This stores data that will be used by virtually all levels. In the official games, it stores mainly raw asset data as well as tag data. However, levels that reference that data also include a copy of the tags (but not the raw model/etc data) that are not linked to shared.map. This is something that we may or may not change within Blamite, but time will only tell.
campaign.map - It serves the exact same purpose as shared.map, except for Campaign and Firefight levels exclusively. It does NOT replace shared.map for those levels, but works in addition to it.

Additionally, there is mainmenu.map. It - you guessed it - handles the game's main menu.

Scenario Types#

There are several different types of scenarios that can be created, and each reflect in the scenario's path as well:

Singleplayer (/levels/solo) - These are levels that are intended specifically for Campaign or Firefight.
Multiplayer (/levels/multi) - These are levels that are intended for Multiplayer, such as Custom Games and Forge.
Mainmenu (/levels/ui) - This is for the Mainmenu, and there should only be a single level of this type - can you guess what it is?
Shared (/levels/shared) - This is for, you guessed it again (gosh you're smart), Shared.

Blam BLF Files#

BLF files (.blf) store one thing and one thing only - map images. Those little preview images you see in the main menu when you're viewing a level? Those are BLF's. They are actually a JPEG image with its headers stripped and special data along with that image packed up in a nice little file. There are generally two per map, one being the standard size and one being smaller, with the _sm suffix. That's it basically, not much more to it. What does BLF stand for? Not a damn clue.

Blam Map Information Files#

Map Information (.mapinfo) files are also fairly self-explanatory. They store the information that goes along with a map. The display name of a level, the map ID, the description, as well as the scenario name and BLF name. It also stores some data describing other basic information about the map, including the level type, it's visibility in the menus, whether or not it's DLC, as well as whether or not to generate a Theater clip. Campaign levels may also include several Insertion Point entries, which are used to start a level at a certain spot - displaying in-game as Rally Point Alpha, Bravo, etc. Halo 3: ODST also used Insertion Points for Firefight, and did so within standard campaign levels strangely enough.

Blam Campaign Files#

Campaign (.campaign) files store a list of map ID's that are all part of the game's campaign, as well as the name and description (though those go unused in the official games). This is used for things such as knowing what level to go to next after finishing one, checking campaign completion, and so on. There can be up to 64 map ID's within a campaign file.

The Engine's Toolset#

The Halo Engine has a few primary tools made available to the community with Halo Custom Edition, as well as Halo 2 Vista (although those were significantly locked down):

Guerilla#

Guerilla is the program used to edit tags. Now that you know what tags are, it all makes a bit more sense now, right?

Sapien#

Sapien is your level editor. This is what is used to place objects of all sorts into levels.

Tool#

Yes. It's literally called 'Tool'. Make no mistake, however - Tool is a fairly important tool. It, unlike Sapien and Guerilla, is a command-line utility. It serves the job of packaging a level folder into a Cache File as well as converting data from other programs to work with the Engine (ie, 3DS MAX), among a few other things (lighting, string table creation, etc).