Scripted levels

From X-Moto
Revision as of 16:19, 13 October 2006 by Jacky J (talk | contribs) (Callable XMoto's functions)
Jump to: navigation, search

Català

Contents

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.

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">

Scripted level.jpg

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.

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.

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

OnSomersault(bClockWise)

[require Xmoto >= 0.2.1]

Explanation

This function is called each time the player make a new somersault. bClockWise is 1 is the somersault is clockwise, 0 if counterclockwise.

Script example

The example displays a message when the player makes a somersault.

function OnSomersault(bClockWise)
  if(bClockWise == 1)  
  then
    Game.Message("ClockWise Somersault")
  else
    Game.Message("CounterClockWise Somersault")
  end
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

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 the 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

SetPlayerPosition(x, y, bRight)

Explanation

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

Script example

The example teleports the player each time he enters the zone.

Zone0 = {}

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

GetPlayerPosition()

Explanation

Return the triplet (x, y, bRight) which give the position of the player 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

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.

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

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

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

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 move blocks to fast otherwise the bike could go throw the block.

entity: Defines, which Entity should move
fX: Defines, where on the X-Axis the Entity should move
fY: Defines, where on the Y-Axis the Entity should move
period: Defines, how long it takes the Entity 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 that the camera 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

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

KillPlayer()

[require Xmoto >= 0.2.1]

Explanation

If you call this function, the player dies. It's interesting if you want the player 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

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, the player wins 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

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