Scripted levels

Català - Español

Introduction

Scripting allows a level to become dynamic. You can change physic settings, move objects, modify game logic, etc. A script is written in the Lua language and can be included in a level file.

Documentation about Lua can be found here :
http://www.lua.org/manual/5.1/

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, description, author, date, etc. Moreover, it includes block and sprite definitions. A block is composed of vertices which link together to draw polygons.

Since 0.3.0, xmoto supports multiplayers ; in the script, a player is defined by an index. The first player has the number 0, the second the number 1, ...

The script examples on this page will use this basic level file:

<?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 easily with the xmoto level editor. It 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 that can execute actions when the player is inside.

Some functions require a minimum X-Moto version to work. If you use one of these functions, please put this information in the level. For example, to make your level require X-Moto version 0.2.0, add this line to your level:

<level id="tutscript" rversion="0.2.0">

All the code of the script is written in Lua. You can find the syntax here. However, if you choose to include the script in an xml file, < and > symbol must be replaced by &lt; and &gt;. The code of the script can be included between <script> and </script> in the level file.

Timers

StartTimer(Name,Delay=100,Loops=0)

[require Xmoto >= 0.5.2]

Explanation

This function is used to create a timer, or start a stopped timer. Basically, if you don't give all parameters the timer uses default values, or if the timer already exists then it is resetted, or started if it is stopped with Game.StopTimer().

Cases:

• if timer doesn't exist then creates
• if timer exist and is stopped then restarts (unless you give attributes delay or loops then it is reseted)
• if timer exist and is running then resets

Script Example

--------------------------
--Delayed Message System--
-----by tuhoojabotti------
--------------------------
--stuff for the msgs
msgs={}
msgt={}
msga=0

--other
Zone0={}

function OnLoad()
	StartMessages({"Hello and welcome!","This level uses timers to show these messages.","Press 'B' to pause and continue messages.","Go right and if you hit the Zone, the messages will end!","I have nothing else to say, good night!"},150)
	Game.SetKeyHook("B","stop")
	return true
end

function stop()
	ToggleMessages()
end

function Zone0.OnEnter()
	ClearMessages()
end

--functions for the message system
function StartMessages(_msgs,_delay)
	msga=1; msgs=_msgs; Game.StartTimer("msgt",_delay,table.getn(msgs))
end
function ToggleMessages()
	if not(table.getn(msgs)==0) then --only if there are messages
		if msga==1 then --msgs are rolling
			msga=0; Game.StopTimer("msgt")
		else --no msgs rolling
			msga=1; Game.StartTimer("msgt")
		end
	end
end
function msgt.Tick(n)
	if table.getn(msgs)>=n then --there are messages
		Game.Message(msgs[n])
		if table.getn(msgs)==n then msga=0 end --shutdown on last msg
	end
end
function ClearMessages()
	if msga==1 then Game.StopTimer("msgt") end
	msgs={}; msga=0; msgd=0
end

SetTimerDelay(Name,Delay)

[require Xmoto >= 0.5.2]

Explanation

Sets the timer's delay, without resetting the amount of loops etc. (Allows you to speed it up or slow it down. ;-))

Script Example

timer={} --declare the timer
entity1={}
function OnLoad()
    Game.Message("You are going to die in 10 seconds!! buahahhahahaaa!")
    Game.StartTimer("timer",1000,1)
    return true
end
function timer.Tick()
    Game.KillPlayer()
end
function entity1.Touch()
    Game.Message("haha! you drank some poison, now you die faster!")
    Game.SetTimerDelay("timer",300)
end

StopTimer(Name)

[require Xmoto >= 0.5.2]

Explanation

Stops the timer, the Name.Tick won't be called anymore. Use Game.StartTimer(Name) to restart it.

Script Example

timer={} --declare the timer
entity1={}
function OnLoad()
    Game.Message("You are going to die in 10 seconds!! buahahhahahaaa!")
    Game.StartTimer("timer",1000,1)
    return true
end
function timer.Tick()
    Game.KillPlayer()
end
function entity1.Touch()
    Game.Message("No! you found antidote!")
    Game.StopTimer("timer")
end

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

Checkpoint.OnUse()

[require Xmoto >= 0.5.3]

Explanation

This function is called when a player go back to a checkpoint. This can be used to set some script values for example.

Script example

The example displays a message when a player uses the checkpoint Checkpoint0.

Checkpoint0 = {}

function Checkpoint0.OnUse()
  Game.Message("Checkpoints are usefull")
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 X-Moto 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

