Try our affiliated browser extension - redirect to BreezeWiki automatically!

Lua

For Lua events, see Lua event.
Out of date
This page is out of date. You can help the Transformice Wiki by updating it.

Lua is a very powerful scripting language.

In Transformice, you can use Lua to write your own tribe house script, modules and Lua events.

To find the latest Lua help, type chat command "/luahelp" in-game. It shows the Lua tree, events and functions. A copy of it, as of February 2025, can be found here.

Documentation

Official Transformice documentation can be found here.

Unofficial documentation for the Module API - the system built into Transformice that allows minigames to run without a bot. Modules are programmed in Lua. This documentation is valid as of Module API version 0.19.

Note: the print() function only displays to the person who runs the script.

Note: The underlined functions can only be used by the Module Team.

Events

These functions are called when the corresponding event is triggered.

Name Arguments Description
eventChatCommand String playerName, String message This event triggers when the player types a message beginning with « ! » in the chat.
eventEmotePlayed String playerName, Int emoteId This event triggers when the player does an emote.
eventFileLoaded String fileName, String file This event triggers when a file is loaded.
eventFileSaved String fileName This event triggers when a file is saved.
eventKeyboard String playerName, Int keyCode, Boolean down, Int xPlayerPosition, Int yPlayerPosition This event triggers when a player presses a key.
eventLoop Int currentTime, Int timeRemaining This event occurs every 500 miliseconds (0.5 seconds).
eventMouse String playerName, Int xMousePosition, Int yMousePosition This event triggers when a player clicks the screen with their cursor.
eventNewGame none This event triggers at the start of a new game.
eventNewPlayer String playerName This event triggers when a new player joins the room.
eventPlayerDataLoaded String playerName, String data This event triggers when the data is loaded.
eventPlayerDied String playerName This event triggers when a player dies.
eventPlayerGetCheese String playerName This event triggers when a player gets the cheese.
eventPlayerLeft String playerName This event triggers when a player leaves the room.
eventPlayerMeep String playerName, Int xPosition, Int yPosition This event triggers when a player meeps.
eventPlayerRespawn String playerName This event triggers when a player respawn.
eventPlayerVampire String playerName This event triggers when a player transforms into a vampire.
eventPlayerWon String playerName This event triggers when a player wins the round.
eventPopupAnswer Int popupId, String playerName, String answer This event triggers when a player answer to a popup.
eventSummoningCancel String playerName This event triggers when a player cancels an invocation.
eventSummoningEnd String playerName, Int objectType, Int xPosition, Int yPosition, Int angle, Int xSpeed, Int ySpeed, Int objectType, Table other This event triggers when a player has finished an invocation.
eventSummoningStart String playerName, Int objectType, Int xPosition, Int yPosition, Int angle This event triggers when a player starts an invocation.
eventTextAreaCallback Int textAreaId, String playerName, String callback This event triggers when a player click on a flash text event. Example : <a href="event:callbackString">Click here</a>

Methods

These methods are defined by the Transformice API.

tfm.exec Package

