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

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

``````"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”).

`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”).