Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
381 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,381 @@ | ||
| # kgDoom | ||
| ###### A doom port. With Lua. | ||
|
|
||
| #### Disclaimer | ||
| Point of this doom port is not to stay compatible or emulate original game accurately. Lua scripts in kgdoom.wad for original games do not reflect 100% original game behavior and are provided only for basic compatibility. | ||
|
|
||
| #### Install | ||
| To install on Switch, you currently have to use HBL. | ||
| Copy kgdoom.nro and kgdoom.wad to /switch/kgdoom/ on your SD card. Also copy any IWADs you have to this directory. | ||
| If you want to run PWAD mods, create directory /switch/kgdoom/pwads/ and copy these there. | ||
| When you start kgdoom, you will see WAD menu where you can pick IWAD, and optionally PWAD. | ||
|
|
||
| #### Map editing | ||
| This manual documents kgDoom Lua game API. I assume you already know how to make doom maps / mods and know Lua scripting. | ||
| Hexen map formap is recommended. Doom map format is present only for compatibility reasons. | ||
|
|
||
| ### Terms | ||
| These are terms used in Lua API. | ||
|
|
||
| - mobj | ||
| - Map object. Anything sprite-based in map. Items, monsters, players ... | ||
| - Default properties and animations are defined by mobjtype. | ||
| - mobjtype | ||
| - This is a template for mobj. When spawning mobjs, you refer to this type. | ||
| - This defines all animations and default properties. | ||
| - player | ||
| - This is a special mobj section that is only present for players. | ||
| - Players have few extra properties that other mobjs do not have. | ||
| - sector | ||
| - This allows access to map sectors. | ||
| - line | ||
| - This allows access to map lines and sides. | ||
| - genericPlane | ||
| - This is a generic plane (floor / ceiling) movement handler. | ||
| - This is bound to a sector. | ||
| - genericCaller | ||
| - This is a generic caller. It calls specified Lua callback periodically. | ||
| - This is bound to a sector. | ||
| - Used for example for light effects. | ||
| - textureScroll | ||
| - This is used to add texture scroll effect to lines. | ||
|
|
||
| ### Lua scripts | ||
| Lua scirpts are stored in WADs. There is only one recognized lump name: GAMELUA. You can have as many GAMELUA lumps in multiple wads. | ||
| Lua scripts are loaded from first wad to last and from first lump to last one. This should allow for overrides (game mods). | ||
| First line in each GAMELUA can specify internal script name. Example: `---test.lua`. Every time Lua has to report error, it will use `test.lua` as a script name. | ||
| ##### Stages | ||
| There are two stages. Loading stage and map stage. Every stage has its own set of global functions. | ||
| ###### Loading stage | ||
| This is stage when all GAMELUA scripts are loaded and executed. At this point you should create all mobjtypes, register player class, weapons and keys. You can not do these later. | ||
| Contents of GAMELUA ouside of any functions is executed at this stage. | ||
| ###### Map stage | ||
| This is stage when level is already loaded and everything in map is spawned. | ||
| Only callbacks and action functions are called. | ||
|
|
||
| ###### Beware | ||
| The is a weird bug(?) in Lua itself. If you make a syntax error, you will get `attempt to call a string value` error, which is not helpful at all. | ||
|
|
||
| ### API | ||
| #### inventory & armor | ||
| - Every mobj can have its own inventory and armor. | ||
| - Inventory item can be any mobjtype that has maxcount other than zero. | ||
| - When count reaches zero, item is removed from inventory. | ||
| - Negative maxcount is undepletable and will be kept even if count reaches zero. Used for ammo sice HUD expects ammo to exist even when depleted. | ||
| #### values | ||
| - angles | ||
| - Angles are specified in range 0 - 8191. This is a whole circle. | ||
| - fixed | ||
| - Any fixed point values can use decimal point in Lua. | ||
| #### globals | ||
| ###### Loading stage | ||
| - function `createMobjType(table)` | ||
| - Table should contain everything required to describe mobj type. | ||
| - See Lua scripts in kgdoom.wad file. | ||
| - See mobjtype section for list of properties. | ||
| - Returns newly created mobjtype. | ||
| - function `setPlayerType(mobjtype)` | ||
| - This function regiters primary player type. | ||
| - There is only one player type requred, multiple calls will only redefine default player type. | ||
| - function `addWeaponType(mobjtype [, mobjtype [, mobjtype])` | ||
| - This function expects weapon type as mobjtype and optionally one or two ammo types as mobjtype. | ||
| - Every weapon that should be listed in weapon menu must be registered using this weapon. | ||
| - If you want to have secret / scriptable weapons, you do not have to register them. | ||
| - function `addKeyType(mobjtype)` | ||
| - This fucntion registers key as mobjtype. This registration is only for display in HUD. | ||
| ###### Map stage | ||
| - function `doomRandom()` | ||
| - This will return a prandom number from 0 to 255. It uses original doom random table. | ||
| - function `doomRandom(max)` | ||
| - This will return a prandom number from 0 to max, including 0 and max. Only whole numbers are supported. | ||
| - function `doomRandom(min, max)` | ||
| - This will return a prandom number from min to max, including min and max. Only whole numbers are supported. | ||
| - function `spawnMobj(mobjtype, x, y [, z [, angle [, action]]])` | ||
| - Spawn new mobj at x and y and optionally z. Uses fixed point numbers. | ||
| - Spawn angle can be specified. | ||
| - If action is `true`, first frame action is executed. Enabled by default. | ||
| - Returns spawned mobj. | ||
| - function `blockThingsIterator(test_mobj, func [, arg])` | ||
| - Calls a callback `func` with optional argument `arg` for every mobj found inside radius of `test_mobj`. | ||
| - Argument `arg` is user specified, and can be anything. It will be passed to callback function. | ||
| - Callback should be function defined as `somecb(thing)` or `somecb(thing, arg)`. | ||
| - If callback returns `false`, iteration will stop and any other return values will get returned by `blockThingsIterator` itself. | ||
| - Beware: no z height checks are computed, you have to do this yourself it you need it. | ||
| - function `blockThingsIterator(x, y, func [, arg])` | ||
| - Same as above, but with single point specified by fixed point x and y. | ||
| - function `blockThingsIterator(x, y, xe, ye, func [, arg])` | ||
| - Same as above, but with manualy specified range. Also uses fixed points. | ||
| - function `globalPlayersIterator(func [, arg])` | ||
| - Calls a callback `func` with optional argument `arg` for every player in level. | ||
| - Callback should be function defined as `somecb(player)` or `somecb(player, arg)`. | ||
| - Return logic is same as in `blockThingsIterator`. | ||
| - function `globalThingsIterator(func [, arg])` | ||
| - Calls a callback `func` with optional argument `arg` for every mobj in level. | ||
| - Callback should be function defined as `somecb(thing)` or `somecb(thing, arg)`. | ||
| - Return logic is same as in `blockThingsIterator`. | ||
| - function `thingTagIterator(func [, arg])` | ||
| - same as `globalThingsIterator` but with automatic TID filter. | ||
| - function `globalSectorsIterator(func [, arg])` | ||
| - Calls a callback `func` with optional argument `arg` for every sector in level. | ||
| - Callback should be function defined as `somecb(sector)` or `somecb(sector, arg)`. | ||
| - Return logic is same as in `blockThingsIterator`. | ||
| - function `sectorTagIterator(tag, func [, arg])` | ||
| - Same as `globalSectorsIterator` but with automatic sector tag filter. | ||
| - function `globalLinesIterator(func [, arg])` | ||
| - Calls a callback `func` with optional argument `arg` for every line in level. | ||
| - Callback should be function defined as `somecb(line)` or `somecb(line, arg)`. | ||
| - Return logic is same as in `blockThingsIterator`. | ||
| - function `fakeContrast(enable)` | ||
| - Set `false` to enable fake contrast in level. | ||
| - Doom uses fake contrast on walls, so it is enabled by default. | ||
| - function `setBackground(patchlump)` | ||
| - This function will set screen background to this gfx from any WAD. | ||
| - Use of this function is not recommendes as specified image will only show trough holes in map (= bad map). | ||
| - It is only used for Doom2 finale emulation. | ||
|
|
||
| #### mobj states | ||
| There are few animations that every mobjtype can have. Only spawn state has meaning for all of them, as it is state it gets set to on level load. | ||
| Other animations depend on flag combinations. Unused states can be used in any way you wish. | ||
| Animations are always specified as `_animName` | ||
| - `_spawn` | ||
| - Basic animation for all mobjs. | ||
| - `_see` | ||
| - Set by internal `a.Look` when mobj has target to go after. | ||
| - `_pain` | ||
| - Used on `__shootable` mobjs. This state is set when mobj is damaged, but with chance specified by `painChance`. | ||
| - `_melee` | ||
| - Set by internal `a.Chase` when mobj is close enough to do melee damage to its target. | ||
| - `_missile` | ||
| - Randomly set by internal `a.Chase`. Used to attack from distance. | ||
| - `_death` | ||
| - Used on `__shootable` mobjs. This state is set when mobj is damaged and resulting health is less or equal to 0. | ||
| - `_xdeath` | ||
| - Used on `__shootable` mobjs. This state is set when mobj is damaged and resulting health is less than negative default health (overkill). | ||
| - `_raise` | ||
| - Not used by engine logic. | ||
| - Used in Doom Lua scripts by Archvile to raise dead bodies. | ||
| - `_crush` | ||
| - Used when there is not enough space in changing sector for this mobj and `__dropped` or `__corpse` is set. | ||
| - `_heal` | ||
| - Not used by engine logic. | ||
| - Used in Doom Lua scripts by Archvile itself to heal dead bodies. | ||
| - `_wRaise` | ||
| - Weapon state. Used when raising selected weapon. | ||
| - `_wReady` | ||
| - Weapon state. Used when holding weapon, waiting for fire. | ||
| - `_wLower` | ||
| - Weapon state. Used when lowering weapon. | ||
| - `_wFireMain` | ||
| - Weapon state. Used when firing using main attack. | ||
| - `_wFireAlt` | ||
| - Weapon state. Used when firing using alternate attack. | ||
| - `_wFlashMain` | ||
| - Weapon state. Added on top of normal animation if internal `a.WeaponFlash` is called. | ||
| - `_wFlashAlt` | ||
| - Weapon state. Added on top of normal animation if internal `a.WeaponFlash` is called. | ||
|
|
||
| #### mobj flags | ||
| Mobj flags are boolean values that affect mobj behavior. Flags are always specified as `__flagName`. | ||
| - `__special` | ||
| - Used for item pickup. Any mobj with `__pickup` enabled colliding with this one will call callback `action`. | ||
| - Callback should be function defined as `somecb(mobj, spec)` or `somecb(mobj, spec, arg)`. | ||
| - mobj is colliding thing (one with `__pickup` flag) and `spec` is this thing. | ||
| - `__solid` | ||
| - This mobj is considered solid and can be collided agains. | ||
| - `__shootable` | ||
| - This mobj can be damaged and is expected to have `health` and `painChance` set. | ||
| - `__noSector` | ||
| - This mobj is not in sector links. This affects rendering. If enabled, this mobj will be invisible. | ||
| - `__noBlockmap` | ||
| - This mobj is non in block links. This affects physics. Nothing can collide with this mobj. Usefull for GFX effects. | ||
| - Projectiles use this. In Doom, nothing coolides with projectiles, but projectiles collide with other mobjs. | ||
| - `__ambush` | ||
| - Used by internal `a.Look`. | ||
| - Monsters with this flag won't react to `a.NoiseAlert` but wait for direct line of sight (even from behind) to wake up. | ||
| - `__spawnCeiling` | ||
| - Used by some Doom decorations. Items with this flag will be spanwed on celing, but only at map loading. | ||
| - `__noGravity` | ||
| - This mobj won't fall down due to gravity. | ||
| - `__dropOff` | ||
| - This mobj can fall of tall edges. | ||
| - `__pickup` | ||
| - This mobj can 'pickup' items. See `__special`. | ||
| - `__noClip` | ||
| - This mobj has collision checks disabled. | ||
| - `__slide` | ||
| - This mobj will slide along walls / other mobjs. | ||
| - `__float` | ||
| - Used for internal `a.Chase` as a hit that this monster is flying. | ||
| - `__missile` | ||
| - Used for projectiles. This mobj has special collision check logic. Any collision would cause its death. And eventual damage to collided mobj. | ||
| - `__dropped` | ||
| - Used as a marker for dropped items. Engine either deletes this mobj, or sets state to `_crush` when there is not enough space in changing sector for this mobj. | ||
| - Doom logic (Lua scripts) also use this flag to give half ammo from items dropped by monsters. | ||
| - `__noblood` | ||
| - Bullet puffs on this mobj are spawned as is instead of having state set to `_pain`. | ||
| - `__corpse` | ||
| - This flag is automatically set on things with `__shootable` flag set when killed (health <= 0). | ||
| - Engine uses this flag set `_crush` state in changing sector when there is no room for this mobj. | ||
| - `__countKill` | ||
| - This mobj is counted as killable for level end screen. | ||
| - `__countItem` | ||
| - This mobj is counted as pickable for level end screen. | ||
| - `__notInDeathmatch` | ||
| - This mobj will not get spawned in deathmatch. Only affects map loading. | ||
| - `__isMonster` | ||
| - This mobj is marked as monster. This is purely informative, to be used for any checks you need. | ||
| - `__noRadiusDamage` | ||
| - This mobj is immune to `RadiusDamage`. | ||
| - `__noRadiusDmgZ` | ||
| - This mobj can be damaged by `RadiusDamage` at any Z distance. Only X and Y distance is checked. | ||
| - `__skullFly` | ||
| - This mobj will damage anything it will collide with. Then it will be stopped, and its state will be set to `_spawn`. | ||
| - Used on Doom lost souls. | ||
| - `__noZChange` | ||
| - This mobj has 3D thing collision disabled. | ||
| - Internaly set when `__missile` explodes. | ||
| - `__troughMobj` | ||
| - This mobj can't collide with other mobjs, and other mobjs can't collide with it. | ||
| - Only level geometry collision is enabled. | ||
| - `__fullVolume` | ||
| - This mobj has is's body sounds at full volume. | ||
| - Used on bosses in Doom. | ||
| - `__noDeathPull` | ||
| - There is a chance that death body will fall towards you instead of getting pushed by damage. This flag will disable it. | ||
| - `__invulnerable` | ||
| - This mobj can't be hurt. | ||
| - Used by invunlerability sphere in doom. | ||
| - `__wallBounce` | ||
| - Used on projectiles. Projectile will bounce off walls. | ||
| - `__mobjBounce` | ||
| - Used on projectiles. Projectile will bounce off other mobjs and do no damage to them. | ||
| - `__Monster` | ||
| - Flag combination of `__isMonster`, `__countKill`, `__solid` and `__shootable` | ||
| - `__Projectile` | ||
| - Flag combination of `__missile`, `__noBlockmap`, `__noGravity`, `__dropOff` and `__noZChange` | ||
|
|
||
| #### mobjtype | ||
| Mobjtype can contain these parameters. Default 0 / none, unless specified otherwise. | ||
| - `ednum` | ||
| - Doom editor number. This is ID for map editor. | ||
| - Integer. | ||
| - `health` | ||
| - Default health. Used on `__shootable` items. | ||
| - Integer. | ||
| - `reactionTime` | ||
| - Default monster reacion time. See mobj. | ||
| - Integer. | ||
| - `painChance` | ||
| - Used on `__shootable` items. Chance to set `_pain` animation, where 0 is 0% and 256 is 100% | ||
| - Integer. | ||
| - `speed` | ||
| - Speed for projectile spawning, or internal `a.Chase` movement code. | ||
| - Fixed point. | ||
| - `radius` | ||
| - Mobj size - radius. | ||
| - Fixed point. | ||
| - `height` | ||
| - Mobj size - height. | ||
| - Fixed point. | ||
| - `mass` | ||
| - Mobj mass. Used on `__shootable` items when taking damage. | ||
| - Can be used for any push strength calculation. | ||
| - Integer. | ||
| - `damage` | ||
| - Used on projectiles, or when `__skullFly` is set. | ||
| - Integer. | ||
| - `gravity` | ||
| - Gravity multiplier. Default is 1. | ||
| - Fixed point. | ||
| - `bounce` | ||
| - Bounce multiplier. If greater than 0, mobj can bounce of celings / floors. | ||
| - Eeach bounce momentnum is inverted and multiplied by this value. | ||
| - Fixed point. | ||
| - `viewz` | ||
| - Rendering height offset when viewing trough this mobj. | ||
| - Fixed point. | ||
| - `shootz` | ||
| - Shooting height offset. Used for `SpawnMissile` and `LineAttack` | ||
| - Fixed point. | ||
| - `bobz` | ||
| - Only usefull for player classes. Amount of screen bouncing while walking. | ||
| - Fixed point. | ||
| - `stepheight` | ||
| - Maximal height difference this mobj can step up. | ||
| - Fixed point, default 24. | ||
| - `species` | ||
| - If other than 0, this mobj is added into specified species cathegory. | ||
| - Same species can't hurt each other with **projectiles**. (Example: Imps won't hurt other imps, baron won't hurt knight.) | ||
| - Integer. | ||
| - `block` | ||
| - Blocking flags for this mobj. Only used when `__solid` is set. | ||
| - This is a bit mask of blocking flags. This allows for custom blocking configuration. | ||
| - Integer, 16 bit only. Default 0xFFFF (block everything). | ||
| - `pass` | ||
| - See blocking. If specified bit is set, this mobj won't be blocked by other mobjs, lines or 3D floors with same `block` bit set as it normally would. | ||
| - Integer, 16 bit only. | ||
| - `icon` | ||
| - Icon to be used for this mobj. Usage depends on mobj type, or can be used for custom Lua scripts. | ||
| - `addWeaponType` expects this to be set to valid icon. If not found or invalid, this weapon won't be listed in selection menu. | ||
| - `addKeyType` expects this to be set to valid icon. If not found or invalid, this key won't be listed in HUD even when picked up. | ||
| - String. Patch type lump in any of loaded WADs. | ||
| - `maxcount` | ||
| - Max count if used as inventory item. | ||
| - Integer. | ||
| - `translation` | ||
| - Custom translation table. If specified, all colors will be tranlsated trough this table when rendering sprites of this mobj. Used on colored blood. | ||
| - Translation table is 256 bytes long. Lump itself can be bigger and offset can be specified. Example: `BLOODMAP:1`. `BLOODMAP` is same as `BLOODMAP:0`. | ||
| - String. | ||
| - `render` | ||
| - Render style. For now there are only few supported internal styles. | ||
| - `!NORMAL` no effects. | ||
| - `!SHADOW` original doom invisibility fuzz effect. | ||
| - `!HOLEY0` every pixel is skipped. | ||
| - `!HOLEY1` every pixel is skipped, alternative version. | ||
| - String. | ||
| - `action` | ||
| - For now only used with `__special` flag. | ||
| - Function or nil. | ||
| - `arg` | ||
| - Argument for `action`. | ||
| - Anything Lua type. | ||
| - `action_crash` | ||
| - Function to call when mobj hits floor (falls down). Callback should be defined as `somecb(thing)`. Used on player for fall down sound effect. | ||
| - Function or nil. | ||
| - `seeSound` | ||
| - Played by internal `a.Look` when target is found. | ||
| - String. Sound lump from any WAD. | ||
| - `attackSound` | ||
| - Played by internal `a.Chase` when melee attacking. | ||
| - String. Sound lump from any WAD. | ||
| - `painSound` | ||
| - Not used by engine. Supposed to be used in `_pain` animation. | ||
| - String. Sound lump from any WAD. | ||
| - `activeSound` | ||
| - Randomly player by internal `a.Chase`. | ||
| - Played by player when pressing `use` key without anything to activate. | ||
| - String. Sound lump from any WAD. | ||
| - `deathSound` | ||
| - Not used by engine. Supposed to be used in `_death` animation. | ||
| - String. Sound lump from any WAD. | ||
| - `xdeathSound` | ||
| - Not used by engine. Supposed to be used in `_xdeath` animation. | ||
| - String. Sound lump from any WAD. | ||
| - `bounceSound` | ||
| - Played when thing is about to bounce. Used for `bounce`, `__wallBounce` and `__mobjBounce`. | ||
| - String. Sound lump from any WAD. | ||
| - `damageScale` | ||
| - Table of damage scalers. | ||
| - Table of Fixed point numbers. Range from -2.7 to 9.0 with 0.05 steps. Or `true` for instant kill. | ||
|
|
||
|
|
||
|
|
||
|
|
||
| ## To be continued ... | ||
| ##### It takes a while to make manual. | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|