Level design

2.1 Adding a game object

Download the game editor, launch the game, and click "Game Editor" on the main menu. You will be greeted by the Worldmap editor. But we'll first get into the level editor, by clicking on the "Levels" tab on the top of the screen.

On the left side of the screen, you will see a list of the tilemaps stored in assets/tilemaps. Click on "stable-cavern" to load it in the level editor.

The game object manager appears on the right side of the screen:

Click on the + button to add open the following dialog:

Our first Game Object will be a puddle of acid. We will use this example to learn how to position objects, before introducing how scripting game objects works.

Select the Other object type, and call it "acid-puddle".

2.2 Game object

Game Objects are the objects populating the world: characters, doors, items, and anything that the player can interact with. All of them can be controlled by a script, and they all share a set of tools to help you program their behaviour:

In our journey to discover game objects, we will start with the simplest of them all: we call it the DynamicObject, and it serves as a basis for all interactive objects.

2.3 Sprite and positionning

We need to create a Sprite for our object to be displayed in a level. We will use the following picture to represent our puddle:

Download this file to your assets/sprites folder. Then, open up the Game Editor, go to the Sprite tab, and create our new sprite as following:

Sprites are organized in groups. Objects usually use sprites from a single group. Here, we created a sprite group named acid-puddle, and added the normal animation to it.

Now that our sprite has been created, let's go back to the Level editor, and select our "acid-puddle" object in the right-sided panel. This will display the game object view with which we can edit the properties and access the resources bound to a game object.

Using this view, we will set a position on the map, and select the sprite we created. See the following video for reference:

Our acid puddle is now rendered in the level. But it's not exactly properly positionned. Characters are going to walk on that puddle, and we want it to be properly rendered below the characters, and not above.

For these kind of situations, we will use the Floating positionning mode, as opposed to the Tile-based one. A tile position will still be required, as it is necessary to determine render order. But we will set the position manually, as following:

Since the rendering order starts with objects from the top and right positions, you should ensure the tile position of your floating objects is set to the upper right tile overlapped by your object.

We also uncheck the Blocks path checkbox, because we want characters to be able to move over the object.

And lastly, we set the Cover value to zero, because we want characters to see through the object. An object with a cover value of 100 cannot be seen through.
The cover value is applied on an object's case. When the objects contains a ControlZone with the Blocks path property enabled, the cover value is extended to all the tiles included in the zone.

2.4 Scripts

In the following steps, our Game Object will need to implement scripted behaviours. Create a script and bind it to your game object as shown below:

The acid-puddle.mjs file has been created in the scripts/behaviours folder. You can open using your system's default application for JavaScript, by clicking on the button at the right of the script picker.

The generated file already contains the skeleton for any script, which looks like this:

class AcidPuddle {
  constructor(model) {
    this.model = model;
  }
}

export function create(model) {
  return new AcidPuddle(model);
}

Within the constructor, we set this.model on our script object. This will allow us to interact with the game object that our script will manage.

2.5 Control zones

We will need a way for it to know when characters are moving around in it. To that end, we will need two things: a script, which we have prepared earlier, and a control zone.

Let's configure our control zone first. Create a control zone for the puddle, like this:

The first thing we did here was unchecking the Blocks path checkbox: by default, control zones block access to the zone cases. But we want characters to walk on our puddle, so our zone must be accessible.

Then, we toggled the zone edit mode: when the zone edit mode is enabled, clicking on tiles will add them to the control zone.

Alright: now that our control zone is ready, let's see how to leverage it using scripts to inflict damage on characters as they enter or exit the zone. To achieve that, our script object can implement the hooks onZoneEntered and onZoneExited, like this:

class AcidPuddle {
  constructor(model) {
    this.model = model;
  }
  
  onZoneEntered(character) {
    this.inflictBurn(character);
  }
   
  onZoneExited(character) {
    this.inflictBurn(character);
  }
   
  inflictBurn(character) {
    if (character == game.player)
      game.appendToConsole("The acid is slowly disolving you !");
    character.takeDamage(10);
  }
}

export function create(model) {
  return new AcidPuddle(model);
}

With that example, we know how to make our object react to characters entering or leaving its control zone. But what if we want to inflict damage over time to the characters that are already within the zone ?

We will update our acid puddle script to inflict damage to the residents of its control zone over time. For that, we will use the getControlZoneOccupants method from our game object, conjointly with its Task Manager:

class AcidPuddle {
  constructor(model) {
    this.model = model;
  }
  
  // The initialize hook only gets called the first time the script object is instanciated
  // for this specific game object
  initialize() {
    this.model.tasks.addTask("inflictBurn", 3500, 0);
  }
 
  inflictBurn() {
    const occupants = this.model.getControlZoneOccupants();
    const characters = occupants.filter(object => object.getObjectType() == "Character");

    characters.forEach(character => character.takeDamage(10, null));
  }
}

export function create(model) {
  return new AcidPuddle(model);
}

• We use this.model.tasks.addTask to schedule a call to a method in the game object's script. The parameters are respectively: the name of the script method to call, the time interval expressed in milliseconds, and how much time will the cycle repeat. If that last number is zero, the task repeats indefinitely.
  In this example, we scheduled a call to inflictBurn every 3.5 seconds.
• The getControlZoneOccupants method returns a list of all the objects in a zone: but we only care about characters, which is why we filtered out the non-character objects using getObjectType.
  Then, we iterate over each character and inflict damage to them by calling takeDamage.
• takeDamage takes two parameters: the first one for the amount of damage inflicted, while the second one is meant to indicate which other character inflicted the damage. When damage hasn't been inflicted by any character in particular, you can just pass null instead.

Note that a control zone position is relative to its owner object. This allows you to implement interesting behaviours when attaching a control zone to a character.

2.6 Detectability

Sometimes, objects should be concealed to the player. Concealed objects can be revealed through script, or through detection by the player. Detection is based on the player's Perception and the distance between the player and the object.

If we edit the initialize method of our script as below, we will make our object invisible to the player until we manually reveal it later. We do this by setting the this.model.hidden property:

  initialize() {
    this.model.hidden = true;
    this.model.tasks.addTask("inflictBurn", 3500, 0);
  }

What if we want to enable detectability for the player ? To do that, we'll use sneaking, as following:

  initialize() {
    this.model.toggleSneaking(true);
    this.model.interruptOnDetection = true;
    this.model.tasks.addTask("inflictBurn", 3500, 0);
  }
  
  onDetected() {
    game.appendToConsole("You detected a puddle of acid");
  }

Note that we also set interruptOnDetection to true: this will cause the detection to interrupt whatever the player is currently doing. It is useful to prevent the player from trigerring a trap that he just detected.

We also added the onDetected method, which is called whenever concealed objects are detected.

Well then ! We've worked hard on that puddle of acid. Let's see it in action:

2.7 Object groups

Object groups are a special kind of game objects. They have two main uses:

• They can contain game objects, as well as other object groups, allowing you to organize your game objects in a tree.
• Much like game objects, they can also include a script, a control zone and a task manager. This is useful when you need an object to manage a bunch of other objects, or when you need to add scripted behaviours that aren't bound to a game object.

To add an object group, click on the following button in the game object manager:

Object groups appear on top of the game object list. Click on your new group to open the group view:

2.8 Copy/Paste

In the game object manager views, there's a set of buttons visible on the top-right corner.
When opening a game object or an object group, you should see the Copy button appear right on the left of the trashbin button.

You can use the Copy button on any object group or game object to save it in the clipper. When something is in the clipper, the Paste button will appear on group views. Click on the paste button to duplicate the object as many time as needed.