Difference between revisions of "Modding:Module"

Latest revision as of 11:51, 31 January 2012

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.

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.

Engine Hooks

Modules are defined by their hooks. In relation to the game itself (and aside from object-specific ones), there are three types of hooks:

• Chained hooks are defined across the various underpinnings of the game. By order of lowest to highest priority are: module hooks, which are written for a given "game"; challenge hooks, which are written for a particular challenge; and core hooks, which take place across all modules. In addition to the normal priorities, chained hooks defined at the module level (at least) always override object-specific hooks when applicable.
• Level hooks are defined for a particular level. All chained hooks are also level hooks, but any of those hooks defined within a level are given lowest priority on the chain.
• Global hooks are defined for an entire module. All chained hooks and level hooks are also global hooks. Global hooks are defined automatically at the core priority level unless manually altered.

OnCreate()

Called whenever any thing is created on the map.

OnDie()

Called whenever any being is destroyed on the map.

OnDieCheck() → boolean

Called whenever any being's HP is reduced to zero on the map, before being:kill() is called.

OnKillAll()

Called whenever there are no beings left on the map (other than the player).

OnFire()

Called whenever a ranged weapon is set to fire on the map, but before the missile is created.

OnFired()

Called whenever a ranged weapon is fired on the map, immediately after all firing consequences (damage, knockback, etc) have ended.

OnPickup()

Called whenever an item is picked up on the map.

OnPickupCheck() → boolean

Called whenever a being attempts to pick up an item on the map.

OnFirstPickup()

Called whenever an item is picked up on the map by a being for the first time.

OnUse()

Called whenever an item is used on the map.

OnUsePickup() → boolean

Called whenever a being attempts to pick up an item on the map.

OnEnter()

Called whenever the player enters the map. This is unchained from the item object's OnEnter hook.

OnTick()

Called every turn (0.1 game seconds) It is advised that specific conditions are used to prevent slowdown.

OnKill()

Called whenever any being is killed on the map. This is unchained from the item object's OnKill hook.

OnExit()

Called whenever the player exits the map.

OnCompletedCheck() → boolean

Called whenever the player exits the map: if the level is determined to be cleared by unique conditions, or if there are no beings on the map other than the player, then this returns true.

OnLoadBase()

Called whenever either the base game or a total conversion module is loaded. This is the very first hook called for a module.

OnLoad()

Called whenever a module is loaded. This occurs immediately after OnLoadBase (if it is called).

OnLogo()

Called immediately after the module is loaded, but before the menu is created. In the base game this is used to create the DooM title graphic.

OnCreatePlayer()

Called immediately after the player has selected their challenge and/or difficulty.

OnIntro()

Called immediately the player has finished selecting a name and traits. In the base game this is used to create the introductory plot screens.

OnCreateEpisode()

Called immediately after OnIntro (if it is called). This only works with episode and total conversion module types.

OnLoaded()

Called immediately before the module starts (that is, with the player on the map).

OnGenerate()

Called whenever a random map is created (that is, whenever a level is not called for a particular floor). This only works with episode and total conversion module types.

OnPreLevelUp()

Called whenever the player levels up, but before they pick a trait.

OnLevelUp()

Called whenever the player levels up, immediately after they pick a trait.

OnWinGame()

Called whenever the player wins the game. Simply, this is called using the player:win() function.

OnMortem()

Called immediately before the mortem is printed.

OnMortemPrint()

Called alongside mortem printing. This is where all player:mortem_print() functions should be used.

OnUnLoad()

Called immediately after the mortem and high score screens are displayed and exited. For single module types, this returns the player to the base game module.

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.