Lua Scripting
From AlephWiki
Lua is a lightweight computer programming language that the Aleph One team adopted for Aleph One. It can modify small things about the game, but usually in different ways from the Marathon Markup Language (MML). It has many more features that one would expect to find in a programming language: conditionals, variables, functions, etc.
Contents |
Capabilities
It can do things ranging from display elements (printing text on-screen, causing screen tints, changing the color and density of fog), to tampering with the in-game physics (allowing teleports from non-teleport polygons, activating and deactivating platforms, causing damage to players and monsters...). It can also alter monster AI behavior (enemy vs. friend, etc). Lua has been used for many things to date, including a prototype class-based Role-Playing Game (now defunct) and a modification to the engine's built-in Capture the Flag game type.
Caveats
What it can't do is replace the physics already defined in a Physics File. While some changes may be simulated--notably, changing how much damage a player inflicts or takes from projectiles, and other similar hacks--there is no way to replace weapons, to change projectile attributes outside of position and direction, etc. It is also incapable of file I/O, which was removed from the Aleph One's implementation of Lua for obvious security reasons.
Mistaken with MML
A common mistake is that Lua scripting can substitute sprites and textures in a way similar to MML, but "live" in-game. This is not possible. MML is not a dynamic language as Lua is; it can only create changes in the engine before a map loads, or during other points when the engine is not in a playing state. Lua, on the other had, works only during the times that the engine is "playing."
Embedding Lua Scripts
Scenario developers may choose to embed Lua scripts in their maps using embedded MML (see the Lua guide, below), but these developers should bear in mind that, as of the July 1, 2006 release, embedded MML and Lua are not transmitted from a host to his joiners; the game may become out-of-sync.
Hosting Lua Scripts
Instead of choosing to embed a script, one may also distribute it externally of any map. The script may have any extension, but the .txt or .lua extensions are the most common.
External scripts are for exclusive use in network games. The player must choose to gather a game, then access the "More Stuff" menu (by clicking on the "General" menu at the top of the gather screen). From there, the host chooses and enables the Lua script by browsing for it in the file system. The file browser is set by default to the user's personal preferences directory, but can be used to traverse the entire filesystem.
Once the player confirms the gathering settings, and other players join, he may start the game. Unlike embedded Lua, a script chosen explicitly in this manner is transmitted to the joiners, so it may be used in network games. Careless Lua scripting has been argued to be the cause of a lot of "out of sync" (OOS) problems. While the Lua itself has never been proven the culprit in some of these inexplicable "OOS" situations, it is entirely possible that a joiner had a map with embedded Lua selected in his Environment Preferences, which, if it is a different script from what the gatherer is using, will cause the game to go OOS.
Lua will cause films to go out of sync; while some scripts only affect graphics (printing text, etc), they too sometimes cause the film to stop following the game it originally recorded. One solution to films affected in this way is to keep a copy of the hosted map file with the script embedded in its resource fork, for the proper level that the film was recorded on, but even this had had limited success.
The MML/Scripts folders
Contrary to popular belief, Lua scripts should not go in the MML directory (which is also called the Scripts folder) that often accompanies the Aleph One directory (or its user preferences directory). The mistake comes from an argument about the name of said directory, in which the compromise was that both names were acceptable. The result is confusion. The Scripts and MML directories are for MML files only. If a Lua script is found in there, the engine will exit as soon as it starts, with parsing error. What is suggested instead is to create a Lua directory, which won't be parsed for MML, and which is a convenient collection place for your scripts.
External Links
- You can find the Lua guide for the 0.20 (6/21) release here
- For the upcoming release, check the CVS version here
- The Lua homepage
- A guide to programming in Lua (can be applied to Aleph One Lua scripting): Programming in Lua
- A complex example script: the CTF/Lua module. (Manual(dead)) (Script package(dead))
