The LuaBindings component allows you map gameobjects and components in your scenes to Lua variables which you can then access in your Lua scripts. You can bind to any component, including standard Unity components, components from the Unity Asset Store and your own custom scripts.
The LuaBindings component allows you map gameobjects and components in your scenes to Lua variables which you can then access in your Lua scripts. You can bind to any component, including standard Unity components, components from the Unity Asset Store and your own custom scripts.
@ -7,7 +7,7 @@ As well as scene GameObjects and components, you can bind to any Unity object in
![LuaBinding](fungus_lua/lua_bindings.png)
![LuaBinding](fungus_lua/lua_bindings.png)
# Adding LuaBindings
# Adding LuaBindings # {#adding_luabindings}
To setup LuaBindings in your scene:
To setup LuaBindings in your scene:
@ -16,7 +16,7 @@ To setup LuaBindings in your scene:
3. The Key field is automatically populated based on the object name. This will be the variable name you use to access the bound object from Lua script. You can change this key to whatever string you prefer.
3. The Key field is automatically populated based on the object name. This will be the variable name you use to access the bound object from Lua script. You can change this key to whatever string you prefer.
4. If the bound object is a GameObject, you can optionally select a component within it to bind to.
4. If the bound object is a GameObject, you can optionally select a component within it to bind to.
# Using a global table
# Using a global table # {#global_table}
The bindings specified in a LuaBindings component are automatically registered as global variables in all LuaEnvironments in the scene at startup.
The bindings specified in a LuaBindings component are automatically registered as global variables in all LuaEnvironments in the scene at startup.
@ -29,11 +29,11 @@ myobjects.camera
Note that by default the LuaBindings component will register its bindings with all LuaEnvironments in the scene. If you don't want this behaviour, deselect the 'All Environments' option and select the specific LuaEnvironment you want to use instead.
Note that by default the LuaBindings component will register its bindings with all LuaEnvironments in the scene. If you don't want this behaviour, deselect the 'All Environments' option and select the specific LuaEnvironment you want to use instead.
# Finding member info
# Finding member info {#finding_member_info}
The Member Info dropdown box lets you to quickly lookup properties and methods for any bound object. When you select a member, a description of the member is displayed together with the Lua script needed to access it. When binding to standard Unity objects, you can also check the API docs to find out more about the supported methods and properties.
The Member Info dropdown box lets you to quickly lookup properties and methods for any bound object. When you select a member, a description of the member is displayed together with the Lua script needed to access it. When binding to standard Unity objects, you can also check the API docs to find out more about the supported methods and properties.
# Register Types option
# Register Types option {#register_types_option}
In order to access a C# type from Lua, that type has to be registered with MoonSharp. When the Register Types option is selected, LuaBindings will automatically register the types of bound objects and all public properties & methods that the type uses.
In order to access a C# type from Lua, that type has to be registered with MoonSharp. When the Register Types option is selected, LuaBindings will automatically register the types of bound objects and all public properties & methods that the type uses.
The %Fungus module provides several functions for working with the standard %Fungus narrative features and flowcharts.
The %Fungus module provides several functions for working with the standard %Fungus narrative features and flowcharts.
@ -7,7 +7,7 @@ You can control Say and Menu dialogs in much the same way you use Say and Menu c
When you use the menu() function, you supply another Lua function to call when that menu option is selected. Make sure to define the function higher up in the file before referencing it in a menu() call. If you don't explicitly set a SayDialog or MenuDialog object to use default ones are created automatically.
When you use the menu() function, you supply another Lua function to call when that menu option is selected. Make sure to define the function higher up in the file before referencing it in a menu() call. If you don't explicitly set a SayDialog or MenuDialog object to use default ones are created automatically.
# Narrative example
# Narrative example # {#narrative_example}
This example Lua script demonstrates some of the Say and Menu dialog functions. To try it out, add a Lua object to the scene (Tools > %Fungus > Create > Lua) and copy this script into the Lua Script text box. You may also need to add an EventSystem object in the scene (GameObject > UI > Event System) so that the menu buttons will respond to user input.
This example Lua script demonstrates some of the Say and Menu dialog functions. To try it out, add a Lua object to the scene (Tools > %Fungus > Create > Lua) and copy this script into the Lua Script text box. You may also need to add an EventSystem object in the scene (GameObject > UI > Event System) so that the menu buttons will respond to user input.
@ -32,7 +32,7 @@ Note: The curly braces syntax means that the list of options is passed as a sing
# Conversation function # {#conversation_function}
The conversation() function allows you to perform long dialogue exchanges with a single function call. Lua's multiline string syntax [[ ]] is handy here. As the conversation() function takes a single string parameter you can also omit the usual function parentheses.
The conversation() function allows you to perform long dialogue exchanges with a single function call. Lua's multiline string syntax [[ ]] is handy here. As the conversation() function takes a single string parameter you can also omit the usual function parentheses.
@ -219,7 +219,7 @@ sherlock: Greetings.
See the docs for the @ref conversation "Conversation System".
See the docs for the @ref conversation "Conversation System".
# Flowchart functions
# Flowchart functions # {#flowchart_functions}
We've added special functions for say() and menu() because these are so common in %Fungus games. To execute any other commands in %Fungus from Lua, you must do it in conjunction with a Flowchart & Block, like this:
We've added special functions for say() and menu() because these are so common in %Fungus games. To execute any other commands in %Fungus from Lua, you must do it in conjunction with a Flowchart & Block, like this:
The LuaEnvironment component manages all the variables, functions, executing code, etc. for a single Lua context, and provides handy functions for loading and running Lua scripts. In order to run Lua code there must be at least one LuaEnvironment component present in the scene.
The LuaEnvironment component manages all the variables, functions, executing code, etc. for a single Lua context, and provides handy functions for loading and running Lua scripts. In order to run Lua code there must be at least one LuaEnvironment component present in the scene.
@ -7,15 +7,15 @@ You can create one via (Tools > %Fungus > Create > LuaEnvironment). You usually
You can use multiple LuaEnvironments in your scene to ’sandbox’ the variables, functions and executing code of independent sets of Lua scripts. If you do this, make sure to specify the appropriate LuaEnvironment when using LuaScript components, ExecuteLua commands, etc. or else they'll just use the first one they find in the scene.
You can use multiple LuaEnvironments in your scene to ’sandbox’ the variables, functions and executing code of independent sets of Lua scripts. If you do this, make sure to specify the appropriate LuaEnvironment when using LuaScript components, ExecuteLua commands, etc. or else they'll just use the first one they find in the scene.
# Remote Debugger
# Remote Debugger # {#remote_debugger}
The 'Remote Debugger' option activates the built-in MoonSharp remote debugger tool. The application will halt execution on the first executed line of Lua code and open a MoonSharp debugger window in your browser. See the [MoonSharp documentation](http://www.moonsharp.org/debugger.html) for more information on using this debugger.
The 'Remote Debugger' option activates the built-in MoonSharp remote debugger tool. The application will halt execution on the first executed line of Lua code and open a MoonSharp debugger window in your browser. See the [MoonSharp documentation](http://www.moonsharp.org/debugger.html) for more information on using this debugger.
# LuaUtils
# LuaUtils # {#lua_utils}
When you create a LuaEnvironment object via (Tools > %Fungus > Create > LuaEnvironment), the created gameobject has another component called LuaUtils which adds many useful features to the basic LuaEnvironment setup. See the @ref lua_utils "Lua Utils" section for more info.
When you create a LuaEnvironment object via (Tools > %Fungus > Create > LuaEnvironment), the created gameobject has another component called LuaUtils which adds many useful features to the basic LuaEnvironment setup. See the @ref lua_utils "Lua Utils" section for more info.
This Lua module provides handy functions for working with Lua, Unity and %Fungus.
The Fungus Lua module provides handy functions for working with Lua, Unity and %Fungus. It is located in FungusLua/Resources/Lua/Fungus.txt and is loaded automatically when you use the Lua Script component.
In this page we cover some of the more generic functionality in the module, other major features are described elsewhere in the documentation.
In this page we cover some of the more generic functionality in the module, other major features are described elsewhere in the documentation.
FungusLua is a simple way to embed Lua scripting into your Unity project. Lua is an easy to learn scripting language so it's a great way to empower artists, writers and designers to use more of the power of Unity.
FungusLua is a simple way to embed Lua scripting into your Unity project. Lua is an easy to learn scripting language so it's a great way to empower artists, writers and designers to use more of the power of Unity.
@ -8,7 +9,7 @@ We made FungusLua in response to requests from the %Fungus community for a way t
FungusLua comes as part of the [%Fungus asset] available on the Unity Asset Store.
FungusLua comes as part of the [%Fungus asset] available on the Unity Asset Store.
# Tutorial Video
# Tutorial Video # {#lua_tutorial_video}
This video shows how to use many of the features available in FungusLua. It's more of a demonstration than a step-by-step tutorial, but hopefully between this video, the docs and the forums you'll have enough to figure it all out :)
This video shows how to use many of the features available in FungusLua. It's more of a demonstration than a step-by-step tutorial, but hopefully between this video, the docs and the forums you'll have enough to figure it all out :)
@ -18,7 +19,7 @@ This video shows how to use many of the features available in FungusLua. It's mo
</div>
</div>
@endhtmlonly
@endhtmlonly
# Using FungusLua On Its Own
# FungusLua without Fungus # {#funguslua_without_fungus}
FungusLua can easily be used on its own if you don't need the rest of the functionality in %Fungus.
FungusLua can easily be used on its own if you don't need the rest of the functionality in %Fungus.
@ -27,13 +28,13 @@ FungusLua can easily be used on its own if you don't need the rest of the functi
The Tools > %Fungus menu will now only show options for creating FungusLua objects. Obviously you won't be able to use %Fungus functions like say(), menu(), etc. anymore, but you can still use LuaEnvironment, LuaBindings, LuaScript to add Lua scripting to your game.
The Tools > %Fungus menu will now only show options for creating FungusLua objects. Obviously you won't be able to use %Fungus functions like say(), menu(), etc. anymore, but you can still use LuaEnvironment, LuaBindings, LuaScript to add Lua scripting to your game.
# About Lua
# About Lua # {#about_lua}
[Lua] is a powerful, fast, lightweight, embeddable scripting language. It is a popular language for game development and supporting user modding. The standard resource for learning Lua is [Programming in Lua].
[Lua] is a powerful, fast, lightweight, embeddable scripting language. It is a popular language for game development and supporting user modding. The standard resource for learning Lua is [Programming in Lua].
![Lua logo]
![Lua logo]
# About MoonSharp
# About MoonSharp # {#about_moonsharp}
[MoonSharp] is an open source implementation of the Lua scripting language written entirely in C#.
[MoonSharp] is an open source implementation of the Lua scripting language written entirely in C#.
The LuaScript component provides an easy way to run Lua scripts in your scene. You can create a LuaScript object via (Tools > %Fungus > Create > LuaScript).
The LuaScript component provides an easy way to run Lua scripts in your scene. You can create a LuaScript object via (Tools > %Fungus > Create > LuaScript).
![LuaScript](fungus_lua/lua_script.png)
![LuaScript](fungus_lua/lua_script.png)
# ExecuteHandler component
# ExecuteHandler component # {#execute_handler}
When you create a LuaScript object, you'll see that it contains a component called 'ExecuteHandler'. This component allows you to specify options for when the Lua script should execute. By default it executes the Lua script when the scene starts, but you can change this to execute after a delay, on every update, on trigger events, etc.
When you create a LuaScript object, you'll see that it contains a component called 'ExecuteHandler'. This component allows you to specify options for when the Lua script should execute. By default it executes the Lua script when the scene starts, but you can change this to execute after a delay, on every update, on trigger events, etc.
If you want to execute a LuaScript from a custom C# script, set On Event to 'Nothing' and instead call the LuaScript.OnExecute() method directly. You can also call the OnExecute() method from a UI event, e.g. a UI Button 'On Click' event.
If you want to execute a LuaScript from a custom C# script, set On Event to 'Nothing' and instead call the LuaScript.OnExecute() method directly. You can also call the OnExecute() method from a UI event, e.g. a UI Button 'On Click' event.
# Lua script and files
# Lua script and files # {#lua_script_files}
You can enter the Lua code you wish to execute directly into the 'Lua Script' text box. You can also put Lua code into a text file in your project and use the Lua File property to execute it.
You can enter the Lua code you wish to execute directly into the 'Lua Script' text box. You can also put Lua code into a text file in your project and use the Lua File property to execute it.
You can also use both options at the same time. In this case, the Lua File contents are loaded first and the Lua Script text is appended to that. This is a handy feature for code reuse and configuration, e.g. create a Lua text file with Lua functions to control your game, and then call those functions from the Lua Script text box.
You can also use both options at the same time. In this case, the Lua File contents are loaded first and the Lua Script text is appended to that. This is a handy feature for code reuse and configuration, e.g. create a Lua text file with Lua functions to control your game, and then call those functions from the Lua Script text box.
# Lua modules and require()
# Lua modules and require() # {#lua_require}
The Lua module system allows you to create reusable packages of Lua code and include these in your Lua scripts. [This tutorial] explains how to write Lua modules. Module files in FungusLua need to be put into a special folder structure so that the Lua require() function is able to locate them.
The Lua module system allows you to create reusable packages of Lua code and include these in your Lua scripts. [This tutorial] explains how to write Lua modules. Module files in FungusLua need to be put into a special folder structure so that the Lua require() function is able to locate them.
@ -33,7 +34,7 @@ local mymodule = require("mymodule")
mymodule.myfunction()
mymodule.myfunction()
```
```
# Error messages
# Error messages # {#error_messages}
When a script contains errors there are a few techniques you can use to track down the source.
When a script contains errors there are a few techniques you can use to track down the source.
@ -70,11 +71,11 @@ For runtime errors, a useful technique is to add print() calls in your code just
MoonSharp includes a remote debugger tool which you can use to step through Lua code and inspect variables. See the @ref lua_environment for more information.
MoonSharp includes a remote debugger tool which you can use to step through Lua code and inspect variables. See the @ref lua_environment for more information.
# Setting the LuaEnvironment
# Setting the LuaEnvironment # {#setting_lua_environment}
By default the LuaScript component will use the first LuaEnvironment it finds in the scene to execute, or create one if none exists. If you want to use a specific LuaEnvironment, set it in the Lua Environment property. This is a good way to keep unrelated sets of Lua scripts sandboxed from each other.
By default the LuaScript component will use the first LuaEnvironment it finds in the scene to execute, or create one if none exists. If you want to use a specific LuaEnvironment, set it in the Lua Environment property. This is a good way to keep unrelated sets of Lua scripts sandboxed from each other.
This option will run the Lua script as a Lua coroutine which is useful for writing asynchronous code via the coroutine.yield() function in Lua. If you don't need to execute your Lua script asynchronously, deselecting this option will avoid the overhead of running as a coroutine. Recommended for advanced users only!
This option will run the Lua script as a Lua coroutine which is useful for writing asynchronous code via the coroutine.yield() function in Lua. If you don't need to execute your Lua script asynchronously, deselecting this option will avoid the overhead of running as a coroutine. Recommended for advanced users only!
A common issue when working with multiple scenes in Unity is how to persist variable values from one scene to the next. By default, all scene objects and their properties are destroyed when you load another scene.
A common issue when working with multiple scenes in Unity is how to persist variable values from one scene to the next. By default, all scene objects and their properties are destroyed when you load another scene.
# The Lua Store component # {#lua_store_component}
The Lua Store component provides an easy way around this when using Lua scripting. A shared global table called ‘store’ is bound in every Lua Environment when the scene starts. This global table persists between scene loads, which means you can set a store variable in one scene, load another scene, then access the same store variable and it will still retain the value you set earlier.
The Lua Store component provides an easy way around this when using Lua scripting. A shared global table called ‘store’ is bound in every Lua Environment when the scene starts. This global table persists between scene loads, which means you can set a store variable in one scene, load another scene, then access the same store variable and it will still retain the value you set earlier.
# Example
# Example # {#lua_store_example}
- Add a LuaStore to the first scene in your game (Tools >%Fungus > Create > LuaStore).
- Add a LuaStore to the first scene in your game (Tools >%Fungus > Create > LuaStore).
The LuaUtils component provides support for simple text localisation.
The LuaUtils component provides support for simple text localisation.
@ -26,7 +29,7 @@ You can use the {$VarName} syntax anywhere that variable subsitution is supporte
You can also extend the %Fungus string substitution system with your own components. Implement the StringSubstituter.ISubstitutionHandler interface in a Monobehavior subclass and then return the modified string from SubstituteStrings().
You can also extend the %Fungus string substitution system with your own components. Implement the StringSubstituter.ISubstitutionHandler interface in a Monobehavior subclass and then return the modified string from SubstituteStrings().
# JSON Format
# JSON Format # {#json_format}
This is an example of the JSON format for the string table. To use this localised string, you would use the {$hello_world} tag.
This is an example of the JSON format for the string table. To use this localised string, you would use the {$hello_world} tag.
@ -45,7 +48,7 @@ This is an example of the JSON format for the string table. To use this localise
}
}
```
```
# Lua Functions
# Lua Functions # {#stringtable_lua_functions}
These Lua functions are available for working with the string table.
These Lua functions are available for working with the string table.
LuaUtils is a component that extends the Lua environment with some commonly used functionality.
LuaUtils is a component that extends the Lua environment with some commonly used functionality.
It can be accessed from Lua scripts via the 'luautils' global variable. This component mostly does a lot of setup work in the background, but it also provides some handy functions for instantiating, finding and destroying gameobjects in the scene.
It can be accessed from Lua scripts via the 'luautils' global variable. This component mostly does a lot of setup work in the background, but it also provides some handy functions for instantiating, finding and destroying gameobjects in the scene.
# Example
# Example # {#lua_utils_example}
Here's an example of the kind of thing you can do:
Here's an example of the kind of thing you can do:
@ -13,7 +14,7 @@ local go = luautils.Find("MyObject") -- Find a game object by name
luautils.Destroy(go) -- Destroy it
luautils.Destroy(go) -- Destroy it
```
```
# GameObject Functions
# GameObject Functions # {#gameobject_functions}
This is the list of GameObject functions provided in luautils.
This is the list of GameObject functions provided in luautils.
@ -39,7 +40,7 @@ Destroy(GameObject go)
GameObject Spawn(string resourceName)
GameObject Spawn(string resourceName)
```
```
# Registering C# Types
# Registering C# Types # {#registering_types}
The most important function of the LuaUtils component is registering C# types so that instances of those types can be accessed from Lua scripts.
The most important function of the LuaUtils component is registering C# types so that instances of those types can be accessed from Lua scripts.
@ -47,7 +48,7 @@ In order to access the members of a C# type from Lua, the type first has to be r
In some cases however, you will need to register a type explicitly. The easiest way to do this is by adding the type's name to the FungusTypes.txt or UnityTypes.txt JSON files referenced by the LuaUtils component. You can also create your own JSON files to register additional types. Note that types that are not contained in the main application DLL will need to use the [namespace qualified type name] in the JSON file.
In some cases however, you will need to register a type explicitly. The easiest way to do this is by adding the type's name to the FungusTypes.txt or UnityTypes.txt JSON files referenced by the LuaUtils component. You can also create your own JSON files to register additional types. Note that types that are not contained in the main application DLL will need to use the [namespace qualified type name] in the JSON file.
If you need to register types directly from C#, or do a more complex type of registration, you can use the MoonSharp UserData class to do this. See the MoonSharp documentation for a list of supported registration methods. A good place to register C# types is in the Awake method of a custom component.
If you need to register types directly from C#, or do a more complex type of registration, you can use the MoonSharp UserData class to do this. See the MoonSharp documentation for a list of supported registration methods. A good place to register C# types is in the Awake method of a custom component.
# Other Utilities
# Other Utilities # {#lua_utils_other}
LuaUtils creates bindings for several useful C# classes and components so that you can access them from Lua script.
LuaUtils creates bindings for several useful C# classes and components so that you can access them from Lua script.
@ -80,7 +81,7 @@ LuaUtils creates bindings for several useful C# classes and components so that y
| test | Support for @ref unity_test_tools (if installed) |
| test | Support for @ref unity_test_tools (if installed) |
| stringtable | The FungusLua localisation @ref string_table |
| stringtable | The FungusLua localisation @ref string_table |
# PODFactory
# PODFactory # {#pod_factory}
Due to limitations in C# / Mono, MoonSharp has limited support for working with Plain-Old-Data (struct) types like [Vector3](http://docs.unity3d.com/ScriptReference/Vector3.html), [Color](http://docs.unity3d.com/ScriptReference/Color.html), etc.
Due to limitations in C# / Mono, MoonSharp has limited support for working with Plain-Old-Data (struct) types like [Vector3](http://docs.unity3d.com/ScriptReference/Vector3.html), [Color](http://docs.unity3d.com/ScriptReference/Color.html), etc.