Xbox 360:Game Modding/Halo 3

This page offers options for modding Halo 3 using an RGH/JTAG. Generally, the most popular program for modding Halo games is Assembly, which is a direct replacement for Ascension and Alteration. The program Adjutant is used to view map geometry in 3D.

Applying XEX Patches

 * 1) Download the XEX PPF patches archive and extract it on your desktop.
 * 2) Copy `default.xex`, `waveShell-Xbox.dll`, `wavesLibDLL.dll`, and a folder named "waves" from the Halo 3 folder on your Xbox 360 to the extracted folder on your desktop. Right click each file (including the ones in the waves folder), select Properties, and uncheck the "read-only" checkbox if it is checked and press OK.
 * 3) Run start.bat, press a key to start it, ensuring that you read everything that pops up on the screen. It will have a single error about a missing `default.xexp` file.
 * 4) (Optional) If you wish to apply a title update to the XEX, note the Media ID line and plug it into Xbox Unity to download the latest title update. Use Modio/Horizon or download Velocity and select File > Open > Package, and choose the update. Extract the update to the TUfiles folder.
 * 5) Run start.bat again, and check that the two Media IDs match. Ensure that no errors occured, and press a button to start. It should indicate success by saying "Successfully wrote altered xex to topatch.xex". This means that it successfully patched your default.xex, and a backup of the original default.xex was made, named default.xex.bak.
 * 6) Press any key to continue. You should see another message indicating "Patching... Successful" and "Successfully wrote altered xex to..." with the game's name or ID. Verify that there are no errors, and press any key to close the window.
 * 7) Copy the generated XEX file, `waveShell-Xbox.dll`, `wavesLibDLL.dll`, the "waves" folder to your Halo 3 installation directory on your Xbox 360. It will prompt you to overwrite the existing files, select Yes each time.

Assembly
Assembly is a program that modifies Halo cache files (.map). Essentially, while any map is running on a console, it is using a cache file which contains all of the variables ("tags") for the currently running map including references to sound effects, models, visual effects, objects and their properties, map geometry (BSPs), and more. You can use Assembly to explore and change these variables and save an "offline" copy of the .map to use in place of the original .map file on the Xbox 360, or you can modify a .map and "poke" it to the console, meaning that the variables in the running map on the console will be updated live.

The tutorials here are an expansion of Lord Zedd's tutorial.

Installation
Download Assembly from the Assembly GitHub. It is *highly* recommended to compile the latest build, as the pre-made release version (found under Releases on the page) is from 2016 and many things have been added.

Afterwards, create a folder called "Maps" in your Assembly installation directory, and another called "Backup". Copy all of the .map files from your Halo 3 installation directory (under the "maps" folder) into Maps on your desktop and a second copy into Backup. The Maps folder will be the sandbox in which you will make modifications to the map files, while the Backup folder will be a clean backup of each map in case you want to revert changes by copying the backup .map into the Maps folder.

Applying Map Patches
Note that applying patch files will require that you have patched the game's XEX file and (unless otherwise specified by the mod creator) the latest title update.


 * 1) Double-click the downloaded patch to open it in Assembly, or open Assembly and select Tools > Map Patcher > Apply Patch.
 * 2) Select "..." next to the Patch File field and choose the patch. The patch's file extension should be `.asmp`, `.ascpatch`, or `.patchdat`. Information about the map patch will populate.
 * 3) Select "..." next to the Unmodified Map field and choose the corresponding map for the patch. If you aren't sure what map you're supposed to use, it should say it at the bottom of the screen next to Patch Target Map.
 * 4) Select "..." next to the Output Map field and name it what you would like. The maps *do not always* have to have the same name as the originals, so consult the patch release post to see if you can just add it to your maps list without replacing one.
 * 5) Some patches will have an extra checkbox asking if you want to use the extra data folder. Go ahead and check it, as without it, the patch will likely not work.
 * 6) Select the Apply Patch button at the bottom of the window. It will generate a new map file. Place this in the ".../maps" folder on your Xbox by copying it over with FTP or a USB storage device.

Troubleshooting

 * Modifications on Forge item tags are not applying when poked
 * Some tags require that you re-spawn the object you have modified or restart the round / match.


 * "Players Failed To Load Content" in lobby
 * If the error pops up near instantly, the .map could not be found. If you applied a patch, open the .mapinfo file that came with it in Assembly (if it exists) and check that the file name matches the name found in the "Map Filename" field. Change it to match and restart Halo 3 and see if it works. Alternatively, if it's a campaign patch, try going to the Campaign lobby first to allow your system to load campaign.map, then change to a Custom Game / Forge lobby.
 * If the error does not pop up near instantly, or loads partially / restarts loading a few times, you either are running an unmodified XEX or have contpatch enabled in DashLaunch. If the map had a custom .mapinfo and you were able to see and select it, then your XEX is fine and it's likely that contpatch enabled.


 * Black Screen/Frozen Loading Animation
 * It is likely a bad patch, botched application of the patch, or a corrupt download. Re-download and re-patch the map. It could also be a bad shader if you modified shaders on the map.


 * Dirty Disk Error
 * Either something is wrong involving the map's raw data or the Map ID in the .mapinfo and .map does not match. Open the .mapinfo in Assembly and get the Map ID value, then open the .map and check the top of the `scnr` tag, replacing the Map ID value if it is different.


 * Kicked Back To The Main Menu After Load Screen
 * The build string of the .map does not match any of the ones listed internally in the XEX. Update to the latest title update and it should work, or manually edit the build string with a hex editor.
 * Others Can't Join Your Game
 * Make sure everyone has the same .map as you do. Some mods, such as .map mods (excluding live variable poking), will only work if everyone has a RGH/JTAG exploited console and the same assets.