SetGravity(x, y)

Explanation

Change the gravity (horizontal and vertical) in the game.

Script example

The example shows how to reverse gravity. Be aware that in X-Moto, vertical gravity must be multiplied by -1 because screen coordinates are reversed in the y direction.

function OnLoad()
  Game.SetGravity(0, 9.81)
  return true
end

GetGravity()

Explanation

Return the pair(horizontal gravity, vertical gravity).

Script example

The example displays the wind and gravity at the start of the level.

function OnLoad()
  x, y = Game.GetGravity()
  Game.Message("Wind : "..x)
  Game.Message("Gravity : "..(y*-1))
  return true
end

IsPlayerInZone(zone)

Explanation

Return true if a player is in the specified zone.

Script example

This example is a bit more complicated. When the player enters the zone, gravity slowly decreases. Once the player leaves the zone, the gravity suddenly becomes 9.81.

Zone0 = {}
x = -9.81

function Tick()
  if Game.IsPlayerInZone("Zone0")
  then
    Game.SetGravity(0, x)
    x = x + 0.1
  end

  return true
end

function Zone0.OnLeave()
  x = -9.81
  Game.SetGravity(0, x)
end

IsAPlayerInZone(zone, player)

[require Xmoto >= 0.3.0]

Explanation

Return true if the player is in the specified zone.

Script example

function OnLoad()
  if Game.IsAPlayerInZone("Zone0", 0) == false
  then
    Game.Message("This player 0 is not in the zone")
  end
  return true
end

SetPlayerPosition(x, y, bRight)

Explanation

Set the position and direction of the players in the game. bRight can be 0 or 1.

Script example

The example teleports the playerq each time one enters the zone.

Zone0 = {}

function Zone0.OnEnter()
  Game.SetPlayerPosition(5, 0, 1)
end

SetAPlayerPosition(x, y, bRight, player)

Explanation

Set the position and direction of the player in the game. bRight can be 0 or 1.

Script example

The example show how to teleport the player 0 at start of the level to the position (20, 5)

function OnLoad()
  Game.SetAPlayerPosition(20, 5, 1, 0)
  return true
end

GetPlayerPosition()

Explanation

Return the triplet (x, y, bRight) which give the position of the player 0 in the game.

Script example

This example make the player unable to get the strawberry ;-)

function Tick()
  x, y, bright = Game.GetPlayerPosition()
  if x > 18
  then
    Game.SetPlayerPosition(5, 0, 1)
  end

  return true
end

GetPlayerVelocity(player)

[require Xmoto >= 0.5.0]

Explanation

Return the velocity of the player.

Script example

This example show informations when the player pressed the key M.

function OnLoad()
 Game.SetKeyHook("M", "Infos")
 return true
end

function Infos()
 Game.Message("Velocity: "..Game.GetPlayerVelocity(0))
 Game.Message("Speed: "..Game.GetPlayerSpeed(0))
 Game.Message("Angle: "..Game.GetPlayerAngle(0))
end

GetPlayerSpeed(player)

[require Xmoto >= 0.5.0]

Explanation

Return the speed of the player.

Script example

This example show informations when the player pressed the key M.

function OnLoad()
 Game.SetKeyHook("M", "Infos")
 return true
end

function Infos()
 Game.Message("Velocity: "..Game.GetPlayerVelocity(0))
 Game.Message("Speed: "..Game.GetPlayerSpeed(0))
 Game.Message("Angle: "..Game.GetPlayerAngle(0))
end

GetPlayerAngle(player)

[require Xmoto >= 0.5.0]

Explanation

Return the angle of the player.

Script example

This example show informations when the player pressed the key M.

function OnLoad()
 Game.SetKeyHook("M", "Infos")
 return true
end

function Infos()
 Game.Message("Velocity: "..Game.GetPlayerVelocity(0))
 Game.Message("Speed: "..Game.GetPlayerSpeed(0))
 Game.Message("Angle: "..Game.GetPlayerAngle(0))
end

GetAPlayerPosition(player)

[require Xmoto >= 0.3.0]

Explanation

Return the triplet (x, y, bRight) which give the position of a player in the game.

Script example

function OnLoad()
  x, y, bright = Game.GetAPlayerPosition(0)
  Game.Message("Player0 position is ("..x..","..y..")")
  return true
end

SetEntityPos(entity, x, y)

Explanation

Set the position of the entity to coordinates (x, y) in the game.

Script example

The example changes the position of the strawberry every second.

