Scripted levels
Introduction
The scripts allow to a level to become dynamic : change some physic settings, move objects, ... A script is written in the Lua language and can be included in a level file.
To write a script, you must know a little about a level file. It is an xml file. It includes somes properties like the name of the level, it's description, ... Moreover, it includes blocks' and sprites' definitions. A block is composed of vertex which are the points to link to draw polygon.
To present the way to write a script, the simple following level example will be used :
<?xml version="1.0" encoding="utf-8"?> <level id="tutscript"> <info> <name>tutscript</name> <description></description> <author></author> <date></date> <sky>sky1</sky> </info> <script> </script> <limits left="0" right="50" top="30" bottom="0"/> <block id="Block0"> <position x="0" y="0"/> <usetexture id="default"/> <vertex x="5" y="5"/> <vertex x="5" y="10"/> <vertex x="10" y="10"/> <vertex x="10" y="5"/> </block> <entity id="MyPlayerStart0" typeid="PlayerStart"> <size r="0.4"/> <position x="7.5" y="10"/> </entity> <entity id="Strawberry0" typeid="Strawberry"> <size r="0.4"/> <position x="20" y="0.5"/> </entity> <entity id="SnowMan0" typeid="Sprite"> <param name="name" value="SnowMan"/> <position x="19" y="0.2"/> <param name="z" value="-1"/> </entity> <zone id="Zone0"> <box left="40" right="50" top="5" bottom="0"/> </zone> </level>
This level can be made easyly with the xmoto level editor. It mainly includes a block called Block0 which is a square, a strawberry called Strawberry0 and a zone called Zone0. A zone is an invisible part of the level to execute actions when the player is around it. Some functions require a minimum xmoto version to work ; if you use one of these function, please put this information in the level like it : <level id="tutscript" rversion="0.2.0">.
All the code of the script is written in Lua. You can found the syntax here. However, if you choose to include the script in an xml file, < and > symbol must be replaced by < and >. The code of the script can be included between <script> and </script> in the level file.
Functions called by XMoto
OnLoad()
Explanation
This function is called one time when the level starts. You must return true if nothing bad appened.
Script example
The example displays a message at the start of the level.
function OnLoad() Game.Message("This level is scripted") return true end
Tick()
Explanation
Function called 1 time every hundreath. You must return true if nothing bad appened.
Script example
This example will initialize gravity to 0 ; then, it will increment it with the time. Because earth gravity is 9.81, the earth gravity will not be reached before the 9.81 seconds. Be aware that in xmoto, vertical gravity must be multiplied by -1 because of screen coords which are reversed.
function Tick() if Game.GetTime() < 9.81 then Game.SetGravity(0, Game.GetTime() * -1) end return true end function Load() Game.SetGravity(0, 0) return true end
Entity.Touch()
Explanation
This function is called when an entity (a strawberry for example) is touched. The entity must be declared in the script. Note that the <size r> parameter allows to choose the distance of the entity which must be considered so that it is touched.
Script example
The example displays a message when the strawberry is touched.
Strawberry0 = {} function Strawberry0.Touch() Game.Message("Nice strawberry !") end
Zone.OnEnter()
Explanation
This function is called when the player enters in a zone.
Script example
The example displays a message when the player enters into the zone Zone0.
Zone0 = {} function Zone0.OnEnter() Game.Message("Entering in the zone") end
Zone.OnLeave()
Explanation
This function is called when the player leaves a zone.
Script example
The example displays a message when the player leaves the zone Zone0.
Zone0 = {} function Zone0.OnLeave() Game.Message("Leaving the zone") end