Funtions for Game Events

From X-Moto
Jump to: navigation, search

Contents

Functions called by XMoto

OnLoad()

Explanation

This function is called one time when the level starts. You must write "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

Checkpoint.OnUse()

[require Xmoto >= 0.5.3]

Explanation

This function is called when the player respawns at a checkpoint.

Script example

The example displays a Message after a Checkpoint was used.

ckpoint1 = {}

function ckpoint1.OnUse()
  Game.Message("Loading checkpoint 1");
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