Name Arguments Description
addConjuration Int xPosition, Int yPosition, Int timeInMillis Add conjuration to the map.
addImage String imageName, String target, Int xPosition, Int yPosition, String targetPlayer Add an image to the map. (Target can be: #mobileId , $playerName , %playerName , ?backgroundLayerDepth , _groundLayerDepth , !foregroundLayerDepth ) Returns an image id. If targetPlayer is nil, it sends it to all players.
addJoint Int id, Int physicObject1, Int physicObject2, Table jointDef Adds a joint between two physic objects. jointDef properties are::type (Int):::0: distance joint::1: prismatic joint::2: pulley joint::3: revolute joint:point1 (String "x,y"): location of the ground1 anchor (default: the ground1's center):point2 (String "x,y"): location of the ground2 anchor (default: the ground2's center), only used with distance and pulley joints:point3 (String "x,y"), point4 (String "x,y"): locations of the pulley's anchors, only used with pulley joints:frequency (Float):damping (Float): Distance joints' frequency and damping ratio
axis (String "x,y")
angle (Int):
Prismatic joints' axis and angle.
limit1 (Float), limit2 (Float), forceMotor (Float), speedMotor (Float): Prismatic and revolute joints' translation/rotation limits and motors.
ratio (Float): Revolute joints' ratio.
line (Int)
color (Int)
alpha (Float)
foreground (Boolean)



If none of these properties are defined, the joint won't be drawn.

Note: On the map editor, players can also add a lua="id" property in a joint definition in the XML code to be able to interact with it with LUA code.

addPhysicObject Int id, Int xPosition, Int yPosition, Table bodyDef Adds a physic object into the game. bodyDef properties are the same as the map editor ones::type (Int):width (Int):height (Int):foreground (Boolean):friction (Float):restitution (Float):angle (Int):color (Int):miceCollision (Boolean):groundCollision (Boolean)
dynamic (Boolean)
fixedRotation (Boolean)
mass (Int)
linearDamping (Float)
angularDamping (Float): for dynamic grounds.



Note: On the map editor, players can also add a lua="id" property in a ground definition in the XML code to be able to interact with it with LUA code.

addShamanObject Int objectId, Int xPosition, Int yPosition, Int angle, Int xSpeed, Int ySpeed, Boolean ghost Adds a Shaman object into the game. Returns the ID of the object.
bindKeyboard String playerName, Int keyCode, Boolean down, Boolean yes Listens to the player’s keyboard events.
changePlayerSize String playerName, Boolean yes Changes the size of a player.
chatMessage String message, String playerName Sends a message to all the players in the room. If playerName isn’t nil, the message is sent to this player only. See colours to use on the stylesheet tags page. Link
disableAfkDeath Boolean yes Deactivates the automatic afk death.
disableAllShamanSkills Boolean yes Disables shamans in the room from having skills.
disableAutoNewGame Boolean yes Deactivates the automatic renewal of rounds.
disableAutoScore Boolean yes Deactivates the automatic scoring management.
disableAutoShaman Boolean yes Deactivates the automatic selection of Shaman.
disableAutoTimeLeft Boolean yes Deactivates the automatic time change.
disableDebugCommand Boolean yes Disables the effects of the /debug command.
disableMinimalistMode Boolean yes Disables the minimalist mode.
disableMortCommand Boolean yes Disables the /mort command.
disablePhysicalConsumables Boolean yes Deactivates physical consumables (like in racing and bootcamp rooms).
disablePrespawnPreview Boolean yes Enables or disables the shaman objects prespawn preview.
disableWatchCommand Boolean yes Disables the effects of the /watch command.
displayParticle Int particleId, Int xPosition, Int yPosition, Float xSpeed, Float ySpeed, Float xAcceleration, Float yAcceleration, String targetPlayer Add a particle. If targetPlayer is nil, it sends it to all players.
explosion Int xPosition, Int yPosition, Int power, Int distance, Boolean miceOnly Throw an explosion.
giveCheese String playerName Gives the cheese to a player.
giveMeep String playerName, Boolean canMeep Gives the meep competence to a player, or removes it.
giveTransformations String playerName, Boolean canTransform Gives the transformations to a player, or removes them.
killPlayer String playerName Kills the selected player.
moveObject Int objectId, Int xPosition, Int yPosition, Boolean offset, Int xSpeed, Int ySpeed, Boolean offset Defines the speed and position of an object.
movePlayer String playerName, Int xPosition, Int yPosition, Boolean offset, Int xSpeed, Int ySpeed, Boolean offset Defines the speed and position of a player.
newGame String mapCode Launch a new game. Use:

Vanilla Map:

6



Map Editor:

@42583



Perm Map:

#4



XML Map:

Begin with ’<’
playerVictory String playerName Gives the victory to a player.
removeCheese String playerName Takes away the cheese from a player.
removeImage Int imageId Remove an image.
removeJoint Int id Removes a joint from the game.
removeObject Int objectId Remove a physical object.
removePhysicObject Int id Removes a physic body from the game.
respawnPlayer String playerName Respawn a player.
setGameTime Int seconds Set the game time.
setNameColor String playerName, Int color Changes the player’s name’s color. The color is in the format "0x000000".
setPlayerScore String playerName, Int score, Boolean add Set the player’s score.
setRoomMaxPlayers Int maxPlayers Sets the max number of players in a room.
setShaman String playerName, Boolean makeAShaman Makes a player a shaman.
setShamanMode String playerName, Int mode Changes the shaman mode of a player.
setUIMapName String text Set text map name.
setUIShamanName String text Set text shaman name.
setVampirePlayer String playerName, Boolean makeAVampire Set player as vampire.
snow Int seconds, Int snowballPower Toggles falling snow.
setFighter none No description
setTimeLeft Int seconds, Boolean init Set the game time.
spawnMonster none No description
joinObject none No description
addParticleEffect none No description

tfm.get Package

tfm.get.misc Package

Name Returns Description
apiVersion Num version Returns the current version of the Module API.
transformiceVersion Num version Returns the current version of Transformice.
bouboumVersion Num version Returns the current version of Bouboum.

tfm.get.room Package

Name Returns Description
community String community Returns the abbreviation of the current community.
maxPlayers Int maxPlayers Returns the number of players that can join the room.
objectList Table objectList Returns a list of shaman objects currently spawned.
name String roomName Returns the name of the current room.
playerList Table playerList Returns a list of players currently in the room.
currentMap String mapCode Returns the code of the map currently playing in the room.
xmlMapInfo Table xmlMapInfo Returns a list of info about the current map.

tfm.get.room.playerList[playerName] Table

Name Returns Description
hasCheese Boolean yes Returns whether the player has cheese.
hasTribe Boolean yes Returns whether the player has a tribe.
isDead Boolean yes Returns whether the player is dead.
isFacingRight Boolean yes Returns whether the player is facing right (or left).
inHardMode Boolean yes Returns whether the player is in hard mode.
isJumping Boolean yes Returns whether the player is in the air.
isShaman Boolean yes Returns whether the player is shaman.
isVampire Boolean yes Returns whether the player is a vampire.
look String look Returns the current items and customisation of the player’s outfit as fur;head,eye,ear,mouth,neck,hairstyle,tail,(back),(paw).
movingLeft Boolean yes Returns whether the player is moving left.
movingRight Boolean yes Returns whether the player is moving right.
playerName String playerName Returns the player’s name.
score Num score Returns the player’s current score.
title Num titleID Returns the ID of the title the player is wearing.
tribeName String tribeName Returns the player’s tribe.
vx Num vx Returns the player’s x velocity.
vy Num vy Returns the player’s y velocity.
x Num x Returns the player’s x coordinate.
y Num y Returns the player’s y coordinate.
registrationDate Num registrationDate No description
statShamanHard Num statShamanHard No description
statFirst Num statFirst No description
statBootcamp Num statBootcamp No description
statShamanCheese Num statShamanCheese No description
statMiceSaved Num statMiceSaved No description
statCheese Num statCheese No description

tfm.get.room.objectList[id] Table

Name Returns Description
id Num id Returns the ID of the object on the map.
x Num x Returns the x coordinate of the object.
y Num y Returns the y coordinate of the object.
angle Num angle Returns the angle of the object.
ghost Boolean yes Returns whether the object is ghosted.
type Num type Returns the ID of the type of object.

tfm.get.room.xmlMapInfo Table

Name Returns Description
permCode Num p Returns the permanent code (P..) of the current map.
author String author Returns the author of the current map.
mapCode Num mapCode Returns the code of the current map as a number (123456 for @123456).
xml String xml Returns the XML of the current map. PS: You should call this at eventNewGame(), otherwise it may return nil.

tfm.enum Package For more enums, visit the enums page here.

tfm.enum.emote Package

Name Returns Description
dance Int 0 Returns the ID of the dancing emote.
laugh Int 1 Returns the ID of the laughing emote.
cry Int 2 Returns the ID of the crying emote.
kiss Int 3 Returns the ID of the kissing emote.
angry Int 4 Returns the ID of the raging emote.
clap Int 5 Returns the ID of the clapping emote.
sleep Int 6 Returns the ID of the sleeping emote.
facepaw Int 7 Returns the ID of the facepawing emote.
sit Int 8 Returns the ID of the sitting emote.
confetti Int 9 Returns the ID of the throwing confetti emote.

tfm.enum.shamanObject Package

Name Returns Description
arrow Int 0 Returns the ID of the arrow shaman object.
littleBox Int 1 Returns the ID of the small box shaman object.
box Int 2 Returns the ID of the large box shaman object.
littleBoard Int 3 Returns the ID of the short plank shaman object.
board Int 4 Returns the ID of the long plank shaman object.
ball Int 6 Returns the ID of the ball shaman object.
trampoline Int 7 Returns the ID of the trampoline shaman object.
anvil Int 10 Returns the ID of the anvil shaman object.
cannon Int 19 Returns the ID of the right facing cannonball shaman object.
bomb Int 23 Returns the ID of the bomb shaman object.
balloon Int 28 Returns the ID of the balloon shaman object.
rune Int 32 Returns the ID of the rune shaman object.
snowBall Int 34 Returns the ID of the snowball shaman object.
iceCube Int 54 Returns the ID of the iced mouse shaman object.

system Package

Name Arguments Description
bindMouse String playerName, Boolean yes Listens to the player’s cursor events.
exit none Deactivates the lua script running.
giveEventGift String playerName, Int amount Undocumented feature.
newTimer Function callback, Int time, Boolean loop, Object arg1, Object arg2, Object arg3, Object arg4 Create a new timer. Return the new timer id. Use system.removeTimer(timerId) to stop a timer.
removeTimer Int timerId Remove a timer.
loadFile Int fileNumber Load a file. Call limited to once per 10 minutes. Returns true if loading has started.
loadPlayerData String playerName Loads the player’s data for this module. Calls eventPlayerData when it’s done.
saveFile String data, Int fileNumber Save a file. Call limited to once per 10 minutes. Returns true if saving has started.
savePlayerData String playerName, String data Saves the player’s data for this module.
disableChatCommandDisplay String command, Boolean yes Deactivates the display of a command in the chat window (100 max).

debug Package

Name Arguments Description
disableEventLog Boolean yes Deactivates the events log.
disableTimerLog Boolean yes Deactivates the timers log.

ui Package

Name Arguments Description
addPopup Int id, Int type, String text, String targetPlayer, Int x, Int y, Int width, Boolean fixedPos (false)) Add a popup. Popup type : 0 (simple), 1 (yes or no), 2 (player input). If targetPlayer is NIL, it sends it to all players.
addTextArea Int id, String text, String targetPlayer, Int x, Int y, Int width, Int height, Int backgroundColor, Int borderColor, Float backgroundAlpha, Boolean fixedPos (false) Add a text area. If targetPlayer is nil, it sends it to all players.
removeTextArea Int id, String targetPlayer Remove a text area. If targetPlayer is nil, it sends it to all players.
updateTextArea Int id, String text, String targetPlayer Update a text area. If targetPlayer is nil, it sends it to all players.

