Monsters integration in Lua


Embedding a monster is done via the game’s configuration files, which can be found in the folder


The engine scans this folder and automatically loads all the .txt it finds there. These .txt files contain entries in the form of

{ ObjectType: { entry1: { params } entry2: { params } } }



Any modifiable content of the game (such as blocks, objects, or monsters) is therefore represented by these entries, and accessible by the engine via their names.

Monsters can be found in



Before scripting a monster, you must already have the animations (sprites) and sounds on hand.

We structure the files of a monster this way:


Sprites in .png format are placed in the Sprites folder. Sounds in .wav in the Sounds folder.

The sprites .json and sounds .json configuration files must be modified to indicate to the engine the assets used by the monster, as well as their parameters (such as sprite offsets).

The config.txt file is the file that the engine will read automatically. It is in this file that we indicate the paths for the lua script, the sprites and sounds configuration files.


To integrate a new monster, the easiest way is to use an already integrated monster as a template.

For land monsters use assets/moddable/Monsters/Zombie/
Just copy and paste the folder, for example


Important: then, don’t forget to change the name of the entry to avoid a collision. Open the config txt file and replace pc_monster_zombi with a separate name. For a mod we prefer not to use the pc_ prefix reserved for official entries.

For example, replace pc_monster_zombi by mod_monster_custom.

Test in game

To test a new monster in game, you must:

  • create a character in creative mode
  • load this part
  • use an order to spawn our monster
  • possibly drop some stuff for the player (ex: weapons) to test the monster in real situation

Creating the character in building mode

Launch the game then:

  • Single Player > New Character
  • Enter a name for your player and press “Ok”.
  • Confirm
  • 3rd line: press the right arrow to select “Building”.
  • Press Confirm

Drop some stuff

Press the “Enter” key to open the console. Enter the following command:

/drop pc_sword_gold

… then do “Enter” by placing the mouse over the player.

You can then retrieve the sword in the inventory (key I), which should be at the very top, or in the “sword” tab. Use the left mouse button to retrieve the sword, then place it on slot [1] of the hotbar. Then you can use the sword with the left mouse button.

In the same way one can spawn magic sceptres, potions…

/drop pc_staff_magic_fire1_simple
/drop pc_boomerang_dark
/drop pc_legendary_stamina_potion 999
/drop pc_pickaxe_gold
/drop pc_catch_gem4

Spawn a monster

In the same way, to spawn a monster you go through the command line:

/spawn pc_monster_zombi 10

Useful options

Stop time:

/time 0

Switch to 12:00 or 00:00:


Reload sounds and lua scripts: press F11.

Minimal class

A lua class to represent a monster. Needs to override multiple methods which are listed below.

Type Function Args
evCreate (LandMonster& entity, MonsterSpawnParam params)
render (LandMonster& entity, Renderer& renderer)
update (LandMonster& entity, float dt)
Rect hitbox (u32 state, LandMonster& entity)
Hit evHurt (LandMonster& entity, Damage& damages, AliveEntity* owner)
evGetHit (LandMonster& entity, AliveEntity* owner, Damage& damages)
evDie (LandMonster& entity, AliveEntity* owner)
{} makeBrain (LandMonster& entity)
bool haveRecoil (LandMonster& entity)
Rect bbox ()
float facingx ()
bool isIdle ()
bool isMoving ()
bool isJumping ()
bool canBeUsedAsMount (LandMonster& entity)
evSend (LandMonster& entity, StreamData& buffer)
evReceive (LandMonster& entity, StreamData& buffer)

Minimal brain class

The engine has a generic AI and pathfinding system for terrestrial monsters. To make it work, you just have to override the methods of the Brain class that follow.

Type Function Args
update (lua_entity, LandMonster& entity, LandAIBrain& brain, Input& inputs, float dt)
bool tryToAttack (lua_entity, LandMonster& entity, Focus& focus, Input& inputs)


Lua classes have been specifically written to simplify the creation of monsters. They can be found in the following folder:


Here is the list of currently implemented classes:

Allows to manage hit/fall/getup states easily.

Allows you to manage jumps easily.

Small library to simplify the creation of monsters.

Allows you to add the trait ‘Leader’ to a monster.