LUA Implementation Limitations & Notes

Underworld's LUA VM is a modified version of the 2009 lufacode project. It implements a small subset of the LUA 5.1 specification.

There's a lot of caveats to be aware of when writing LUA code for it:

• A LUA global is registered under the name 'this' to point to the LUA object that is executing the code.
  • See GPS for a sample.
  • However, as this is just a global variable and not an actual language keyword, if your code creates classes, 'this' will still point to the entity.
• Equality operator on entities, maps, locations, and other Underworld classes should be generally avoided currently
  • This is because AS3 will return a new LUA table for each requested class. In future, these will be cached which should allow for accurate equality comparison. In the meanwhile, you can check locations equality by comparing if they both have the same RoomID and map.getName. Entity equality is trickier since many entities may share the same name.
• Most LUA library functions are not implemented
  • This includes the pairs function. Foreach is available, however. I've also implemented a simple table.keys function as a workaround (see the clone utility function that uses it)
• Sometimes LUFA returns an array with the first return parameter correct, but additional entries of garbage data. An example of this is the Weight Pendant.
  • This code did not work:

          io.write(GameText.parseText("You try to take off the pendant with " ..
             "your [[HANDS DESCRIPTION]], but it won't budge... it's " ..
             "cursed!\n\n"));
    

    It caused the correct line to be output, followed by each of the raw lines.
  • Changing this to the MainScreen caused only the first parameter to print, thus working correctly.

          MainScreen.addGameText(GameText.parseText("You try to take off the " ..
             "pendant with your [[HANDS DESCRIPTION]], but it won't budge... " ..
             "it's cursed!\n\n"));
    

  • Possibly something going on with the lua stack? If anyone wants to dive into LUFA and figure out what's going on, a patch is much appreciated!
• Inheritance, and most stuff with __index doesn't seem to work. However, someone with more LUA experience should verify this.
• Each entity currently runs in its own VM, and not in an OOP fashion.
  • It's not currently possible to make calls between custom functions on different objects.  May be able to come up with a hacky message-passing solution for this in future if it's desired. 
  • A better solution would be an object oriented programming design.  Unfortunately, LUFA doesn't currently support AS3 calling into a function on an object, nor does it support Inheritance, which makes it hard to have multiple objects running in the same VM.  This could potentially be mitigated by having function names of the format AuthorObjectFunction(), all running in the same VM.  However, in this first proof of concept of LUA modding, I'm going to defer in the hopes that someone wants to update LUFA and make it more OOP supporting so as to allow a future iteration of modding in the 'right' OOP way.  With each entity structured with OOP, all entities could run in the same VM and call each other's methods directly.
• The LUA integration/API may change in future. For this reason, it is highly suggested to post your LUA source code when you post entity mods. That way, someone might help update them if you're no longer around / don't want to. Also, then people can learn from each other and make better mods!
• If anyone wants to improve LUA language support, check out the lufacode source link above. After you've had a chance to download and play with it a bit, I can post my modified version as a starting point.
  • LUA wishlist:
    • Inheritance support
    • Ability to call functions on objects from AS3 so as to support an OOP design (see above rant)
    • In-game LUA compiler so as to simplify the luac -> base64 -> edit json -> execute loop
• If you encounter unexpected bugs, post on discord with a link to some sample code to reproduce the bug.
• If you run into a wall due to functions not being exposed to LUA, please leave feedback on what you would like to build with the mod API but can't due to current limitations! This helps inform future revisions of the mod API.