API Tree

String => Can contain text, numbers and symbols.
Int => Can only contain integers(numbers)
Boolean => true or false


_G
ipairs()
ui
 updateTextArea(
  Update a text area.
  Int id
  String Text
  String targetPlayer
   If targetPlayer is nil, it sends it to all players.
 )
 removeTextArea(
  Remove a text area.
  Int id
  String targetPlayer
   If targetPlayer is nil, it sends it to all players.
 )
 addPopup(
  Add a popup.
  Int id
  Int type
   0 (simple), 1 (yes or no), 2 (player input).
  String text
  String targetPlayer
   If targetPlayer is nil, it sends it to all players.
  Int x
  Int y
  Int width
  Boolean fixedPos
 )
 addTextArea(
  Add a text area.
  Int id
  String text
  String targetPlayer
   If targetPlayer is nil, it sends it to all players.
  Int x
  Int y
  Int width
  Int height
  Int backgroundColor
  Int borderColor
  Float backgroundAlpha
  Boolean fixedPos
 )
math
 deg()
 fmod()
 random()
 asin()
 max()
 modf()
 log10()
 floor()
 cosh()
 ldexp()
 log()
 pow()
 randomseed()
 frexp()
 abs()
 tanh()
 acos()
 atan2()
 tan()
 mint()
 ceil()
 sinh()
 sqrt()
 huge()
 rad()
 sin()
 exp()
 cos()
 atan()
 pi()
