View source for Lua Scripts

= 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:

<source lang="lua">
module(..., package.seeall)
debug.ReloadScripts.allowReload(...)
</source>


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

<source lang="lua">
require "myscripts"
</source>

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 [http://en.wikipedia.org/wiki/CamelCase 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''.

<source lang="lua">
require "myScripts"
</source>

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

<source lang="lua">
require "foo.bar.myScripts"
</source>


== Adding Functions to your script ==

So let's add a function:

<source lang="lua">
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
</source>

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:

<source lang="lua">
tmpVar = myscripts.findEntity("Foobar")
</source>

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

<source lang="lua">
return tmpVar
</source>

== 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:

<source lang="lua">
local object= findEntity(name)
local transformComponent= object:getTransformComponent()
transformComponent.setPosition(VC3(10,0,0))
</source>

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

<source lang="lua">
myscripts.myFunction()
</source>

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 ''<nowiki>{{Trine 2 folder}}\log\console.log</nowiki>'', which would be, by default:
<pre>
C:\Program Files (x86)\Steam\steamapps\common\Trine 2\log\console.log
</pre>

== TrineFUILoadingScreenComponent ==

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

<source lang="lua">
-- 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!")
</source>

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