Lua in SWBFII

Star Wars Battlefront II uses Lua 5.0.2 as an easier (than C++) method of interacting with the underlying game engine (Lua 5.0.2 binaries have been posted here if you wish to use/play with the Lua 5.0.2 interpreter on your PC).

There are 2 Lua environments in the SWBFII game.

1. The Menu/shell Lua space.
2. The 'ingame' Lua space.

Stock SWBFII Files containing Lua code

1. 'common.lvl'
2. 'shell.lvl'
3. 'mission.lvl'
4. 'ingame.lvl'

The menu/shell Lua space

The main 'interesting' script for the menu space is 'shell_interface.lua' (inside shell.lvl). On startup it looks like the game does the following (albeit from C++):

StartShellLuaEnv()          -- this is not a 'Lua' call; this refers to C++ starting up the lua env
ReadDataFile("core.lvl")
ReadDataFile("common.lvl")  -- I'm not actually sure if 'core.lvl' or 'common.lvl' is read in first.
ReadDataFile("shell.lvl")
ScriptCB_DoFile("shell_interface")
AddMods()                   -- this is not a 'Lua' call; this refers to the C++ code looking for and adding the mods/DLC

The ingame Lua space

The main 'interesting' script for the in-game lua space is 'game_interface.lua' (contained inside 'ingame.lvl'). When starting a map it looks like the game does the following:

-- Note: Some of this code looks like Lua, but it's all basically called from the C++ side.
StartGameLuaEnv()                          -- this refers to the operation of starting up the Lua env from the C++ code. 
mission_file   = GetMissionLVL()           -- this refers to the operation of finding the correct 'mission.lvl' file to load
mission_script = GetMissionScriptName()    -- this refers to the operation of finding out which script belongs to the mission
core_file      = GetMissionCoreLVL()       -- this refers to the operation of finding which 'core.lvl' file to load (for strings)
ReadDataFile(core_file)
ReadDataFile("common.lvl")
ReadDataFile(mission_file)
ScriptCB_DoFile(mission_script)
ScriptCB_DoFile("game_interface")
Execute("ScriptPreInit")
Execute("ScriptInit")
Execute("ScriptPostLoad")

Passing data between shell and ingame lua environments

ScriptCB_SaveMissionSetup and ScriptCB_SaveLoadMissionSetup (passes a table).

For saving Galactic Conquest progress to a file, you have ScriptCB_SaveMetaGameState and ScriptCB_LoadMetaGameState (combined with a saveOP).

ReadDataFile

The 'ReadDataFile' function reads in a file's contents into the game space it can add new items into the environment as well as replace items in the environment.

An example of something that gets replaced a lot is the 'addme' Lua script. A device may have 'n' mods with 'n' addme scripts. When the game reads in an "addme.script" file the newly read in 'addme' script replaces the last one. It is however the only script that we seem to be able to replace. When I’ve tried replacing other scripts it didn’t work, I had to name them uniquely in order to load them.

Passing data from the 'Shell' space to the 'ingame' space

Used primarily for Galactic conquest the game does the following from a mission to read in data from the 'shell' space.

    -- from spa3c_ass
    -- load sky dome
    local world = "kas"
    if ScriptCB_IsMissionSetupSaved() then
        local missionSetup = ScriptCB_LoadMissionSetup()
        world = missionSetup.world or world
    end
    ReadDataFile("SPA\\spa_sky.lvl", world)

And it can be saved like this from the shell space:

    -- from ifs_freeform_main.lua
    ScriptCB_SaveMissionSetup(missionSetup)