The Storyboard Engine Lua plugin provides a slightly different execution environment when compared to normal Lua script execution.
Normally a single Lua script serves as the starting point of script execution and all other scripts would be included using the Lua
require() declaration. The Storyboard Lua plugin provides a slightly different loading behavior in that it will pre-load all of the Lua scripts contained in the scripts directory at engine initialization time. The load ordering can be controlled by using the
require statement to explicitly order dependencies. Since the
require mechanism is used to perform the loading, any project files that use the same names as built-in Lua modules (i.e. table.lua, string.lua or io.lua) will generate a load time warning indicating the potential load time resource collision. Care should also be taken with Lua and asset file naming standards with respect to portability as some OSes are case sensitive whereas others are not.
It should be noted that in most OSes the filesystem directory API does not apply any ordering and only utilities like ls and dir apply sorting logic primarily for display purposes. When the Storyboard engine loads Lua files, it loads them based on unsorted content in a directory and hence to manage dependencies as mentioned above the use of Lua
require() declarations is recommended good practice.
A side effect of this early module loading and execution is that any Lua script that is located outside of function blocks will have the opportunity to run before the application is fully initialized. This can be used to seed early execution environments or load preferences before the UI is in place and ready to render. Alternatively, this early initialization is possible by binding a callback to the
In addition to loading all of the script files in the scripts directory, the Lua plugin modifies the package.path variable and ;; default search path to automatically search the scripts directory.
A convenience variable, gre.SCRIPT_ROOT is pushed into the execution environment that contains the path from the current working directory to the scripts directory. This variable can be used to locate additional resource files or to include extra script directories in a manner that is relative to the overall deployment bundle. Each seperate path is delineated by a single ';'.
print("Script base directory: " .. tostring(gre.SCRIPT_ROOT)) -- Look for additional module files in the scripts/modules directory. -- This will search the added directory first package.path = gre.SCRIPT_ROOT .. "/modules/?.lua;" .. package.path