function Tick()
  i,f = math.mod(math.ceil(Game.GetTime()), 2)

  if i == 1
  then
    Game.SetEntityPos("Strawberry0", 10, 0.5)
  else
    Game.SetEntityPos("Strawberry0", 30, 0.5)
  end

  return true
end

GetEntityPos(entity)

Explanation

Return the position of the entity entity in the game.

Script example

This example shows another way to move a strawberry.

last_update = 0

function Tick()
  sec = math.ceil(Game.GetTime())

  if last_update < sec
  then
    x, y = Game.GetEntityPos("Strawberry0")

    if(x == 20)
    then
      x_new = 25
    else
      x_new = 20
    end

    if(y == 0.5)
    then
      y_new = 2
  else
      y_new = 0.5
    end

    Game.SetEntityPos("Strawberry0", x_new, y_new)
    last_update = sec
  end

  return true
end

SetKeyHook(key, function)

Explanation

Whenever the player hits the "key" specified, a function will be called. You can use key like "a", "b", "c" or technical values returned by GetKeyByActionTech

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

GetKeyByActionTech(function)

[require Xmoto >= 0.5.4]

Explanation

Return the key associated to an action. Possible actions are Drive, Brake, PullBack, PushForward, ChangeDirection. Note that GetKeyByAction returns a human readable string while GetKeyByActionTech returns a value which is usable by SetKeyHook and that can be a joystick, mouse or keyboard key.

Script example

The example show how to use the Drive key to do other things than driving.

function OnLoad()
  Game.SetKeyHook(Game.GetKeyByActionTech("Drive"), "BalloonA")
  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

MoveBlock(block, x, y)

[require Xmoto >= 0.2.0]

Explanation

This function allows X-Moto to move a block in the level. The block must be dynamic (modify the level to get <position x="0" y="0" dynamic="true" />). Be aware that moving a block can be dangerous: make sure that the player will not be inside the block once you have moved it.

Script example

In the example, when the player presses the key M, the block moves to the right.

function OnLoad()
  Game.SetKeyHook("M", "MoveTheBlock")
  return true
end

function MoveTheBlock()
  Game.MoveBlock("Block0", 1, 0)
end

SetBlockCenter(block, x, y)

[require Xmoto >= 0.2.0]

Explanation

This function gives the center of the block relative to the block position (then, to the level if block position is (0, 0)). The center is used by the function SetBlockPos(), GetBlockPos() and SetBlockRotation(). This function should generally used in the Load() function because the center should not logically be changed (however, you can change it).

Script example

In the example, the center of the block is set to the center of the square. Then, when the player press M, the block is placed just under the player.

function OnLoad()
  Game.SetKeyHook("M", "PutTheBlock")
  Game.SetBlockCenter("Block0", 7.5, 7.5)
  return true
end

function PutTheBlock()
  x, y = Game.GetPlayerPosition()
  Game.SetBlockPos("Block0", x, y -2.5 -1)
end

SetBlockPos(block, x, y)

[require Xmoto >= 0.2.0]

Explanation

This function allows X-Moto to change the position of a block according to its center. The block must be dynamic (modify the level to get <position x="0" y="0" dynamic="true" />). Be aware that moving a block can be dangerous: make sure that the player will not be inside the block once you have moved it.

Script example

In the example, the center of the block is set to the center of the square. Then, when the player press M, the block is placed just under the player.

function OnLoad()
  Game.SetKeyHook("M", "PutTheBlock")
  Game.SetBlockCenter("Block0", 7.5, 7.5)
  return true
end

function PutTheBlock()
  x, y = Game.GetPlayerPosition()
  Game.SetBlockPos("Block0", x, y -2.5 -1)
end

GetBlockPos(block)

[require Xmoto >= 0.2.0]

Explanation

This function gives the position of a given block. The block must be dynamic (modify the level to get <position x="0" y="0" dynamic="true" />).

Script example

The example shows how to use this function as a condition. Here, you can move the block under the bike only if you play on the right.

function OnLoad()
  Game.SetKeyHook("M", "PutTheBlock")
  Game.SetBlockCenter("Block0", 7.5, 7.5)
  return true
end

function PutTheBlock()
  x, y = Game.GetPlayerPosition()
  bx, by = Game.GetBlockPos("Block0")
  if(x > bx)
  then
  Game.SetBlockPos("Block0", x, y -2.5 -1)
  end
end

SetBlockRotation(block, angle)

[require Xmoto >= 0.2.0]

