jonetiz / h3randomizer

Character and Weapon Randomizer for Halo 3 on the Master Chief Collection (Steam Only)

Halo 3 Character and Weapon Randomizer

Program that randomizes characters and their weapons in Halo 3 for Halo: The Master Chief Collection. Intended for use in randomized speedruns, or casual playthroughs with random enemies. Feel free to adapt or modify the code. I am more than happy to accept improvements in the form of pull requests.

End-User Usage

ATTENTION: This program uses some very exerpimental or "hacky" methods to accomplish it's goals. Please use at your own risk, and know that any project contributors are not responsible for any potential damages. Feel free to go through the source code at your leisure.

Requirements

• 64-bit Windows Operating System (Should be required for MCC anyway)
• Halo: MCC for PC (Steam only supported currently)

Usage

For self-build instructions, see Build Instructions below.

1. Go to Releases.
2. Download the latest or desired release.
3. Place h3randomizer.exe in it's own directory (it will create files).
4. Launch the game without Anti-Cheat.
5. Run the .exe file as Administrator and it should automatically hook to the game.

Project Contribution

Requirements

• Visual Studio 2022
  • Python Development Module
  • C++ Development Module
• Python 3.9 or Later (3.10.6 preferred)
• Additional Requirements:
  • pymem - used for basic memory access - install via pip install pymem
  • pyinstaller - used to build executable - install via pip install pyinstaller
  • pybind11 - C++ <--> Python binding - installation instructions in link
  • tkinter - used for GUI - included in modern python

Development Process

Having Visual Studio 2022 with the Python and C++ development workflows and all other requirements, simply open the visual studio solution. I've only set things up for Debug configuration, and x64 is required.

Include Paths

The H3Randomizer_CPP visual studio project has some required include directories that should work if your confgiuration is similar to mine (Python 3.10 installed in %LOCALAPPDATA%/Programs/Python310), however there's always a chance that it won't. Below is a list of things to double-check in the H3Randomizer_CPP Project Properties.

Configuration Properties > C/C++ > General > Additional Include Directories:

• {PythonInstallDir}\include
• pybind11\include (if installed with pip, should be in {PythonInstallDir}\Lib\site-packages\pybind11\include)

Linker > General > Additional Library Directories:

• {PythonInstallDir}\libs

Build Instructions

1. Right-click "H3Randomizer_CPP in the Solution Explorer and click "Build".

• This places a few files in H3Randomizer/x64

2. Copy the generated "/x64/Debug/H3Randomizer_CPP.pyd" file to "/H3Randomizer/" (the python project folder).
3. Open a command prompt/powershell in "/H3Randomizer/"
4. pyinstaller main.spec
5. Build should be placed as an exe file in /H3Randomizer/dist

h3randomizer's Issues

Randomizer Incompatible with Windows 11

MCC reportedly hangs when attempting to attach randomizer and is unusable (CPP/backend functions). Reported by Maxlew.

This issue should have been solved by this commit, however I'm creating this issue for posterity and in case similar issues arise in the future.

Covenant Bridge Softlock

Arbiter's phantom pilot after the two scarabs gets randomized causing potential softlocks. Need to find a way to prevent it from being randomized.

Determine the zone set/bsp in which a tag (character/weapon) becomes available

WIP; Two potential ideas:

• Force-load tag at start of level so we don't need to check zoneset/bsp at all, this will also improve variety.
• Detour designer zonesets in scnr tag to our own data and just allow everything to be used in a single zone set, and load that designer zoneset everywhere.

stuck in "Waiting for valid level..."

Handle Marines in Phantoms and Covenant in Pelicans

The solution burnt devised for HCE doesn't seem that it will work quite as simply in H3 due to how jmad tags work, and since I am not very adept at reverse engineering, I may need help.

• Make it possible for ANY npcs to be vehicle_load_magic'd into phantoms and pelicans (ideally any vehicle
• Make it possible for all NPCs to be unloaded from pelicans and phantoms

Potential idea: build a custom map/use mod tools to play around with vehicle_load_magic and try to find function address?

Automatic Updates/JSONify Memory Offsets and things that will be broken on new MCC updates

Shouldn't be too hard.

• Create a JSON file for each update containing all memory and instruction addresses with good documentation of what each thing does
• Grab the game version and check against JSON, if it doesn't match, check this or a different repo for the correspondent JSON file. If game version doesn't have a JSON online, throw an error.
• Document process of gathering each offset so it shouldn't be difficult for new (or downpatched) versions

Update Visual Studio Project Configurations/Paths

Need to update/document include paths in CPP project and update Debug-ConsoleOnly configuration to actually work.

• Update include paths in CPP project to be neutral/not locked to my own directories
• Document required include paths in CPP project in readme.md
• Update Debug-ConsoleOnly to work properly
• Fix the discrepancies between main.pyw and main.py (ie. build only supports main.py but project needs pyw for consoleonly

Reduce Reliance on Hard-coded Tag Data

Currently, the characters and weapons are hardcoded with index, bsp, and string for character weapon class. Ideally, these shouldn't have to be hardcoded; a good start may be reversing h3randomizer.Game.get_tag_string() mentioned in #3, but that may be impossible since datum tags are only coded to the lower 2 bytes; would need to find how the other 2 are coded.

• Determine character datum from tag string (ie. get_tag("grunt") => 0x87AA2618)
• Determine weapon datum from tag string (ie. get_tag("plasma_pistol") => 0xEF260DB0)
• #11

Need to Determine if charspawn R9/Rbx are Consistent

Seems that the Squad and/or Squad Group registers are not consistent given continuing issues on Crow's Nest.

Need to determine if the R9/R14 and/or Rbx/R15 registers are a consistent way of tracking specific enemies - if not, will need to backtrack or step further into the function to find some place that we can still modify character datum and grab some kind of consistent UID.

Enumerate Tag Strings from Datum

Tag strings are loaded into memory in bulk; there must be some way to consistently find and enumerate them. This would reduce the current reliance on hard-coding certain features and make updating a lot easier.