LunaCON User Manual -- The ``Lunatic Translator'' ================================================= Helixhorned :max-width: 56em :numbered: :icons: :conf-files: lunatic.conf Introduction ------------ The Lunatic build of EDuke32 completely reimplements the CON scripting language using the framework provided by its Lua interface. It does so by generating at start-up time one Lunatic module from all specified CON files and mutators.footnote:[In CON, the *`include`* directive amounts to merely textual inclusion, as is mutator appending with the `-mx` switch. All CON code is translated in one global context sharing the same namespace.] LunaCON implements nearly all of modern EDuke32 CON. One of its main aims is correctness in a broad sense, which encompasses multiple issues. * LunaCON more strictly validates the CON source at translation time. For example, using labels of mismatched type, such as a ++define++d number where an `move` is expected, issues an translation error. * Lexically and syntactically, LunaCON accepts only a subset of what the C-CON translator would pass through. This includes rejecting clearly erroneous code such as an unfinished directive at the end of a translation unit, but also code that implies ambiguities in the language. * On the run-time side, most checking is done by Lunatic. For example, indexing actor gamevars with out-of-bounds values produces an error that gets permanently displayed on the screen. Like with Lua code, the link:lunatic.html/#error[error] entry in the log then contains a traceback annotated with line numbers, making it possible for the CON coder to pinpoint its location and context. For these reasons, many existing CON mods and TCs are expected to need amendments in order to translate and/or run properly. This is generally a desired thing, since otherwise (most of the time, unintentional) misuse of the CON system may produce behavior that is either erratic, or appears to work on the surface but is hiding potential issues. .A warning The code generated by LunaCON is unsuitable for human consumption -- specifically, it should not be used as a base for new Lunatic code. Even though that code runs in Lunatic's protected user environment, it uses private interfaces that are subject to change in addition to the officially exposed and documented ones. Nevertheless, LunaCON is also available as a stand-alone Lua script. Primarily, this allows it to be used as a checking tool during CON development without the need to start EDuke32. Also, multiple CON codebases can be checked in a batch fashion for non-runtime problems. Usage ----- :LuaJIT: http://luajit.org :LPeg: http://www.inf.puc-rio.br/~roberto/lpeg/ The stand-alone LunaCON script, `lunacon.lua`, needs {LuaJIT}[LuaJIT] for execution and {LPeg}[LPeg] as additional dependency.footnote:[In order to translate some very large CON files, minor modifications have to be made to LuaJIT and LPeg. Refer to `lunatic/doc/how_to_build_lunatic.txt` in the EDuke32 source distribution for details.] The script also requires `con_lang.lua` to be present. It expects one or more names of root CON files together with any number of options, in any order (arguments starting with a dash are always interpreted as the latter). .Example usage ---------- luajit ./lunacon.lua -Wall mymod.con ---------- All arguments after a single `@` argument are taken to name _file lists_. These are files containing lines either * a file name of a root CON file which gets processed, or * a completely blank line or a line starting with `#`, both of which are ignored. Options ------- Most options documented in the following can also be passed to the Lunatic build of EDuke32. Options on the command line are processed in their given order, from left to right. Many of them can be negated by appeding `no-` after the ``option category letter'', for example `-Wno-not-redefined`. This index only lists the positive forms of each non-compound option and labels whether it is enabled or disabled by default. General options ~~~~~~~~~~~~~~~ ++-I__directory__++ (stand-alone only):: Specifies a _default directory_ to search for CON files as a last resort. This can be useful if mods expect part of their included files to reside inside GRP or ZIP containers, which the stand-alone translator cannot examine. This option can only be passed once. Warning options ~~~~~~~~~~~~~~~ These options affect on which occasions warnings, or in some cases, errors instead of warnings, are produced at translation time. `-Wall`:: Enables all warning and errors described in this subsection. `-Wbad-identifier` (default: off):: Warns whenever an identifier does not match `[A-Za-z_][A-Za-z0-9_]*`. In words, a ``good'' identifier is expected to start with a letter or an underscore, followed by zero or more letters, underscores, or digits. `-Wchained-loadactor` (default: on):: Warns whenever an `eventloadactor` block appears multiple times for the same tile number. In LunaCON, these are translated to an `EVENT_LOADACTOR` block that checks the tile number of its current actor. This event gets chained to the end of all preceding `EVENT_LOADACTOR` definitions, whereas with C-CON, a new `eventloadactor` block for the same tile number would override the existing one. `-Werror-bad-getactorvar` (default: off):: When enabled, produces an error whenever a global or per-player gamevar is attempted to be read using ++getactorvar++. Otherwise, a warning is emitted. In this case, the generated code is either a read of the (global) gamevar, or an access of the _per-player_ gamevar with an actor index, which is probably not what the coder intended. `-Wnot-redefined` (default: on):: Warns whenever a `define` directive was ignored because it attempted to redefine an already existing label to a different number. The label can exist either due to a previous `define`, or because it is a predefined label such as `NO`. `-Wnumber-conversion` (default: on):: Warns whenever a literal decimal number is encountered that is out of the range for a 32-bit integer, but inside that of an unsigned 32-bit integer. In this case, 2^32^ is subtracted from the number, producing a negative value without changing the bit representation. `-Wsystem-gamevar` (default: on):: Warns whenever the initial value of a system gamevar was overridden (by issuing `gamevar` at file scope), but the provided gamevar flags did not match those of the kept predefined ones. Code generation options ~~~~~~~~~~~~~~~~~~~~~~~ These options change the way certain CON code constructs are translated to Lua, set the output behavior of the stand-alone translator, or toggle various error conditions. `-fno` (stand-alone only):: Disable printing out the generated code and validating its syntax. `-fno=onlycheck` (stand-alone only):: Disable printing out the generated code, but validate whether it is syntactically legal Lua code. A failure of this check represents a bug with LunaCON itself. `-ferror-nostate` (default: on):: If enabled, an attempt to call a `state` that was not previously defined results in an error. Otherwise, a warning is issued and no code is generated for the `state` invocation. `-fplayervar` (default: on):: If enabled, per-player `gamevar` definitions really generate `con.playervar` initializations in the translated Lua code. Otherwise, per-player gamevars are treated as global gamevars, which can be useful for code that attempts to access them in contexts with no current player, yielding errors in Lunatic. `-ftrapv` (default: off):: Enable _trapping_ behavior for arithmetic operations whose result overflows the range of a signed 32-bit integer, i.e. generate an error on overflow. By default, overflow results in undefined behavior. Currently, only multiplication is handled. `-fwrapv` (default: off):: Enable _wrapping_ behavior for arithmetic operations whose result overflows the range of a signed 32-bit integer, i.e. after each operation, only the 32 lower bits of the result are kept. Currently, only multiplication is handled. Only one of `-ftrapv` or `-fwrapv` may be enabled at the same time. Differences from C-CON ---------------------- Despite the aim to provide as much compatibility to CON as possible where reasonable, a couple of its ``features'' -- some of which are coincidental -- cannot be implemented without unnaturally bending the implementation into shape. On the other hand, LunaCON sports some features that C-CON lacks, and does not exhibit some of its strange quirks or outright bugs. Syntactic and lexical changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The two command classes ^^^^^^^^^^^^^^^^^^^^^^^ LunaCON makes a clear distinction between ``outer'' commands that have an effect when translating a CON file (_directives_ such as `gamevar`, `definesound` or `spritenvg`) and ``inner'' commands meant to be effective at execution time of `actor`/`useractor`, `state`, `event` and `eventloadactor` blocks. This, issuing directives inside of these will make LunaCON reject the input file due to a syntax error, as will an attempt to use run-time commands such as `sizeat` at file scope. This strict behavior is one hand a consequence of how the LunaCON parser is structured, but on the other hand it may expose code for which the author misunderstood its meaning. An example for the first case would be a `gamevar` inside a block, which one mistakenly could take to have local scope. Gamevars in CON always have both global scope and lifetime though, so such a mental model on the coder's part may lead to unexpected bugs. In the second case, run-time commands at file scope are really translated to bytecode by C-CON, but as they reside outside of any block, they are never reached -- in other words, they are dead code. Currently, the only exception to this rule is that a `definequote` is allowed inside delimited blocks, which however does not change its semantics in any way: it still only defines the initial contents of a quote, and does not magically act like `redefinequote`. Ambiguous lexical elements ^^^^^^^^^^^^^^^^^^^^^^^^^^ LunaCON is fairly relaxed as to which character sequences constitute valid identifier names used for e.g. ++define++d labels or variables. It does so out of the necessity of supporting CON code found ``in the wild''. An identifier * must not be a token denoting a number, * must start with an _allowed first character_, * may contain any number of _allowed following characters_, where * allowed first characters are: letters, digits, and those in ```_*?`'' * allowed following characters are the same as allowed first characters, plus ``+++++'' and ``++-++'' . // ^ `+` and `-` Numbers can be written in either decimal or hexadecimal form, optionally prepended by a ``++-++'' sign. In the decimal case, the modulus of the number can be (lexically) any sequence of decimal digits, though there are restrictions on the permitted values.footnote:[Specifically, it is forbidden to write a number whose value falls outside the range [--2^31^-1 .. 2^32^--1\].] Hexadecimal number literals must be prefixed with `0x` or `0X`, and may optionally be suffixed with an `h`. The following constructions are not allowed, as they would create ambiguities with the definitions above: * A sequence of digits followed by letters to mean the the digits interpreted as a number, ignoring the trailing letters, e.g. `1267AT`. * A hexadecimal constant denoted using only a trailing `h`, for example `00000000h`. Miscellaneous ^^^^^^^^^^^^^ * Read array expressions as well as `switch` statements can be arbitrarily nested. // XXX: 'Read' is confusing. Need better wording. Run-time changes ~~~~~~~~~~~~~~~~ Behavior on error ^^^^^^^^^^^^^^^^^ As LunaCON is implemented by translating all given CON code to a Lunatic module, it is the Lunatic runtime that checks for proper use of its services at execution time and takes care of error handling and reporting. In Lua, an error link:lunatic.html/#nlcf[transfers control] to the end of the innermost ``protected'' call of a Lua chunk. This is in contrast to C-CON, which for some errors would print a message to the log, but otherwise would continue execution as if nothing had happened. In LunaCON, the code following an error is *not* executed. This way, the author of the CON code is notified of the presence of the bug, and by fixing it eventually obtains cleaner code. Quote behavior ^^^^^^^^^^^^^^ * The `redefinequote` command can be issued even if the given quote number has not been previously allocated using the `definequote` directive. This makes it possible to use a range of quote numbers ``on the fly'' without the need to declare their future use. Miscellaneous ^^^^^^^^^^^^^ * Issuing `break` inside a part of an event chain (defined using multiple `onevent` blocks for one event) does not abort the whole chain. Unavailable functionality ~~~~~~~~~~~~~~~~~~~~~~~~~ C-CON's `jump` and `getcurraddress` are not available and will not be implemented. The following commands are not yet implemented. Those highlighted in bold give errors, while the others merely warn either at translation or execution time. Parenthesized commands are of questionable use. Directives ^^^^^^^^^^ *`includedefault`*, `definecheat`, `setcfgname`, `setgamename`, (`precache`) Run-time commands ^^^^^^^^^^^^^^^^^ *`activatecheat`*, *`qstrncat`*, *`qsubstr`*, *`clearmapstate`*, `save`, `savenn`, *`lineintersect`*, *`rayintersect`*, *`sectorofwall`*, *`ssp`*. Additionally, various multiplayer-related commands either unconditionally return results as if no multiplayer game is in progress, or are non-functional for more than the first player. Also, some MP-related variables are merely predefined constants. Miscellaneous ^^^^^^^^^^^^^ * gamevar flags 1024 (```NODEFAULT`'') and 131072 (```NORESET`'') are not handled * mapstate handling in savegames is not yet implemented * not LunaCON-specific: `EVENT_INIT` is never reached as it runs before Lua state creation