Explanation

This function rotates a block. The block must be dynamic (modify the level to get <position x="0" y="0" dynamic="true" />).

Script example

In the example, if the player keeps the key M pressed, the block will rotate.

a = 0

function OnLoad()
  Game.SetKeyHook("M", "PutTheBlock")
  Game.SetBlockCenter("Block0", 7.5, 7.5)
  return true
end

function PutTheBlock()
  a = a + math.pi / 256.0
  Game.SetBlockRotation("Block0", a)
end

SetDynamicEntityRotation(entity, initAngle, radius, period, startTime, endTime)

[require Xmoto >= 0.2.0]

Explanation

This function tells an entity to make circles for a given duration. The current position of the entity on the circle of radius radius is at position initAngle (in rad). The entity will make a circle in period hundreads. The animation will starts in startTime hundreadths and will finish in endTime hundreadths, so, the duration time is endTime-startTime/100 seconds. An endTime of 0 means an infinite animation. Note that you can compose rotations and translations. Note that negative arguments allow you to change the behavior of the animation. For example, a negative period will rotate the entity in the negative direction.

Script example

The example shows how to easily move the strawberry. InitAngle is set to -PI/2 because the strawberry is placed at the bottom where we want it moves.

function OnLoad()
  Game.SetDynamicEntityRotation("Strawberry0", -math.pi/2, 2, 500, 0, 0)
  return true
end

SetDynamicEntitySelfRotation(entity, period, startTime, endTime)

[require Xmoto >= 0.3.0]

Explanation

This function allows to tell an entity to rotate for a given duration. The entity will rotate in period hundreads. The animation will start in startTime hundreadths and will finish in endTime hundreadths, so, the duration time is endTime-startTime/100 seconds. An endTime of 0 means an infinite animation. Note that negativ arguments allow to change the behavior of the animation, for example, a negativ period will tell to turn in the other sense.

Script example

The example shows how to rotate easily a entity.

function OnLoad()
  Game.SetDynamicEntitySelfRotation("Entity2", 1000, 0, 0);
  return true;
end;

SetDynamicEntityTranslation(entity, fX, fY, period, startTime, endTime)

[require Xmoto >= 0.2.0]

Explanation

This function allows to tell an entity to make translation for a given duration. The translation's length is fX on the X axis and fY on the Y axis. The entity will make the translation in period/2 hundreads. The animation will starts in startTime hundreadths and will finish in endTime hundreadths, so, the duration time is endTime-startTime/100 seconds. An endTime of 0 means an infinite animation. Note that you can compose rotations and translations. Note that negativ arguments allow to change the behavior of the animation.

Script example

The example shows an example of composed animations.

function OnLoad()
  Game.SetDynamicEntityTranslation("Strawberry0", 10, 0, 500, 0, 0)
  Game.SetDynamicEntityTranslation("Strawberry0", 0, 1, 100, 0, 0)
  return true
end

SetDynamicEntityNone(entity)

[require Xmoto >= 0.2.0]

Explanation

This function removed all the animations applicated on an entity.

Script example

The example first shows how to ask an entity to make a translation in a first time and then, to make rotations. If the user press the key S, the strawberry stops to move.

function OnLoad()
  Game.SetDynamicEntityTranslation("Strawberry0", -2, 0, 1000, 0, 500)
  Game.SetDynamicEntityRotation("Strawberry0", -math.pi/2, 2, 500, 500, 0)
  Game.SetKeyHook("S", "StopAnimation")
  return true
end

function StopAnimation()
  Game.SetDynamicEntityNone("Strawberry0")
end

SetDynamicBlockRotation(block, initAngle, radius, period, startTime, endTime)

[require Xmoto >= 0.2.0]

Explanation

This function allows to tell a block to make circles for a given duration. The current position of the block on the circle of radius radius is at position initAngle (in rad). The block will make a circle in period hundreads. The animation will starts in startTime hundreadths and will finish in endTime hundreadths, so, the duration time is endTime-startTime/100 seconds. An endTime of 0 means an infinite animation. Note that you can compose rotations and translations. Note that negativ arguments allow to change the behavior of the animation, for example, a negativ period will tell to turn in the other sense. The block must be set dynamic so that it works (modify the level to get <position x="0" y="0" dynamic="true" />). Don't make move blocks to fast otherwise the bike could go throw the block.

Script example

The example shows how to make move easily a block.

function OnLoad()
  Game.SetDynamicBlockRotation("Block0", -math.pi/2, 2, 500, 0, 0)
  return true
