# TirNanoG User's Manual

# TirNanoG Editor User's Manual

Welcome to the manual for TirNanoG Editor, the Free and Open Source Adventure and Action RPG Games creation suite.

## Getting Started

- Installing and running the TirNanoG Editor
- Creating a Project
- Import Game from `game.tng`
- Directory structure of a TirNanoG Project (external link)

Hint

This manual can be used off-line. From the right-click pop-up menu, choose "Save As". Save it under `C:\Program Files\TirNanoG\doc` (Windows) or `/usr/share/doc/tnge` (Linux). If `manual_en.html` can be found on your machine in the above directory, then the editor will open that whenever you press the Help button or the `F1` key. Otherwise it opens the on-line manual.

## Supported Formats

The editor is not only capable of creating games, but you can also import assets in different formats with it. The required conversion is done under the hood, you can concentrate on your game without worrying about the details.

### Fonts

It'd be easier to list what's not supported. Most common formats include:

- TrueType (.ttf) and OpenType (.otf)
- FontForge (.sfd)
- WebFonts (.woff, .woff2)
- X11 Fonts (.bdf, .pcf, also their compressed versions, .bdf.gz, .pcf.gz)
- Scalable Screen Fonts (.sfn)
- and any image file for colorful pixel fonts

As for the encoding, only UTF-8 encoded UNICODE supported, so the fonts must contain glyphs for the ISO-10464 code page. Special characters above the Basic Multilingual Plane (U+0 - U+FFFF) like emoji icons are supported too (up to U+10FFFF) as well as multi-character ligatures.

### Sprites

To import your sprites it is greatly recommended to use true-color PNG with alpha channel (32-bit), but you can also use

- any Portable Network Graphics (.png, 8-bit, 16-bit, grayscale, 24-bit true-color, indexed etc.)
- GIMP eXperimental Computing Facility (.xcf)
- Photoshop Document (.psd, limited features, not all files supported)
- Joint Photographic Experts Group's (.jpg .jpeg, baseline and progressive too, but not all)
- WebPicture (.webp, all variants, lossy and lossless, animations too)
- Graphic Interchange Format (.gif, animations supported too)
- Targa Graphics (.tga)
- Windows Bitmap (.bmp, non-rle compressed only)
- Model 3D (.m3d, animated 3D models)
- Wavefront OBJ (.obj, static 3D models)
- any 3D model in other formats (.blend, .dae, .fbx, .glTF, etc. if you have assimp installed)

### Palettes

- GIMP Palette files (.gpl)
- Adobe Photoshop Color File (.aco)
- Adobe Swatch Exchange files (.ase)
- Microsoft Palette files, JASC-PAL (.pal)
- Paint.NET Palette files (.hex, .txt)
- plus you can use any image to load a palette from.

### Audio

- Xiph.org's Ogging Vorbis Audio (.ogg)
- MPEG Audio (.mp3)
- Windows Wave Format (.wav)
- Protracker Module (.mod)
- Fast Tracker II (.xm)
- Scream Tracker 3 (.s3m)
- Impulse Tracker (.it)
- FLAC (if you have libflac installed)
- Opus (if you have libopus installed)

### Video

- Xiph.org's Theora Video (.ogv)
- any other video format (.mp4, .mkv, .avi, .mpg, .flv, etc. if you have ffmpeg installed)

Do not try to import full-length movies, only short (1 - 2 min) cutscenes.

## Get Involved

This manual is written by volunteers. Please consider to join the effort and contribute to this manual by submitting a PR to the git repo.

Currently we are in a big need for translators.

Next

# Getting Started

## Installing

Note

The default game assets are distributed separately to avoid licensing conflict with GPL. The TirNanoG Base template can be downloaded from here.

Go to the repository and download the archive for your operating system.

### Windows

1. download tnge-i686-win-static.zip
2. extract it to `C:\Program Files` directory and enjoy!

This is a portable executable, no installation required.

### Linux

1. download tnge-x86_64-linux-static.tgz
2. extract it to the `/usr` directory and enjoy!

Alternatively you can download the deb version and install that with

    sudo dpkg -i tnge_*.deb

## Running

You can start the editor any time by running `tnge`. The tarball includes a .desktop file to place it in your Application menu too (for Windows, a similar .lnk shortcut exists).

Hint

Just start `tnge` once, it will add itself to the menu for your convenience.

The editor will create a directory called `~/TirNanoG` in your home folder to store all your game projects. If this doesn't suit you, you can specify a different projects directory as a command line argument.

Your machine's localization will be autodetected, and if possible, the editor will greet you in your own language. If you want, you can explicitly select a language on the command line, for example `tnge -L ru` or `tnge -L ja` (on Linux) or `tnge /L ru` or `tnge /L ja` (on Windows).

Windows
  Right click on the .lnk file, from the popup menu choose "Properties". In the "Target" field you can add the command line options:
  Setting options on Windows
Linux
  Use your favourite terminal for the command line, or edit the desktop file `/usr/share/applications/TirNanoG.desktop`.

      <a>Desktop Entry</a>
      Version=1.0
      Type=Application
      Name=TirNanoG Editor
      Comment=Create TirNanoG games
      Exec=/usr/bin/tnge -L hu
      Icon=tnge
      Terminal=false
      StartupNotify=false
      Categories=Development;

### Command Line Options

On Windows, replace `-` with `/` for the flags (because that's the Windows' way of specifying flags, for example `/t`, `/vv`), otherwise all options are identical.

    tnge [-L <xx> ] [-t <theme> ] [-g <gameid> ] [-c <gameid> ] [-v|-vv] [projdir]
    tnge [-p|-u|-l] <atlas>

It also has five non-GUI, command line only operation modes: `-g`, `-c`, `-p`, `-u` and `-l`. These modes do not open a GUI window, nor do they need graphical environment or any installed shared libraries, they merely work in command line alone.

Option | Description
--- | ---
`-L <xx>` | The argument of this flag can be "en", "es", "de", "fr" etc. Using this flag forces a specific language dictionary for the editor and avoids automatic detection. If there's no such dictionary, then English is used. Also sets the default language for the game.
`-t <theme>` | Loads a GUI color theme for the editor's window from a GIMP Palette file. Does not influence the created game.
`-g <gameid>` | Generates a new, and each time unique end user license key (game file decryption key) and prints it to the standard output. Requires `~/TirNanoG/(gameid)/license.txt`.
`-c <gameid>` | Loads a game in TirNanoG Project format and creates a production ready game file in TirNanoG File Format. The result is saved as `~/TirNanoG/(gameid)/game.tng.`
`-v, -vv` | Enable verbose mode. `tnge` will print out detailed information to the standard output, so run this from a terminal.
`[projdir]` | Overrides the default projects directory where the gameid is looked for. If not given, the default directory is `~/TirNanoG`.
`-p <atlas>` | Pack all PNG files starting with `(atlas)` into an atlas `(atlas)_atls.png`.
`-u <atlas>` | Unpack sprites from an atlas `(atlas)_atls.png` into multiple PNG files.
`-l <atlas>` | List sprites in an atlas `(atlas)_atls.png`.

For more details on how to use the `-g` switch, the section Selling Your Game has some tips and tricks. About the `-p`, `-u` and `-l` flags, see working with atlases.

## Templates

Starting a game from scratch and creating everything from ground up every time is very cumbersome and time consuming. To help you with that, you can use template zip files. You just copy them into the `~/TirNanoG` projects folder, don't bother to extract, the editor will do that for you.

A downloaded template and its folder location

The purpose of these templates is to give you a quick start creating games. These contain pre-configured sprites, animations, map tiles, objects, NPC definitions etc. Starting from the TirNanoG Base template makes the use of the TirNanoG Editor very similar to RPG Maker (but much more featureful and hopefully with a much simpler to use user interface). The editor can also create a template from your project with a single click, no 3rd party zip tools required.

Note

Not all templates contain everything needed for a game. There are also smaller, so called module templates, which provide assets for just a specific feature. You can import these modules later on into your project with the Import Template function.

PreviousNext

# Interface Overview

The window is splitted into 5 horizontal areas with 2 vertical blocks in the middle:

### 1. The Menu Bar

This has the usual menus, plus two bottons: Help button, which opens this manual (also accessible by the shortcut key `F1`); and the Play button which saves and then runs the game (its shortcut is `Ctrl` + `R`).

You can access the menus by pressing and releasing the `Alt` key. Selecting "Quit" from the first menu is the same as pressing `Alt` + `Q`.

### 2. The Tool Bar

Depending on which page you're on, the tool bar might be missing. However usually it has at least the edited entity's internal name on the right.

### 3. Entity Selector

Depending on which page you're on, the entity selector might be missing. This is where you choose which entity to edit. On the figure above, which was made on the Map Editor, this entity selector lists maps. On the Object Editor page, it would list the objects.

### 4. The Main Editing Area

Is where you edit the selected entity. The lookout of this area highly depends on which page you're on.

### 5. The Button Bar

If there's an Entity Selector then it usually holds a Delete button for deleting the highlighted entity; a main editor area Clear button; sometimes (if applicable) a Preview button; and finally and probably the most importantly the Save button which saves the modifications you made to the entity.

### 6. The Status bar

This is where you can see the status messages. It will print out information and tips as you hover over elements, and this is also the place to display error messages.

PreviousNext

# Projects

## Creating a Project

In the menu, choose `Project` > `New Project`. Fill in the fields:

- GameID is the internal name of your game. Up to 16 characters, which may only contain Latin letters and numbers.
- Title is the translateable name of your game that user's see. You can use any UTF-8 character in this.
- Template if you have downloaded some game templates, you can choose one of them here.
- Tiles type and size of the map tiles. Tile type can be either:

  orthographic (also top-down) | isometric (sometimes called 2.5D)

- Map Size in tiles. One map will only be N x N tiles in size, but you can chain up multiple maps into a big open world.

Warning

The product of the Tile Size and the Map Size should not exceed 4096, because that could lead to problems for some players with older GPUs or limited resource handhelds.

When ready, press the Create New Project button.

## Loading a Project

If you have already created a project, go to `Project` > `Load Projects`. From the list, select your game and double-click on it.

When you start the TirNanoG Editor, and you already have some projects, this is the page that will greet you.

More info about what files are stored in a TirNanoG Project.

## Import Game

You can import a game in production ready TirNanoG File Format into the editor. Go to `Project` > `Import Game`. Select the desired game file and press the Import button.

This will also create a project for that game.

## Import Template

Go to `Project` > `Import Template`. Select the desired template file and press the Import button.

This is very similar to creating a new project from template, except this will not create a new project, rather loads the template into an existing project. With this feature you can load several smaller templates into the same project, thus it is not used with full game templates, rather with small modules.

## Export Game

Go to `Project` > `Export Game`. You can also access this with the `F2` keyboard shortcut.

Output `game.tng` files will be generated under the corresponding project's `~/TirNanoG/(gameid)` subdirectory. To use these, you'll need the TirNanoG Player.

You can play the `game.tng` file from the project's directory by pressing the Play button, or copy first to the game's normal path, `C:\Program Files\(gameid)\game.tng` (on Windows) or `/usr/share/games/(gameid)/game.tng` (on Linux), where the TirNanoG Player is looking for these files. In addition to the `.tng` file, launchers like a `(game title).lnk` shortcut link (for Windows) and `(game title).desktop` (for Linux) are also generated. These start the game from its normal path.

## Export Extension

Go to `Project` > `Export Extension`. You can also access this with the `Shift` + `F2` keyboard shortcut.

An extension is very similar to a `game.tng` file, but it must have a different name, and you can control which parts of the project to export into the file.

## Export Template

You can not only load templates into you project, but you can also generate a template from a project. For that, go to `Project` > `Export Template`.

The resulting template will be saved as `~/TirNanoG/(gameid).zip`.

## License Keys

### Editor License for Game Files

The `Project` > `License Keys` menu might be inactive. To create encrypted and proprietary games with this editor, you must ask for permission from the author in a confidential issue (see TirNanoG File Format License). In return I'll send you a `license.txt` file that has to be copied under the game project's folder. This will unlock the creation of encrypted `game.tng` files and generation of end user decryption keys within the editor. Generating end user license keys How you distribute and sell those decryption keys and to whom is entirely up to you (see some tips and tricks below). When end users try to play an encrypted game file, the TirNanoG Player automatically asks for these license keys and decrypts, no third-party tool nor special player required. What's more it is not possible to import encrypted game files back into the TirNanoG Editor for further modifications.

### Selling Your Game

You have several methods to do this, in increasing order of automation.

#### Method 1: Manually

Note

Ideal for hobbyists, fan and doujin games, with just a static website or an FB profile.

The simplest of all, go to `Project` > `License Keys`. On that page, press the Generate button. A new end user decryption key will be copied to your clipboard, and you can paste that into an e-mail, into a chat etc.

Although this is extremely simple, this method requires human interaction each time a game is sold.

#### Method 2: Pre-generated Keys

Note

Ideal for somewhat popular indie game studios and semi-professionals, renting their site from a webhost provider (typically running WordPress, Drupal, Joomla, eCommerce etc.).

Second choice is to pre-generate a bunch of keys. Like before, go to `Project` > `License Keys` and press Generate button a couple of times (and now, press it a few more times). Then upload `~/TirNanoG/(gameid)/endusers.txt` to your server, and use that file from your webshop. You can import that into an SQL table, or just read the file directly, up to you.

Warning

Your webshop is in charge of keeping track which keys in the file were sold.

When your webshop runs out of available keys, just press Generate a couple more times and upload the new `endusers.txt` to your server.

This does not need anything special on the server, just a plain text file (so this is extremely secure and easy to integrate, works with all kinds of webshops) and it only requires human interaction occassionally.

#### Method 3: On Demand Key Generation

Note

This method is for professional game makers who make enough profit to afford their own webserver (typically Azure, AWS, etc. instance) where they can run 3rd party applications.

On your server, create a directory `/home/(webserver user)/TirNanoG/(gameid)`, and copy your editor license there. For example, `/home/apache/TirNanoG/fantasticrpg/license.txt`. When a new key is needed, execute `tnge -g (gameid)` from your webshop, which returns a new, unique key on the standard output.

For example, in PHP you could do:

    1

`$new_end_user_key = trim(exec("/usr/bin/tnge -g fantasticrpg"));`