Live Map Editing (Poking)
Modifying game attributes such as weapon damage, fired projectile, animations, vehicle speed, jump height, etc while in-game is possible on an RGH/JTAG Xbox 360 using a patched default.xex file that removes cryptographic checks present in the retail version. Using a tool such as Assembly, desired modifications can be sent from a PC to an RGH/JTAG 360 located on the same network running devkit software or xbdm.xex dashlaunch plugin. These tools can be installed in a Virtual Machine if desired and still function correctly, as long as the VM has correct network settings. This is beyond the scope of this tutorial. The process to set up and conduct poking is as follows:

Initial Setup (Xbox 360 and Downloading / Building Required PC Software)

 * 1) Obtain or build an RGH / JTAG Xbox 360.  Your 360 must be capable of running unsigned code.
 * 2) Install dashlaunch and a dashboard of your choosing (Aurora is a good choice these days).
 * 3) (If you do not have a devkit) Obtain xbdm.xex, copy to your 360's hard drive, and add it to your dashlaunch plugins.  Restart to ensure the xbdm.xex plugin is loaded.
 * 4) Connect to your RGH/JTAG 360 via Xbox Neighborhood and ensure that you have access to it (to confirm Neighborhood has a good connection).
 * 5) Obtain a copy of the game and copy the map file that you wish to modify to your computer via a FAT32 formatted USB (preferred) or via FTP (slow, but will work).
 * 6) Install the latest version of Visual Studio (2022 as of writing).
 * 7) Obtain and install the Xbox 360 SDK (containing Xbox Neighborhood).  Google is your friend here.
 * 8) (optional) Install git.  Git can be used to clone the repository for Assembly - one tool (among other options) that can be used to poke - and can be used to navigate between branches as well as pull down up to date code from the repository (beyond the scope of this tutorial).

Git Clone and Compile Assembly

 * 1) Clone the git repository (or otherwise download the full source) for Assembly and open the solution file located in "/src".  This file is called "Assembly.sln".
 * 2) Visual Studio will prompt you to download the required packages (C++ Development, and .NET Development).  Select download and allow to complete, restarting if prompted.
 * 3) Retarget the solution to the latest installed version of the Windows SDK by right clicking on the solution (called "Solution 'Assembly' (9 of 11 projects)" at the very top of the "Solution Explorer", and selecting "Retarget Solution", then selecting "OK".
 * 4) At the bar near the top, select the build configuration "Release", by clicking on the drop box which says "Debug", and selecting "Release".
 * 5) Click the "Build" option on the top bar, and select "Rebuild Solution".  Allow this process to finish.  Once complete, if no errors result, Assembly will be compiled.
 * 6) Create a shortcut to your newly compiled Assembly binary in a location of your choosing.  The compiled Assembly binary is located in "/src/Assembly/bin/x64/Release/Assembly.exe".  Assembly is now ready to use.

Patch default.xex in Preparation for Poking
The default.xex file has cryptographic checks that will cause the game to fail in the event a modification is loaded. It is unclear whether this check is triggered in the event of live poking, or just when patching a map and launching. To ensure no issues, patch the default.xex file as stated in the above section, and copy this modified default.xex along with all the other game files to your 360's harddrive.

Poke Map

 * 1) PC: Launch Assembly and click "Tools -> Settings" in the toolbar, and click on "Xbox 360 Development" in the new tab that launches.  In "Xbox Name/IP", fill out your 360's IP address (or Dev Name - usually "Jtag" - if easier).
 * 2) PC: Open the .map file that corresponds to the map you wish to poke on your 360.
 * 3) Xbox 360: Launch Halo with the modified default.xex.
 * 4) Xbox 360: Load the map up that you wish to modify in Halo and launch a game with that map.
 * 5) PC: Modify your map with the desired changes:
 * 6) (Example replacing Assault Rifle bullets with Rocket Launcher rockets)
 * 7) Click on "Tags" in the window that opens.
 * 8) Scroll down to "weap" and click the triangle to expand the menu.
 * 9) Click on "objects\weapons\rifle\assault_rifle\assault_rifle".
 * 10) Scroll all the way down (about 80% down) to the field: "Projectile".  Note the box that says: "objects\weapons\rifle\assault_rifle\projectiles\assault_rifle_bullet".
 * 11) Click on this box, which will produce a drop down menu.  Select "objects\weapons\support_high\rocket_launcher\projectiles\rocket_launcher_rocket".
 * 12) Click the "Poke" button at the bottom of the screen.  You should see a small success message indicating that the changes have been poked.
 * 13) If you get an error message stating that Assembly is "Unable to connect...", check your xbdm.xex file (redownload and ensure it's the same), that it's loaded properly in dashlaunch, and that your PC is on the same network and that Xbox Neighborhood still has a connection to the Xbox (by being able to traverse the hdd and caches).
 * 14) Your ARs will now shoot Rockets in game (be careful, you'll kill yourself if you're not careful).