pcall()
assert()
tonumber()
rawequal()
table
 maxn()
 foreachi()
 concat()
 remove()
 insert()
 foreach()
 sort()
 getn()
tfm
 exec
  bindKeyboard(
  Listens to the player's keyboard events.
   String Playername
   Int KeyCode
   Boolean down
   Boolean yes
  )
  snow(
  Makes the snow fall.
   Int Secondes (6)
   Int SnowBallPower (10)
  )
  disableAutoNewGame(
  Deactivates the automatic renewal of rounds.
   Boolean yes
  )
  setShaman(
  Set a shaman.
   String PlayerName   
  )
  addImage(
  Add an image to the map.
   Only available for Lua members.
   String imageName (imgur)  
   String Target
    #mobileId
    $playerName
    %playerName
    ?backgroundLayerDepth
    _goundLayerDepth
    !foregroundLayerDepth
    &fixedLayerDepth
   Int xPosition
   Int yPosition
   String targetPlayer
    If targetPlayer is nil it sends it to all players.
  )
 addJoint(
 Adds a joint between two physic objects.
  Int physicObject1
  Int physicObject2
  Table jointDef
   jointDef properties are:
   Int type
    0: distance joint
    1: prismatic joint
    2: pulley joint
    3: revolute joint
   String point1
    ("x,y"): location of the ground1 anchor (default: the ground1's center)
   String point2
    ("x,y"): location of the ground2 anchor (default: the ground2's center), only used with distance and pulley joints
   String point3
    ("x,y")
   String point4
    (String "x,y"): locations of the pulley's anchors, only used with pulley joints
   Int physicObject1
   Float frequency
   Float damping
    Distance joints' frequency and damping ratio
   String axis
    ("x,y")
   Int angle
    Prismatic joints' axis and angle.
   Float limit1
   Float limit2
   Float forceMotor
   Float speedMotor
    Prismatic and revolute joints' translation/rotation limits and motors.
   Float ratio:
    Revolute joints' ratio.
   Int line
   Int color
   Float alpha
   Bool foreground
  If none of these properties are defined, the joint won't be drawn.
  Note: On the map editor, players can also add a 'lua⁠⁠=⁠"id"' property in a joint definition in the XML code to be able to interact with it with LUA code.
 )
 addPhysicObject(
 Adds a physic object into the game.
  Int id
  Int xPosition
  Int yPosition
  Table bodyDef
   bodyDef properties are the same as the map editor ones:
   Int type
   Int width
   Int height
   Bool foreground
   Float friction
   Float restitution
   Int angle
   Int color
   Bool miceCollision
   Bool groundCollision
   Bool dynamic
   Bool fixedRotation
   Int mass
   Float linearDamping
    angularDamping (Float) for dynamic grounds
  Note: On the map editor, players can also add a 'lua⁠=⁠"id"' property in a ground definition in the XML code to be able to interact with it with LUA code.
 )
  respawnPlayer(
  Respawn a player.
   String playerName
  )
  newGame(
  Launch a new game.
   String Map code
    If nil it will play a random map.
    6 (vanilla map), @42583 (editor map), #4 (perm category map), begin with '<' (xml map)
  )
  disableAllShamanSkills()
   Boolean yes
  )
  setGameTime(
  Set the game time.
   Int seconds
   Boolean init
  )
  movePlayer(
  Defines the speed and position of a player.
   String PlayerName
   Int xPosition
   Int yPosition
   Boolean offset
   Int xSpeed
   Int ySpeed
   Boolean offset
  )
  removeImage(
  Remove an image.
   Only available for Lua members.
   Int imageID
  )
  chatMessage(
  Sends a message to all the players in the room.
   Only available for Lua members.
   String message
    If playerName isn't nil, the message is sent to this player only.
  )
  setVampirePlayer(
  Set player as vampire.
   String Playername
  )
  explosion(
  Throw an explosion.
   Int xPosition
   Int yPostition
   Int Power
   Int Distance
   Boolean miceOnly
  )
  moveObject(
  Defines the speed and position of an object.
   Int objectId
   Int xPosition
   Int yPosition
   Boolean offset
   Int xSpeed
   Int ySpeed
   Boolean offset
  )
  disableAutoScore(
  Deactivates the automatic scoring management
   Boolean yes
  )
  giveCheese(
  Gives the cheese to a player.
   String Playername
  )
  killPlayer(
  Kills the selected player.
   String Playername
  )
  displayParticle(
  Add a particle.
   Int particleId
   Int xPosition
   Int yPosition
   Float xSpeed
   Float ySpeed
   Float xAcceleration
   Float yAcceleration
   String targetPlayer
    If targetPlayer is nil it sends it to all players.
  )
  setNameColor(
  Changes the player's name's color.
   String playerName
   Hex color
    For example if #FFFFFF is your color you need to use: 0xFFFFFF
  )
  giveMeep(
  Gives the meep competence to a player.
   String playerName
  )
  disableAutoTimeLeft(
  Deactivates the automatic time change.
   Boolean yes
  )
  setPlayerScore(
  Set the player's score.
   String playerName
   Int score
   Boolean add
  )
  setRoomMatxPlayers(
  Sets the max number of players in a room.
   int maxPlayers
  )
  addConjuration(
  Add conjuration to the map.
   Int xPosition
   Int yPosition
   Int timeInMillis
 )
  removeJoint(
  Removes a joint from the game.
   Int id
  )
  removeObject(
  Remove a physical object.
   String objectId
  )
  removePhysicObject(
  Removes a physic body from the game.
   Int id
  )
  setUIShamanName(
  Set text shaman name.
   String text
  )
  disableAfkDeath(
  Desactivates the automatic afk death.
   Boolean yes
  )
  setUIMapName(
  Set text map name.
   String text
  )
  playerVictory(
  
   String playerName
  )
  addShamanObject(
  Adds a Shaman object into the game.
   Int objectId
   Int xPosition
   Int yPosition
   Int angle
   Int xSpeed
   Int ySpeed
   Boolean ghost
  )
  disableAutoShaman(
  Deactivates the automatic selection of Shaman.
   Boolean yes
  )
 enum
  emote
   sit 8
   facepaw 7
   laugh 1
   sleep 6
   angry 4
   confetti 9
   clap 5
   cry 2
   kiss 3
   dance 0
  shamanObject
   bomb 23
   arrow 0
   trampoline 7
   balloon 28
   box 2
   rune 32
   snowBall 34
   board 4
   littleBox 1
   cannon 19
   ball 6
   anvil 10
   iceCube 54
   littleBoard 3
 get
  misc
   bouboumVersion 1.26
   transformiceVersion 2.75
   apiVersion 0.19
  room
   community
    currentMap 0
    maxPlayers 50
    objectList
   name
    playerList
    isJumping
    title 0
    y 0
    x 0
    isDead
    look 1;0,0,0,0,0,0,0,0,0
    isShaman
    vx 0
    score 0
    inHardMode
    vy 0
    movingRight
    hasCheese
    registrationDate 0
    playerName Tigrounette
    movingLeft
    isFacingRight
    isVampire
pairs()
os
 difftime()
 time()
 date()
xpcall()
type()
error()
string
 len()
 find()
 gmatch()
 byte()
 dump()
 reverse()
 upper()
 format()
 rep()
 lower()
 sub()
 gsub()
 match()
 char()
debug
 disableEventLog()
 disableTimerLog()
tostring()
print()
next()
system
 disableChatCommandDisplay()
 newTimer()
 savePlayerData()
 bindMouse()
 exit()
 removeTimer()
 loadPlayerData()
 loadFile()
 saveFile()

External Links

Official Transformice Forum

Lua Resources

Editors

Collaborative Text Editors

v · d · eTransformice
Events
Game modes
Gameplay
Game updates
Maps
Shaman
Shop
Historical