fungus/Docs/fungus_lua/lua_fungus_module.md

%Fungus Lua Module

[TOC]

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.

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().

-- 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 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.

This is the list of available functions for waiting and working with coroutines.

-- 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.

-- 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')