Lunatic User Manual =================== Helixhorned :max-width: 56em :numbered: :icons: Introduction ------------ Language -------- :Lua51: http://www.lua.org/about.html :Lua51Ref: http://www.lua.org/manual/5.1/ :PiL: http://www.lua.org/docs.html :LuaJIT: http://luajit.org :LuaJIText: http://luajit.org/extensions.html The base language for writing Lunatic user code is {Lua51}[Lua 5.1]. It is extensively documented in a {Lua51Ref}[Reference Manual], as well as described more broadly and accessibly in the {PiL}[Programming in Lua] books. // TODO: describe Lua a bit // TODO: give hints which PiL to read / how Because Lunatic is implemented using {LuaJIT}[LuaJIT], a just-in-time compiler for the Lua language, some {LuaJIText}[extensions] to the core language are automatically available. They may be used if no compatibility with Rio Lua 5.1 is desired. NOTE: The length operator (`#`) for table arguments should be taken to be defined by the http://www.lua.org/manual/5.2/manual.html#3.4.6[stricter wording of Lua 5.2]. Environment and Usage --------------------- Lunatic aims to provide a _safe_ scripting environment for EDuke32. Thus, not all of Lua's functionality is available in Lunatic, and some is slightly altered to play well with being embedded into a game, or to prevent commonly occurring mistakes. .Differences from default Lua environment - Creating new global variables in the global environment is forbidden. - In module context, referencing a non-existent variable (i.e. one that has value *nil*) is an error. EDuke32 can load multiple Lunatic _modules_ when starting up. This is always done after translating CON code to Lua and loading it. Such modules must be named `*.lua` (case-sensitive) and should be passed directly, without any option letters, at the command line. Directory separators must be forward slashes. .Invocation example ==================== `eduke32 -nologo MYTC.CON -mx addition.con test.lua weapons/nuke.lua -v1 -l1` ==================== Global Environment ------------------ When a Lua module is loaded, its global environment contains both selected functions from core Lua, as well as Lunatic's own pre-defined variables. These allow access and manipulation of EDuke32 engine and game data. [icon="icons/din_w_explosive.png"] CAUTION: If an attempt is made to create a new variable in the global environment or to assign any value to an existing variable, the behavior is undefined. Lua functions ~~~~~~~~~~~~~ The following base Lua functions are available in Lunatic's global environment: `assert`, *`error`*, `ipairs`, `pairs`, `pcall`, *`print`*, *`module`*, `next`, *`require`*, `select`, `tostring`, `tonumber`, `type`, `unpack`, `xpcall`. The bold ones add functionality or behave slightly differently, described below. Additionally, `printf` is provided for convenience. *`error(message [, level])`*:: In Lunatic, errors also print to the on-screen display (OSD) and are written to the log (unless a maximum error count is exceeded). These also have a _backtrace_ added. Additionally, errors not caught by a `pcall` result a permanent message to appear on the screen, containing the source file name and line number. *`print(...)`*:: The messages are printed to the OSD and the log. Color codes available in EDuke32 (e.g. `^10` for dark red) are interpreted. *`printf(fmt, ...)`*:: Calls `print` with the result of `string.format(fmt, ...)`. Writing and using modules ~~~~~~~~~~~~~~~~~~~~~~~~~ In Lunatic, like in Lua, a _module_ is a conceptually a sort of package that unites related bits of functionality. Language-wise, it is simply a Lua table holding its contents, as described and motivated at length in _Programming in Lua_. The ``creation'' and ``usage'' sides of the modularity concept are reflected in two functions known from Lua 5.1, `module` and `require`. The former is a convenient way of separating the _import_, potential _gamevar_, and main body sections when writing a package. It is not required to use `module`, but it is the only way to declare _game variables_, that is, variables that EDuke32 stores within savegames, recreating their values when they are loaded. The other side of the coin, `require`, is also used like in Lua: ``including'' a named module is requested by passing its name to `require`. This searches for a matching module, loading and running it if the request happens for the first time. ==== The function `require(modname, ...)` Attempts to find a Lua or Lunatic module named `modname`. The name can refer to a _built-in_ module, of which the following ones are allowed: * The http://bitop.luajit.org/[`bit`] module for bitwise operations * `math`, `string` and `table`, base modules from Lua * Lua's `os` module, containing a single function, `clock`. Like the <>, it should only be used to profile bits of code. * Modules provided by Lunatic, which will be described in <>. If `modname` does not designate a built-in module, Lunatic first replaces every dot contained in it with a directory separator. Then, it looks for a file with that base name suffixed with `.lua` in the EDuke32 search path (virtual file system, GRP, ZIP). Using directory separators directly is not allowed. The loaded module is ``protected'' so that write accesses to its table yield errors. Unlike Lua, our `module` does not return *true* when a module is ++require++d that has not yet finished loading (that is, the inclusion chain contains a loop). Instead, an error is raised. Issuing `require` for `'end_gamevars'` has a special meaning that is described below. ==== The `module()` function Initiates a _module_ environment by creating a new empty table and setting it as the global environment of the chunk. Unlike Lua 5.1, our `module` takes neither a name argument nor ``option'' varargs. A Lunatic file may have at most one call to `module`, which (if there is one) *must* be called at file scope. ===== Game variables Lunatic has a special mechanism to mark variables that represent some ``persistent'' state and whose values should be stored in savegames. If such variables are desired, they must initialized between the `module` call in a Lua file and a closing `require("end_gamevars")`. These variables may also be *`local`*. [icon="icons/din_w_collapse.png"] CAUTION: A game variable must contain a non-nil value at any time. Otherwise, the behavior is undefined. // TODO: when are they restored, example // TODO: the rest The ``gv'' variable ~~~~~~~~~~~~~~~~~~~ Some constants, global C variables, and miscellaneous functions and structures are accessible via the global `gv` variable. Constants ^^^^^^^^^ `gv.MAXSECTORS`, `gv.MAXWALLS`, `gv.MAXSPRITES`:: The hard engine limits on the number of sectors, walls, and sprites. These constants *must* be used instead of any literal numeric values because they can change depending on how EDuke32 was configured and built. ////////// `gv.MAXSTATUS`, `gv.MAXTILES`, `gv.MAXSPRITESONSCREEN`:: TODO `gv.MAXBUNCHES`, `gv.CEILING`, `gv.FLOOR`:: TODO ////////// `gv.CLIPMASK0`:: A clipping (collision detection) mask specifying to consider only _blocking_ walls and sprites. `gv.CLIPMASK1`:: A clipping (collision detection) mask specifying to consider only _hitscan sensitive_ walls and sprites. // Game-side `gv.*` inventory indices:: `GET_STEROIDS`, `GET_SHIELD`, `GET_SCUBA`, `GET_HOLODUKE`, `GET_JETPACK`, `GET_DUMMY1`, `GET_ACCESS`, `GET_HEATS`, `GET_DUMMY2`, `GET_FIRSTAID`, `GET_BOOTS`. `GET_MAX`. `gv.*` weapon indices:: `KNEE_WEAPON`, `PISTOL_WEAPON`, `SHOTGUN_WEAPON`, `CHAINGUN_WEAPON`, `RPG_WEAPON`, `HANDBOMB_WEAPON`, `SHRINKER_WEAPON`, `DEVISTATOR_WEAPON`, `TRIPBOMB_WEAPON`, `FREEZE_WEAPON`, `HANDREMOTE_WEAPON`, `GROW_WEAPON`. `MAX_WEAPONS`. // TODO: the others, like EVENT_*. ////////// [[gv_STAT]] `gv.*` sprite status numbers:: `STAT_DEFAULT`, `STAT_ACTOR`, `STAT_ZOMBIEACTOR`, `STAT_EFFECTOR`, `STAT_PROJECTILE`, `STAT_MISC`, `STAT_STANDABLE`, `STAT_LOCATOR`, `STAT_ACTIVATOR`, `STAT_TRANSPORT`, `STAT_PLAYER`, `STAT_FX`, `STAT_FALLER`, `STAT_DUMMYPLAYER`, `STAT_LIGHT`. ////////// ////////// `gv.MAXPLAYERS`:: TODO ////////// Variables ^^^^^^^^^ `gv.totalclock` (read-only):: The current value of the engine timer that increments at a rate of 120 per second under default settings. (Thus, one game tic corresponds to four `totalclock` increments.) When staying within one ``mode'' such as in-menu or in-game, it is guaranteed to not decrease. However, going from one mode to another may produce discontinuities. `gv.screenpeek` (read-only):: The player index of the player from whose position the scene is being displayed. `gv.hudweap`:: A structure containing information about the currently displayed HUD weapon. Contains the following members, which are set from C before entering `EVENT_DISPLAYWEAPONS`: `cur`, `count`, `gunposx`, `gunposy`, `lookhalfang`, `lookhoriz`, `shade`. // TODO: describe // TODO: g_logoFlags, g_RETURN? // TODO: structures such as .cam Functions ^^^^^^^^^ [[timing_funcs]] `gv.getticks()`, `gv.gethiticksms()`:: Each of these functions return a number that increases at a rate of 1 per millisecond. Their only intended application is to profile bits of code; they should not be used to control the game world. The two functions differ in their precision: `getticks()` always returns integral values, while the result of `gethiticksms()` also has an unspecified precision in the fractional part. (It can be expected to give a time precision of at least one microsecond.) `gv.doQuake(gametics [, snd])`:: Requests from the game to perform the ``quake'' effect that shakes the screen etc. for the next `gametics` game tics. If a sound index `snd` is passed, also start playing that sound. // TODO: Play sound how? ("globalsound") ////////// `gv.currentEpisode()`:: TODO `gv.currentLevel()`:: TODO `gv.currentRenderMode()`:: TODO ////////// Lunatic structures ~~~~~~~~~~~~~~~~~~ The primary means of effecting game state in Lunatic is via _composite variables_ defined in the global environment. These provide direct, but restricted, access to C _structure arrays_ of the EDuke32 engine or game. [icon="icons/din_w_toxic.png"] CAUTION: If an attempt is made to access any composite variable outside of event or actor code, the behavior is undefined. Composite variables can be used in various ways. All of them allow indexing with an integer value from `0` to some maximum (sometimes the size of the array minus one, but occasionally less). For example, the code snippet ---------- local sec = sector[0] ---------- gets a _reference_ to the first sector of the loaded map into the local `sec`. This reference can then be used to both read and write its members. Various structures also provide _methods_ in Lunatic to modify their state, usable with Lua's `v:func(args...)` syntax. Building on the previous example, ---------- local cz = sec:ceilingzat(wall[sec.wallptr]) ---------- would get into `cz` the ceiling z position at the first sector's first wall-point. Finally, some composite variables offer _static data_, which can contain functions or tables of constants. These are accessed using the dot notation on the composite variable, *not* its constituents. For instance, the following can be used to change the sector number of the sprite with index `i` manually: ---------- sprite.changesect(i, sectnum) ---------- Type of structure members ^^^^^^^^^^^^^^^^^^^^^^^^^ In the following, some structure members will be annotated with their _integer type_, for example _`i16`_ or _`u8`_. The letter _`i`_ denotes a _signed_ integer whereas a _`u`_ designates an _unsigned_ one. The number following that letter indicates the _bit width_ of that integer. .Representable values * A member of signed integer type and bit width _B_ can contain any whole number from --2^_B_--1^ to 2^_B_--1^--1. + * A member of unsigned integer type and bit width _B_ can contain any whole number from 0 to 2^_B_^--1. .Assignment * If an assignment to a member having signed integer type is made, the ``right-hand side'' value must be a number in the closed interval [--2^31^ .. 2^31^--1]. * If an assignment to a member having unsigned integer type and bit width _B_ is made, the ``right-hand side'' value must be in the closed interval [--2^31^ .. 2^31^-1] if _B_ is less than 32, or in [0 .. 2^32^-1] otherwise. * If the appropriate requirements hold, an assignment from a Lua number to a member having integer type begins by discarding the fractional part (``truncation''). Otherwise, the behavior is undefined. + * If the truncated value is outside the range of representable values for the corresponding integer type of bit width _B_, the final value is obtained by successively adding or subtracting 2^B^, until the value falls inside that range. .Examples 1. Assignments to _`u8`_ member `visibility` * `sec.visibility=3.94159` results the member to contain the integer `3` * `sec.visibility=1/0` is undefined (attempt to assign an infinity) * `sec.visibility=-1` results the member to contain the integer `255` 2. Assignments to _`i16`_ member `lotag` * `sec.lotag=32768` results the member to contain `-32768` * `sec.lotag=2^32` is undefined Bit fields ^^^^^^^^^^ Some structures contain members that represent a collection of _flags_, for example `sprite[].cstat` or `actor[].flags`. These flags can be toggled by setting or clearing their respective _bits_ (integer numbers that are powers of two). For convenience, Lunatic provides alternative names for some of these members, together with methods to examine or modify any number of bits of such a member in one expression. Whenever there is such an alternative name available, it is declared as having type _`bitfield`_ in the listings of the structure members. ===== methods of the _`bitfield`_ type `bf:set(bits)`:: _Sets_ (toggles to an ``on'' state in a boolean sense) those bits of `bf` that are set in `bits`. `bf:clear(bits)`:: _Clears_ (toggles to an ``off'' state in a boolean sense) those bits of `bf` that are set in `bits`. `bf:flip(bits)`:: _Flips_ those bits of `bf` that are set in `bits`, that is, reverse their boolean state. `bf:test(bits)`:: Returns a boolean that indicates whether `bf` has *any* of the bits set in `bits` set. .Examples ========== After the lines setting sprite `i` to 33% translucent and blocking, ---------- local CS = sprite.CSTAT local spr = sprite[i] spr.cstat = CS.TRANS1 + CS.BLOCK ---------- one could proceed as follows for the sake of example: * `spr.cstatbits:set(CS.TRANS2)`, make the sprite 66% translucent now * `spr.cstatbits:flip(CS.BLOCK + CS.HITSCAN)`, make it hitscan-sensitive but not blocking * `spr.cstatbits:test(CS.FLIP_BITMASK)`, check whether it is flipped (no) ========== Engine-side ^^^^^^^^^^^ The composite variables described in this subsection provide access to engine-side structures. The first three, `sector`, `wall`, and `sprite`, are part of a BUILD map saved to disk. The other ones only exist when running the game. ===== `sector` Accessible from `0` to `gv.numsectors-1`. Each element has the following members: `wallptr`, `wallnum` (read-only):: The index of the sector's first wall and the number of walls in the sector, respectively. _`u8`_ `visibility`:: Determines the amount of distance fading. In the range [`0` .. `239`], the ``darkening'' increases with rising values. The range [`240` .. `255`] should be thought of as [`-16` .. `-1`]. // TODO: better wording? _`i16`_ `lotag`, `hitag`, `extra`:: General-purpose ``tags'' provided for game programming. They may be used by various EDuke32 sector effects, so it's not recommended to use them in scripting code. In addition to the members described above, each sector has two sets of members for its ceiling and floor. A sector reference can be indexed with the strings `ceiling` or `floor` to get references to the respective ``parts'', or one can access the consituent members by prefixing `ceiling` or `floor` to the base member names given below. .Different ways of accessing the same member ========== After the code lines ---------- local sec = sector[0] local ceil = sec.ceiling ---------- the following expressions all denote the same location, both if read or written to: `sec.ceilingheinum`, `ceil.heinum`, `sector[0].ceiling.heinum`, `sector[0].ceilingheinum`. ========== In the following, `cf` will stand for a ceiling or floor reference, while `sec` will label a sector reference. `cf.picnum` (read-only):: The tile number of the ceiling or floor. [[cf_stat]] _`u16`_ `cf.stat`, _`bitfield`_ `cf.statbits`:: A bit field holding various flags about how the ceiling or floor shoud be displayed, how collision detection should be handled, etc. The <> object should be used to obtain the values for applicable flags. _`i16`_ `cf.heinum`:: If `cf.stat` has bit `sector.STAT.SLOPE` set, the tangent of the slope angle multiplied by 4096. Positive values make the ceiling or floor slope towards the floor, negative ones slope upward. _`i32`_ `cf.z`:: The BUILD z coordinate (scaled by 16 compared to the x and y directions) of the pivoting line of the ceiling or floor. `cf.bunch` (read-only):: The ``bunch'' number of the ceiling or floor used for True Room over Room. One bunch comprises _N_ ceilings and _M_ floors (_N_ ≥ 1, _M_ ≥ 1) such that each set covers the same planar, connected area. _`i8`_ `cf.shade`:: The shade of the ceiling or floor. Larger values mean a more darker appearance. _`u8`_ `cf.pal`:: The ``palette swap'' index of the ceiling or floor. _`u8`_ `cf.xpanning`, `cf.ypanning`:: The panning values of the ceiling or floor. One full cycle is covered by values from `0` to `255`. ===== `sector` methods `sec:set_ceilingpicnum(tilenum)`, `sec:set_floorpicnum(tilenum)`:: Set the tile number of the ceiling or floor. `sec:ceilingzat(pos)`, `sec:floorzat(pos)`:: Return the z coordinate of sector `sec`'s ceiling or floor at position `pos`, which can be anything indexable with the strings `x` and `y`. ////////// `zrangeat(pos, walldist, cliptype)`:: TODO ////////// ===== `sector` static data [[sector_STAT]] `sector.STAT`:: Provides a mapping of symbolic names to values applicable to <>. These name single bits: `PARALLAX`, `SLOPE`, `SWAPXY`, `SMOOSH`, `FLIPX`, `FLIPY`, `RELATIVE`, `MASK`, `TRANS1`, `TRANS2`, `BLOCK`, `HITSCAN`, while the following denote _bit masks_: `FLIP_BITMASK`, `ORIENT_BITMASK`, `TRANS_BITMASK`. ''' ===== `wall` Accessible from `0` to `gv.numwalls-1`. Each element has the following members: `x`, `y`:: The 2D coordinates or this wall point. Should not be set directly. `point2` (read-only):: The index of the second wall point. `nextwall`, `nextsector` (read-only):: If the wall is ``white'', these members equal `-1`. For ``red'' walls, they contain the wall and sector indices (respectively) of the wall on the other side. `upwall`, `dnwall` (read-only):: For walls constrained by TROR extension, the upper and lower neighbor walls, respectively. Any of them may be `-1`, meaning that the wall is not attached to a neighbor in this direction. [[wall_cstat]] _`u16`_ `cstat`, _`bitfield`_ `cstatbits`:: A bit field holding various flags about how the wall shoud be displayed, how collision detection should be handled, etc. The <> object should be used to obtain the values for applicable flags. [[wall_picnum]]`picnum` (read-only):: The tile number of the non-masked portion of the wall. If `wall.CSTAT.BOTTOMSWAP` is set on this wall's `.cstat`, it is only displayed in the upper portion. (The lower portion takes it from this wall's `.nextwall` then; this will be labeled _use-other-bottom_ in the following.) `overpicnum` (read-only):: The tile number of the masked portion of the wall, i.e. that which is drawn if this wall's `.cstat` has bit `wall.CSTAT.MASK` or `wall.CSTAT.ONEWAY` set. _`i8`_ `shade` (<>):: The shade of the wall for both non-masked and masked portions. Larger values mean a more darker appearance. _`u8`_ `pal` (<>):: The ``palette swap'' index of the wall. _`u8`_ `xrepeat`, `yrepeat`:: Values that are proportional to the number of times that the wall's texture repeats in each direction per given wall length/height. A value of `8` renders 64 texels across a length of 1024 x/y map units or a height of 16384 z units. _`u8`_ `xpanning`, `ypanning` (<>):: The panning values of both masked and non-masked portions of the wall. One full cycle is covered by values from `0` to `255`. _`i16`_ `lotag`, `hitag`, `extra`:: General-purpose ``tags'' provided for game programming. They may be used by various EDuke32 effects internally, so it is advised to do some research before claiming them for oneself. ===== `wall` methods `wal:set_picnum(tilenum)`, `wal:set_overpicnum(tilenum)`:: Set the tile number of the wall or its masked portion. ===== `wall` static functions `wall.dragto(i, pos)`:: Set the position of the point of the wall with index `i` to `pos`, which can be anything indexable with `x` and `y`. This function is the preferred way of changing wall coordinates, since it takes care to reposition dependent wall points, too. ===== `wall` static data [[wall_CSTAT]] `wall.CSTAT`:: Provides a mapping of symbolic names to values applicable to <>. These name single bits: `BLOCK`, `BOTTOMSWAP`, `ALIGNBOTTOM`, `FLIPX`, `MASK`, `ONEWAY`, `HITSCAN`, `TRANS1`, `FLIPY`, `TRANS2`, while the following denote _bit masks_: `FLIP_BITMASK`, `TRANS_BITMASK`. ''' ===== `sprite` The `sprite` composite is accessible with indices from `0` to `gv.MAXSPRITES-1`, but accesses to sprites that do not exist in the game world have no meaning. Each element has the following members: `x`, `y`, `z`:: The BUILD coordinates of the sprite. It is not advisable to set these directly. ////////// _`i16`_ `ang`:: TODO (make set_ang() out of that which always ANDs with 2047?) ////////// [[sprite_cstat]] _`u16`_ `cstat`, _`bitfield`_ `cstatbits`:: A bit field holding various flags about how the sprite shoud be displayed, how collision detection should be handled, etc. The <> object should be used to obtain the values for applicable flags. `picnum` (read-only):: The tile number of the sprite, also used to determine which _actor_ code is run if this sprite has a `statnum` of `actor.STAT.ACTOR`. _`i8`_ `shade`:: The shade of the sprite. This may not be the shade that this sprite is ultimately drawn with, though. _`u8`_ `pal`:: The ``palette swap'' index of the sprite. This may not be the palette swap that this sprite is ultimately drawn with, though. _`u8`_ `clipdist`:: If this sprite is _view-aligned_, controls the distance at which another moving object is considered to be in collision with this *stationary* sprite. (It does not control the inverse case.) More precisely, it designates half the side-length of the bounding square divided by 4. Thus, a value of `255` keeps moving objects away from this one at a max-norm distance footnote:[The max-norm distance between points _p_~1~=(x~1~, y~1~) and _p_~2~=(x~2~, y~2~) is defined as max(abs(x~2~ -- x~1~), abs(y~2~ -- y~1~)).] of at least 1020 BUILD x/y units. _`u8`_ `xrepeat`, `yrepeat`:: The size of the sprite in each dimension. For wall- and floor- aligned sprites, a value of `64` means a width of 16 x/y BUILD units or a height of 256 z BUILD units per texel. `sectnum` (read-only):: The index of the sector that this sprite is currently contained in. `statnum` (read-only):: The current _status number_ of this sprite. Applicable values are contained in `actor.STAT`. // <>. `owner` (read-only):: The index of the sprite from which this sprite was spawned. If this sprite is not a ``child'' of another one, then `owner` is the index of this sprite itself. //Occasionally, game effects may use this member for their particular purposes, //so research is recommended before claiming it for oneself. _`i16`_ `xvel`, `zvel`:: For _actors_ and other moving sprite types, the horizontal and vertical components of the current velocity. //It is not advisable to set these directly //unless one knows how they are processed. //`yvel` (read-only):: //A general-purpose member of which the game has exclusive control. _`i16`_ `lotag`, `hitag`, `extra`:: General-purpose ``tags'' provided for game programming. They may be used by hard-coded actors internally, so it is advised to do some research before claiming them for oneself. ===== `sprite` methods `spr:set_picnum(tilenum)`:: Set the tile number of the sprite. ===== `sprite` overridden operators `spr^zofs`:: Returns an `xmath.vec3` object that is the position of this sprite, diminished by `zofs` in the z direction. Because in BUILD, z coordinates increase toward the floor, the `^` can be thought of as ``raise the sprite by `zofs` units''. ===== `sprite` static data [[sprite_CSTAT]] `sprite.CSTAT`:: Provides a mapping of symbolic names to values applicable to <>. These name single bits: `BLOCK`, `TRANS1`, `XFLIP`, `YFLIP`, `ALIGNWALL`, `ALIGNFLOOR`, `ONESIDE`, `CENTER`, `HITSCAN`, `TRANS2`, while the following denote _bit masks_: `ALIGN_BITMASK`, `TRANS_BITMASK`. ===== `spriteext` ===== `atsprite` Game-side ^^^^^^^^^ `actor`:: `player`:: `projectile`:: `g_tile`:: TODO Lunatic functions ~~~~~~~~~~~~~~~~~ Engine-side ^^^^^^^^^^^ cansee hitscan inside neartag sectorsofbunch spritesofsect spritesofstat updatesector updatesectorbreadth updatesectorz wallsofsect Game-side ^^^^^^^^^ `gameactor`:: `gameevent`:: TODO [[ext_api]] Extended API (Lunatic modules) ------------------------------