Lua Script Migration

Between 0.8.1 and 0.8.2, the lua scripting system has changed. When you reserialize mods between these versions, the lua scripts will go through an automatic conversion.

Diff Modding

In the new system, lua scripts are diff modded. This means that instead of having to replace the entire file in the base game, you can chose to just add or redefine functions that you want.

For example, the script event_misc.lua contains the following methods:

function STATUS_SCRIPT.Test(owner, ownerChar, context, args)
function MAP_STATUS_SCRIPT.Test(owner, ownerChar, character, status, msg, args)
function MAP_STATUS_SCRIPT.ShopGreeting(owner, ownerChar, character, status, msg, args)
function MAP_STATUS_SCRIPT.SetShopkeeperHostile(owner, ownerChar, character, status, msg, args)
function ITEM_SCRIPT.Test(owner, ownerChar, context, args)
function ITEM_SCRIPT.CastawayCaveShift(owner, ownerChar, context, args)
function ITEM_SCRIPT.SleepingCalderaShift(owner, ownerChar, context, args)
function REFRESH_SCRIPT.Test(owner, ownerChar, character, args)
function SKILL_CHANGE_SCRIPT.Test(owner, character, skillIndices, args)

In the old system, if you wanted to mod just the MAP_STATUS_SCRIPT.ShopGreeting event, you would need to copy the entire event_misc.lua from the base game, modify MAP_STATUS_SCRIPT.ShopGreeting, and save it to your mod.

In the new system, all you need to do is create an event.lua with your custom MAP_STATUS_SCRIPT.ShopGreeting in it, and nothing else.

This makes it easy to maintain scripts, as the base game scripts can change. In the old system, if MAP_STATUS_SCRIPT.SetShopkeeperHostile in the base game changed after you copied over event_misc.lua, you would have had to copy the changed version of that method to your own mod to stay updated. Now in the new system, if you don't redefine the method in your mod, you won't have to worry about it.

This works on all scripts found in the Data/Script folder, and all subfolders except Data/Script/services.

Services behave slightly differently. Originally, creating a new service in the mod would add its events on top of the base game's events. However, it now replaces the original service and removes the base game's event triggers in favor of your new ones.

Breaking Changes

With the diff modding changes, a caveat is that all lua scripts are namespaced. This way, you can reference methods from the base game specifically. However, it means that all scripts need to be moved to a subfolder in the name of your mod's namespace.

For example, your mod has the namespace my_mod, and your scripts are currently in the Data/Script folder of your mod (You can find/specify your mod's namespace in the Mod.xml). In this situation, you should move all your code to a new folder, Data/Script/my_mod

Additionally, your require calls must be updated to specify whether you're importing code from the origin namespace or your own namespace. For example, the header of a zone you created may look like this:

example

You will need to change it to this:

example

If you made custom scripts on your own mod, such as example, you need to instead change the require to reflect your namespace, because the code is in your namespace of mod.

example

your mod must contain the top level script corresponding to .

common.lua, main.lua, include.lua, and event.lua scripts on the top level (as well as the scripts they call, such as common_vars.lua or event_battle.lua),

Before you could just override common_vars, and the base game's common.lua would call it.

Now you have to load it yourself.

There are 3 fundamental scripts that you have to call if you are modding anything downstream of them:

• main.lua: Services
• common.lua: common_*.lua
• event.lua: event_*.lua

Also, due to the change in services, several things must be accounted for:

• If you have services with the same name as those of the base game (debug_tools, menu_tools, upgrade_tools), your service now overwrites the original instead of adding onto it. If you want to add new functionality without overwriting the old, make a new service with a new name.
• The base game's debug_tools service used to have an event for OnMenuButtonPressed. That event has been moved out of the service and into its own service, menu_tools.
• When modding services, you used to need to copy baseservice.lua from the original game's services folder to yours. Now you don't.

Migration Checklist

When you reserialize mods between these versions, the lua scripts will go through an automatic conversion. Some breaking changes detailed in the above section are automatically covered. Some will not.

Items marked with ★ are automatically converted on reserialization from versions <=0.8.1 to >=0.8.2

• ★ Lua scripts are moved to a subfolder based on the mod's namespace.
• ★ References to require "common" become require "origin.common"
• ★ MapStrings is deprecated.
  • ★ This means the initial variable declaration is removed
  • ★ the initialization method is removed
  • ★ Instead of MapStrings, use STRINGS.MapStrings
• ★ All scripts must be loaded from init.lua
• References to your own scripts require "yourscript" changed to include your namespace require "yournamespace.yourscript"
• Services behave differently now (how?)

These are optional changes that you don't have to make, but is good to clean up files or code no longer needed:

• ★ Deleted bin and lib subfolders
• ★ Functions identical to the base game are removed in the mod, for the files of common.lua and event.lua
• Functions identical to the base game are removed in the mod, for the files in ground and zone