Difference between revisions of "Modding:Module"
From DoomRL Wiki
Game Hunter (Talk | contribs) m (removed 0994 warning) |
Game Hunter (Talk | contribs) (added engine hooks for each module hook type (descriptions on the way)) |
||
| Line 39: | Line 39: | ||
== Main == | == 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. | ||
| + | {|class="wikitable" style="border: 2px solid darkred; border-spacing: 0; font-size: 90%; margin: 0.25em 0.5em;" | ||
| + | ! colspan="2" style="background: darkred; color: yellow; font-size: 120%; text-align: center"|'''Chained Hooks''' | ||
| + | {{Table2Col | ||
| + | |es=background: #333; | ||
| + | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
| + | |c2=padding:0px 2px; | ||
| + | |void|[[#chained_OnCreate|OnCreate]]() | ||
| + | |void|[[#chained_OnDie|OnDie]]() | ||
| + | |boolean|[[#chained_OnDieCheck|OnDieCheck]]() | ||
| + | |void|[[#chained_OnKillAll|OnKillAll]]() | ||
| + | |void|[[#chained_OnFire|OnFire]]() | ||
| + | |void|[[#chained_OnFired|OnFired]]() | ||
| + | |void|[[#chained_OnPickup|OnPickup]]() | ||
| + | |boolean|[[#chained_OnPickupCheck|OnPickupCheck]]() | ||
| + | |void|[[#chained_OnFirstPickup|OnFirstPickup]]() | ||
| + | |void|[[#chained_OnUse|OnUse]]() | ||
| + | |boolean|[[#chained_OnUseCheck|OnUseCheck]]() | ||
| + | |}} | ||
| + | |} | ||
| + | |||
| + | {|class="wikitable" style="border: 2px solid darkred; border-spacing: 0; font-size: 90%; margin: 0.25em 0.5em;" | ||
| + | ! colspan="2" style="background: darkred; color: yellow; font-size: 120%; text-align: center"|'''Level Hooks''' | ||
| + | {{Table2Col | ||
| + | |es=background: #333; | ||
| + | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
| + | |c2=padding:0px 2px; | ||
| + | |void|[[#chained_OnEnter|OnEnter]]() | ||
| + | |void|[[#chained_OnTick|OnTick]]() | ||
| + | |void|[[#chained_OnKill|OnDie]]() | ||
| + | |void|[[#chained_OnExit|OnExit]]() | ||
| + | |boolean|[[#chained_OnCompletedCheck|OnCompletedCheck]]() | ||
| + | |}} | ||
| + | |} | ||
| + | |||
| + | {|class="wikitable" style="border: 2px solid darkred; border-spacing: 0; font-size: 90%; margin: 0.25em 0.5em;" | ||
| + | ! colspan="2" style="background: darkred; color: yellow; font-size: 120%; text-align: center"|'''Global Hooks''' | ||
| + | {{Table2Col | ||
| + | |es=background: #333; | ||
| + | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
| + | |c2=padding:0px 2px; | ||
| + | |void|[[#chained_OnLoadBase|OnLoadBase]]() | ||
| + | |void|[[#chained_OnLogo|OnLogo]]() | ||
| + | |void|[[#chained_OnLoad|OnLoad]]() | ||
| + | |void|[[#chained_OnLoaded|OnLoaded]]() | ||
| + | |void|[[#chained_OnCreateEpisode|OnCreateEpisode]]() | ||
| + | |void|[[#chained_OnOnCreatePlayer|OnCreatePlayer]]() | ||
| + | |void|[[#chained_OnIntro|OnIntro]]() | ||
| + | |void|[[#chained_OnGenerate|OnGenerate]]() | ||
| + | |void|[[#chained_OnPreLevelUp|OnPreLevelUp]]() | ||
| + | |void|[[#chained_OnLevelUp|OnLevelUp]]() | ||
| + | |void|[[#chained_OnOnWinGame|OnWinGame]]() | ||
| + | |void|[[#chained_OnMortem|OnMortem]]() | ||
| + | |void|[[#chained_OnMortemPrint|OnMortemPrint]]() | ||
| + | |void|[[#chained_OnUnLoad|OnUnLoad]]() | ||
| + | |}} | ||
| + | |} | ||
| + | |||
| + | == 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. | 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. | ||
Revision as of 19:16, 24 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.
Contents |
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.
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.
| Chained Hooks | |
|---|---|
| void | OnCreate() |
| void | OnDie() |
| boolean | OnDieCheck() |
| void | OnKillAll() |
| void | OnFire() |
| void | OnFired() |
| void | OnPickup() |
| boolean | OnPickupCheck() |
| void | OnFirstPickup() |
| void | OnUse() |
| boolean | OnUseCheck() |
| Level Hooks | |
|---|---|
| void | OnEnter() |
| void | OnTick() |
| void | OnDie() |
| void | OnExit() |
| boolean | OnCompletedCheck() |
| Global Hooks | |
|---|---|
| void | OnLoadBase() |
| void | OnLogo() |
| void | OnLoad() |
| void | OnLoaded() |
| void | OnCreateEpisode() |
| void | OnCreatePlayer() |
| void | OnIntro() |
| void | OnGenerate() |
| void | OnPreLevelUp() |
| void | OnLevelUp() |
| void | OnWinGame() |
| void | OnMortem() |
| void | OnMortemPrint() |
| void | OnUnLoad() |
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.
