# Difference between revisions of "Level alteration Functions"

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

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.

x, y = Game.GetGravity()
Game.Message("Wind : "..x)
Game.Message("Gravity : "..(y*-1))
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

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

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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

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

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