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. 14th of February, 2012

Sign in to follow this  
Followers 0

A new way to write LUA SAPP scripts



If you have written advanced LUA scripts for SAPP, you will quickly realize that the size of the file can grow dramatically, to well over 1k+ lines. This can be very inefficient for busy bodies like myself who don't have a lot of time to work on halo projects.


In my experience of LUA scripting, I have realized there are 4 main components of a LUA script that can be abstracted:

  1. API version, Global values used by LUA scripts (BIPED_ID tables for biped switching, tables that store directories for biped models, etc.)
  2. Callbacks (OnScriptLoad callback definitions & implementations)
  3. Functions (That you can call from callback implementations to make them look neater. This also includes utilizing the prototype model to implement complex classes)
  4. Cleanup for OnScriptUnload


Using this utility, you can now initialize an empty project that gives you a template project to start from. This template consists of:


callbacks (directory)

  • callbacks.lua --> allows you to implement your callbacks in this single file.
  • NOTE: You can make as many files in here as you want. You can even implement each callback in a separate file. 

definitions (directory)

  • config.lua --> allows you to define basic config (API version)
  • definitions.lua --> allows you to define callbacks in this file (OnScriptLoad)
  • garbage_collection.lua --> allows you to define your garbage collection in this file. (OnScriptUnload)
  • variables.lua --> allows you to define global variables in here.
  • NOTE: You can make as many files in here as you want. 

functions (directory)

  • functions.lua --> utility functions that you call from your callback functions (So that you don't clutter your callback implementations)
  • NOTE: You can make as many files in here as you want. You can implement all of your utility functions in separate files.

config.lua --> For the API version, and Global values used in LUA scripts (listed above in #1)



Figure 1 - Shows the working directory in VSCode.


Once you are done, you can use the utility to build all of the lua files into one working .lua file.



Figure 2 - Shows the built lua file from the files in Figure 1.




Simply download lua.py located here: https://github.com/Nickzster/Lua-Projects-for-Halo


There are three commands for this utility:

python3 lua.py init <name>

Run this command to initialize a new project. It will create a new directory named the specified <name>, and create the respective files and directories listed in the Introduction section.


Write your LUA script. When you are done, run this command:


python3 lua.py build <name>

This will take all of the LUA files located within the specified directories, and build them into one file, named <name>.lua, that you can then use for Halo.

To better understand how to set up your scripts, the build process builds in the following order:

  1. Builds all of the files in definitions directory, in alphabetical order.
  2. Builds all of the files in the functions directory, in alphabetical order.
  3. Builds all of the files in the callbacks directory, in alphabetical order. 



python3 lua.py help

Displays the two commands in the terminal for reference.


Admittedly, it has been a while since I have messed with SAPP LUA scripting. Before getting back into it, I wanted to build a utility for myself to make this workflow more efficient. If there is anything that I missed, forgot, or made a mistake on, please let me know!


I hope this is helpful for some of you!


*Made some major edits to the original workup, as I thought this was a better layout.

Edited by Nickster5000
x-dec and Tucker933 like this

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
Sign in to follow this  
Followers 0
  • Recently Browsing   0 members

    No registered users viewing this page.