end

SetDynamicBlockSelfRotation(block, period, startTime, endTime)

[require Xmoto >= 0.3.0]

Explanation

This function allows to tell a block to rotate for a given duration. The block will rotate in period hundreads. The animation will starts in startTime hundreadths and will finish in endTime hundreadths, so, the duration time is endTime-startTime/100 seconds. An endTime of 0 means an infinite animation. Note that you can compose rotations and translations. Note that negativ arguments allow to change the behavior of the animation, for example, a negativ period will tell to turn in the other sense. The block must be set dynamic so that it works (modify the level to get <position x="0" y="0" dynamic="true" />). Don't make move blocks to fast otherwise the bike could go throw the block.

Script example

The example shows how to rotate easily a block.

function OnLoad()
  Game.SetBlockCenter("Block2", -2.5, -19.0);
  Game.SetDynamicBlockSelfRotation("Block2", 1000, 0, 0);
  return true;
end;

SetDynamicBlockTranslation(block, fX, fY, period, startTime, endTime)

[require Xmoto >= 0.2.0]

Explanation

This function tells a block to make a translation for a given duration. A translation is a looped movement from one point to another, and back. The translation's length is fX on the X axis and fY on the Y axis. The animation will start in startTime hundredths and will finish in endTime hundredths, so the duration is endTime-startTime/100 seconds. An endTime of 0 means an infinite animation. Note that you can compose rotations and translations. The block must be set dynamic so that it works (modify the level to get <position x="0" y="0" dynamic="true" />). Don't make blocks move too fast otherwise the bike could go through the block.

block: Defines which Block should move
fX: Defines where on the X-Axis the Block should move
fY: Defines where on the Y-Axis the Block should move
period: Defines how long it takes the Block to move back to the starting point
startTime: Defines when the translation should start
endTime: Defines when the translation should end

In order to make replay files as small as possible, you should use Translation instead of the MoveBlock function. An example on how to convert a MoveBlock function into a Translation is given below.

Script example

In this example, the block makes an infinite movement: It moves from its originating point (0,0) to (10,1) within 750ms, and then back in another 750ms.

function OnLoad()
  Game.SetDynamicBlockTranslation("Block0", 10, 1, 1500, 0, 0)
  return true
end

Example on how to convert a MoveBlock function into a Translation (see above):

function Tick()
  Game.MoveBlock("Block0", 0.5,0)
  return true
end

Block0 moves forever to the right: 0.5px every 1/100s So it moves at a speed of 300m/60s

function OnLoad()
  Game.SetDynamicBlockTranslation("Block0", 300,  0, 12000, 0, 6000)
  return true
end

This is the MoveBlock function in the translation-version. It moves 300m to the right and 300m back to the left in 12000ms. endTime is set to 12000/2=6000, so that the translation stops as soon as Block0 reaches (300,0)

SetDynamicBlockNone(block)

[require Xmoto >= 0.2.0]

Explanation

This function stops all the animation applied on the block. The block must be set dynamic so that it works (modify the level to get <position x="0" y="0" dynamic="true" />).

Script example

In the example, the block will move until the player presses the key S.

function OnLoad()
  Game.SetDynamicBlockTranslation("Block0", 10, 1, 1500, 0, 0)
  Game.SetKeyHook("S", "StopAnimation")
  return true
end

function StopAnimation()
  Game.SetDynamicBlockNone("Block0")
end

CameraZoom(z)

[require Xmoto >= 0.2.0]

Explanation

In some levels, you may want that the camera is a bit more far from the player. Use this function to change the camera zoom.

Script example

The example shows how a different zoom can be used to play a level.

function OnLoad()
  Game.CameraZoom(-0.05)
  return true
end

CameraMove(x, y)

[require Xmoto >= 0.2.0]

Explanation

For some particular levels, you may want the camera to be moved. Use this function to do that.

Script example

The example shows how you can focus a level on the part above the player.

function OnLoad()
  Game.CameraMove(0, 3)
  return true
end

CameraRotate(angle)

[require Xmoto >= 0.3.0]

Explanation

For some particular levels, you may want that the camera be rotated. Use this function to do that.

Script example

The example shows how you use this function.

function OnLoad()
  Game.CameraRotate(math.pi / 4.0);
  return true
end

CameraAdaptToGravity()

[require Xmoto >= 0.3.0]

Explanation

For some particular levels, you may want that the camera be rotated. Use this function to do that in function of the gravity.

Script example

