Spring Lua Scripting Guide How to write your own Gadgets, Widgets, Map Scripts, Unit Scripts and AI for Spring using Lua interfaces Rough Draft - 23 Jan 2010 Table of Contents INTRODUCTION...........................................................................................................................2 About this guide..........................................................................................................................2 What it covers.............................................................................................................................2 What it does not cover................................................................................................................3 License........................................................................................................................................3 GLOSSARY.....................................................................................................................................3 CONVENTIONS.............................................................................................................................5 Filenames and Paths....................................................................................................................5 Code............................................................................................................................................5 TUTORIALS...................................................................................................................................5 Creating a basic widget...............................................................................................................5 GENERAL.......................................................................................................................................6 Local variables............................................................................................................................6 INPUT..............................................................................................................................................7 Keyboard.....................................................................................................................................7 Mouse..........................................................................................................................................7 FILESYSTEM.................................................................................................................................7 Virtual File System (VFS)...........................................................................................................7 Widget Config Data....................................................................................................................9 SOUNDS.........................................................................................................................................9 UNITS............................................................................................................................................10 Team vs. Allied Units................................................................................................................10 Unit IDs.....................................................................................................................................10 Unit Definitions (UnitDefs)......................................................................................................10 Unit Animation / Scripting........................................................................................................10 Unit Categories..........................................................................................................................11 Unit Commands (Orders)..........................................................................................................11 WEAPONS....................................................................................................................................11 Weapon Definitions (WeaponDefs)...........................................................................................11 Damage and Armor...................................................................................................................12 LIBRARIES...................................................................................................................................12 Using built-in libraries..............................................................................................................12 Custom libraries written in Lua................................................................................................12 Custom libraries in other languages (advanced).......................................................................13 GADGETS (LuaRules)..................................................................................................................13 Info............................................................................................................................................13 Synced versus unsynced code...................................................................................................13 Synced / Unsynced Protection..................................................................................................13 Transfering variables between synced and unsynced code.......................................................14 Call-ins......................................................................................................................................14 MAP SCRIPTS (LuaGaia).............................................................................................................14 WIDGETS (LuaUI).......................................................................................................................14 Info............................................................................................................................................14 Installing widgets......................................................................................................................15 Activating and deactivating widgets.........................................................................................15 DEBUGGING................................................................................................................................15 Logging.....................................................................................................................................15 Stop on errors............................................................................................................................15 Debug commands......................................................................................................................15 Reloading scripts.......................................................................................................................16 Bigger console...........................................................................................................................16 Advanced debugging.................................................................................................................16 PERFORMANCE..........................................................................................................................17 REFERENCE.................................................................................................................................18 Lua Class Tree...........................................................................................................................18 Access Modes Table..................................................................................................................18 Function Library Access Table..................................................................................................18 Debugging Functions................................................................................................................19 Unit States.................................................................................................................................19 Call-in Access Quick Reference...............................................................................................20 Widget Handler Actions List.....................................................................................................21 Widget Call-in List....................................................................................................................21 Gadget Handler Actions List.....................................................................................................23 Gadget Call-in List....................................................................................................................23 Call-in Functions.......................................................................................................................24 Unit Script Call-ins...................................................................................................................30 Unit Script Call-outs.................................................................................................................34 Lua FeatureDefs........................................................................................................................37 Lua WeaponDefs.......................................................................................................................38