Welcome to Open Carnage

A resource for Halo Custom Edition and MCC modding, with unique means of rewarding content creation and support. Have a wander to see why we're worth the time! - EST. 2012


Update: New scripting API

I've been thinking more about the new scripting API, and having talked with a few other people, we found this to be the best thing for Chimera (and Halo modding in general) moving forward.


There are two key things:

  • No functions for reading/writing to arbitrary memory addresses
  • More functions for reading/writing values of objects, gametypes, players, etc.


Let's refill the ammo of the player's weapons, for example. In the Lua API, you do something like this:

local player = get_player(PlayerIndex)
local dynamic_player = get_dynamic_player(PlayerIndex)

if dynamic_player ~= nil then
    for w = 0,12,4 do
        local weapon = read_dword(dynamic_player + 0x2F8 + w)
        if weapon ~= nil then
            write_float(weapon + 0x23C, 0)
            write_float(weapon + 0x240, 0)
            local weapon_tag_data = read_dword(get_tag(read_dword(weapon)) + 0x14)
            local magazine_count = read_dword(weapon_tag_data + 0x4F0)
            local magazine_address = read_dword(weapon_tag_data + 0x4F4)
            for m = 0,magazine_count-1 do
                local maximum_reserved_ammo = read_word(magazine_address + 0x8 + m * 112)
                write_word(weapon + 0x2B6 + m * 0xC, maximum_reserved_ammo)
                local maximum_loaded_ammo = read_word(magazine_address + 0xA + m * 112)
                write_word(weapon + 0x2B8 + m * 0xC, maximum_loaded_ammo)


Using addresses requires assuming that everything uses the same offset. This might not be the case on some versions of the engines for some things. In theory, the same code above could be represented with this code instead:

local player = engine.get_player(player_index)
local dynamic_player = player.get_object()

if dynamic_player ~= nil then
    for w = 0,dynamic_player.get_weapon_count()-1 do
        local weapon = dynamic_player.get_weapon(w)
        for m = 0,weapon.get_magazine_count()-1 do
            local maximum_reserved_ammo = weapon.get_maximum_reserved_ammo(m)
            weapon.set_reserved_ammo(maximum_reserved_ammo, m)
            local maximum_loaded_ammo = weapon.get_maximum_loaded_ammo(m)
            weapon.set_loaded_ammo(maximum_loaded_ammo, m)

Using functions does not require this assumption, as the mod handles this for you. This guarantees that your script will be portable for any version of the game that uses this scripting API.


There may be some things that will only be possible in the older API that will not be possible in the new API, so the older API isn't going to be going away any time soon, even if I start on the newer API. However, note that anything that uses the older API will be stuck on its respective game. The new API, on the other hand, is intended to be portable, and it may be ported to other versions of Halo: Combat Evolved such as MCC (if MCC ever becomes viable to mod lol), and since these read/write functions may not work very well on non-Gearbox versions due to completely different addresses/offsets/signatures, the older API won't be ported over.


I'm still planning on expanding the older API with newer functions, events, etc. It isn't going to be inferior to the newer one (besides the portability and verbosity), but note that it'll always be a product of its time (after all, doing things like this is how we've always modded Gearbox Halo, right?), and using it isn't advised if you want your script to work beyond whatever version(s) of the game you wrote it for.


For some people who prefer the old ways of modding, I imagine they'll be fine just targeting Halo Custom Edition, retail Halo PC, and maybe even the demo version (of course, there's no way to detect what versions a script that uses the older API will work on, so it'll be up to the community to do that).


For people getting into scripting as well as some more seasoned script writers who want to get back into modding Halo through Lua scripting, they may find the newer API's verbosity and portability to make their lives easier and their scripts more pleasant to read and write.


Update (2020-11-18): I wrote down that I was going to use, but due to the apparent lack of support and updates for it, I might decide against that. Its forum is kinda dead, so, yeah... I'll probably use Lua for this too.


Update (2011-11-19): Added information regarding the new vs. old API.

Edited by Kavawuvi

Share this post

Link to post
Share on other sites


Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
  • Recently Browsing   0 members

    No registered users viewing this page.