Difference between revisions of "Modding:Module"

From DoomRL Wiki

Jump to: navigation, search
(Created page with some initial info on the module system)
 
m (extensions)
Line 46: Line 46:
 
== Data Files ==
 
== Data Files ==
  
Sound files used by a module must be included in a subdirectory called ''sound'' of the main module folder. These files are automatically loaded when the module is run even if they aren't referenced by DoomRL's config file. Their lua string ids correspond to their file names (without any file type extension).
+
Sound files used by a module must be included in a subdirectory called ''sound'' of the main module folder. These files are automatically loaded when the module is run even if they aren't referenced by DoomRL's config file. Their lua string ids correspond to their file names (without the file type extension). Sounds can only have a .wav extension.
  
Music files are handled analogously to sound files; they should be put in a directory called ''music''.
+
Music files are handled analogously to sound files; they should be put in a directory called ''music''. Music can have a .mid, .mp3, or .ogg extension.
  
 
ASCII art should be contained in a directory called ''ascii''. ASCII art files are text files that use [[valkyrie color escapes]] for coloring. By convention these files have the .asc extension. The name of an ASCII art file should be the same as the corresponding being's string id (or for custom player armor art, the same as the armor's string id). Currently, DoomRL only loads ASCII art from compiled modules.
 
ASCII art should be contained in a directory called ''ascii''. ASCII art files are text files that use [[valkyrie color escapes]] for coloring. By convention these files have the .asc extension. The name of an ASCII art file should be the same as the corresponding being's string id (or for custom player armor art, the same as the armor's string id). Currently, DoomRL only loads ASCII art from compiled modules.

Revision as of 03:44, 14 August 2011

Note: This page is related to DoomRL 0.9.9.4 modding. For information on 0.9.9.3 modding, check out the old wiki. Keep in mind that, as 0.9.9.4 is as-of-yet unreleased, this information is subject to change.

A module is the DoomRL name for a mod. A module must contain a module.lua metadata file and a main.lua source file. It may also contain sounds, music, and ASCII art.

Modules can be either compiled or raw. Generally, modders distribute compiled modules. Compiled modules are files with the .wad extension. A .wad file contains all the information needed to run a module including sounds and music. A raw module is a folder with the .module extension. A raw module's folder contains all the files separately. Modders will typically have their own mod in raw format while they are developing it. A raw module can be compiled into a .wad file. In either case, modules should reside in the modules subdirectory of the main DoomRL folder.

Metadata

Every module must contain a module.lua metadata file. For raw modules, it should be directly in the module folder (not in any subdirectory). This file should define a global table called module to hold the metadata. This metadata is loaded when browsing mods in the Custom Game menu. The valid entries in the table are listed below.

Module Metadata
string id This is the name DoomRL internally use for the module. It should not be changed from version to version. The folder of a raw module must be named as the module's id with the ".module" extension. The .wad file of a compiled module must be named as the module's id with the ".wad" extension. By convention, only lowercase letters, numbers, and the underscore are used in a module's id.
string name This is the proper name of the module that will be displayed in the Custom Game menu.
string author This is the author's name (or alias). It will be displayed in the Custom Game menu.
string webpage This is the author's webpage. If you don't have a webpage, use "(none)". This will be displayed in the Custom Game menu.
integer list version This is the module's version number. The mod's version number should be updated whenever a new version is release, as future versions of DoomRL will use this to determine whether local mods are synced with the mod server. The format for a version is e.g. {1,0,0}.
integer list drlver This is the version of DoomRL that the module was designed to run with. For modules developed for 0.9.9.4, this will be {0,9,9,4}.
string type Currently, this must be "single", as no other types are supported yet.
string description This is the description of the module that is displayed in the Custom Game menu. Keep in mind that space is somewhat limited. Also, this description will be used in the upcoming mod server, so it should be designed to make people want to play the module.
boolean difficulty This determines whether or not player's will get to choose a difficulty level after selecting the mod. If not, the default difficulty level is I'm Too Young To Die (at least for now... this may get changed to HNTR --tehtmi).

Main

Every module must also have a main.lua file directly in the module folder. This file will be loaded after the module is selected from the Custom Game menu. It must declare a global table (via core.declare) with the same name as the module's id. This table contains various functions that determine how the module works. For single-type modules, the available hooks are precisely the Level hooks, with a new function called run used to handle initial set up.

Data Files

Sound files used by a module must be included in a subdirectory called sound of the main module folder. These files are automatically loaded when the module is run even if they aren't referenced by DoomRL's config file. Their lua string ids correspond to their file names (without the file type extension). Sounds can only have a .wav extension.

Music files are handled analogously to sound files; they should be put in a directory called music. Music can have a .mid, .mp3, or .ogg extension.

ASCII art should be contained in a directory called ascii. ASCII art files are text files that use valkyrie color escapes for coloring. By convention these files have the .asc extension. The name of an ASCII art file should be the same as the corresponding being's string id (or for custom player armor art, the same as the armor's string id). Currently, DoomRL only loads ASCII art from compiled modules.

Personal tools