Lua Scripting
From Aleph One Wiki
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 |
[edit] 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.
[edit] 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.
[edit] 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."
[edit] Embedding Lua Scripts
Lua scripts can be embedded into levels using a tool such as Atque. As the Lua scripters' guide says, embedded Lua scripts should only be used for map-specific functionality like custom teleporters, not gametype-specific changes. For example, it may be tempting to embed the latest version of Lua CTF into a CTF-only map. However, this would prevent players from using any updates to Lua CTF, as well as any other scripts designed for use on CTF maps.
[edit] Hosting Lua Scripts
Instead of choosing to embed a script, one may also distribute it externally of any map. Scripts should use the ".lua" extension.
External scripts can be used to enhance solo games. Solo scripts can be chosen in the Environment Preferences screen.
External scripts can also be used 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.
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, would cause the game to go OOS. As of 0.21 this bug no longer exists--scripts are truly embedded in the map and transmitted to players during net games.
Lua netscripts can 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. A temporary workaround is to select the netscript as a solo script before playing back the film.
[edit] The MML/Scripts folders
Aleph One will not try to parse scripts ending with ".lua" as MML, so it is safe to store them in the Scripts folder if they have this extension.
[edit] External Links
- You can find the Lua guide for the 0.21 (12/13) release here
- For the upcoming release, check the SVN 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))
