Funtions for Game Events
Contents
- 1 Functions called by XMoto
- 1.1 OnLoad()
- 1.2 Tick()
- 1.3 Entity.Touch()
- 1.4 Entity.TouchBy(player)
- 1.5 Zone.OnEnter()
- 1.6 Zone.OnEnterBy(player)
- 1.7 Zone.OnLeave()
- 1.8 Zone.OnLeaveBy()
- 1.9 OnSomersault(bClockWise)
- 1.10 OnSomersaultBy(bClockWise, player)
- 1.11 OnWheel1Touchs(status), OnWheel2Touchs(status)
- 1.12 OnWheel1TouchsBy(status, player), OnWheel2TouchsBy(status, player)
- 2 Callable Functions
Functions called by XMoto
OnLoad()
Explanation
This function is called one time when the level starts. You must return true if nothing bad happened.
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 hundredth. You must return true if nothing bad happened.
Be aware that if this function use is abusive, levels will not be validated : action function like setBlockPos, setPlayerPos, ... (contrary to request function getBlockPos, getTime, and lua code) require that the information is store into the replay. If you put a setBlockPos call into the Tick function, it will make big replays : around 20 bytes * 100 * 60 / minute => several hundreads of KB / minute To limit this if you really want to call such functions into your level : - first, play your level and check that replay size is under 100 ko - reduce the number of time you call setBlockPos by adding a variable to make this function called not in all Tick() but 1/3 for example - add a zone so that the animation (tick) is called only when you're in this zone - use dynamicBlock or dynamicEntity functions
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
Entity.TouchBy(player)
[require Xmoto >= 0.3.0]
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.TouchBy(player) Game.Message("Player "..player.." takes the strawberry") end
Zone.OnEnter()
Explanation
This function is called when a player enters in a zone.
Script example
The example displays a message when a player enters into the zone Zone0.
Zone0 = {} function Zone0.OnEnter() Game.Message("Entering in the zone") end
Zone.OnEnterBy(player)
[require Xmoto >= 0.3.0]
Explanation
This function is called when a player enters in a zone.
Script example
The example displays a message when a player enters into the zone Zone0.
Zone0 = {} function Zone0.OnEnterBy(player) Game.Message("Player "..player.." enters the zone") end
Zone.OnLeave()
Explanation
This function is called when a player leaves a zone.
Script example
The example displays a message when a player leaves the zone Zone0.
Zone0 = {} function Zone0.OnLeave() Game.Message("Leaving the zone") end
Zone.OnLeaveBy()
[require Xmoto >= 0.3.0]
Explanation
This function is called when a player leaves a zone.
Script example
The example displays a message when a player leaves the zone Zone0.
Zone0 = {} function Zone0.OnLeaveBy(player) Game.Message("Player "..player.." leaves the zone") end
OnSomersault(bClockWise)
[require Xmoto >= 0.2.1]
Explanation
This function is called each time a player make a new somersault. bClockWise is 1 is the somersault is clockwise, 0 if counterclockwise.
Script example
The example displays a message when a player makes a somersault.
function OnSomersault(bClockWise) if(bClockWise == 1) then Game.Message("ClockWise Somersault") else Game.Message("CounterClockWise Somersault") end end
OnSomersaultBy(bClockWise, player)
[require Xmoto >= 0.3.0]
Explanation
This function is called each time a player make a new somersault. bClockWise is 1 is the somersault is clockwise, 0 if counterclockwise.
Script example
The example displays a message when a player makes a somersault.
function OnSomersaultBy(bClockWise, player) Game.Message("Nice ! player "..player) end
OnWheel1Touchs(status), OnWheel2Touchs(status)
[require Xmoto >= 0.2.1]
Explanation
This function is called each time just the wheel 1 touchs the ground or stops to touch the ground. (status is 1 is the ground was not touching and is now touching, and 0 else)
Script example
The example displays the new max duration of a jump each time a new one is done.
max_jump_time = 1.0 -- start at 1 to not count smaller jumps jump_begin = 0.0 touch_1 = false touch_2 = false function OnWheel1Touchs(bStatus) if(bStatus == 1) then updateMax() touch_1 = true else touch_1 = false jump_begin = Game.GetTime() end end function OnWheel2Touchs(bStatus) if(bStatus == 1) then updateMax() touch_2 = true else touch_2 = false jump_begin = Game.GetTime() end end function updateMax() if(touch_1 == false and touch_2 == false) then if(Game.GetTime() - jump_begin > max_jump_time) then max_jump_time = Game.GetTime() - jump_begin Game.Message("New high jump: "..max_jump_time) end end end
OnWheel1TouchsBy(status, player), OnWheel2TouchsBy(status, player)
[require Xmoto >= 0.3.0]
Explanation
This function is called each time just the wheel 1 touchs the ground or stops to touch the ground. (status is 1 is the ground was not touching and is now touching, and 0 else)
Script example
function OnWheel1TouchsBy(status, player)
if(status == 1) then Game.Message("Player "..player.." touches with wheel 1") end
end
function OnWheel2TouchsBy(status, player)
if(status == 1) then Game.Message("Player "..player.." touches with wheel 2") end
end
Callable Functions
GetTime()
Explanation
Return the time since the start of the level.
Script example
The example displays a message if the player takes more than 10 seconds to enter the zone.
Zone0 = {} function Zone0.OnEnter() if Game.GetTime() > 10.0 then Game.Message("10 seconds to come there, that's a lot !") end end
Message(msgs)
Explanation
Display a message on the screen. The message is automatically remove after 5 seconds. You can call this function several times : the messages will be all displayed.
Script example
The example displays some messages at the start of the level.
function OnLoad() Game.Message("This level is scripted") Game.Message("GO GO GO !!!") return true end
ClearMessages()
Explanation
Remove messages on the screen.
Script example
The example shows how to clear old messages and display a new one in some circumstances.
Zone0 = {} function Zone0.OnEnter() Game.ClearMessages() Game.Message("OnEnter") end function Zone0.OnLeave() Game.ClearMessages() Game.Message("OnLeave") end
IsEntityTouched(entity)
[require Xmoto >= 0.2.0]
Explanation
There is a function called when you touch an entity. But sometimes you want to know when you don't touch an entity. Use this function.
Script example
The example shows how to make an action when the player is not touching an entity.
g = -9.81 function OnLoad() Game.Message("Gravity is increasing while you are not touching the snowman") return true end function Tick() if(Game.IsEntityTouched("SnowMan0") == 0) then g = g - 0.03 Game.SetGravity(0, g); end return true end
Game.AddPenaltyTime(time)
[require Xmoto >= 0.5.0]
Explanation
Increment the value of the time counter to make a penalty.
Script example
In the following example, the time will be increased of 5 seconds if the player enters in the zone Zone0.
Zone0 = {} function Zone0.OnEnter() Game.AddPenaltyTime(5.0) end
RemainingStrawberries()
[require Xmoto >= 0.2.1]
Explanation
This function returns the number of strawberries remaining in the level.
Script example
In the following example, when the player will enter in the zone Zone0, the number of remaining strawberries is displayed.
Zone0 = {} function Zone0.OnEnter() Game.Message(Game.RemainingStrawberries()) end
SetKeyHook(key, function)
Explanation
Whenever the player hits the "key" specified, a function will be called.
Script example
The example shows how to change gravity just by pressing a key.
g = -9.81 function OnLoad() Game.SetKeyHook("G", "GravityChange") return true end function GravityChange() g = g * -1 Game.SetGravity(0, g) end
GetKeyByAction(function)
Explanation
Return the key associated to an action. Possible actions are Drive, Brake, PullBack, PushForward, ChangeDirection.
Script example
The example displays how to drive at level start.
function OnLoad() Game.Message("To drive, press "..Game.GetKeyByAction("Drive")) return true end
Log(msgs)
Explanation
Log a message in the xmoto.log.
Script example
The example log the message "An error occured" when the level starts.
function OnLoad() Game.Log("An error occured") return true end