uLua Documentation v2.2.0

This update adds more options for exposing game objects to Lua and tweaks the Lua API behaviour when Unity scenes are changed.

API.cs:

• The Lua API will now fully reset when a new Unity scene is loaded.
• Added a DontDestroyOnLoad option to the inspector UI.
• Fixed a bug which prevented non-global Lua objects from automatically registering event handlers.

Lua.cs

• Logging functions have been moved to the API class. Their implementation in Lua.cs is deprecated.

ExposedMonoBehaviour.cs

• Implemented the option to expose objects on scene load events (ExposeOn.OnSceneLoaded).
• Added a new method OnExpose() which can be overridden in derived classes.
• The Register() method has been deprecated.

LuaClass.cs

• The Register() method has been deprecated.

uLua Documentation v2.1.0

This update adds support for a Lua debugger and significantly improves error reporting for Lua scripts. For instructions on how to set up the debugger, read section 8 in the documentation of this version.

API.cs:

• Significantly improved error messages for errors in Lua scripts. The majority of errors should now include the filename of the script that caused the exception.
• Added support for the MoonSharp Visual Studio Code debugger. The debugger can be enabled with the 'Enable Debugger' option in the inspector. To attach the debugger to your scene, you must use set up a Visual Studio Code workspace. Read section 8 in the documentation for detailed instructions.
• Added a MainResourcesFolder variable which is used by the debugger to locate resource scripts.

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 [email protected] for additional support.

uLua Documentation v1.3.2

This update contains various bug fixes.

uLua/ScriptLoader.cs:

• Fixed a bug which caused the script loader asset path to be set to null, preventing the script loader from working.

uLua/Lua.cs:

• Fixed a bug which caused the NewFunction property to always incorrectly return a null value.

uLua/LuaClass.cs:
uLua/LuaMonoBehaviour.cs:

• The code defined in the Register function will now always overwrite previous function definitions.

uLua Documentation v1.3.1

This update implements support for Lua's script loading functions 'require' and 'loadfile', and fixes an issue with Lua objects.

uLua/ScriptLoader.cs:

• Added a custom script loader to implement support for the Lua 'require' and 'loadfile' functions. Read the latest documentation for more information on how to use these functions.

uLua/LuaClass.cs:
uLua/LuaMonoBehaviour.cs:

• Changed the Handle property to support multiple levels of Lua contexts.

Specifically, in the following structure of Lua objects:
Parent1.Parent2.Parent3.MyObject

MyObject.Handle will now correctly return the full global handle "Parent1.Parent2.Parent3.MyObject", instead of "Parent3.MyObject" which was returned until now.

uLua Documentation v1.3.0

This version introduces a new feature called Script Packages which lets users organise Lua scripts and control the order of execution. Technical details are listed below.

uLua/ScriptPackage.cs:

• Added a new class ScriptPackage which contains information about a script package, such as its name, description, version, list of contents, and dependencies, etc.

uLua/API.cs:

• Added support for execution of scripts from folders located in the directory specified by ScriptPackagesPath. The specified directory is parsed for folders which contain a json file with the structure dictated by the ScriptPackage class. Scripts contained in these folders are executed as a package. Properties defined in the json file can control the execution order, dependencies, and load behaviour of the script package. For more information and examples on how to structure a script package read section 2.4 in the documentation.
• Methods AddUserScript, ClearUserScripts, and RemoveUserScript have been made obsolete.

Other:

• Support for Unity Editor versions 2019.4 and 2020.3 is discontinued with this release.

uLua Documentation v1.2.1

This version introduces two new features. A blacklist for user API calls, and the ability to specify the Lua name of an ExposedMonoBehaviour component. Technical details are listed below.

uLua/API.cs:

• Added an API blacklist for user scripts. Using the UserBlacklist option on the Unity inspector, you can exclude specific Lua globals from being available in user scripts.

uLua/LuaMonoBehaviour.cs:

• Added the option to assign a Lua name to LuaMonoBehaviour scripts. To use this feature, use the Name option on the Unity inspector, or the Name field in a script. If a name is not specified, the game object's name will be used by default.

uLua/Lua.cs:

• Added a warning for when a Lua global is reassigned using the Lua.Set() method.

uLua Documentation v1.2.0

This version introduces a new simplified syntax for the base classes ExposedClass and ExposedMonoBehaviour. It is recommended to update your code to use the new implementation which does not require use of generic parameters. The previous syntax will still work, however it is now deprecated. Specific changes are detailed below.

In addition, a new feature is implemented which allows C# methods of ExposedClass and ExposedMonoBehaviour to be overriden in Lua. Methods can be declared as overridable using the [AllowLuaOverride] attribute.

uLua/API.cs:

• Added a new RegisterIndexedType() method to replace the previously used RegisterIndexedType<T>(). These two methods are identical in functionality.

uLua/ExposedClass.cs:

• Added a new ExposedClass script to replace the previously used ExposedClass<T>. These two scripts are identical in functionality.

uLua/ExposedMonoBehaviour.cs:

• Added a new ExposedMonoBehaviour script to replace the previously used ExposedMonoBehaviour<T>. These two scripts are identical in functionality.
• Added a Manual option to the ExposeOn enum. This is equivalent to None, but may be used to differentiate between scripts which will be manually exposed and those which are not intended to use in Lua.

uLua/IndexedUserDataDescriptor.cs:

• Added a new IndexedUserDataDescriptor class to replace the previously used IndexedUserDataDescriptor<T>. These two classes are identical in functionality.
• Added the [AllowLuaOverride] attribute and implemented it in the indexed data descriptor.

uLua Documentation v1.1.2

This version adds some new functionality to the default Lua API and makes improvements to exception handling. The changes are detailed below.

uLua/API.cs:

• The Invoke() function may now be called within Lua as a global.
• Improved exception handling for various methods.

uLua/ExposedClass.cs:
uLua/ExposedMonoBehaviour.cs:

• Improved clean-up when exposed objects are destroyed.

uLua/Lua.cs:

• Improved functionality for message, warning, and error logging. The following methods are now used: Log(), LogWarning(), LogError(). These methods each trigger a Lua event when called: "LuaMessageLogged", "LuaWarningLogged", and "LuaErrorLogged" correspondingly.
• Improved exception handling for various methods.

uLua Documentation v1.1.1

This version includes mostly bug fixes. The changes are detailed below.

uLua/API.cs:

• Fixed various bugs related to changing Unity scenes.
• Added the Lua API commands LogError() and LogWarning() to raise errors and warnings from Lua in Unity.
• Added an "OnSceneUnloaded" event call which is called when a unity scene is unloaded.

uLua/ExposedClass.cs:
uLua/ExposedMonoBehaviour.cs:

• Prevented unnecessary warning messages from being generated by "OnLoad" and "OnExit" callback calls.

uLua/Lua.cs:

• Fixed a runtime exception caused by passing a null object parameter to ValueToLuaValue().