Or in Python:

    1

`new_end_user_key = os.popen("/usr/bin/tnge -g fantasticrpg").read().strip()`

This does not need human interaction at all, but in return is has to execute TirNanoG on the server. Because no user input is passed on the command line and just a string constant is executed, the security risk of doing this is very minimal.

Hint

You don't have to copy any of the project files, nor will you need dynamic libraries nor a graphical enviroment installed on the server! None of those! All you need is the `tnge` executable and a `license.txt` file, nothing else.

PreviousNext

# Fonts

Go to `Assets` > `Fonts`. You'll see the list of available fonts here. To add a new one, click on the "Add" button in the bottom right corner. A file selector window will appear.

You can use the sfnedit editor to modify the already imported fonts, or you can modify the fonts with FontForge before you import them.

## Bitmap and Vector Fonts

In the file selector window select a font. In the button bar, you can specify a range to import, but most of the time just leave it as-is. When the font is selected, click on the Import button.

## Pixel Fonts

You can also import images as fonts. In this case it is very important to specify the range. Both from and to fields can be an UTF-8 character or a UNICODE codepoint if prefixed by "U+" followed by (up to 6) hex digits.

Glyphs can be placed both vertically and horizontally on the image. If the image is wider than tall, then the font's height will be the image's height, and image width will be divided by the range getting that many glyphs. Likewise, for taller than wide images, the image's width will be the font's width, and image height will be divided by the range to get that many glyphs.

For example, if you want to import a pixel font with numbers, your image should look like

    0123456789

or

    0
    1
    2
    3
    4
    5
    6
    7
    8
    9

In the range specify `0` (the first character in the image) and `9` (the last character in the image). You could also use "U+30" and "U+39" to specify in UNICODE codepoints. This is very important, because without a range it is not known what glyphs will be imported from the image. Finally click on the Import button.

PreviousNext

# Sprites

Hint

If you don't want to load your own custom sprites, you can also use the sprite generator.

## Importing Sprites from Images

Go to `Assets` > `Sprites`. You'll see the list of available sprites here. Note the category selector at the bottom middle, here you can filter the sprites. The categories are as follows:

- user interface related sprites
- tiles and on map object sprites
- character and equipted object sprites
- portraits in dialogs
- fullscreen background images

You can change the category here, but also changeable later before you do the actual import. Now click on the Add button in the bottom right corner.

The screen will change and sprite sheet specification window will appear. Here you can see a toolbar on the top. The icons are as follows:

- load an image as sprite sheet
- change the palette
- resize to half
- resize to double
- flip image vertically
- flip image horizontally
- grid specification (a checkbox and multiple number inputs)
- layout (a combobox and a save icon)
- sprite's name
- erase sprite from import list

Below the toolbar you'll see the sheet image on the left (big area) and the selected sprites list on the right.

## A Typical Workflow

1. Load an image file.
2. From the layout drop-down, select the desired sprite layout.
3. When the layout is chosen, the import list will be filled up with animated sprites automatically.
4. If the import list preview looks okay, press Import to add sprites to the project.

## Loading the Sprite Sheet

Click on the "Load Sprite Sheet" icon in the top left corner (first icon on the toolbar, but also duplicated on the button bar for easy access).

A sprite sheet is an image with several sprites on it. These can be independent sprites, or animated frames of the same sprite. You can also import 3D models and generate sprites from those. For more details, see Models.

## Palette Conversions

Many designers like to create games with limited colors to provide a consistent look-n-feel. To help you with that, you can restrict the loaded image to a certain palette.

Palettes can be loaded from all common formats (.gpl, .ase, .aco, .pal etc.) and from images. With images for the best results, you should use an indexed image (gif or quantized png), or a true-color image that has no more than 256 different colors in it. Dimensions and number of pixels doesn't matter, only how many different pixels there are.

When finding a match for a color on the sheet to a color on the palette, you have two options: either use sRGB distance (fast, mostly good results, but in some very rare edge cases makes bad matches) or CIE76 (slow, works with converting both the image and palette colors to CIE LAB color space first and then calculating the color distances there).

If you're using non-PNG images, then for some exotic formats the color channels might be swapped. You can fix that with the "Swap Red and Blue channels" button. Should not be needed, just in case.

## Basic Conversions

You can resize to half or double, but not to arbitrary sizes. You should load the image with proper dimensions, but it might happen that your game uses 32 x 32 sprites but you only have 64 x 64 sheets. In that case to avoid using a third party imaging tool, you can quickly resize. Both the downscaling and upscaling uses bilinear interpolation, so the results should be good. However keep in mind that upscaling images are always bad, try to avoid that as much as you can.

For portraits, they can be on the dialog's left (face looking to right) as well as on the right side (face looking to the left). The editor and the player does this conversion for you, so you must import all portraits as face looking to the left. It might happen that you only have a portrait facing in the wrong direction. To avoid the use of third party tools, you can quickly flip the image here with a single click.

Some exotic formats stores the image up-side-down. The image loader will take care of that, but if not, you can press the flip image button to quickly fix that. Should not be needed, just in case.

These operations are for quick fix only, the editor does not (and never intended to) replace a sophisticated image manipulation tool.

## Specifying the Sprites

The next on the toolbar is the grid specification. You can uncheck the checkbox and use the entire image as one sprite. Or you can have the checkbox checked and specify a grid of sprites. It is pretty straightforward, play with the width, height, margin and padding values to see what areas are marked for possible selection on the sheet.

If the sprite sheet does not fit in the box, you can move it around by right clicking on it.

### Single Sprites

On the right, there's the list of selected sprites. If you haven't clicked on any, or clicked on the topmost "New sprite" icon, then each time you make a selection on the sheet with left button, a new sprite will be added. This is ideal for selecting tiles from a tilemap for example.

### Animations

To import animations, first you have to select the first sprite using "New sprite". Then you must click on the sprite in the list on the right for which you want to add further frames (or use the mouse wheel). This might sound complicated, but actually doing it is not: frames are added to the sprite which is selected on the right.

Hint

After adding the first frame of a sprite, press the `⯆` down cursor key, and then you can select its further frames. When finished, press the `⯅` up key to go back to add new sprite mode.

When a sprite in the list on the right is selected, you'll be able to see it as an animation. You can also set the animation's type (play once, play forth and back, play in a loop) and its direction (which will help you a lot later filtering the sprites). Animations that happen in place should be marked as "south", otherwise you have 8 directions to choose from. You don't have to use all the directions, it is possible that a certain game only uses 4 for example.

### Larger Sprites

Not all sprites are equal in size, some are larger. For that you can select multiple adjacent grid blocks on the sheet, just left click on the first block, hold the mouse button down, move the cursor to increase the selection, and when you're happy with it, release the mouse button. For animations, all frames must be the same size.

### Deleting

If you have accidentally added a bad sprite from the sheet, you can select it on the right and click on the Erase icon above the list, that will remove the entire sprite. Pressing the `⇦` Backspace key will delete the last frame from the selected sprite, and only remove the sprite if no more frames left.

## Layouts

Specifying the grid and sprite selections might be very time consuming and repetative. To help you with that, you can save the sprite layout: on the toolbar, right to the grid specification, you can enter a layout name and press the Save icon.

Next time you load a sprite sheet image, you'll be able to click on the layout name combobox, and select the layout from a dropdown list. After that, all the grid and sprite selections will be applied to the new sprite sheet image, and selected sprites will appear in the list on the right automagically.

Even more, when applying a layout on the entire image and if the image has a 8 x 16 palette at its bottom right corner, then dynamic recoloring will take place. With this you can import a big variety of different sprites using the same sprite sheet. You can also select the "?" (ask) color variant, in which case the palette will be imported separately, and you can set it on the character options. With this, the player will be able to select the color variant during character generation.

You can also specify which part of the sheet should be used with a layout. If you hold down `Shift` and make a selection with the mouse left button, then areas outside of that selection will turn red. When you choose a layout from the combobox, those red parts won't be parsed at all. This is useful if you have multiple for example terrain types on an atlas, each with its own wang-set, and therefore should be parsed separately. You select the first terrain type, then apply the layout, and import the sprites. Then you select the second terrain type, apply the layout and import etc., no need to cut up the atlas into separate terrain sheet images apriori.

## Do the Actual Import

When you're satisfied with the selected sprites on the right, you have to give a name to them in the input box above the list. Sprites witout a name will be imported with a "_xxx" suffix where the "xxx" is a serial number from 001 to 999.

You got that selected list, you've given a name to the list (input box above), and named the sprites (above each sprite image in the list), you've double checked that you're in the correct category (icons at bottom middle), then you can press on the Import button. After that you can go back to the sprites page or load a new sheet to import further sprites.

## Working with Atlases

Normally the editor saves each sprite in a separate PNG file (with frames stored horizontally), which is good for compatiblity if you want to organize, copy or edit sprites with a third party software. However having lots of small files could slow down project loading considerably. To speed that up, the editor supports sprite atlases. It can not only load these atlases, but it is also capable of doing the sprite packing and unpacking on its own, no third party tools required.

Atlas packing `-p` reads in all PNG files in the current directory which start with `(atlas)`, and saves `(atlas)_atls.png`. For example, assuming you have sprites like `sword_walk_soo6.png`, `sword_walk_weo6.png`, `sword_walk_noo6.png`, `sword_walk_eao6.png`, `sword_slash_soo6.png`, `sword_slash_weo6.png`, `sword_slash_noo6.png` and `sword_slash_eao6.png`, then

    tnge -p sword

will pack all of these into `sword_atls.png`. Atlas meta info is stored in PNG comment.

Unpacking `-u` does the opposite, it reads in `(atlas)_atls.png`, and saves separate sprite PNG files. For example

    tnge -u sword

will read in `sword_atls.png` and will save the aforelisted PNG files.

If you're just interested which sprites are stored in an atlas, but don't want to unpack, you can use

    tnge -l sword

to list the sprites.

Warning

Never modify these sprite atlases in a third party pixel editor, because you might loose the atlas meta info.

Warning

Although the TirNanoG Editor saves atlas info with the tilesets into the maps, Tiled does not support that, so it is commented out for now. This means you must unpack any tile and object atlases if you intend to edit the maps in Tiled as well.

PreviousNext

# Generator

Go to `Assets` > `Generator`. Here you can generate sprites using modular templates with just a few clicks.

Note

If the generator appears empty and all options are inactive, then you have to install the TirNanoG Base to get the sprite templates.

Hint

For the TirNanoG Base, the generator is also available over a web interface.

On the toolbar on the right, you have the input field for the name of the sprite to be generated.

## Components

Other icons on the toolbar select which component you want to configure, like body, head, clothes, etc.

On the left in the entity list area, you can see the list of available variants of the selected component. Each variant has a checkbox, with which you can enable / disable that particular variant. For some components, like body, usually you'll only need one active variant, however other components, like clothes, might need more.

Some templates might have dynamic recoloring options. If that's the case, then you'll see the available color variants for the currently selected option beneath the entity list. Clicking on the color chooses that variant.

Component types are flexible, and fully customizable. See expanding the character sprite generator for more details.

## Sprite Preview

On the right in the main area you'll see a preview of the character to be generated.

When you're satisfied with the preview, press the Import button, and sprites will be generated and added to your project. After that they will appear on the "Sprites" tab, and you can use them for your NPCs.

Hint

If you want to use some of these as a player character option too, you can enable exactly one variant and generate sprites for that. Alternatively you can import the sprite template image on the Sprites tab by selecting the "TNG-Base" layout.

PreviousNext

# Models

## Importing Sprites from 3D Models

Go to `Assets` > `Sprites`. You'll see the list of available sprites here. Click on the Add button in the bottom right corner.

The screen will change and sprite sheet specification window will appear. Click on the "Load Sprite Sheet" icon in the top left corner (first icon on the toolbar, but also duplicated on the button bar for easy access).

## Loading the Model

Several formats supported, and the steps required for importing them might slightly vary depending what is stored in the model file. For importing sprite sheets from 2D images, see Sprites.

On the file selector window, select a 3D model file. At the bottom left, specify the size to rasterize at (width and height will be the same), set the Frames Per Second value and in which direction the model is facing (for Model 3D files that is always "south"). By checking the "Manual" checkbox, you'll be able to select the action animations from the timeline manually (see below).

Note

