Lua automations and limitations

What is Lua?

Lua is a light-weight scripting language. It does not need to be compiled and has support for common concepts, like object-orientation.

You can get an introduction to Lua from the official Lua resources.

Adding Lua automations to your mod

To add Lua automations to your mod you need to add the automation directive to your patch.txt. You can have multiple automations for your mod and they will work independently of each other. Note they do not share variables or runtime at all, if you want to include multiple Lua files in the same runtime, use the standard Lua require() function in your Lua file.

Automation vs mod

We call the scripting capabilities in RaCMAN "automations" because the code is never injected into the system. Instead, what happens when you read or write a value is that a network request is performed to the PS3 to read/write the respective memory. This gives you access to write to any part of the game, even parts of memory that is write-protected to the game itself (like all executable memory in PS3 games).

Limitations

Because all reads and writes use network requests, there are some limitations to what's possible in the game. Perfomance of each operation is extremely dependant on the setup of the automation's user. On a good connection, operations typically take between 0.5ms and 2ms, but a bad connection can take a lot longer, there is no upper bounds on a truly terrible connection.

Scaffolding

All Lua automations need to 3 specifically named functions. You can use this as basic scaffolding:

-- Function that runs once when the automation is loaded.
function OnLoad()

end

-- OnTick runs ever 16ms, so that should be about 60 times per second
-- The `ticks` argument is the current tick, it counts up by 1 for every tick.
function OnTick(ticks)

end

-- This function runs as the mod is being unloaded, either through an execution error or the user unloading the mod manually
function OnUnload()

end

OnLoad

OnLoad is the first function that runs in your automation. It is run as the automation is loaded and will always run before OnTick is ran.

OnTick

OnTick runs once every 16ms to match 60FPS. If your OnTick-function takes more than 16ms to run, all subsequent calls to the tick-function will be skipped. However, the ticks-argument is always incremented by 1, even if the call to it is skipped.

OnUnload

OnUnload is ran as the mod is being unloaded, this is so you can undo any changes made to the game. RaCMAN makes an effort to run this function even if your automation makes an unrecoverable error, but that might not always be the case, depending on the error.