Lua Scripts

From Frozenbyte Wiki
Jump to: navigation, search

Lua Scripts

"As a general rule, you can do anything in Lua."

Creating Custom Scripts

Start by creating a file, like myscripts.lua to data/script folder (you can use sub-folders as well). Add following lines to start of the file:

module(..., package.seeall)
debug.ReloadScripts.allowReload(...)


Then edit init.lua in data/script and add following line to the end of the file:

require "myscripts"

You need to restart the editor to get init.lua processed again, but after that you can add functions to myscript.lua and access them in namespace or module names myscripts.

Namespaces and naming

Identifiers

The naming convention used here is lowerCamelCase for module, while file names are lowercase_separated_with_underscores.

This means that if you want a module to be named myScripts the associated file will be named my_scripts.lua.

require "myScripts"

Namespaces and subfolders

If you want to put your scripts under a specific folder tree, let's say foo/bar/my_scripts.lua, the folders will be separated by a dot.

require "foo.bar.myScripts"


Adding Functions to your script

So let's add a function:

function findEntity(name)
	local thingy = common.CommonUtils.getSceneInstanceManager():findInstanceByName(name)
	if thingy then
		logger:info("Myscript.findEntity: Found " .. name)
	else
		logger:error("Myscript.findEntity: Could not find " .. name)
	end
	return thingy
end

If you have editor running, you need to reloadScripts before the changes take effect. So in console (accessed by pressing F8) type reloadScripts() and hit enter (You can also access it under the "Debug->Reload Scripts" menu). Remember to reload scripts everytime you launch the game for a test, Or restart the editor and the changes will take effect permanently.

Now you can test the newly created findEntity function by typing:

tmpVar = myscripts.findEntity("Foobar")

Note that the script prints to Error List, so you can see if it found anything. If it did, variable tmpVar will now contain it. You can see some of it by simply typing in console

return tmpVar

Accessing object properties

Finding what you are looking for is not easy.

You can figure out many things by using TAB autocompletion in console, and know that accessors for everything, such as components and properties, are available.

For example, a snippet accessing an object and moving it:

local object= findEntity(name)
local transformComponent= object:getTransformComponent()
transformComponent.setPosition(VC3(10,0,0))

Check out other scripts in the "scripts" folder and Helpful Lua Snippets page!

Trigger Lua Call

CustomLuaExpressionPropertyAnimationEntity

This entity, found under the Entity->PropertyAnimationEntity tree, allows you to call a Lua script.

Change its Expression property to call your function, for example

myscripts.myFunction()

Change its Immediate property to trigger the call when the game is loaded.

TriggerToLuaCallEntity

This entity can be found under the Entity->TriggerEntity tree.

When triggered by a collector (see Gameplay Events), it executes a lua expression. You can then link it to an AreaCollector, or a lever, or anything.

TriggerToLuaCallComponent's properties

  • Expression : a lua expression, like "myscripts.myFunction()"
  • RunOnce : allow script to be ran only once

Pro Tips

Console Logs

You use the console (F8) to try your script out, and find out what component to call and how to modify it. After you finally get what you want, you can copy-paste it from the console log file into a new lua scripts.

Console log file is accessible under {{Trine 2 folder}}\log\console.log, which would be, by default:

C:\Program Files (x86)\Steam\steamapps\common\Trine 2\log\console.log

TrineFUILoadingScreenComponent

Custom values Public editor users might want to set their own images and stories via Lua like this:

-- Making loading screen use custom values
trineLoadingScreenComponent:setInitializeToDefaultValues(false)

-- Setting image file paths (not sure if modders can add images)
trineLoadingScreenComponent:setChapterImagePath("path/to/the/chapter/image.png")
trineLoadingScreenComponent:setChapterTextPath("path/to/the/chapter/text/image.png")

-- Setting custom story texts (should not be used with ChapterTextPath as it occupies the same space as these)
trineLoadingScreenComponent:setTitleNumber("Part 13")
trineLoadingScreenComponent:setTitleText("This is a title")
trineLoadingScreenComponent:setStoryText("Once upon a time...\n\n...and then...\n\nThe End!")

TitleText and StoryText can also be locale keys if modders have acces to those.