uLua Documentation v2.0.0

What's New in v2.0

This is a major update to uLua addressing and reviewing various aspects of the asset. A number of the changes are listed and explained below.

Script Packages

Script packages were introduced in 1.3.0 as a means for users to organise external scripts and control their order of execution. In this update, the script packages have been reviewed so that they can be defined in Unity's Resource folders inside a project. A package by the same name may be defined as an external script, overriding the internal definition. You may prevent a script package from being overridden using a json parameter called AllowExternalOverride.

These changes give more options for developers who may want to implement a large part of their game logic in Lua.

Script Execution Order

The overall script execution order was reviewed. Lua scripts are now executed in the following order:

1. Script Packages (from Resources)
2. Script Packages (from External directory)
3. Scene Script (from Resources or External directory)
4. External Scripts (general)
5. External Scripts (Scene-specific)

The design intent is for script packages to implement the base game logic and required utilities which subsequent Lua scripts may need.

Registering Events and Event Handlers

The process of registering event handlers has been streamlined. Event handlers are now registered implicitly for all objects but must follow a common naming convention. For example, an event named GameLoaded will implicitly call all functions named OnGameLoaded. In order for the implicit handler registration to work, you must register events early in your project's execution (e.g. on an object's Awake), before any of the event handlers are defined. In addition, all event handlers are automatically removed when an object is destroyed.

Built-in Lua functions

You may now customise the default Lua API by disabling built-in functions in the API class inspector. This allows you to select which features you want to use in your Lua code by disabling access to specific functions.

Code Review

A large part of the library has been reviewed for this version. As a result, some variable and class names have been changed, and some variables are no longer available. Efforts have been made to maximise backwards compatibility, but please check the full patch notes if you are running into issues with upgrading.

Some significant changes are listed below:

• ResourcePath and UserScriptsPath were removed from the API class. These were replaced by a single path variable named ScriptsPath.
• EnableResourceScript was renamed to EnableObjectScript for Lua objects.
• "User scripts" are now known as "External scripts" throughout the project.
• The low level interface IHasLuaIndexer has been renamed to ILuaObject.

Deprecated Code

All previously deprecated and obsolete code has been removed with this update.
If you are upgrading from a much older version, you may run into compatibility issues with your previous scripts. This documentation provides up to date instructions on how to use uLua, however, feel free to contact me on support@antsoftware.co.uk for additional support.