Ads keep us online. Without them, we wouldn't exist. We don't have paywalls or sell mods - we never will. But every month we have large bills and running ads is our only way to cover them. Please consider unblocking us. Thank you from GameBanana <3

Open Sauce

A Mod for Halo Custom Edition

No ads for members. Membership is 100% free. Sign up!

Open Sauce for Halo: Custom Edition

More info and updates at []( "") Introduction ------------ It is assumed that you have downloaded and are using the latest version of OpenSauce. Note that OS only supports v1.10 of HaloCE. Common Notes ------------ Debug and various other files (eg, sapien_model_index.dat) that use to be created in the same directory as the .exe which created them are now all found in My Documents\My Games\Halo CE\OpenSauce\Reports\. This obviously only applied to cases where you're using an OS program. If you're using a stock (ie, non-OS) version of a tool or game, it's the same shit, different day, in terms of functionality. OpenSauce for the HEK ===================== How it all plugs in ------------------- When the "CheApe" modifications are applied, the installer first makes copies of the HEK exes. Eg, it makes a copy of tool.exe and names it OS_tool.exe. All copies use the "OS_" prefix. The copy is then modified to load a specific build of the CheApe dll. Eg, OS_tool.exe will load CheApeDLLT.dll, where the letter before the extension corresponds to the first letter of the tool (so, G for Guerilla, etc). We now have the "OS HEK". There's one more, dynamic, component to this setup though: This is not a map file like It's a memory cache of prebaked binary data which the CheApe DLLs all load and then use to fixup their owning exe (eg, OS_tool.exe) with the various definitions. Definitions found in include custom tag groups, script functions, etc. When it comes to new GFX, scripting, etc features, none of them are actually implemented in the HEK. They're only stubbed out enough to allow the tools to interface or make use of them. So you won't see detail maps in Sapien or be able to use physics_set_gravity in the console. Such things can only be fully used in game. Setting up your scenario ------------------------ OS makes a couple of modifications to the scenario. One, it changes the very first field, a tag_reference, become a project_yellow tag reference. This is how we link in OS-specific data. Another modification is to the hs-syntax-data. OS-made scenario tags by default have an upgraded script node count. This count makes the scenario tag incompatible with the stock HEK. But, you can still use the stock build-cache-file command in OS_tool.exe to build .map files compatible with the stock game. With that said, you should only be using to the OS HEK to create OS-bound maps. Use the stock HEK to create regular maps and tags. Setting up your project yellow definition ----------------------------------------- The project_yellow tag group can be considered OS's equivalent to a "scenario" tag. This tag is referenced by .scenario tags. So you must first create a new project_yellow tag, just like you would any other new tag. By convention, it's best to save this in the same directory as the owner scenario tag. Let's take levels\test\tutorial\ for example. We would first copy levels\test\tutorial\tutorial.scenario and rename it to tutorial_os.scenario (remember, scenarios made/edited by the OS HEK can't be read by the stock HEK). We would then create levels\test\tutorial\tutorial_os.project_yellow. Withtutorial_os.scenario open in OS_Guerilla, we would then set the "project yellow definitions" field to reference our tutorial_os.project_yellow tag. Now our scenario is setup to to use custom project_yellow data. Setting up your project yellow globals definition ------------------------------------------------- Setting up a project_yellow_globals tag is pretty simple. By convention, this should be stored in your globals\ folder. For example, let's say we created a globals\globals_os.project_yellow_globals tag. In our tutorial_os.project_yellow we created earlier, we would then set the field named "yelo globals" to reference our globals\globals_os.project_yellow_globals tag. Note that you can also setup your project_yellow tag to use a different stock .globals tag as well, via the "globals override" field. OpenSauce for the Game ====================== The installer for OS should take care of pretty much everything needed to use the extensions with the game (eg, putting the DLLs in your selected HCE install path, patching the game/HEK, etc). There are a couple of cases where user intervention is required (eg, when installing a mod's Mod-Set data files), but let's first go over how OS hooks into the game exes. How it all plugs in ------------------- For the client (haloce.exe), we use a proxy dinput8.dll file (aka a 'dll hook'). What this means is that we compiled all of our code into a dll, renamed it to a dll the game looks for and uses, then we ourselves load the real dll and run off that, and finally, we place our dll into the same directory as the exe file. Essentially we wrap the DirectX 8 APIs. For the dedi (haloceded.exe), we actually copy the exe, rename the copy to OS_haloceded.exe, and then modify that exe to load our "OpenSauceDedi.dll" (which is based on the same code used to build our proxy dinput8.dll, except it's made just for and has features specific to the dedi server). Playing the game with OS ------------------------ There's nothing you need to do to run haloce.exe with OS, it's all taken care of behind the scenes. If, however, you want to play haloce.exe without running the OS extensions, you'll need to move the dinput8.dll out of your haloce.exe's directory (and then put it back when you want to use it again). For the dedicated server, you need to run OS_haloceded.exe instead of just haloceded.exe. This setup also makes it easier for server hosters to run both stock and OS servers at the same time, from the same directory. Yelo maps --------- .yelo map files are map files that are specially made for features/settings in OS that are incompatible with the stock game. Things like increased memory, mod-sets, new script support, etc all fall into this category. How it .yelo support implemented? We override the normal map loading process so that if a .map file isn't found, it tries looking for a .yelo file instead. Eg, if the game says it wants to run "zanzibar", it will still try to load first. If it exists, everything goes about as normal. If it doesn't, it tries to load zanzibar.yelo instead. If neither exist, then the game does the default handling of a non-existent map file. If both and zanzibar.yelo exist at the same time, will be loaded first, unless you have chosen to prioritise loading of .yelo maps in your settings.


Sign up to access this!

No comments yet


Share banner
Image URL
HTML embed code
BB embed code
Markdown embed code


Kornner Studios
Project Lead / Core Design / Programming / Unit Testing / Code Review / Feedback
Feature Design / Programming / Unit Testing / Package Releases
Choking Victim
Special Thanks


realdomdom avatar
realdomdom Joined 4y ago
Are you the owner? Request Ownership
Sign up to access this!
Sign up to access this!
Sign up to access this!

Development Info

Introduction ------------ Project Yellow (later abbreviated to just “Yelo” because it looked liked "Halo") originally started off as a very small venture into using DLL hooks (both by force and by a DirectX proxy) to perform custom operations in Halo PC. I partnered up with Shaun W. (moniker: ‘bitterbanana’) on this project as he was originally the one who brought up the methods. For the curious: the name was derived from the fact that our monikers were both food related, whose colors are also yellow. Also because of the Coldplay song by the same name, 'Yellow'. (Shaun: I don't remember this part...) Don’t judge us. Halo PC ------- We started off with rather simple stuff. Shaun mostly dazzled with camera magic, putting in his third person modification (originally an external application written in VB6) along with a custom reticule. I spent my time transitioning my research of the engine into usable code in our Yelo project. I also had to bring Shaun up to speed on how the game state was designed and functioned. Months drove on with the codebase starting to become a somewhat manageable mess and more nifty little ditty modifications came about. Such things included custom external scripting components, which allowed us to make the global gravity scriptable, and multi-team vehicles (or MTV; i.e. different team members can ride in same vehicle). Halo 2 had it, so we figured Halo 1 MP wouldn’t hurt to have it. Snazzier constructs started come about as well. One of them well worth mentioning was our Gravity Gun. It wasn’t a first class object itself (like the Physics Gun in the popular GMod but rather a set of code which ran based on an object’s view and a unit’s input (so it wasn’t fixed to a player datum...hell, an AI could have potentially used it). The Gravity Gun was a pretty bad hack in terms of engine interaction: all it did was modify the basic object_datum’s world position and velocities. While we could filter the object types it could interact with, this still didn’t always solve the issue that I believe stems from “connecting” objects to the BSP. I originally noticed this when I had the bright idea to grab a rocket which I had just shot. I increased its speed and then finally let it fly off into a wall. Bam. Crash. I shrugged it off at first; I didn’t expect to allow projectile types to be mimicked in a public release anyway, better to spend my time frying bigger fish (coming up next). However, whilst on a map, I had grabbed a vehicle and started moving very far across the map. Somewhere in between letting go of it to maybe trying to get into it, the game crashed. I then set the feature aside to later try to find a more proper implementation (possibly a function which disconnected the object for editing then reconnecting when we let go?) to see if the problem persisted. I never had the time to do this sadly. Halo 1 & 2 Xbox --------------- The project would later evolve to consume another project a friend (Mike D. [xbox7887]) and I were working on for the Xbox version of Halo 1 & 2. Initially, we were using a custom Xbox Dashboard to launch our “trainers” (or as I prefer to call them: game modules). Due to this method of code injection, we were limited to about ~11KB of x86 assembly code and data. Other games didn’t push the RAM to its limits (which H1 & H2 do) so I’ve heard of larger module usage. We were doing things like allowing users to dump screenshots (both normal, faked hi-res, and panorama), custom debug camera, Skull enabling\disabling, allowing AI in MP modes, etc. As you can probably imagine, these features and their implementations in pure assembly code started to rack up in size after a while. Even with some of more ambitious assembly hacks we were able to conjure up. It was time to think outside the box. I forget which box I found myself wondering around, dazed and confused, when I thought of this solution but it must have been black and monolithic. The solution to our problems was based on compiled C (with some usable C++ language constructs) code, linked into a very bare DLL file. From this DLL and optionally a .MAP (Linker Address Map) file we would then process the code and data so that the addresses were relocated to a base address which we were going to inject the module at in the game memory. The .MAP option was for finding any implicit compiler/linker clashes (eg, any at-start or at-exit routines) or unneeded/garbage code/data which we could exclude in our Module Linking process to further reduce the required memory needed to run a module. With the power of a high-level language like C++ I was able to create a custom Xbox SDK which Module codebases could link to. Then those modules could also call Xbox API functions and run their own C code. This reduced code maintenance ten-fold. Not only could we now have an abstract Xbox SDK (abstract to an extent and in terms of the game we were targeting) we could link to, but we were able to expand on the things we could target due to struct/class definitions and truly reusable code. However, this new technology didn’t get pushed very far. Mike himself was growing busy in his personal life and was really only fluent in x86 and some C# at the time. I stopped any major development for the system around the release of Halo 3 (was also when I got my 360 XDK which distracted me from any current Xbox 1 works) OpenSauce SDK ------------- Eventually in 2008 I would come to realize that this codebase we had created would be better off in an open source environment. We weren’t doing any real work on the Yelo system (however, Shaun did release a module for both PC and Custom Edition named Yelo: Battery earlier) and both of us were distracted by real life so I didn’t want to neglect the community of something we had been showing off to them; it didn’t settle well with me. Seriously, a tear just ran down my cheek. I should get that leak fixed. So I spent a few months creating a somewhat new codebase for OpenSauce. I wanted to clean up the dump which Yelo’s code came to be. Along with crafting a more recent codebase, I set out to quash any bugs like any good developer would and to also finish something that had, until then, been a personal project: CheApe. CheApe ------ CheApe was thought up after I reviewed a GDC presentation by Chris Butcher (archived link). One of the concerns which really sparked my attention was the fact that designers couldn’t edit or annotate tag fields. I wanted to prototype a system which would not only work for defining tag definitions, but allowed for post-compile editing of the editor specific values for those definitions so designers can make comments (e.g. for a ‘real’ field, “1.2 to 2.4 are good values”). I had already done extensive research with the Halo 1 tool kit so I decided it would just be better to create a tool which processed XML data into a memory mappable data file, then use a DLL with my own code to hook in functionality. The data file would act just like a game cache file: pre-baked data located at a fixed base address, load said data from file to that base, perform fix-up operations, and continue normal tool kit code flow. Initially I ended up programming support for statically built byte-swap definitions in the data file but I eventually figured out how to setup the tool kit hook so that the engine did all that for me. I figured it was good practice implementing it anyway so nothing meaningful was lost in adding the support. So here it was, CheApe: an extension to the Halo 1 tool kit which could allow new tag definitions. Since this was just a prototype and an extension to alien software I didn’t see a need to add support for changing existing Blam Engine definitions. However, later I did implement custom script definition and data fix-up support. At the end of the day, CheApe isn't a real viable solution for providing developer hooks for things like custom comments or annotations. A more ideal solution would be to separate the struct definitions from the editor definitions (which is what I believe Bungie has done since at least Reach). However, since Halo1 and Halo2 are released and no longer updated, CheApe was great for extending the game's tools. The name "CheApe" is based on the logo used by Guerilla. They used a Planet-of-the-Apes-style logo of Che Guevara. Hence, the 'Che' and 'Ape', as CheApe was originally suppose to be an extension for Guerilla only. Guerilla Halo1_CE (Yelo) Codebase ------------------------ The meat of the SDK; this is where the game changing code for Halo Custom Edition can be found. The project is named "Halo1_CE" due to the Halo2 (Xbox) code being added to the codebase and thus needing to have some kind of unique naming scheme for each game Yelo is implemented for. Refer to the naming conventions for more information This codebase is really just a re-factored and cleaned up Project Yellow. Notable changes from Project Yellow to OpenSauce include using boost C++ libraries, switched to a specialized include files for all compile-time game engine addresses (ie, addresses within the game exe), polished Networking code, removed statistics collection from public release in favor of the “Synapse” extension (which would be closed source), started working on game simulation/film support for Synapse’s development (that too, closed source). Synapse Extension ----------------- Cerebrum and Synapse were never finished. Synapse was/is a specialized build of OS for the HaloCE dedi that aggregates game events and such into a game "film" (much like Halo3+ game films) which would then later be parsed for player and game stats (plus additional automated analysis like detecting cheaters). Halo1_CheApe Codebase --------------------- This codebase is where the tool kit hook code resides. Tool, Guerilla, Sapien; we use specialized build configurations to produce a DLL which is loaded by each respective modified OpenSauce tool EXE (eg, OS_Guerilla).


Sign up to access this!



OpenSauce is [licensed under GPLv3]( ""). The main reasoning behind this is to force the community to share derivative works. Another major bullet is the fact that the engine extensions (eg, OpenSauce for Halo1_CE) don't allow for additional plugins. So a third party can't create their own special little modification and have it plug into the existing engine extension binary. The codebase is far too developed to mould it into something that could support such functionality. Due to the fact that the Blam engine is a closed source system to multiple games, everyone benefits from shared research. Sometimes, people create really cool food based on different mixtures of other's recipes. The same goes for code. With all derived works requiring source modifications to be released, we can see if there are things which we would like to see integrated into the main source tree of OpenSauce (a good example was the PostProcessing render modifications for Halo1_CE).



  • Share on Reddit
  • Share on Twitter
  • Share on Facebook
  • 0
  • 564
  • 6.0k
  • 4y
  • 4y

More Other/Misc Game files