Movies usually use 25 - 30 FPS, but NOT animated sprites. An animated sprite usually has 3-5 frames (for a one second long animation that's 12 FPS), maybe 10 frames in total if the animation is very fluid.

When file choosen and dimension given, click on the Load button.

### Model 3D Format (.m3d)

This is the most featureful format and it is fully supported. If you choose this, nothing left to do, everything will be taken care for you. You will be redirected back to the sprite specification page with a fully populated sprite import list.

You can convert any 3D format into Model 3D format, and there's a Blender export plugin too.

### Wavefront Object (.obj)

These can only store static (non-animated) objects, but it is a very popular and widespread format, supported by many tools and model editors. Again, if you choose this, nothing left to do, because there will be only one sprite imported in 8 directions without animations.

### Other Formats

For that, you'll have to have an installed Assimp library. On Linux, use your distro's package manager, for example `apt-get install libassimp`. On Windows, yeah, good luck finding the pre-built DLL that the installation page is talking about. But if you've found it, copy `assimp32.dll` to `C:\Program Files\TirNanoG` (next to `tnge.exe`).

If the library is detected, other 3D models in various formats (.3ds, .blend, .glTF, .b3d, .collada, .dae, .fbx, .x3d, etc.) will automatically show up in the editor's file selector window.

Warning

I give no support for Assimp. If you run into any problems, try asking on their forums.

## Specifying the Sprites

If the model contains an animation but no action specifications, or you have checked the "Manual" checkbox, then you have to select action frames from a timeline.

1. source, animated model
2. timeline with frames
3. the add "New Sprite" button

Just like with 2D sprite sheets, you'll see the source on the left (big area), and sprite selections on the right (import list). Only this time you'll see one big model, and a timeline beneath instead of a sheet. You don't select images for 3D models, rather frame intervals on the animation timeline for each action. Once a selection is made, press the "New Sprite" button in the topmost record of the import list, and sprites will be generated and added to the import list in all 8 directions.

Hint

You can move the selection on the timeline by pressing the `⯇` left and `⯈` right cursor keys.

## Do the Actual Import

When you're satisfied with the sprite list on the right, you have to give a name to them in the input box above the list. Sprites without a name will be imported with a "_xxx" suffix where the "xxx" is a serial number from 001 to 999.

You got that selected list, you've given a name to the list (input box above), and named the sprites (above each sprite image in the list), you've double checked that you're in the correct category (icons at bottom middle), then you can press on the Import button. After that you can go back to the sprites page or load a new sheet to import further sprites.

PreviousNext

# Media

## Importing Audio and Video

Go to `Assets` and select the media type. On the page that appears, you'll see the list of available media files of that kind. Note the category selector at the bottom middle, you can select media category there too. To add a new one, click on the Add button in the bottom right corner. A file selector window will appear.

### Instrumental Music

In the file selector window select a music file. It can be in various formats, .ogg, .mp3, .wav, .voc, .mod, .xm, .it etc. (if you have `libflac` or `libopus` libraries installed, then those formats are supported as well). When the file selected, click on the Import button.

All music will be converted into .ogg (with stereo or surround 5.1 channels) automatically.

For the music, I recommend to use SoundTracker or MilkyTracker (you can record music with Audacity too). For old school goodies, there's a modernized clone of FastTracker II running on Linux.

### Sound Effects

Same as with music files, but they are going to be converted to an .ogg with mono channel (sounds are mixed into the output using a placement effect, so they must be mono).

For the sounds, I recommend to use Audacity.

### Speech

Recordings of voice actors are similar to sound effects, will be converted to an .ogg with mono channel. The only difference is, the filename will be suffixed by the ISO language code, for example `_en`.

### Movies

You can always import .ogv Theora videos without any dependency. But if you have ffmpeg installed, then all the other formats (.mp4, .mkv, .mpg, .avi, .flv etc.) supported as well, and they will automatically show up in the editor's file chooser window.

On Linux, use your distro's package manager, for example `apt-get install ffmpeg`. On Windows, download the latest from ffmpeg.org (probably called `ffmpeg-git-essentials` something), and from the downloaded archive, extract `ffmpeg.exe` (and that file only) to `C:\Program Files\TirNanoG` (or anywhere in your `%PATH%`).

Do not try to import full-length movies, only short (1 - 2 min) cutscenes. Audio tracks in videos must never contain speech, only instrumental music and sound effects (that's because game translation would be impossible otherwise). The editor (and the player) takes care of mixing the localized speech audio track onto the video.

To create videos, you can use OpenShot or ShotCut. You can also generate videos of animated 3D models and scenes with Blender. All of these tools can export to Theora.

Note

You can convert your video in any format into Theora by hand:

    $ ffmpeg -i movie.avi -q:v 5 -r 30 -q:a 3 -ar 44100 -ac 2 movie.ogv

BTW, this is what the editor does under the hood.
PreviousNext

# UI Elements

## Specifying the Game's Look'n'Feel

Go to `Interface` > `Elements`. Here you can specify all the UI elements, therefore it is one single form with a bunch of sprite and font selector buttons.

There's really not much to talk about this one. You have to select which sprites to be used for the UI. It is a boring and repetitive task, but has to be done only once.

## Preview

By clicking on the "Preview" button at the bottom, you'll be able to see how the selected sprites will make up the interface. You'll get an example window with example tabs, inputs, scrollbars, etc. Below the window, there'll be an example dialog box.

If you have set cursor sprites too, then on the top left corner you'll see three hotspots (with slightly different background colors, redish, greenish and blueish). Hovering the mouse over them will show you how those cursor sprites look (including animation, handy for the loading cursor for example).

The preview IS NOT a working user interface. Only the checkbox and the buttons can be pressed to check how the pressed state looks. You won't be able to move the slider or the scrollbars.

PreviousNext

# Main Menu

## Customizing the Main Menu

Go to `Interface` > `Main Menu`. It is one single form with all the relevant options.

Just like the other menu entries under the Interface menu, this also has a "Preview" button at the bottom, but here you have two: one for the main menu itself, and another one for the character generation window which is shown when the user selects the "New Game" option.

## Intro

You can select an intro cutscene which is played before the main menu is first shown. You typically want to select a cutscene with a neat animation of your team's logo here.

It is possible that a game doesn't have a main menu at all. It that case, uncheck the "main menu enabled" checkbox.

## Background

You can select a background music, a background movie or a background image with 3 parallaxes. Music works both for movie and background image, however movie files could have their own audio tracks as well.

## Title

Here you have two options. Either you can use a header image sprite with some cool graphics of the game's title, or you can display the game's title using a specified font. You can also do both, if it this is a sequel, then the header image should be the same as the in the first game (it is important that users recognize it), and text title should be the episode's title.

Note

The textual title is translated to the end user's language, while the header image isn't.

## Buttons

These are the buttons used to display the main menu's options. Could have used the standard buttons, but thought game makers would like to use menu options on the main menu that stand out. Just like with the UI elements, you can specify the button's left sprite, background and right sprite, as well as font type, size, color etc.

## New Game

Probably not the best place for this, but when the player clicks on the "New Game" main menu option, they have to be asked for their character's name, and also an attribute distribution graph is shown. As this is the one and only place where the player needs to enter text into an input box, as well as the only place where the distribution graph is displayed, I put their configurations here.

## Exit Game

To configure what is shown when the player selects the "Exit Game" option, see Credits.

PreviousNext

# Heads-Up Display

## Configuring the Heads-Up Display

Go to `Interface` > `HUD`. Here you can set up the look'n'feel of the HUD during the game.

Just like the other menu entries under the Interface menu, this also has a "Preview" button at the bottom.

## Controls

For touchscreen devices, there must be a navigation control and an action buttons control on screen. These use a default image in the game, but if you want, you can customize these to your liking to match your game's look'n'feel.

The navigation circle is shown in the bottom left corner, while the action buttons on the bottom right.

## Itembar

This is which shows what items the characters are carrying on their belt and in their main hand.

You can select a background image, and if you want, a semi-transparent front cover image too.

The various number inputs specify the number of items, one item's width, height, starting position on the background image and the gap between the items in pixels (in this order). Because you probably want to visually separate the item hold in hand, there's also an additional gap between the handheld item and the other items.

The item bar is always displayed in the bottom middle of the screen.

## Statusbar

This is where the user's status is shown. Typically health points, mana points, experience and such.

You can have the statusbar combined on the itembar's background image. Typically used with orb like progress bars. When you have a separate statusbar, then it is displayed on the top middle of the screen.

Similarily to the itembar, you have a background image, and you can also have a semi-transparent front cover.

## Progressbars

With this engine there's no hard coded stat, everything is configurable. Therefore you must specify what variable to show where, and this is what the progressbar specification list is for.

In the list you can see the bars that are already defined. Below the list you have input boxes to specify a new one. By selecting a progressbar from the list, the "Erase" button will became active and the selected bar can be removed.

For defining bars, you have the options:

- direction: can be left-to-right (standard), bottom-to-top (orb-like bars) and alpha-channel (for temporary effects, like poisoning), enemy's HP bar (shown above the enemy)
- position: on the statusbar (or itembar) in pixels. When both coordinates are 0, that defines a temporary effect progressbar.
- value attribute: select the attribute to be used to get the value from.
- max attribute: selects the attribute which holds the maximum value for the progressbar.
- image: the sprite for the bar. Depending on the direction only either the left or the bottom part will be shown.
- background image: this is optional, and can be useful for temporary effects when they don't use alpha as direction.

With "enemy" direction the progress bar is left-to-right and not shown on the statusbar, rather above the enemy character. It is used to specify which sprites to use to display the enemy's HP.

Temporary effects are stacked and displayed at the top middle of the screen regardless to the statusbar. For the position there's a coordinate picker, but in order to use it, first you have to specify the status bars' (or item bars') background image as well as the progressbar's image.

When all input box are filled in, click on the "Add" button to add a new progressbar to the list.

If you have misplaced a bar on the statusbar's background, there's no need to delete and add it again. When a progressbar is selected, you can left click on the direction and position coloumns to increase them, and right click to decrease them. This is not very intuitive, but a neat trick to move the bars around without the need of redefining them.

## Inventory

Shows what the user has. It has three tabs: "Items", "Stats" and "Quests". Here you can configure the first one (for the others see objects with skills, and quests).

In the inventory's first row, you can specify the inventory's normal and pressed icons, similar sizes and margins for the items as with the itembar, the font to be used to display the number of items in the inventory, and finally three sprites: normal item's background, selected item's background and an image for the equipment slots.

In the game, the inventroy's icon is shown on the top right corner of the screen. It must be 32 x 32 pixels in size (if not, it will be resized automatically).

Similarily to the HUD's item bar, you can specify the item's size and the position where the item is displayed. Here there's no gap configuration, because that's specified by the slot background sprite, and therefore the item's position is relative to the slot background sprite. You have two slot images, one for normal slots, and one for the active, selected slot.

The last sprite, the equipment figure must contain at least one slot, but might have more. This should be an image of a figure which displays what items are worn by the user and where. The one mandatory slot is for the handheld item. The item's size on the equipment figure is the same as with the slots, but if you want background slots too, those must be drawn on the sprite image (might mean more work for the designer, but greater flexibility).

## Equipment Figure and Slots

Now the problematic part is, that the TirNanoG engine does not hardcode how many slots there can be, therefore you must specify all of them here. As said, only one slot is mandatory, for the handheld item, and that must be the first (typically the right hand of the figure). Others (like body for armour, legs for trousers, head for hat etc.) depends what game you're creating. The table below lists these slots.

By selecting a slot from the list, the "Erase" button will became active and you can delete that slot.

After specifying the starting position (relative to the equipment figure's background image), and a comment, press the "Add" button to add the slot to the list. The same trick works here as with the progressbar, for the selected slot in the list, left clicking the position will increase, while right clicking will decrease the coordinate, allowing to re-position the slots without the need to removing and adding again (you can use the "Preview" button to see if the coordinates are correct). Just like with the item bar, there's a coordinate picker helper too.

The slot's name is irrelevant, and won't be shown to the player. It is merely a comment for the developer so that they can select the slot more easily in the objects' in inventory tab when they are configuring the "equipted at" choices for a certain object.

PreviousNext

# Alerts

## Configuring Alerts

Go to `Interface` > `Alerts`. Here you can set up the look'n'feel of the pop-up messages.

Just like the other menu entries under the Interface menu, this also has a "Preview" button at the bottom.

## Font

Specify which font to use.

## Duration

Specify (in partial seconds) for how long an alert message should be shown. You can also specify the fade in and fade out times with the sliders.

## Messages

The translatable text and sound effect to be used. Currently only quests have alerts.

PreviousNext

# Credits

## Specifying Authors and Attributions

Go to `Interface` > `Credits`. It is one single form with all the relevant options.

This page looks very similar to the main menu: you can specify the background music, the background image, the font's size, style, color etc.

Just like the other menu entries under the Interface menu, this also has a "Preview" button at the bottom.

## Background

To select the background music and image.

## Header

Specifies the category header's font.

## Font

The normal font to be used with authors' names.

## Category

Selects the author list for that category.

## Authors

When you select a name, the "Erase" button will became active and you'll be able to remove. If you enter a name into the input box below the list and click on the "Add" button, then the author's name will be added to the list lexicographyically ordered.

PreviousNext

# Choosers

## Specifing Route Choosers

Go to `Interface` > `Choosers`. Choosers are a construct that display a list of icon options on screen and may alter the game's state. They are typically used to choose a game route, but could be useful for other things as well.

Just like the other menu entries under the Interface menu, this also has a "Preview" button at the bottom.

## Choosers List

On the left, in the Entity Selector there's a list of already configured choosers. By double-clicking on an item, it will be loaded.

Pressing the "Remove" button on the bottom left corner will remove the selected chooser. Clicking on the "Erase" button on the bottom center on the other hand will just clear the form.

To add a new one, specify a name on the top right and press Save in the bottom right corner.

## Chooser Tool Bar

At the top, in the tool bar, you can see the usual inputs for specifying margins and paddings for the icons.

On the right, you can specify the chooser's internal name.

## Chooser Options

Under that there's the list of available options. This list has 4 coloumns: the position, the icons' images, a required field and a provided field. On the right you also have two buttons to change the icons' order on the stack if desired.

## Positions

There are several stacks depending on position, and you can add multiple icons in each one. Typically there's a stack for center middle horizontal, top left corner horizontal, top center horizontal, top right horizontal, top right vertical, middle right vertical etc.

The last option isn't an icon stack, rather a list of backround areas. This last position is specified by providing a rectangle with coordinates in percentage. There's a coordinate picker helper too, which works fine but quite useless unless you load an example background image (this background image is not saved with the chooser, it is only used for the coordinate picker).

## Requires

You can specify if a certain icon has some condition in order to show up or not. Local variables are from `a` to `z`, and if you choose and empty local variable from the list (a space), then you can select an attribute as well.

Expressions are simple, in the form if a `variable=value` (variable equals value) or `variable=value&variable>=value` (one variable equals a value and another variable is bigger or equal to another value).

## Provides

Choosers always provide the selected icon's index in the local variable `a`. If you want, you can set other local variables or attributes too.

The "Keep running" checkbox, if checked, avoids the chooser quiting when that option is selected.

## Example

Imagine you have a background image with two mountains, and you want to display two separate lists of options to the user depending which mountain is chosen. To do this,

1. Create an icon stack (let's say at the top left corner horizontal) where every icon has its "requires" set to `b=1`.
2. Then create another icon stack (let's say at the top right corner vetical) where every icon has its "requires" set to `b=2`.
3. Specify a background area on the first mountain (use the coordinate picker), set its "provides" to `b=1` and check "Keep running".
4. Specify another background area on the second mountain, set its "provides" to `b=2` and check "Keep running".

In the game, this will look like: the background image with the mountains and the chooser displayed somewhere (with a cutscene for example). When the user clicks on the first mountain, the icon stack on the top left corner will show up. When they click on the second mountain, this list will disappear and the one on the top right corner will show up instead.

Now imagine that you want certain icons to only appear for experienced players, and you have a `score` attribute to know how experienced the players are. For that change the "requires" to `b=2&score>=100` for example.

PreviousNext

# Cutscenes

## Creating and Editing Cutscenes

Go to `Interface` > `Cutscenes`. These are used for various purposes: displaying your team's logo, telling the background story for your game, creating the mood between levels etc.

Just like the other menu entries under the Interface menu, this also has a "Preview" button at the bottom.

## Cutscenes List

On the left, in the Entity Selector there's a list of already configured cutscenes. By double-clicking on an item, it will be loaded.

Pressing the "Remove" button on the bottom left corner will remove the selected cutscene. Clicking on the "Erase" button on the bottom center on the other hand will just clear the form.

To add a new one, specify a name on the top right and press Save in the bottom right corner.

## Cutscene Tool Bar

At the top, in the tool bar, you can see and interval and a "Play" button. If there's a selection on the timeline, pressing this will play the selected part of the background music. It is used to help you locate where you are on the timeline.

On the right, you can specify the cutscene's internal name.

Below the toolbar is the timeline with the channels:

- Background Audio (Music or Movie, depending on type)
- Slideshow
- Speech
- Subtitles
- Scripts

Clicking on the channel's icon will operate on that channel. By right clicking on the timeline you can move it around, or you can also use the scrollbar. The granulatity is in 1 / 100th of a second, meaning 100 pixels cover 1 second duration.

## Adding Background

Click on the "Movie" or "Music" channel's icon. Below the timeline four selectors will appear.

The first row is for the play once (or play first) movie and music, the second row is for the play in a loop. If you have set both, then the play once will be played for the first time, then afterwards the play in a loop will be repeated until the user interrupts. Without a play once, only the play in a loop will be repeated.

Here the video and the audio isn't related: for example you can have a short movie with only video as play first, then another movie with only video as play in a loop, and one long, play once music for them both. The editor (and the player) will cut these together automatically.

This background is what gives the backbone of the cutscene. Without you can't use the other channels.

## Adding Slides

Click on the "Slideshow" channel's icon. Select a range on a timeline. To help you with the selection, the background's audio is visualized, and you can also press the "Play" icon on the toolbar to listen to that selected range. When you're happy with the selection, below the timeline specify the details.

You can also set the selected range in numeric form. After that with the sliders you can set the fade in and fade out intervals. If you move the left one to the beginning and the right one to the end, then the image will appear and disappear instantly, there'll be no fading. The last icon in this row, the "Erase" button will remove this slide from the timeline.

Below there are two input fields, as you have two options to specify the slide: either you pick a background image, or a color. Using a fullscreen color slide with specific fade in or out intervals can be used to cover other channels of the cutscene. For example, if you want a map to fade in nicely, then create a full black slide which fades out at the time you want the map to appear.

Slides may overlap, but only two at any given time. If you have two images with the same background but different front composition (let's say actor at a different position), then you can set them up in a way that the first's fade out happens exactly the same time as the second's fade in.

That way what the user will see is an unchanged background image on which the the actor's first position fades out, and at the same time their new position fades in, giving a simple illusion of animation. This kind of "animation" is particularly common with voice narrative and still images.

Later you can click on the slide on the timeline's slideshow channel to modify (or remove).

## Adding Speech

Click on the "Speech" channel's icon. Select the time when you want the narration to start (you could select an entire range, but the length of the range will be overridden according to the length of the loaded audio file).

That is why the range's end numeric input is inactive. Next to that you can choose the audio file from the selectbox. For your convenience, there's a "Play" button here too to listen to what you've selected. The last icon in this row, the "Erase" button will remove this audio from the timeline.

Warning

Different translations of the narration might be a bit longer or shorter than the version you're using. Keep this in mind when you select the starting positions. Narrations cannot overlap.

Note

If you also use scripts, then don't forget that "Dialog" commands might also contain translated speech, which will override the speech channel.

Clicking on a speech entry on the timeline will allow you to modify (or remove).

## Adding Subtitles

Likewise to the others, click on the "Subtitles" channel's icon and select the range. Just like with slides, in the first row you have the numerical range input, sliders to specify the fade in and fade out times, and the last icon in this row, the "Erase" button will remove this subtitle from the timeline.

These can be actually used more for just subtitles. Therefore in the second row, you can specify a position (with a coordinate helper) and the alignment of the text. A typical subtitle would have position of `50%, 98%` and would be `center`ed, but you can set up different values too. After this you can find the usual font selector, specifying the font color, font weight, font size, font family for the text.

In the third row, you have one text input field, for the text itself. In it you can use `{}`, which will be replaced by the player's name, or `{attribute}` which will be replaced by that attribute's value. No newlines allowed, but you can add multiple subtitles with adjacent positions.

As with the others, you can click on a subtitle entry on the timeline to modify (or erase).

Now texts can not only overlap, but it is very likely that you want to display multiple texts at the same time, just in different positions. Selecting multiple entries on the timeline which have exactly the same starting and ending range isn't possible. For that reason, below the text input there's also a list selector for the subtitles, where you can choose by text, no matter if they overlap or not.

## Adding Scripts

Finally, you have a "Scripts" channel too. You cannot really add entries for it on the timeline, since there's only one. But if you set a range, the script will start with an appropriate "Delay" command (and if you change the range, the "Delay" command will change automatically).

On the left you have the main script editor area. On the right there is the command palette. You can drag'n'drop commands from the palette into the editor area to add new commands. You can also drag'n'drop commands on the editor area to re-order them. To delete a command, simply drag it and drop it outside of the editor area.

First things first, you should add a "Select a scene" command and select a map and position, so that you'll have a background for your script. This also selects the daytime, which is important if you have set up an ambient lights overlay for that map.

Here in the cutscene editor you have limited number of commands on the palette. No control structures (like iteration or conditional), but you have some Logo-like moving commands for the actors. To use these, first you have to "Place an NPC" on the map. After that, that NPC will become the selected actor. If you have more NPCs, then there's a "Select the NPC" command to select which one you want to control. Giving movement commands to actors happens asynchronuously, this means you can select an actor, give a pile of movement commands to him, then select another actor and add another pile of movements to her. The script won't wait until they finish those movements, it will continue immediately, and both actors will do the movements simultaneously. If you want the script to stop execution until the actors are finished, you have a "Wait for actor to finish task" command (which also applies to the selected actor, just like the movement commands).

There's one exception to this, and that's the dialog. Dialogs are shown for the specified amount of time, and they stop the script until that time passes. This is so because you can display a dialog while the actors are moving or playing a character animation.

Other things you can do in a cutscene includes removing and placing objects on the map; playing object and NPC animations etc. One more thing, with objects the same selection mechanism applies as with actors, meaning the object that was last placed on the map will become the selected object, and that's the one that will play the object animation. To select another object, then "replace" the object on the map with exactly the same object.

## Checking and Saving the Cutscene

You can check the entire cutscene by clicking on the "Preview" button, even in an unfinished state.

But before you could save the cutscene you have to add an internal name to it (last input box on the toolbar), then press the Save button.

PreviousNext

# Startup

## Configuring Startup Scripts

Go to `Game` > `Startup`. That page has multiple event handlers actually, all starting when the game starts (more precisely when the "New Game" was choosen in the main menu). The main one runs only once, while the others are executed later on at specific intervals too.

## Using Event Handlers

Unlike the other manual pages, this mostly isn't about a specific menu entry per se. Instead event handlers can be found in several places, on multiple forms. The most prominent one being in the menu `Startup`, but this description applies to the others as well.

In general event handlers are list of commands and they encode simple game logic algorithms. You can put anything in them, and since there's sequence, conditional and iteration too, all kinds of algorithms can be described. For every event handler,

- on the left, the bigger part is the event handler editor area. You can re-arrange its commands by drag'n'drop.
- on the right, there's always a command palette. You can add commands to the event handler by simply drag'n'dropping icons from this palette to the editor area.

To delete a command, just remove it from the handler, e.g. drag'n'drop off the editor area.

## Control Structures

### Sequence

Simple, just put one command after another. The execution flow's direction is up to down.

### Conditional

Is a mixture of "if" and "switch". You have a "+" and "-" icon to add and remove branches, of which by default there's two, 1 and 0. If the given expression returns 1, then the branch on the left is executed, if it returns 0, then the branch on the right. You can use more complex expressions returning more possible values if you add more branches.

### Iteration

There's only one kind, equivalent of "while" in programming languages. The block is repeated until the given expression returns 0.

### Assignment

With this, you can assign an expression's value to a local variable or attribute.

## Variables

You can use any attribute as a variable, just by referencing them by their names. If the names aren't prefixed, they refer to the entity's attribute that triggered the event. For example, in an object's "on touch" event handler, they refer to that object's attribute. If you prefix these attributes by `@`, then they refer to the other party in the event (which is typically the player, but in case of default action handlers, the other party is the attacked NPC).

Each event handler has local variables. These are ones with only one letter names, from `a` to `z`. Since they are local, all event handler has a copy of those, and are free to use them without interfering with other event handlers. There's one exception to this rule, when the "call another event handler" command is used. There the local variables of the caller are copied to the callee's local variables, and when the called event handler finished, it's `a` local variable is copied back to the caller's `a` local variable.

In general, functions (like choosers and dialogs) always return their results in `a`.

## Commands

These do many different things. They can play sounds, replace the background music, play a specific animation etc. There are also commands to manipulate the map, and to give items to the player (or take away). Basically the game logic is described by these commands, no logic is hardwired in the engine. This gives absolute freedom over your game, but also means it is easy to mess up, because logic is only syntactically checked, but there is no (and can be no) semantic checking.

More info can be found about event handlers (when encoded as scripts) in the TirNanoG Project documentation.

PreviousNext

# Attributes

## Configuring Attributes

Go to `Game` > `Attributes`. On the left you'll see the list of already configured attributes. Double-clicking on one of them will load that attribute.

Attributes are the essential building blocks of your game, that describe the current state. They can belong to characters, NPCs, objects or to the world.

## Attributes Setup

By clicking on the "Attribute setup" button at the center bottom, you'll see the setup form. Here you can assign attributes to the engine. There's only a few of them, like which attribute stores the player's speed or the light's radius for light sources, or the level up attribute which you should add points to when the character advances a level.

This is also the place to configure the attribute limits in free-form mode. Read about these in free-form mode characters.

## Attribute Properties

As for the non-setup mode, you can specify the attribute here. Each attribute has an internal name used inside the editor, a translatable title, a type and some additional information. If title is not given, then the attribute will be hidden from the user. When given, then it will be listed with its current value in-game, on the inventory's "Stats" tab. You can also display attributes as progressbars on the Heads-Up Display. As for the types, you can choose primary, calculated, variable and global.

### Primary

These are primary attributes that influences all the other attributes of a character (or NPC). In free-form mode the user are free to assign values to these. They are configured during character generation, and either not modified later, or just by special events, like level up. Typically "Strength", "Intelligence", etc.

### Variables

The are the typical attributes, used throughout your game logic. Event handlers can change their values directly, using the "assign" command, and they also have their own "on change" event handlers.

Typically skills that the players learn during the game are stored as variable attributes, like "swordfighting", "lock picking", etc. But it is up to you how you set up attributes in your game.

### Calculated

These are defined by an expression, and their values are always calculated, and cannot be directly modified, only indirectly, through modifying the attributes their expressions depending on. Typically "HP", "HPmax", "MP", "MPmax" etc. which rely on certain primary values.

### Global Value

Just like the variable attributes, they have a default value, they can be modified directly with the "assign" command, and they have event handlers. The only difference is, while variable attributes belong to the characters (or NPCs or objects), global attributes belong to the world. They are useful to store the status of your overall, player-independent story line.

Typically things like a castle's gate is open or not, the king has dispatched the knights or not, how many days left before the princess starves to death in the tower etc.

### Global Calculated

Similar to per-character caluclated attributes, but for world attributes.

PreviousNext

# Actions

## Configuring Default Actions

Go to `Game` > `Actions`.

There are interactions between the player and other elements of the game, like NPCs, objects etc. These are always interpreted in relation. You can either set a handler for all kinds, or set a specific for a particular element. You can configure the former, global handlers here. For the element specific handler (which override the global ones if they exists), see NPCs and Objects.

## Default Action Handlers

You can have 9 actions. How you define these is totally up to you and to the game you're creating. In a simple fantasy RPG, action 1 could be the melee attack, and action 2 could be the ranged attack. In an adventure type game action 1 could be the use object action, action 2 the examine, action 3 the open, action 4 the push, action 5 the talk to etc.

For actions that does not need close proximity, you'll have to tell which attribute stores the range of that action. For example, if action 2 is the ranged attack, then you could choose the Strengh attribute for the range, meaning the stronger the player become, the farther they will fire with a bow. Just an example, it is up to you.

What is important, that for all actions that you intend to use, create a default event handler. For example, if action 1 is melee attack, then this event handler is triggered when the player uses an object which has action 1 set (like a sword), and then this event handler should describe if the sword hits or not, and if so it should decrease the opponent's HP etc. Without default event handlers, the objects in your game are just for show and useless.

PreviousNext

# Character

## Configuring Character Options

Go to `Game` > `Characters`. On the left you'll see the list of already defined option groups. Double-clicking on one of them will load that option group.

There's no clear-cut instructions on how to set up characters, because that mainly depends on what kind of game you're creating. The TirNanoG engine gives you absolute control over how your define these. See also how to create predefined heroes, hero classes and free-form mode characters.

Character options are groupped. For example, brown hair or blonde hair are options, and they probably belong to the same hair option group. This can be difficult at first to wrap your head around. When the players are creating characters, they can choose different options, exactly one from each group. It is hard explain this better, because of the freedom the engine gives you. Let's say one option group is "spicies", with options like "human", "elf", "orc" etc. Another option group is "class", with options like "warrior", "thief", "mage" etc. The first group assigns sprites to the character, the second assigns attributes. Hope this example helps.

This could get more complicated because the engine allows you to define multiple groups that alter the outlook of the character. If you choose this, then one of those option groups must be marked as "base look out". For example, an option group can be "body", with options like "human male", "human female", "elf male", "elf female" etc. These would assign different base sprites. Then you can have option group for "hair" for example. In this case, the player would be able to select the base look out, the body and the character's hair independently during character creation.

Note

When "base look out" is selected, you also have to tell where the base line is (which is the ground level on the sprite with other words). The base line is normally at the vertical center, but you can move it down by a delta y value to match the character's foot. This is very important to set if you want to add oversized sprites too.

## Option Group

The name of the option group which is internally used in the editor can be set in the top right corner.

## Options

Options with translatable names are added to the list in the middle. Each option might add attributes, inventory items or sprite overlays to the character.

### Option Attributes

There are two kinds of attributes, required and provided. If you set the relation to "(set)", then it's going to be a provided attribute. If you use any other relation, then a required attribute. Again, it is easier to explain through an example. Let's say like in the previous example, you have an option group for "spicies", with options "human male" and "human female". For the first one, you can add a provided attribute "sex" with value 1, and for the latter with value 2. Then, in another option group, which would be "career", you can add an option "blacksmith" with the required attribute of "sex" being 1, and "waitress" with required attribute "sex" being 2. In this case the player would be to choose during character generation between "human male" and "human female". Depending on that choice, they would be offered different career choices: with a "human male", they can choose "blacksmith", but not "waitress", and similarily, if they choose "human female", then they can choose "waitress", but not "blacksmith". This makes also sense when you think about having different sprites, for example "human male" can have a different set of options in the "hair" group than "human female" characters.

### Option Inventory

You can specify inventory items for an option which will be added to the player's starter inventory if they choose this option. For example, in the option group "class", the option "warrior" might add a sword, and "mage" might add a magic wand to the starter inventory.

### Option Sprites

Normally a sprite sheet would offer you ready to use characters. However it is possible that the imported sprites are modular: they only contain parts of the character (like separate sprite sheet for body, face, ears etc.) For this latter case, you can add multiple sprite layers. Each layer should contain a specific kind of sprites: for example the first layer should contain the body, the second layer the hair etc. If you have ready to use sprites with fully drawn characters, then you'll need only one layer.

If you have sprites with special grayscale colors (`#101010` to `#f0f0f0`), then you can select a 8 x 16 pixel palette sprite on the toolbar. With this, the player will be able to choose different color variants during character generation (for more details, see recoloring). You can get such a palette if you have imported sprites with the "?" (ask) color variant.

On a layer, you have to specify sprites for each action. This could be overwhelming at first, but the sprite selector helps you a lot: you can search sprites by name, which filter is kept. For example, click on the "walking" coloumn's button. In the pop up selector, you search for "elf". The list will be filtered only to sprites with "elf" in their names. You choose the sprite by clicking on it. Now in the same row you select another action, eg. "swimming". The sprite selector will pop up again, but only with sprites depicting elves (you can clear the search field to list all sprites again).

Now you don't need ALL actions. If you don't plan to use swimming or flying in your game, then you can leave those sprites empty entirely. If your collision masks contain no climbing cell, then you won't need the climbing animations either. You can also skip the block attack, but you probably should add sprites for hurt and die. With the actions, only those need to be set up, for which you have added event handlers.

Below the sprite matrix are the copy'n'paste controls. You can copy and paste the entire layers configuration from one option to another (or as a matter of fact, to other layers too, like to an NPC's character layer.) There are two more buttons with up / down arrows on them. With these you can re-arrange the layers' ordering by moving the selected layer up or down.

By clicking on the "Preview" button, you'll be able to see the selected action's animations in all directions. This is very handy to see if you haven't specified all directions then which direction's sprites will be used to fill in. It is also useful to see how the sprites on different layers are merged and if they look nice together or not. If some sprites are oversized (bigger than the base character sprite), you can also check here if they fit to the base line properly.

Hint

the preview shows the selected action by default. But in preview mode, you can press `⯇` left and `⯈` right cursor arrows to switch actions. When the number of frames (or the playback type of the animation) differs on some layers, a flashing Warning sign will be shown next to that merged sprite.

### Option Description

Finally, if you want, then you can add a translatable description for the option.

Once you have configured the character option, don't forget to press Save.

## Character Examples

### Predefined Heroes

The are many games with a storyline which demands no configurability and a specific protagonist (like Geralt of Rivia). There are also many games with storylines that only allow selecting one of a few predefined characters (like Bernard, Laverne and Hoogie). In this section I'll explain how to set up these.

First of all, you'll only need exactly one option group, no more.

In that group, add as many options as many choosable characters your game has. For each option specify both the attributes and the sprites (and maybe inventory too). It's very likely that you'll have ready to use sprites for these characters, so you'll need only one Layer. But it is also possible to use multiple layers and construct the protagonist character from modular sprite sheets.

It is also possible to have only one predefined character, but let the user choose it's primary attributes. For that, do not set up attributes, just sprites, and in the Attributes Setup menu configure points. For more details, read free-form section below.

### Hero Classes

A typical RPG allows the player to choose a character and a hero class independently.

For this, you'll need at least two option groups. In the first group, call it let's say "spicies", define the base look out of the character by defining the sprites, but configure no attributes nor inventory.

In the second group, name it let's say "class", add options with only attributes and inventory, but no sprites. For example, the "warrior" option should have large "Strength" value, but lower "Intelligence", while the "mage" option should have lower "Strength" and higher "Intelligence".

You can also use sprites with this second group of course, for example you can set up the "mage" option to add a pointy sorcerer's hat to the character's portrait.

It is also possible to configure this with freemode primary attributes. In this case configure points in Attributes Setup. Then in the second group, which is called "class", specify required attributes, for example for "warrior", specify "Strength" at least 8, and for "mage" specify "Intelligence" at least 8. In this case the player will be able to freely configure their character's primary attributes, but they won't be able to choose certain classes if the given primary attribute is too low. It is also possible to use calculated attributes with the classes in freemode. See the free-form section below for more details.

### Free-Form Mode Characters

Go to `Game` > `Attributes` and on the attributes page click on the `Attributes setup` button. On that form, you can set up the total points and the maximum point per attribute.

When these are set, then the players can freely assign the total points among the primary attributes, but no attribute can have more points than the given maximum.

In this case the character's main attributes would be probably calculated attributes that rely on these primary attribute values. For example, you can have 3 primary attribute ("Strength", "Intelligence", "Endurance"), each with maximum points of 10, and you can give 21 points in total to the player to assign between these 3 as they like. Then the base attributes could be all calculated (like "Physical" = (Strength + Endurance) / 2, "Mental" = Intelligence, "Attack" = Strength, "Defense" = (Strength + Intelligence) / 2 etc.) Note, these are just examples, you can set up the attributes as you like.

Go to `Game` > `Characters`. With the character option groups, you can specify attributes for certain options, but do not specify any primary, unless as a required attribute.

PreviousNext

# NPCs

## Adding Non Player Characters

Go to `Game` > `NPCs`. On the left you can see the list of already defined NPCs. Double-clicking on one of them will load that NPC.

On the tool bar, you can see the "basic configuration" and "inventory configuration" icons, and on the right, the internal NPC name. These icons will switch tabs, because there are quite a lot configuration options for NPCs, did not fit into one page.

Hint

To duplicate an NPC, load them, then modify the internal name and press Save.

## Configuring Behaviour

The first and most important thing to configure is what the NPC should do when the players do not interact with them.

- Standing makes the NPC stand in one place
- Wandering makes the NPC randomly move
- Patrol makes the NPC to follow a predefined path

All have the "Speed" argument (even standing), but "Wandering" also has a frequency how often the NPC should change course, and "Patrol" has a patrol path id argument (see maps on how to set up a patrol path).

You can change the behaviour from event handlers. For example, you can set the default to "Wandering", and in the "on approach" event handler switch that to "Attack".

Hint

Treasure chests are standing "NPC"s with just an "on touch" event handler.

## Event Handlers

The second important thing is to configure how an NPC would react when they interact with a player. These event handlers can change the NPC's behaviour, or make the NPC to start a dialog, open up their invertory for doing business etc.

- on click: activates if the player uses no object, or an object in any action category
- on touch: when player collides with the NPC
- on leave: when player's and NPC's distance increases above the given value
- on approach: when player's and NPC's distance decreases below the given value
- on action: when the player uses an object on the NPC which belongs to a specific action category
- on using: when the player uses one particular, specific object

## Attributes, Sprites and Preview

Looks like and works exactly like in character options, except there's only provided attributes for NPCs. For more details, please refer to the character chapter.

Hint

You can create a great variety of NPC characters with the sprite generator.

## Inventory

By pressing the "Inventory" icon on the tool bar, you'll get the NPC's inventory setup.

Here you can specify the in-game name of the NPC and what items they should have. Quantity and chance of having those can be configured too. When the NPC gets killed, all the items in their inventory is dropped on the map as loot.

Note

Note the difference between these:

    50%, 2 swords

means there's a 50% chance of the NPC having 2 swords or none. No way they are going to have 1 sword. On the other hand

    50%, 1 sword
    50%, 1 sword

means the NPC might have 0, 1 or 2 swords.

### Creating a Merchant

If you want to create someone whom the player can trade with, you must specify "Sell price" and "Buy price" event handlers. These receive the given object's base price (see object's in inventory tab) in the `a` local variable and category in `b`, and should return the modified price in the same `a` local variable. Normally you want to have something like this

    a:=a*110/100

to sell 10% more expensive than the base price, and

    a:=a*50/100

to buy at half of the base price. But since you have the control structures for these event handlers, you can create exciting conditionals too, like for example a racist orc Merchant who sells to humans for double the price.

Using the price category in `b` is optional, and you can set it up as you wish. But if you want a certain merchant to only accept certain items, then simply only return a price if the item is in the desired category, for example:

    +-----------------------------+
    | [+] [-]  b                  |
    +---2---+------1------+---0---+
    | a:=0  | a:=a*50/100 | a:=0  |
    +-------+-------------+-------+

There's another feature for merchants, you can set their inventory to replenish themselves. Normally an item creation executed only once, when the NPC is created, but with this you can repeat the process every N minutes. A merchant can't have more than 999999 items of the same kind.

PreviousNext

# Spawners

## Configuring NPC Spawners

Go to `Game` > `Spawners`. On the left you can see the list of already defined spawners. Double-clicking on one of them will load that spawner.

## Number of maximum NPCs

This is the number of maximum how many NPCs this spawner handles at any given time. If it has already spawned this many, no new NPCs will be born.

## Spawning Frequency

Is a time interval, when to check if the maximum number of NPCs has been spawned.

## NPC list

This list contains what kind of NPCs will be spawned by this spawner. You can add an NPC type multiple times and thus increasing the chance of spawning that kind. The list always sums up to 100% chance.

You can set a condition to a kind. For example, let's say you have a `level` character attribute, and a spawner only spawns weak slimes if it's less than 5, but it also might spawn minotaurs if the player's `level` is above 10.

In the provides coloumn, you can specify an attribute which will be set on the spawned NPC. For example, in conjuction with the conditional, you can set different strengths to the NPCs. If the provides expression is empty, then the NPCs will be spawned with the attributes specified on the NPC attributes page.

PreviousNext

# Dialogs

## Creating Dialogs

Go to `Game` > `Dialogs`. On the left you can see the already created dialogs. Double-clicking on one of them will load that dialog.

You have on the right the internal name of the dialog that the editor uses, otherwise the tool bar is empty.

## Who said and What is Said

Title is translatable and shown in-game. It contains the name of the NPC who is saying the dialog, and optional.

Message is translatable, and mandatory. You can't place newline characters in the message, line breaks are handled automatically, because each player might have a different screen resolution, and with that a different dialog size. On the other hand you can use `{}` characters, which will be replaced by the player's name, or `{attribute}` which will be replaced by that attribute's value.

If your game has voice actors and speech recordings, then you can also set an audio file speaking the words of the message.

On the right, you have a button to set the portrait. This has to be independent to the NPCs, because not only NPCs can make dialogs. For example a sign on the wall might pop up a dialog with the translated text (in which case there should be no portrait at all, or could be a portrait of the sign). Second, NPCs might have several face expressions, so you should choose the proper one for this dialog (like happy, angry etc.).

## Possible Answers

You don't have to specify answers, but you can. If you do, you can add as many options as you like, but keep in mind that for a good in-game experience 4 or 5 tops is recommended. More than 8 will most definitely confuse the players and will ruin your game.

If you are creating a game where the players can't customize their character (see predefined heroes), you might want to add speech audio to the answers. With customizable characters I do not recommend this, because it looks strange (or rather funny) when a brutal orc warrior sounds like a little girl.

Furthermore, dialog answers can be conditionals and they can provide attribute changes. For example, a certain answer can only be shown if the player's character is an elf.

## Using in Event Handlers

You can display dialogs from event handlers, using the "Dialog" command. To give you more control than just providing attributes, it will return the selected answer's number in the local variable "a" in reverse order (first answer = number of answers - 1, last answer = 0). If you place a conditional structure right after a "Dialog" command and set its expression to "a", then you can do different things depending on the answer. The first branch will be executed if the player chooses the first answer, the second branch when they choose the second answer, etc. and the last, zero branch when they choose the last answer.

For example

    +---------------------+
    | () dialog1    00:01 |
    +---------------------+
    +-----------------------------------+
    | /\ [+][-] a                       |
    |     2     |     1     |     0     |
    +-----------+-----------+-----------+
    | things    | things    | things    |
    | to do on  | to do on  | to do on  |
    | first     | second    | third     |
    | answer    | answer    | answer    |
    +-----------+-----------+-----------+

## Preview Dialog

To get a glimpse how the dialog will look like in the game, press the "Preview" button. If you don't like the dialog window or the font, you can set those in the `Interface` > `Elements` menu, see UI Elements.

When you're satisfied with the dialog, do not forget to press Save.

PreviousNext

# Objects

## Configuring Objects

Go to `Game` > `Objects`. By default objects are just roadblocks on the map. If you want the player to interact with them, you have to add meta information too. On the left you can see all the objects that already have such a meta info. Double-clicking on the list will load that object. To load an object that does not have meta info yet, use the object sprite chooser on the tool bar.

Note

Beneath the object list, you can see the usual "Delete" button, but there's also a "Duplicate object" input box and button. Give a name to the copy and press the button, that will duplicate not only the sprite, but all the meta info as well.

On the tool bar you can see the object sprite chooser, the "On map" icon and the "In inventory" icon. These icons will switch tabs, because there are quite a lot configuration options for objects, did not fit into one page.

## Objects on Map

The simplest one is when the object is on map, like a wall or a street lamp. These have no in-game name. All you need is a collision mask for them, which can be set on the right. Select the sprite and then you'll see the grid with the transparent image of the object.

### Collision Mask

Visibility (transparency of the object) can be changed by clicking on the "Visibility" icon above the mask. It has `25%`, `50%`, `75%`, `100%` steps, left clicking goes in ascending direction, while right clicking goes in the other, descending direction.

On the grid, you can click on each cell individually. Here left clicking changes the status forwards, while right clicking changes it backwards. Each cell can be of different collision:

- empty means walkable and flyable but not swimmable
- wall means block, not walkable, not swimmable and not flyable
- ship means not walkable but swimmable and flyable,
- airplane icon means not walkable and not swimmable but flyable,
- a ladder means walkable, but played with a different animation,
- a jumping man means not walkable, not swimmable but flyable; except with jump it is walkable,
- half wall below means block underground, but walkable above,
- half wall above means walkable underground, but block above.

For simple objects on the map, you don't need events at all, but by toggling the blue board game figure "Event" icon (), you can specify the event trigger hotspots for the object.

### Event Handlers

If you specify event trigger hotspots, then you can set up events handlers on the left. These are exactly like for NPCs, except where NPCs have behaviour, objects have an action category. This category tells the engine that when the object is equipted and being used, which one of the default action handlers should be executed.

Let's say you have configured "action 1" as a melee attack, and "action 2" as a ranged attack. Then for a sword object, you want to choose "action 1" category, while for a bow "action 2". This only selects the default event handler (when the player is using that object), but you can add further event handlers for other interactions.

For example to automatically pick up items, one would need to specify an "on touch" event handler with a "remove object from map" and "give item to player" commands.

### Equipted Objects

When objects are equipted, they might alter the character's outlook. This is optional, and only make sense with clothes, weapons, shields, etc. Below the collision mask, you can configure this.

First, you can use a common outlook for all character groups (if you choose "(default)"), or you can set one for each, if you select a specific character option (the available options came from the option group that is marked as "base look out").

There are only two layers for equipted objects: one that's above the character sprite layers, and one that's behind. You can set up sprites for each standard actions (idle, walking, swimming etc.), but the action sprite is only available if you have chosen an action category for the object.

### Preview

With the "Preview" button, you can check how an equipted object looks like on the characters. This looks and works exactly like the preview for the character options, for more detials see the option sprites in the character chapter.

## In Inventory

On this tab, you can configure how an object looks like in the player's inventory. If the object can be picked up (or is a virtual one, like a magic spell), then you must set a translatable in-game name for it in the "Title" field.

If you want, then in the inventory you can set a different sprite for the object than the sprite used when the object is on the map. This can be set on the right in the same row as the "Title". This sprite should be the same size as the slot size specified for the inventory slots in the `Interface` > `HUD` menu.

On the left, you can configure where the object can be equipted at, and if you want to have specific sprites, with what sprites. Below are two inputs, one for the sound effect thats played when the player places the object in an inventory or equipment slot, and the other being the object's base price (with units, see creating a merchant). You can specify the price category as you wish, it is entirely up to you, it is optional. For example, you could say that category 1 is meat and 2 is hardware, and a certain weaponsmith only buys items in category 2, but not items in category 1.

On the right, you can set up the object's attributes.

### Equipted Objects

Some objects might be equipted. You can check here in which equipment slots (slots are defined in the inventory, see `Interface` > `HUD` menu). There's a special equipment slot, the "skill". If you check this, then the "object" will be treated not as a material object, but a fictionary; it will be shown on the Stats tab of the HUD and not on the Inventory tab. These cannot be equipted as normal object, yet they need a place on the player's item bar so that they can use them and access them by a shortcut key. In a fantasy RPG, these are typically used for magic spells, but you can use these "skills" any way you like in your game.

By default, the same object sprite will be shown in the equipment slot as in the inventory slot. However there are some objects that require multiple equipment slots, in which case you might want to use different sprites in the equipment slots. For example a bow would require both hands, but showing the same bow icon in both hands looks strange. Therefore you can keep the default icon for the primary hand, and use an arrow icon for the secondary hand for example.

Here you can set the price for the object, if you want to. Unit is freely configurable depending on your game, for example it could be a gold coin.

Finally, if the selected action category is a ranged one, then you should specify a projectile sprite for the object (like an arrow for a bow, or a fireball for a magic wand), and if it requires ammunition or not.

### Object Attributes

Not all objects can be equipted by all players. Some require a certain skill or level. To describe that, you can fill up the "Required attributes" list on the top right. If the player has all the attribute requirements met, then they can equip that object.

Furthermore, when objects are equipted or used, they might alter the character attributes temporarily. For example a longsword might add a modifier to the "Attack" attribute. Or a magic wand might increase the "MPmax" attribute, etc. These are configured in the "Attribute modifiers" list. You have two options how to change a value: by adding a constant to it, or increasing by a percentage.

There's one special modifier, which does not modify any attribute, rather changes how the player moves, and it is called "(transport)". For example, in a fantasy RPG the player could find a dragon's wing, and when that wing is equipted that may alter the transportation mode from "walking" to "flying".

### Preview

If you click on the "Preview" icon when the "In inventory" tab is active, then you'll see how the object will look like in the inventory.

When you've finished configuring the object, don't forget to press Save.

PreviousNext

# Crafting

## Defining Crafting Rules

Go to `Game` > `Crafting`. On the left you can see the already created crafting dialogs. Double-clicking on one of them will load that dialog.

You have on the right the internal name of the dialog that the editor uses, otherwise the tool bar is empty.

## Crafting Dialog

Similarly to normal dialogs, you can display crafting dialogs from event handlers, using the "Craft" command.

Title is mandatory, translatable and shown in-game. It contains the name of the NPC who is doing the crafting (could be a blacksmith or a fireplace).

Message is translatable, and optional. You can't place newline characters in the message, line breaks are handled automatically, because each player might have a different screen resolution, and with that a different dialog size. On the other hand you can use `{}` characters, which will be replaced by the player's name, or `{attribute}` which will be replaced by that attribute's value. Do not use large texts, just brief descriptions to hint the users what can be crafted in this dialog.

If you want a sound effect to be played when the crafting is done, you can set it up here.

There's also a "order irrelevant" checkbox. By default the placement of the ingredients are important, and crafting only works if the player places them exactly as you set it up in the recipe. If you check this checkbox, then the player can place the ingredients in any order.

On the right, you have a button to set the portrait. This has to be independent to the NPCs, because not only NPCs can make dialogs. For example an owen could have a crafting dialog too.

## Recipes

Each crafting dialog must have at least one, but might have more recipes. These describe the ingredients and the product.

Important

You can set up required quantity of 0. This means when the crafting is done, that item won't be removed from the player's inventory, but still required to craft the product (for example a pan).

## Preview Crafting Dialog

To get a glimpse how the dialog will look like in the game, press the "Preview" button. If you don't like the dialog window or the font, you can set those in the `Interface` > `Elements` menu, see UI Elements.

When you're satisfied with the dialog, do not forget to press Save.

PreviousNext

# Tiles

## Defining Meta Data for Tiles

Go to `Game` > `Tiles`. By default tiles just provide the background of the map. But you can add meta info to them, and by that give properties to them. On the left you can see all the tiles that already have such a meta info. Double-clicking on the list will load that tile. To load a tile that does not have meta info yet, use the tile sprite chooser on the tool bar.

On the tool bar you can see the tile sprite chooser and the tile combining tool.

## Combining Tiles

It might happen that your imported tiles contain an edge or corner, but not in combination with another background tile, just with a transparent background. TirNanoG supports multiple layers of tiles, so you can place both the background tile and the transparent tile at the same spot on the map, yet sometimes that manz layers isn't enough. When that happens, you can combine those tiles into a new single tile which then can be placed on one layer.

For example, in an imported tileset there can be a lake. The shore of the water might be a unique tile (like water with grassland, water with rocks, water with snow etc.), or it could be just the shore with a transparent background. For the latter, open the grassland tile, select the water shore tile then press "Combine" icon. You'll get a new tile saved as if grassland + water combination would be provided by the imported tileset.

## Tile Properties

You might want to set how fast the characters can move on specific tiles. For example, on ice the speed can be 110%, and on rocky mountains only 50%. If you set the modifier to 100%, there'll be no change. It is common to set the modifier to 150% for "road" type tiles, so that characters will be able to move faster on roads.

Tiles doesn't have event handlers, but you can set an audio for the "on walk", "on swim", and "on fly" events. These are played when the player moves above a tile of this kind with that transportation method.

## Automap Rules

Placing edge and corner tiles on maps can be overwhelming. To help you with that, TirNanoG supports automapping (which is different to autotiling). In autotiling you have tiles splitted into 2 x 2 subtiles. This only works with orthographic tiles, and with a little hack with isometric, but not for hexagonal ones. Automap on the other hand defines a pattern, which if matched, then the tile is automatically placed. This works with all kinds of grids without hacks. You have a list of these pattern rules, meaning you can set up multiple combinations with different neightbours if you want.

PreviousNext

# Maps

## The Map Editor

Go to `Game` > `Maps`. On the left, you'll see the list of maps. Double-clicking on one of them will load that map.

In the toolbar, you'll see the "Map Meta Information" icon, the Layer Selector, the item selector, a special icon to select an "erase" item, and on the right the map's internal name, used within the editor. Other icons on the toolbar depend on which layer is the active one, for example for tile type layers, there will be painting tools, selection tools, copy'n'paste tools etc.

The zoom control is located below the map, on the button bar.

Hint

To duplicate a map, first load it, give it a different name and press Save.

## Shortcuts

There are some shortcuts that work on the map regardless which layer is active:

- using the right-click, holding it down and moving the mouse will move the map
- `⯇` left, `⯈` right, `⯅` up and `⯆` down cursor keys will scroll the map
- `Ctrl` + `⯇` left, `⯈` right, `⯅` up and `⯆` down cursor keys will rotate the map
- `-` minus will zoom out, `+` / `=` plus and equal will zoom in
- mouse wheel will scroll the map (in horizontal too, if your mouse / touchpad supports that)
- `Ctrl` + mouse wheel will zoom in or out
- `Ctrl` + `Z` will undo the last modification
- `Ctrl` + `Y` will redo it
- `Ctrl` + `S` will save the map (only if it has an internal name set)

## Map Meta Information

If you click on the "Meta Info" icon, then you'll be able to see and edit the map's meta information.

- Here title is the map's translatable, in-game name, if any.
- Daylight specifies the light overlay, you can set the daylight's duration in minutes, and a palette using a sprite. For more information, see the lights section.
- This is also the place to set a background music for the map.
- Below are the parallaxes. You can have more of them, and you can set them below or above the map layers.

The first and third values specify how much the parallax moves every given time intervals on the X and Y axis (good for example creating a raining effect). The second and fourth values on the other hand specify how much the parallax moves when the player moves (good to create a perception of depth). The combination of these can give a very nice-looking effect on the parallaxes.

## Map Layers

Next to the info icon, there's the "Layers" icon. Clicking on that will bring up the layer selector. Here you can click on the visibility (eye) icon to show and hide layers individually, or you can double-click on the layer's name to select that layer for editing. Keep in mind that the selected layer is always set to visible. You can also change the current layer with the `PgUp` and `PgDn` keys.

There are several layers:

- "Ground 1" to "Ground 4" are under the player, and there's more of them so that you can use transparent tiles too.
- "Objects" is at the same level as the player, and it also loads the collision mask if the tile has an object meta info.
- "NPCs" and "Spawners" are at the same level as the player too. They are separated because they use different sprite sets.
- "Roof 1" to "roof 4" are above the player, and "Roof 4" layer disappears when the player walks under.

There are two additional techinal layers, not shown in-game:

- "Collision" is a read-only layer, calculated automatically from the "Objects" layer.
- "Patrol paths" contains routes, directed vector lines.

## Choosing Brush

Depending on which layer you are editing, the brush chooser will offer different items. For all layers except the paths, the "Erase" icon selects a special "clear" item. For the path layer erase icon erases the path. The keyboard shortcut for selecting the item is the `Space`. Press `E` to switch to erase mode.

Hint

There's a logic behind tile suffixes, which could help you a lot picking the correct one. See tile naming for details. You can search for tile tags, and if translation exists, translated tags too.

## Pipette

Just like in GIMP, using this Pipette tool you can select a tile or object from the map to draw with. The keyboard shortcut for this tool is `O`.

## Paint

The default tool looks like a brush , and you can paint the selected item on the map by left clicking and holding the mouse button down. The keyboard shortcut for this tool is `P`.

If you press the `Shift` key, then you can draw lines, just like in GIMP.

Note

If there's an active selection, then you'll be only able to draw inside that selection.

## Bucket Fill

The bucket fill tool replaces contiguous areas with the selected tile. The keyboard shortcut for this tool is `B`.

If there's a selection and you `Shift` + click, then the entire selection will be filled, no matter the continuity in tiles.

If you press `AltGr` / `GUI` while you click, then all occurances of the tile at the position where you clicked will be replaced with the selected tile.

Note

Just like with the paint tool, if there's an active selection, only the selected area is modified.

## Selections

Works exactly like in GIMP. You have three tools:

- rectangle selection (shortcut `R`),
- free-form polygon selection (shortcut `F`) and
- fuzzy selection (shortcut `U`).

If you just click on the map with the rectangle selection, that will clear all selection. If you hold down the left mouse button and move the mouse, then you can select a rectangular area with rectangle select.

With polygon select, first you click on the start point. Then you can make further clicks on other coordinates, each will add a line from the previous point to the new one. When you click again on a point which has the same map coordinate as the first point, then the path is closed, and the selection is made.

Fuzzy select will select all neightbouring tiles of the same kind. If you press `AltGr` / `GUI` during selection, then all tiles of the same kind will be selected, not just the neightbouring ones.

Normally a new selection will clear the previous one, but just like in GIMP, you can combine selections.

- By holding `Shift` down, you can add a new selection to the previous one.
- By holding `Ctrl` down, you can intersect the previous selection with the new one.
- `Ctrl` + `I` will invert the current selection.
- `Ctrl` + `A` will select all.

There's no restriction, you can combine selection tools as you like. For example, you can select a rectangular area, then switch to polygon select, press and hold `Ctrl`, make a selection to "cut out" some parts of that rectangular area.

## Copy'n'paste

Selected areas are not only good to limit where Paint and Bucket fill can modify the map. You can also copy the selected items to a clipboard (`Ctrl` + `C`), and then paste them (`Ctrl` + `V`) at a different position. To cut out the selected part, use `Ctrl` + `X`. With this you can easily edit larger parts of the map.

Hint

You can copy'n'paste between layers too. For example to move an entire area to another layer, select the area, press `Ctrl` + `X`, switch to the new layer and press `Ctrl` + `V`.

## Flipping

You can flip the copy'n'paste clipboard vertically (`V`) or horizontally (`H`). This way you can make a selection, copy it, flip it and then paste it to create more variations on the map.

Flip also works for patrol paths, but there it changes the direction.

## Chaining

The size of one map is limited (by default to 32 x 32). But don't worry, these relatively small maps can be chained indefinitely (ok, to be precise you can chain up a few million maps). When you scroll the map (or you right click on the map and move the mouse), on the corners in the corresponding directions a "Link" button will appear with an anchor icon. Clicking on these will pop up the list of maps, and you can select which map should be in that direction. These chained maps are loaded automatically in-game, so the player will not know where one map ends and where another starts, for them it will look like one big map.

It is not necessary to chain maps. You can create separate maps too, which are not chained, or chained in a local group. These can still be accessed by players via the "set player location" command in event handlers. Typical example is multiple chained maps of the overworld, and when the player touches the cave's entrace, he gets teleported to another group of chained maps, the dungeon.

## Preview

On the button bar, you have a "Preview" button. With that you can see the map in its entirety: with neightbours, parallaxes, lights etc.

When you're finished with the map, don't forget to press Save.

## Tiled Compatibility

The editor saves maps in TMX format, which is native to the Tiled mapeditor. There's a catch though, TirNanoG can handle tilesets in atlases, while Tiled can't, so you must unpack atlases first, otherwise you'll get "image not found" errors in Tiled. See working with atlases for more details. (For the records, this is an open, and still unresolved issue in Tiled since 2015.) For the TirNanoG Editor this simply doesn't matter, it works with both packed and separate sprites, no matter how tilesets are stored (FYI it does not use the image URI in the TMX at all, just passes the tileset's `name` attribute to its sprite manager).

PreviousNext

# Quests

## Adding Quests

Go to `Game` > `Quests`. On the left you can see the list of already existing quests. You can load one by double-clicking, or you can just create a new quest.

On the tool bar, you have a checkbox to set the quest global, and on the right the internal name of the quest that the editor uses.

On the button bar, you have the usual buttons: pressing the "Remove" button will remove the selected quest. Clicking on the "Erase" button on the bottom center on the other hand will just clear the form. You also have a "Preview" button as usual.

Quest alerts can be configured in the `Interface` > `Alerts` menu, see alerts for details.

## Defining Quests

In the main editor area, you'll see the details of the quest. There's a translatable title, shown in-game in the inventory's "Quests" tab.

The description can be longer, but newline characters not allowed, line breaks are handled automatically. On the other hand you can use `{}`, which will be replaced by the player's name, or `{attribute}` which will be replaced by that attribute's value.

A quest can be global or local. Local quests can be fulfilled by each player individually. Global quests can be completed only by one player.

Below the form, there's the "On completition" event handler. Here you can specify commands to be executed when the quest is completed. You can revard the player with items, change things on the map, you can play a quest specific sound effect (only if you haven't set up a common audio effect in alerts), display a dialog to the player, etc.

## Preview Quest

On the button bar, you have a "Preview" button, with that you can check how the quest dialog looks like and how the quests shows up in the inventory. If you don't like the dialog window or the font, you can set those in the `Interface` > `Elements` menu, see UI Elements.

When you're finished with the quest, don't forget to press Save.

PreviousNext

# Lights

## Ambient Lights

First of all, there's a daylight component to each and every map, in `Map` > `Map meta info`, see maps. It is specified by two variables:

- length of the daylight in minutes
- and a sprite with the light map

The sprite should be N x 1 pixel. The overlay's color is taken from this sprite depending on the time of the day modulo sprite's width. If that pixel is fully transparent, or if the sprite isn't set, then there will be no light overlay. If that pixel is fully opaque black, that means pitch dark and then the light overlay will hide everything in the game area. You probably never want to use a black pixel with more than 75% alpha, so that the users can see at least something without a light source.

A daylight sprite example Setting the daylight length to 20 minutes and providing a sprite that has a gradient with 75% black (midnight) to 50% orange to 25% orange (morning) to full transparent (day, afternoon) to 25% orange to 50% orange (evening) and then to 75% black (night) again will provide a nice time of the day effect to the game by mimicing sunlight's colour and dark at night.

For dungeons without sunlight, you want to set daylight length to 1 minute and provide a sprite with a single pixel of 75% transparent black. This means everything would be dark, except some circles around light sources.

For chained maps, you probably want to have the same daylight length and light map sprite configuration, otherwise you'll get some very strange effects in-game.

## Wielded Lights

In the `Attributes` menu, under the Attributes setup you can set which attribute is responsible for the light radius. Then you can assign a value to this attribute for each object under `Objects` > `In inventory` > `Attribute modifiers` (see object's in inventory). When the player is equipted with an object that has this attribute set (or just wears such an object on his/her belt), then the light overlay will get a circular transparent "hole" in it with that radius and with the player in its centre.

## Stationary Light Sources

Similarily, you can place an object with light radius attribute set on the map, like for example a tourch on the wall. These also punch a circular transparent "hole" on the light overlay of that radius, with the object's position on the map as centre.

PreviousNext

# Translations

## Providing Translations

Select the `Translations` menu. In the drop down, you can select one of the existing translations, or you can choose the "New language" for a new language.

## Identifier

On the top right corner, you'll see the language's two letter ISO-639-1 code, and its native name. The code is like "en", "es", "ru", "de", "ja" etc. The name is always the one how the language is called by its native speakers, so for example it's not "German", rather "Deutsch". Or with another example, it's not "Japanese" rather it must be "日本語". There are some codes and names predefined for the most commonly spoken ones and for the languages of the EU, meaning when you enter the code, the name field gets filled in automatically. You can of course modify that name if you wish.

## Specifying Speech

Some audio files are special in that they contain speech which might be translated. All audio files that are categorized as such will be listed here, and then you can assign a translated audio file for each. It is not 100% possible, but always try to keep the translated audio files to have the same duration as the original ones. A few seconds more or less doesn't matter, but much more like double the duration can cause troubles in cutscenes where the speech uses precise timings.

## Specifying Text

Below the audio block, you can see all the texts in your game. These are collected automatically, so if you modify your game (for example you add a new object), then the list will change accordingly.

You can use this interface to fill in the translated texts. Pasting from another application (like from a text editor) works as expected. But if you find it problematic, then you can save the translation to a file. It is stored in a format that resembles .po files, so you should have no issues translating them with your usual tools. Keep in mind that the comment in the first line is MANDATORY, do not change that. Also the first id-string pair must be the language code and the translated name of the language, and the second is the title of the game.

When you're finished with translating the texts, don't forget to press Save.

PreviousNext

# Purpose

To give you a quick start creating games, TirNanoG provides the TirNanoG Base asset set.

Note

Unlike in other programs, you're not forced to use a specific asset set with the editor. This is just a convenience set, one of the many possibilities, the TirNanoG Editor can work with any game templates.

This part of the manual describes everything you need to know if you want to expand that default set with new assets in a compatible way.

Assets in the TirNanoG Base template were originally based on the Liberated Pixel Cup, however diverged from that significantly. Most notable differences:

- Standardized animations
- Standardized number of frames
- Standardized head and hands positions on every frame
- Standardized sprite sheet (see layouts)
- Use of guidelines to help keeping compatibility
- Strictly using CC-by-sa-4.0 license only (or any later version of that license).

To convert the old LPC assets into this new TirNanoG Base format, you can use the sprsheet converter tool.

1. use the sprsheet tool to convert the old assets into TirNanoG Base layout
2. use your favourite pixel editor, load both the guides and the newly created sheet
3. do fine adjustments so that each frame match the guidelines properly

When creating assets from scratch, follow the instruction in this section of the manual. The most important part is to match your frames with the guidelines, so that your set will fit with the already existing assets nicely.

PreviousNext

# Colors

Important

Things that are important enough to be worth repeating

- No pure colors!
- Vary the hues of your color ramps!
- Highlighted areas are yellow-ish, shadowed areas are purple-ish.
- Block your art out first, including shadows, before adding detail.

## Shades

Roughly a “toon style rendering” with medium-low levels of texturing. We want some detail, but not so much that things are so ornate that it might make collaboration difficult. We don’t want things to be “noisy” either. But detail is good. Texturing should have a toon-style; this is accomplished with medium to low amounts of texturing. Details should be used sparsely, so make them count!

Process of creating shades

Shade in blocks. Begin drawing by blocking out the object first, paying attention to its volume. Lines should be added afterward, and generally only around the edges and with very important details. Details should mostly be implied by form and color, not by outlines.

## Lighting

Lighting should primarily come from above. If there is any side directionality, it should come from the left, but not by much: keep it mostly center.

The direction of sublight (yellow arrows)

An example scene in blender with a sun light pointing in the appropriate location:

Left example shows from the “top-facing” camera used in this style; right example shows a sideview. Yellow “sun” with ray is the light source, big orange triangle on right is the camera.

Your light to dark color ramps should never all have the same hue. Vary the hue and saturation a bit as you go from light to dark, or your objects will look flat.

## Shadows

To create shadows or lowlights, once you have the main color the shade you want it to be move the hue (HSV selector) slightly towards the closest purple. To create highlight color, do the same but instead of purple and shade move the hue slightly towards the closest yellow and lighten it up. Adjust as necessary until it looks “right”.

Inside, things will be cooler in overall color, with slightly less contrast. This is doubly true for things like basements, caves and other underground areas.

All drop shadows should be done with the color #322125 at 60 percent opacity. If it makes sense, one may also provide a combined version of two tiles, so only one layer is needed to, say, put a house on a grass background.

Dithering should be used sparingly if at all. None of the base artwork has dithering.

## Outlines

Outlines should be a darker version of the current color, or a dark color generally, not black. (Extreme circumstances obviously may have exceptions.)

Note how the outline is a darker version of the same color

## Props and Objects

Props should be colored so that they don’t blend in with the surrounding background tiles (vary color, brightness, and saturation to provide contrast).

There’s should be a large difference in lighting between the sides and the top of objects. Look at these objects as example:

Examples of object lighting via a barrel and a bucket

Props should have shadows, or they will appear not to be part of the scene. Shadows should follow the same transparency blending rules as mentioned in the “lighting“ and “shadows” sections above.

## Character Colors

Characters should have their own color palettes so that they stand out from the background. Drop shadows should follow the same rule as the tiles, #322125 at 60% opacity.

Note

The sprite generator can handle dynamic recoloring of the character layers.

## Palettes

There’s no specific palette required for TirNanoG Base asset conformance, but it’s generally best to try to match to the colors used in the base set.

PreviousNext

# Objects and Tiles

There are not much to say about objects, because they have minimal compatibility requirements. Keep in mind that objects have orthograpic (top-down) perspective, and you must choose the colors for props and objects carefully so that they nicely fit with the tiles.

When you're creating bigger objects, don't forget that players might walk inside. That's only possible if you create multiple layers of an object.

Separate large object into layers

## Grid Size

The general tile grid is 32x32 with (possible) sub tiles at 16x16. The rationale being that the basic size of a square object (eg a chair or a character) is a 32x32 area. All base assets are designed to work at 32x32 tiling, and it’s recommended that you build yours to be so as well. However, for versatility tiling can happen at 16x16 resolution.

32x32 grid example

## Perspective

The camera angle is top-down, roughly 60 degrees.

Top-down, orthographic projection

Rendering should be orthographic, which means there is no perspective... things do not get smaller as they move into the distance. If you’re using perspective techniques on your props or tiles, that’s wrong.

Chest perspective example

## Tile Authoring

Details are simplistic. There are more details on the edges, and the center tile should be either one color or a very subtle pattern.

Occasional detail tiles should be thrown in to break the monotony of having a single repeating tile.

Demonstrating tiles that can be used to make more complex patterns

Edged tiles such as walls and floors should be arranged in a similar manner as the establishing art.

Hint

You can set up automap rules and then the map editor will automatically place these edge tiles whenever preferable.

PreviousNext

# Character Animations

For characters and their assets, those must use the TirNanoG Base sprite sheet layout (see an example sheet below). This is very important, because using the same layout is what guarantees compatibility and makes the sprite generator possible.

## Proportions

Characters are squashed, roundish, and not realistically proportioned. Bases are approximately two and a half heads tall and in the same perspective as the tiles. The base should fit in a 32x48 space and the clothing should fit in 48x64 space. The outlines should be black or near black, no selective outlining.

Example of accessorized characters

## Modularity

Characters are made up of multiple, strictly-positioned sprite sheets. This means that in TirNanoG Base the characters are modular, you can select different sprite sheets to create a player or NPC character of your liking.

Demonstrating modularity through multiple sprite sheets

### Body and Head

The first and most important layer is the `body`, which consist of a torso, arms and legs and the second layer is `head`. There must be at least two variations of it:

- female (feminine)
- male (masculine)

For both, the positions of the head and the hands are fixed, they must be at the same spot for every frame, depending on the animation and the direction.

### Clothes and Accessories

This layer could mean multiple layers, depending on the accessory's requirements. A full-body armour typically needs one, while a modern day outfit would probably need at least three (shirt, trousers, shoes). There's no limitation, these layers are fully customizable in the character sprite generator.

Since a clothes asset is using the same guides as the body layer, there should be multiple variations of it as well (female, male, etc.), but unlike the body layer, it is okay if only one of the variations exists for clothes.

### Tools

Everything that has to be positioned in the character's hands. Includes weapons, magic staff, torch etc. too. The guidelines provide standardized hand positions, which means there should be no need for multiple variations of tools per body (e.g. the same sword sprite sheet should work with both the male and female body layer). This is the most relaxed layer for animation requirement: typically all of movement type animations are required, but only one "use" animation is needed for them.

Tools layer typically consist of one single layer. But it might be split into two: `toolb` is behind all the other layers and `toolf` is on top of all the other layers. This is needed if the tool has a long handle, like a scythe for example, or if you don't want to "cut out" parts of the accessory where the body should cover it.

## Animation Types

Name | #frames | Description
--- | --- | ---
idle | 2 | idle animation
hurt | 2 | played when character takes damage
block | 2 | successfully blocked an attack
walk | 6 | normal walking
run | 6 | similar to walk, but faster movement
jump | 6 | vertical jump
slash | 6 | action 1: melee attack with sword
thrust | 6 | action 2: melee attack with spear
bowing | 6 | action 3: ranged attack, firing a bow
cast | 6 | action 4: casting a magic spell
push | 6 | action 5: push objects, same as walk
carry | 6 | action 6: carry objects, same as walk
climb | 6 | climbing on a ladder 1 direction
spawn | 6 | character appearing 1 direction
die | 6 | out of HP, death 1 direction

## Sheet Layout

Important

You can download this grid as well as the guidelines in guides.zip. This archive contains `guides.xcf` for GIMP, but in case you aren't using that, each layer is saved as a PNG as well.

Animations are arranged on the sprite sheet by strict rules. Directions are encoded in rows (South, West, North, East in this order), and animation frames in coloumns (except idle, hurt and block animations, which have only 2 frames and are packed together, all animations have 6 frames).

Next, each animation (6 x 4 grid cells) is arranged on the sheet in a strict order, like this:

The TirNanoG Base sprite sheet layout

You can import these sprite sheets under the sprites menu using the "TNG-Base" layout, and they are also used by the character sprite generator.

The bottom right corner of the layout contains a 4 x 5 grid size portrait. This is used to construct a modular portrait, but without facial expressions.

Expressions for portraits are also modular and made up from multiple images (one for the eyes, one for the nose, one for the mouth etc.), but contain 4 times 4 x 5 grid size sprites in a row (so total of 16 x 5 grid cells), one sprite for each expression in order: neutral, happy, sad, angry.

The Portrait layout

## Expanding

You can add new sprite templates any time. These are stored in `~/TirNanoG/.common`, and all are PNG files. Just like with the other assets, there's no database, the editor picks up new image files automatically.

### Layer Definitions

Images by the name `(layer).png` which are 16 x 16 pixels in size contain an icon, and define a layer type. Since layers are ordered alphabetically, it worth starting its name with a number (that number won't be shown in the layer's name, it just specifies the correct order, like `1hair`, `2clothes`). There are 4 hardcoded layers, `body`, `head`, `toolb` and `toolf` (the reason for this is, again, to guarantee correct layering order).

Important

The generator constructs the final sprite sheet by adding layers in this order: first, `toolb` layers. Then other layers except `toolf` ordered by the variant's `(number)`, within each iteration `body`, `head` first, then all the user defined layers in alphabethical order, then finally `toolf`. Within a layer, variants are ordered alphabethically.

### Sprite Templates

Non-icon sprite template images are named like `(layer)_(number)_(variant).png`, where `(layer)` is one of the hardcoded names or the user specified layer's name. Images with height of 16 times the grid's size are character animation templates, they must follow the TirNanoG Base sprite sheet layout. These layers might add parts to the portrait too, but only if those parts aren't facial expression related. The tools layer is special in a way that it has a background layer `toolb` and a foreground layer `toolf` too, handled together. The `(number)` part is a number between `0` and `9`, and it just tells the correct ordering of the variants, and finally, `(variant)` is the name, free to choose, but without spaces (use underscore) or parenthesis (see below).

Portrait templates are named `(layer)_(number)_(variant).png` too, but their height is 5 times the grid's size. They do not add to the character animation sprites, only to the portrait sprite, but with multiple facial expressions.

The layer types aren't hardcoded, you can create new types any time just by providing an icon first. For example, you can add an icon by the name `ears.png`, and then you can start adding templates like `ears_1_elf.png`, `ears_1_small.png` etc.

Optionally template names might look like `(layer)_(number)_(variant)_((depends)).png`, for example `ears_1_elf_(male).png`. These variants are only selectable if the variant `*_[0-9]_(depends).png` is enabled. Only one parenthesis allowed, and only at the end of the filename. If there are multiple templates by the same name on different layers, then only the first match is counted as dependency, however the `(variant)` part of the templates should be unique in the first place.

### Recoloring

You can use a neat trick with the templates to allow dynamic recoloring. For that, the image must have some special grayscale colors, namely `#101010`, `#303030`, `#505050`, `#707070`, `#909090`, `#b0b0b0`, `#d0d0d0` or `#f0f0f0`, and a 8 x 16 pixel matrix at the bottom right corner (or, in case of a character option sprites, on a separate sprite). Here each row corresponds to a palette. These grayscale values index one of the coloumns (brightest on the left, darkest on the right), and the user can choose one of the rows. Then the generator will replace these grayscale colors on the image with those selected colors.

Explanation of how color variants work

In order for a color variant to show up, the brigthest color (at image width - 8, the one which replaces `#f0f0f0`) must be specified. Others depend on which grayscale colors are used on the image. For example, the second color can be left empty if there's no `#d0d0d0` on the image.

The sprsheet tool can automatically de-colorize any image for you with the `-p` flag. Follow these steps:

Step | Description
--- | ---
1 | create a transparent image of 8 x 16 pixels size, this will hold the palette variants
2 | choose a color and add its gradients (exactly as they appear on the sprite) to the top row
3 | add more color variations
4 | use `sprsheet -p palette.png lpc2tngbase.csv output.png input.png` to de-colorize and create a recolorizable new sheet

You have to create this `palette.png` only once, it can be used to de-colorize any number of sheets. For example, create a palette image with the hair color variants (brown, blonde, gray, pink, orange etc.), with the brown hair's gradients on top. Then you'll only ever need just the brown hair LPC sprites (long, short, curly, messy etc.), and you can convert and add the recolor option to them all.

In case some sprites use a different palette (for example the brown shirt uses one kind of brown gradient, but brown boots is using another one), then you can use `sprsheet -r replace.png` to replace the colors. Here `replace.png` must have at least 2 rows, but can have more, and it has as many coloumns as many colors you want to replace. The first row is the "to" palette, others are the "from" palettes.

PreviousNext

# Tile Naming

Note

The editor allows any naming scheme you'd like. The one below is just the naming convention used in the TirNanoG Base asset set.

Hint

The suffix guide is also available in the guides.zip as GIMP layers and as individual PNG files too.

## General Suffixes

Tiles are named systematically. Most variants are labelled `a` - `z`, sometimes with `1` - `9`. Things that can be open or closed are always suffixed by `0` (closed) or `1` (open). Suffix strings follow a simple rule, a combination of letters: `l` (left), `m` (middle, repeatable), `r` (right) if it's horizontal, and `t` (top), `m` (middle, repeatable), `b` (bottom) if the item is vertical. If it has both horizontal and vertical variations, then the suffix contains `h` or `v` too, respectively. If there's also a one slot big version, that's suffixed `c` (center).

    t                 vt
    m     l m m r     vm  hl hm hm hr
    m                 vm
    b                 vb  c

When the item can be stretched both horizontally and vertically at the same time, then the combinations are `tl` (top left), `tm` (top middle, this item repeatable horizontally), `tr` (top right); `ml` (middle left, repeatable vertically), `bg` (instead of middle-middle it's called background, repeatable both vertically and horizontally), `mr` (middle right, repeatable vertically); `bl` (bottom left), `bm` (bottom middle, repeatable horizontally), `br` (bottom right). If the middle item can be used in combination with another (giving a two slots wide version), then that additional tile is suffixed `n` (next), but more commonly alternate version are just simply numbered.

    tl tm tm tr
    ml bg bg mr
    ml bg bg mr
    bl bm bm br

## Terrain Suffixes

Terrain types are simply suffixed `a` - `r`. There's no logic in that, instead when you search for a terrain type it should be displayed in a visually helpful way in the search results box. Here `d`, `l` is repeatable horizontally, `f`, `n` vertically. The center item `a` is always repeatable both vertically and horizontally, and it usually has alternate versions (suffixed by `b`, `i`, `j`) to break the monotonity. Items `q` and `r` have all their edges cleared, with a little bit of terrain in the middle. The wangset correlations are as follows:

    11 - a, b   00 - c   00 - d   00 - e   01 - f   11 - g   11 - h
    11          01       11       10       01       10       01

    11 - i, j   01 - k   11 - l   10 - m   10 - n   10 - o   01 - p
    11          00       00       00       10       11       11

    00 - q, r
    00

## Roof Suffixes

Similar to general suffixes, but with little additions depending on the direction the roof is facing.

### South

This is the default, the widest area shown of the roof. The edges are 2 x 2 grid sized to accomodate ornaments if any. Therefore the top middle and bottom middle sprites are 1 x 2 grids, and middle left and middle right 2 x 1 grids in size.

    so_tl    so_tm    so_tr
    so_ml    so_bg    so_mr
    so_bl    so_bm    so_br

### North

Since the TirNanoG Base asset is an orthographic set, this is more likely top view. Usually roofs might have a flat top, that's their North side.

    no_tl    no_tm    no_tr
    no_ml    no_bg    no_mr
    no_bl    no_bm    no_br

There's a twist, because it usually has an edge, so there's a need for some continuation sprites too (using wangset notation):

    10 - no_bg1    01 - no_bg2
    00             00

    00 - no_bg3    00 - no_bg4
    10             01

### South-West and South-East

These are beveled diagonal, and consist of bigger sprites. You cannot stretch these, because they must match the 1:2 sloop, have fixed size of 2 x 4 grids.

    sw    se

### Rooftop Parts

These mini towers also have their own roof. Usually they are smaller, perpendicular protrusion parts. Single sprite each, with fixed size, 2 x 2 grids (or with south direction 3 x 2).

    we_top    ea_top

         so_top

### Joins

These are named after the two directions to make life simpler. The `t1` and `t2` are both top elements, the only difference is, there's no more roof above `t1`, while the roof continues upwards for `t2`.

                      we_so_t1    ea_so_t1
                      we_so_t2    ea_so_t2
             we_so_m                        ea_so_m
    we_so_b                                          ea_so_b

                       so_we_t    so_ea_t
              so_we_m        so_bg         so_ea_m
    so_we_b   so_bm          so_bm         so_bm     so_ea_b

### West-East Roof

This is the case when you see both sides of the roof going down in West-East direction (up-side down V). There are two versions, an acute angled (suffixed `acute_`) and a bevel angled roof (suffixed `bevel_`). The last suffix part comes from the position:

            la    ra
        lb  lc    rc  rb
    ld  le  lf    rf  re  rd
    lg  lh  li    ri  rh  rg
    lj  lk  ll    rl  rk  rj
    lm                    rm

On both sides the `le` or `lh` is the background (depends on the roof's "thickness"), so those are stretchable both vertically and horizontally. The only difference between acute and bevel is, that the second column on both sides (`lb`, `le`, `lh`, `lk` and `rb`, `re`, `rh`, `rk`) have double width for bevel to accomodate the 1:2 sloop. The last row, `lm` and `rm` is always twice the width, even for `acute_lm` and `acute_rm`.

The roofs are made carefully in a way so that you can mix the second columns of acute and beveled roofs, creating a "break" in the roof's sloop if you like. For example:

                                  acute_lb
                                acute_lb
                        bevel_lb
                bevel_lb
      acute_lb
    acute_lb

PreviousNext

# TirNanoG Editor License

The TirNanoG Editor is Free and Open Source software available under GPLv3+ or any later version of that license.

     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 3 of the License, or
     (at your option) any later version.

     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

PreviousNext

# TirNanoG File Format License

Note

The file format's license has nothing to do with the game's license stored in this format, just like how PKWARE's copyright does not influence the file's licenses stored in a .zip file.

The TirNanoG File Format is dual licensed:

## Unencrypted

By default, TirNanoG File Format is licensed under CC-by-nc-sa (attribution required, non-commercial, share-alike):

    CREATIVE COMMONS - BY - NC - SA
    https://creativecommons.org/licenses/by-nc-sa/

    You are free to:

     - Share — copy and redistribute the material in any medium or format

     - Adapt — remix, transform, and build upon the material
         The licensor cannot revoke these freedoms as long as you follow
         the license terms.

    Under the following terms:

     - Attribution — You must give appropriate credit, provide a link to
         the license, and indicate if changes were made. You may do so in
         any reasonable manner, but not in any way that suggests the
         licensor endorses you or your use.

     - NonCommercial — You may not use the material for commercial purposes.

     - ShareAlike — If you remix, transform, or build upon the material,
         you must distribute your contributions under the same license as
         the original.

## Encrypted

With the written permission of the TirNanoG File Format's author, you can create encrypted game files, see chapter License Keys for more details. For commercial games I recommend this file format option as it gives you not just encryption but a legal guarantee too that your assets in the .tng file can't be stolen.

The decision and the responsibility of which licensing version to use for the game files is up to the editor's users, and it does not influence the game's license stored in this format. Under no circumstances can I, bzt, the TirNanoG Editor and TirNanoG File Format's author be held responsible for the game files created by others.

Trying to decrypt, disassemble or any other way reverse engineer the proprietary encrypted format is strictly forbidden to protect the rights of the copyright holders of the assets inside the file.

PreviousNext

# TirNanoG Base License

The default game template, the TirNanoG Base is licensed under CC-by-sa (as well as the LPC assets it is based on). Uses the 4.0 version, or any later version of that license.

    CREATIVE COMMONS - BY - SA
    https://creativecommons.org/licenses/by-sa/

    You are free to:

     - Share — copy and redistribute the material in any medium or format

     - Adapt — remix, transform, and build upon the material
         The licensor cannot revoke these freedoms as long as you follow
         the license terms.

    Under the following terms:

     - Attribution — You must give appropriate credit, provide a link to
         the license, and indicate if changes were made. You may do so in
         any reasonable manner, but not in any way that suggests the
         licensor endorses you or your use.

     - ShareAlike — If you remix, transform, or build upon the material,
         you must distribute your contributions under the same license as
         the original.

Previous