This document provides information for building the world of Akagoria.

Warning
 This is a work in progress, it may change in the future

1. Introduction

All the pieces described in Section 2, “Map” and in Section 3, “Data” are serialized into akagoria.dat. The scripts described in Section 4, “Scripts” are not serialized and are part of the distributed package.

2. Map

The map of Akagoria is built with Tiled. It has \(2048 \times 2048\) tiles of size \(32 \times 32\).

Tip
 It is recommanded to desactivate the minimap as it can slow down Tiled with a big map.

2.1. Floors

The map is composed of several floors. The floors are numbered with integers, even floors are outside floors, and odd floors are insdide floors. Floor 0 is the floor at the sea level.

Table 1. Floors number
Inside Outside

First Basement

-2

-1

Sea level

0

1

Each floor is composed of a group of layers. The group has an integer property named floor and fixed to the floor number. Each layer has a string property named kind. Some layers provide graphics while other provide invisible data that is necessary for the game.

Table 2. Graphics layers on each floor
Name Type Value of kind

Ground

Tile layer

ground_tile

Low Tiles

Tile layer

low_tiles

Low Sprites

Object layer

low_sprites

High Tiles

Tile layer

high_tiles

High Sprites

Object layer

high_sprites

Graphics layers are rendered in the order of Table 2, “Graphics layers on each floor”. The hero and the NPCs are rendered between "Low Sprites" and "High Tiles".

Table 3. Data layers on each floor
Name Type Value of kind

Areas

Object layer

areas

Locations

Object layer

locations

Zones

Object layer

zones

Collisions

Object layer

collisions

2.2. Graphics layers

2.2.1. Ground tile layer

This layer is used for the ground, so it must cover the whole floor.

This layer must use a single tileset, generally the Biomes tileset.

2.2.2. Other tile layers

These layers are dedicated to large items that can not be represented with a single sprite.

Table 4. Examples of items
Layer Items

Low Tiles

roads, rivers, unreachable areas, …​

High Tiles

roofs, …​

2.2.3. Sprite layers

These layers contain all the small items that are spread all around the world. If the item has an upper part that can cover the hero, then it must go in the "High Sprites" layer. Otherwise, it goes in the "Low Sprites" layer.

Each sprite in the tileset can have a collision shape. It is defined in Tiled. The collision shape is represented by an ellipse object or a rectangle object or a polyline object.

2.3. Data layers

2.3.1. Areas layer

The "Areas" layer contains the name and position of the areas of the world. A location is represented by a point object or an ellipse object with no size.

2.3.2. Locations layer

The "Locations" layer contains special points of interest that can be used in the script (see Section 4.2, “Adventure script”). A location is represented by a point object or an ellipse object with no size.

2.3.3. Zones layer

The "Zones" layer contains zones that can trigger an event in the script (see Section 4.2, “Adventure script”). Each zone has a string property named message that contains the message to be sent. Optionnally, it may have a string property named requirements that contains a comma-separated list of requirements. The event is triggered only if the hero has all the given requirements.

A zone is represented by a rectangle object or a polygon object.

Table 5. Special messages
Message Description

MoveUp

Move the hero one floor up (floor number is increased by 2)

MoveDown

Move the hero one floor down (floor number is decreased by 2)

2.3.4. Collisions layer

The "Collisions" layer contains the collision shapes that prevent the hero to go in unreachable areas.

A collision shape is represented by the a polyline object or a polygon object.

3. Data

In this section, all the files are plain JSON files.

3.1. Atlases

"SmallItems": {
  "path": "sprites/items-s.png",
  "width": 16, "height": 16
}

3.2. Characters

"Alice": {
  "size": { "width": 60, "height": 55 },
  "weapon": "SmallSword"
}

3.3. Items

"GemRuby": {
  "description": "Ruby",
  "trait": { "type": "rare" },
  "shape": { "type": "circle", "radius": 10 },
  "sprite": { "atlas": "SmallItems", "index": 0, "scale": 0.25 }
}

3.4. Weapons

"SmallSword": {
  "description": "small sword",
  "type": "melee",
  "ATK": 10,
  "REQ": 30,
  "VP": 3,
  "range": 1,
  "angle": 90,
  "cooldown": 2000
}

3.5. Dialogs

"Name": {
  "type": "Simple",
  "content": [
    { "speaker": "Alice", "words": "Hello!" },
    { "speaker": "Bob", "words": "Hey you!\nHow are you?" }
  ]
}

3.6. Quests

3.7. Notifications

"Welcome": {
  "message": "Welcome to Akagoria!",
  "duration": 3.0
}

4. Scripts

Scripts are written in the Wren language. They are loaded at startup. They contain classes with static functions only. The script must not store any state as they can not be serialized when saving the game.

4.1. World script

This script handles the interactions with the state of the game.

4.1.1. Hero functions

World.moveHero(location) move the hero to the specified location. The location parameter is a valid location name on the map (see Section 2.3.2, “Locations layer”).

World.moveHeroDown() and World.moveHeroUp() are used when the messages MoveDown and MoveUp respectively are triggered (see Table 5, “Special messages”).

4.1.2. Notifications functions

World.postNotification(notification) send a notification on the screen. The notification parameter is a valid notification name (see Section 3.7, “Notifications”).

4.1.3. Requirements functions

World.addRequirement(requirement) adds a requirement to the hero.

World.removeRequirement(requirement) removes a requirement to the hero.

4.1.4. Characters functions

World.addCharacter(character, location) adds a character in the specified location. The character parameter is a valid character name (see Section 3.2, “Characters”). The location parameter is a valid location name on the map (see Section 2.3.2, “Locations layer”).

World.setCharacterMood(character, mood) set the character’s mood. The character parameter is a valid character name that has been added with addCharacter. The mood parameter can be one of Mood.Quiet or Mood.Angry.

4.1.5. Items functions

World.addItem(item, location) adds an item in the specified location. The item parameter is a valid item name (see Section 3.3, “Items”). The location parameter is a valid location name on the map (see Section 2.3.2, “Locations layer”).

World.addItemToInventory(item) adds an item to the hero’s inventory. The item parameter is a valid item name (see Section 3.3, “Items”).

4.1.6. Dialogs functions

World.startDialog(dialog) starts a dialog. The dialog parameter is a valid dialog name (see Section 3.5, “Dialogs”).

World.attachDialogToCharacter(dialog, character) set the next dialog of a character. The dialog parameter is a valid dialog name (see Section 3.5, “Dialogs”). The character parameter is a valid character name (see Section 3.2, “Characters”).

4.2. Adventure script

This script contains the callbacks that are called by the engine.

Adventure.initialize() is called just after script loading. It is responsible for initializing all the other callbacks.

Adventure.start() is called at the beginning of the game. It is responsible for setting the initial state of the game.

Adventure.onMessage(message) is called when the hero hits a zone. The message parameter is the message that is defined in the zone (see Section 2.3.3, “Zones layer”).

Adventure.onDialog(dialog) is called at the end of a dialog. The dialog parameter is the name of the dialog that just ended (see Section 3.5, “Dialogs”).