Lua scripting

Article under construction

Lua scripts and proceses are similar to that of macros and dialogue conditionals, where a series of operations and checks are made in order to allow players to essentially mod the game by adding new gameplay mechanics.

The feature is wrapped inside classic macros and dialogue trees in the form of two main dialogue actions:

OrcLuaScript

This action will inject a lua script into your orc. Normally, the injection only initializes the script and keeps it in memory, so that no further injections are necessary. A good use of this action would be to place it at the very beginning of your macro and have its code nested under handy functions that we call later using a different action. Further executions of the same action on the same macro line will not re-inject the code when an instance of the same lua script with the same ID name already exists, so you can safely loop through your macro as usual without having it re-interpret your action's script.

Here is an example of a lua script to be injected:

function start ()

    if orc.game.sceneis ('Outback1') then

        -- give him the pipe from the start

        orc.game.consolecommand ('asset bopipe')

        if orc.game.consoleasset == nil then

            orc.consolecommand ('batch target @self;asset World/Items/Pipe1;assetnameset bopipe;hrattachca;assetpos -0.0289,0.0571,-0.0238,-21.348,-118.294,217.56,true;assetscalereset')

        else

            orc.consolecommand ('batch target @self;hrattachca;assetpos -0.0289,0.0571,-0.0238,-21.348,-118.294,217.56,true;assetscalereset')

        end

        orc.consolecommand ('forceanim Idle SmokePipe1')

    end

end

This code injects only one function named start that does a series of setup adjustments to the character Bo, in order to have him hold his pipe. Remember that this code is not being executed upon injection; only later on we will call this and any other function that your script contains. Please note that right now it is not possible to include function parameters within the parentheses.

OrcLuaScriptFunction

This action will let you execute any of the functions contained in a lua script that were previously injected using the OrcLuaScript action. It will ask for the ID name of the script that was injected, and the name of the function that you want to execute (for example, the start function from above). Note: functions only need their name provided, without the end parentheses.

Bonfire Lua API

An up-to-date documentation for all the known commands is available at on the Lua API Reference. page.

Stepping up: Advanced Lua execution (for 0.36.0)

So far we've read on how to use Lua from within a macro or dialogue structure. However, if your wish is to directly use Lua and advanced iterators without needing to wrap everything using an old school macro and timed console tricks, a more advanced implementation is available.

Inventory injection

Raw Lua scripts written and saved in the game's %appdata%/Prasetto/Bonfire/Mods/lua can be directly injected into the console @target character's inventory as an item that will be saved within their data, much like the classic macros, using the following command:

oluainj luaScriptName

...where "luaScriptName" is the name of the script file that is saved on the aforementioned %appdata% location in your computer. The name has to be provided as is, without a directory path nor a file extension. If successful, a new item in the form of a Lua parchment will be visible on the character's inventory. It will attempt to initialize and execute any code in your script that isn't wrapped inside a function scope upon first injection.

Iterated execution

Once a Lua script is injected, it will remain in the character's inventory and active process memory for actual execution. The idea is to allow you to either call any of the script's functions directly at any given time, or to create a timed iterator that will execute any of its functions repeatedly for a given amount of time.

Immediate and single execution of an injected Lua script function can be achieved by writing:

oluacf luaScriptName,functionName

While iterated execution can be achieved by writing:

oluaiifr luaScriptName,functionName,executionTime

Additionally, if you wish to stop execution of any previously invoked function iterators from a script, use:

oluaria luaScriptName,functionName

...Or simply write "oluaria" without parameters and it will remove all iterators currently running in the character.

Invoked iterators will also create an inventory entry on the character that represents their ongoing process, meaning that they save with the character and will automatically resume their process upon spawning on the scene. Iterators will also remember their elapsed execution time, unless they were set to run for an "Infinity" amount of seconds, in which case they will last forever unless manually removed.