diff --git a/Docs/fungus_lua/execute_lua.md b/Docs/fungus_lua/execute_lua.md index de3843d9..f3055d19 100644 --- a/Docs/fungus_lua/execute_lua.md +++ b/Docs/fungus_lua/execute_lua.md @@ -1,6 +1,6 @@ -# The ExecuteLua Command {#execute_lua} +# ExecuteLua Command {#execute_lua} -This command allows you to embed a Lua script to be executed as part of a command sequence in a Block. The Lua script to be executed can be specified in the inspector or in a text file, in the same way as in the [Lua Script component](lua_script.md#lua-script-and-files). +This command allows you to embed a Lua script to be executed as part of a command sequence in a Block. The Lua script to be executed can be specified in the inspector or in a text file, in the same way as the @ref lua_script component. You can provide an optional LuaEnvironment to use for the execution. If none is provided then a LuaEnvironment will be selected / created automatically. If a LuaEnvironment has been set on the parent Flowchart then that environment will be used by default. @@ -10,7 +10,7 @@ You can also store the return value from the Lua script in a Flowchart variable. # Evaluating expressions -The Fungus If command can only compare 2 variables at a time. For more complex expressions involving multiple variables or [math functions](http://lua-users.org/wiki/MathLibraryTutorial), you can use Lua to evaluate the expression and store the result in a Flowchart variable. +The Fungus If command can only compare 2 variables at a time. For more complex expressions involving multiple variables or [math functions], you can use Lua to evaluate the expression and store the result in a Flowchart variable. 1. Add a Flowchart object (Tools > Fungus > Create > Flowchart). Add some variables to the Flowchart. 2. Add a LuaBindings object (Tools > Fungus > Create > LuaBindings) @@ -34,3 +34,5 @@ return (v1.value == v2.value or v3.value == 5) ``` Don't forget to use .value to access the value stored in the variable object, rather than the variable object itself! + +[math functions]: http://lua-users.org/wiki/MathLibraryTutorial \ No newline at end of file diff --git a/Docs/fungus_lua/fungus_module.md b/Docs/fungus_lua/fungus_module.md index 97a978ac..1d599936 100644 --- a/Docs/fungus_lua/fungus_module.md +++ b/Docs/fungus_lua/fungus_module.md @@ -18,7 +18,7 @@ inspect(v) # Running Unity coroutines -When you bind to a C# component using Lua Bindings, you can access any public method in the class. If a method returns IEnumerator then that method can be executed [as a coroutine](http://docs.unity3d.com/Manual/Coroutines.html), which is a powerful way to run asynchronous code. +When you bind to a C# component using Lua Bindings, you can access any public method in the class. If a method returns IEnumerator then that method can be executed as a [Unity coroutine], which is a powerful way to run asynchronous code. The runwait() function allows you to call a C# coroutine method from Lua which may take multiple frames to finish its work, and then carry on with the rest of the Lua code once that C# method has finished executing. This is how the say() function works for example. @@ -58,4 +58,6 @@ sub('a string') -- Use Fungus Variable fungus.sub('a string') -``` \ No newline at end of file +``` + +[Unity coroutine]: http://docs.unity3d.com/Manual/Coroutines.html \ No newline at end of file diff --git a/Docs/fungus_lua/controlling_fungus.md b/Docs/fungus_lua/lua_controlling_fungus.md similarity index 95% rename from Docs/fungus_lua/controlling_fungus.md rename to Docs/fungus_lua/lua_controlling_fungus.md index d3afb826..eb9e6bb4 100644 --- a/Docs/fungus_lua/controlling_fungus.md +++ b/Docs/fungus_lua/lua_controlling_fungus.md @@ -95,7 +95,7 @@ end say "End options" ``` -A useful pattern is to use choose() together with Lua's goto statement and labels. This can be handy for 'flattening out' nested menu options. The [goto statement](http://lua-users.org/wiki/GotoStatement) doesn't support jumping into the scope of a local variable, but it's easy to work around this by declaring the local variable in the outer scope. You could also use a global variable (by not using the local keyword). +A useful pattern is to use choose() together with Lua's goto statement and labels. This can be handy for 'flattening out' nested menu options. The [goto statement] doesn't support jumping into the scope of a local variable, but it's easy to work around this by declaring the local variable in the outer scope. You could also use a global variable (by not using the local keyword). ```lua local choice = 0 @@ -174,7 +174,7 @@ Stage portraits can be controlled by using the stage. First, add your characters and stage to the LuaBindings list. -![Lua Stage Binding](images/lua_stage_binding.png) +![Lua Stage Binding] Then, in a lua script, use the stage commands show, showPortrait and hide to control the portraits on stage. @@ -216,7 +216,7 @@ sherlock: Greetings. ]] ``` -The conversation system is [documented here](../conversation/index.html#lua). +See the docs for the @ref conversation "Conversation System". # Flowchart functions @@ -264,3 +264,8 @@ getvar(flowchart, varname) -- nowait: If false, will yield until the Block finishes execution. If true will continue immediately. runblock(flowchart, blockname, commandindex, nowait) ``` + +[goto statement]: http://lua-users.org/wiki/GotoStatement + +[Lua Stage Binding]: fungus_lua/lua_stage_binding.png + diff --git a/Docs/fungus_lua/lua_fungus_module.md b/Docs/fungus_lua/lua_fungus_module.md new file mode 100644 index 00000000..97a978ac --- /dev/null +++ b/Docs/fungus_lua/lua_fungus_module.md @@ -0,0 +1,61 @@ +# Fungus Module {#lua_fungus_module} + +This Lua module provides handy functions for working with Lua, Unity and Fungus. + +In this page we cover some of the more generic functionality in the module, other major features are described elsewhere in the documentation. + +# Inspecting Lua objects + +You can use Lua's built in print() function to get a basic description of any object printed to the console. When you want to get a more detailed description of an object, use inspect(). + +```lua +-- Prints a short description of object v +print(v) + +-- Prints a summary of object v in a human readable format. +inspect(v) +``` + +# Running Unity coroutines + +When you bind to a C# component using Lua Bindings, you can access any public method in the class. If a method returns IEnumerator then that method can be executed [as a coroutine](http://docs.unity3d.com/Manual/Coroutines.html), which is a powerful way to run asynchronous code. + +The runwait() function allows you to call a C# coroutine method from Lua which may take multiple frames to finish its work, and then carry on with the rest of the Lua code once that C# method has finished executing. This is how the say() function works for example. + +This is the list of available functions for waiting and working with coroutines. + + +```lua +-- Waits for a number of seconds, then continue execution of Lua script +wait(duration) + +-- Waits until the Lua function provided returns true, or the timeout expires. +-- Returns true if the function succeeded, or false if the timeout expired +waitfor(fn, timeoutduration) + +-- Run a C# coroutine and continue execution of Lua script +run(co) + +-- Run a C# coroutine, wait until it completes, then continue execution of Lua script +runwait(co) +``` + +# Globals vs Table mode + +The Fungus module can be used in three modes, controlled by the Fungus Module option in the LuaUtils component. + +1. Use Global Variables: all module functions are mapped to global functions. This allows for convenient access, but it runs the risk that you might accidentally declare a variable with the same name as a Fungus module function. +2. Use Fungus Variable: all module functions are accessed through a global table called 'fungus'. This gives a degree of namespace safety at the cost of more typing. +3. No Fungus Module: the Fungus module will not be registered. Used if you don't want to use the Fungus module. + +Options 1 and 2 are functionaly equivalent, it's just a matter of personal preference which you want to use. + +```lua +-- sub is a function in the Fungus module, mapped to a global variable + +-- Use Global Variables +sub('a string') + +-- Use Fungus Variable +fungus.sub('a string') +``` \ No newline at end of file