The example shows how you use this function.

function OnLoad()
  Game.SetGravity(0.0, 9.81)
  Game.CameraAdaptToGravity()
  return true
end

SetCameraRotationSpeed(z)

[require Xmoto >= 0.4.2]

Explanation

For some particular levels, you may want that the camera beeing rotated does that at a certain speed. With this function you can make it rotate either very slow ( z = 0.1 ) or extremely fast ( z = 7.2 ). The values are given in RAD, so they can reach from 0 to 2 * PI.

Script example

The example shows how you use this function.

function OnLoad()
  Game.SetGravity(0.0, 9.81)
  Game.SetCameraRotationSpeed(0.2)
  Game.CameraAdaptToGravity()
  return true
end

GetEntityRadius(entity)

[require Xmoto >= 0.2.0]

Explanation

Return the radius of an entity. This radius is used for collision. You can use this function for your own collision or anything else.

Script example

The example shows you the radius of the strawberry.

function OnLoad()
  Game.Message("Radius of the strawberry : "..Game.GetEntityRadius("Strawberry0"))
  return true
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

KillPlayer()

[require Xmoto >= 0.2.1]

Explanation

If you call this function, the players die. It's interesting if you want the players be killed by an enemy for example.

Script example

In the following example, the player will die when he will enter in the zone Zone0.

Zone0 = {}

function Zone0.OnEnter()
  Game.KillPlayer()
end

KillAPlayer(player)

[require Xmoto >= 0.3.0]

Explanation

If you call this function, a player dies. It's interesting if you want the player be killed by an enemy for example.

Script example

function OnLoad()
  Game.KillAPlayer(0)
  return true
end

KillEntity(entityID)

[require Xmoto >= 0.2.1]

Explanation

If you call this function, the entity entityID will be deleted. The entity can be a strawberry or any sprite.

Script example

In the following example, the strawberry will be deleted when the player will enter in the zone Zone0.

Zone0 = {}

function Zone0.OnEnter()
  Game.KillEntity("Strawberry0")
end

WinPlayer()

[require Xmoto >= 0.2.1]

Explanation

If you call this function, all players win the game (even if there are remaining strawberries).

Script example

In the following example, the player win on entering in the zone Zone0.

Zone0 = {}
 
function Zone0.OnEnter()
  Game.WinPlayer()
end

WinAPlayer(player)

[require Xmoto >= 0.3.0]

Explanation

If you call this function, a player wins the game (even if there are remaining strawberries).

Script example

function OnLoad()
  Game.WinAPlayer(0)
  return true
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

NumberOfPlayers()

[require Xmoto >= 0.3.0]

Explanation

This function returns the number of players (dead or in live) in the level

Script example

function OnLoad()
  Game.Message(Game.NumberOfPlayers().." players")
  return true
end

AddForceToPlayer(forceX, forceY, startTime, endTime, player)

[require Xmoto >= 0.4.2]

Explanation

This function apply an external force on the player player. The force will apply from startTime to endTime or will be infinite if endTime is 0. startTime and endTime are expressed in hundreaths and are relativ to the call function time. The force applied will be of (forceX, forceY). Application point is the center of the biker. In the example, a force will be applied to all players from time 5 to 10 seconds. Force is expressed in newton, mg/s-2 (meter * gramm / (seconds * seconds)).

Script example

function OnLoad()
 for i=0,Game.NumberOfPlayers()-1 do
   Game.Message("Kicking player "..(i+1))
   Game.AddForceToPlayer(0, 1000, 500, 1000, i)
 end

 return true
end

PlayAudio("NameOfSound")

[require Xmoto >= 0.4.2]

Explanation

Using this function you can play a sound effect (or a music). The parameter is the name of the sound, which is defined in the actually used theme file. In the following example, there must be a zone named "Zone0", As soon as you enter the zone, the sound effect is played:

Script example

Zone0 = {}
function Zone0.OnEnter()
 Game.PlaySound("ring");
end

SetPhysicsBlockSelfRotation (block, torque, startTime, endTime)

[require Xmoto >= 0.5.0]

Explanation

This function allows to tell a block to rotate for a given duration. The rotation will be performed by applying forces (torque) on the block (if possible). The block will rotate in period hundreads. The forces application will start in startTime hundreadths and will finish in endTime hundreadths, so, the duration time is endTime-startTime/100 seconds. An endTime of 0 means an infinite application. Note that negativ arguments allow to change the behavior of the forces, for example, a negativ torque will tell to turn in the other sense.