T4 Modules Howto Guide/Directory Structure
An Overview
Player Profiles
When you run T-Engine or a module for the first time a player profile will be created. This contains your settings and keybindings, as well as module specific settings and achievements.
On linux this profile can be found in your home directory.
For Windows the profile folder will be called T-Engine. It will be located in the following locations.
Windows 7 - C:\Users\<username>\T-Engine Windows XP - C:\Documents and Settings\<username>\T-Engine
Profiles are now kept online, allowing the community to easily show off and compare character sheets, statistics, wins, and losses.
T-Engine Root Directory
In your T-Engine directory, the one where your executable is located, you will find a game directory. This directory contains all the Lua scripts used by the game and all its modules. The script is interpreted at runtime, so no recompilation is needed after modifying a file.
If you are writing a custom module you should avoid editing any file outside your module directory, since you will not be able to distribute those changes along with your module if you do.
This directory is located in your game folder and contains every module currently available to T-Engine. Every module has its own folder and copying a module directory here is sufficient for it to be detected and appear on the list of available modules when starting a new game.
For all of these guides, the convention to refer to a filepath will use the game's module directory as its root. This is the folder that contains your init.lua file.
Note that the structure described here is only a convention used by ToME, but it is advised that third party module writers follow it for consistency. Few of these paths are hardcoded.
Directories and files not in the example module are underlined. Directories are boldface.
ToME uses many more than listed here, this is only intended to be a rough guide for structuring your own modules.
| Directory or file | Purpose |
|---|---|
| / | Root Module directory |
| /init.lua | Description and basic information about the module. |
| /load.lua | This file loads all the basic code and definitions needed to run the module. |
| /resolvers.lua | Contains additional custom resolvers. |
| /ai/ | Directory for custom AI definitions. |
| /class/ | Directory for module custom class files. These usually extend the generic T-Engine classes of the same name and are used instead of them if they exist. |
| /class/Actor.lua | Both the player and all NPCs use this class. |
| /class/Game.lua | Handles game initialization, lower level code like keybindings and changing levels and displaying to screen. |
| /class/Grid.lua | Defines tooltips for grids and methods that handle what terrain blocks movement. |
| /class/NPC.lua | Handles non-player actors. |
| /class/Object.lua | Handles all objects in the game. |
| /class/Player.lua | Handles all player specific code that isn't generic to all Actors. |
| /class/PlayerDisplay.lua | Handles displaying the player's stats. |
| /class/Store.lua | Handles stores. |
| /class/Trap.lua | Handles traps. |
| /class/World.lua | Handles saving and Achievements. |
| /class/generator/ | Directory for custom generators in zones. |
| /class/interface/ | Directory for custom interfaces. These are inherited by other classes to help segment and seperate code and improve readability for complex classes. |
| /class/interface/Combat.lua | Module custom combat code is defined here. |
| /data/ | Most of T-Engine is data-driven, not code-driven. This directory contains all the module custom definitions loaded to make your game unique. |
| /data/damage_types.lua | Defines the default damage projector and all the different damage types used in the module. (fire, water, acid, etc) |
| /data/talents.lua | Default talents file loaded by /init.lua. This file often Load()'s other talent files to improve readability. |
| /data/timed_effects.lua | Defines various timed effects available to the module. |
| /data/achievements/ | Stores module achievements. |
| /data/birth/ | Birth descriptors folder. |
| /data/birth/descriptors.lua | Default birth descriptors file. Often Load()'s other descriptor files to improve readability.. |
| /data/chats/ | Stores NPC chats for mobs that can speak. |
| /data/general/ | Defines entities available to your module. Note that zones may define their own entities, such as bosses or special items, in the zone directories. |
| /data/general/grids/ | Defines general grids (terrain). |
| /data/general/npcs/ | Defines general NPCs. |
| /data/general/objects/ | Defines general objects. |
| /data/general/stores/ | Defines general stores. |
| /data/general/traps/ | Defines general traps. |
| /data/gfx/ | Special module image or particle assets. |
| /data/gfx/particles/ | Particle script files. |
| /data/maps/ | Static map definitions. |
| /data/music/ | Module music. |
| /data/quest/ | Module quests. |
| /data/rooms/ | Special generators for rooms. |
| /data/sound/ | Sound effects directory. |
| /data/talents/ | Stores talent description files. These are Load()'ed by the /data/talents.lua file. |
| /data/texts/ | Special non-quest or monster related texts. Used in ToME for introduction messages and new class unlock texts. |
| /data/tilesets/ | Data folder for the map generator. |
| /data/zones/ | Zones folder. Each zone has its own directory. |
| /data/ZONE/grids.lua | Zone load file for grids. |
| /data/ZONE/npcs.lua | Zone load file for npcs. |
| /data/ZONE/objects.lua | Zone load file for objects. |
| /data/ZONE/traps.lua | Zone load file for traps. |
| /data/ZONE/zone.lua | Zone description file. |
| /dialogs/ | Contains module specific dialogs. |
| /dialogs/DeathDialog.lua | Dialog displayed on death. |
| /dialogs/Quit.lua | Dialog displayed when a quit is requested. |
Module team files
The team files are renamed zip files. However, they have a different directory structure. The data folder remains the same and everything else is put in a mod folder.
Go back to T4 Modules Howto Guide
