Home
DownloadDevelopment < Lua Scripting < Lua Beginners FAQ
Q: I'm interested in learning to use Lua with Spring. Where should I start?
A: You can start by reading the tutorial here. The "Introductory topics" and "Programming in Lua" sections should suffice, in the beginning. After that, you can try editing simple LuaUI widgets, like snd_chatterbox.
Q: Where can I find documentation?
A: "Spring/LuaUI/widgets.lua" and "<modname>/LuaRules/gadgets.lua" contain the call-ins and their arguments. Almost all call-outs are documented in the following wiki articles:
Game
Lua_ConstGame (holds game relevant constants & variables)
Lua_UnitDefs
Lua_WeaponDefs
Lua_FeatureDefs
Commands
Lua_CMDs (documents all CMDs and CMDTYPEs)
Game Dynamics
Lua_SyncedCtrl
Lua_SyncedRead
Local Dynamics
Lua_UnsyncedCtrl
Lua_UnsyncedRead
OpenGL
Lua_OpenGL_Api
Lua_GLSL_Api (OpenGL Shading Language)
Lua_FBO_and_RBO (Framebuffer and Renderbuffer Objects)
Lua_ConstGL (some OpenGL constants)
Lua_UnitRendering (manage unit LODs and materials)
Unit Physics
Lua_MoveCtrl (changes the physics of single units)
Lua_PathFinder
Engine
Lua_VFS (used to access files in the virtual filesystem, e.g. modfiles)
Lua_Scream
Lua_BitOps
Lua_SaveLoad (engine-assisted Lua save/load)
You can also consult the Spring source code.
Q: What can't Lua do in the current version of Spring?
A: You can't ...
- write to the metal/texture map.
- control the ground LOS (but you can set the los status of units!).
Q: How do I open ".lua" files?
A: Notepad or any text editor might be enough. If you are using windows and the text is all garbled, try a programmer's editor. Notepad++ can read Lua files with syntax highlighting.
Q: What is a call-in? And a call-out?
Call-ins are functions defined in your script that Spring calls when a determined event takes place. For example, the gadget:Initialize() call-in is run by Spring when the widget is loaded. Call-outs are functions defined in Spring you can run at whichever moment you desire. For example, when you call Spring.GetUnitTeam(unitID), the engine returns the teamID of the unit identified by "unitID".
Q: What is the difference between a widget and a gadget?
A: A widget is a Lua script that works with LuaUI. A gadget works with LuaRules, LuaCob or LuaGaia. Widgets allow you to customize your interface, and must be unsynced. They can be bundled with the mod or you can save them in your "Spring/LuaUI/Wigets" directory. Gadgets can be synced or unsynced. LuaRules and LuaCob gadgets are usually part of a mod. LuaGaia gadgets should be part of a map. Gadgets can contain both synced and unsynced code.
Q: Where can I find examples?
A: The "Spring/LuaUI/Widgets" directory contains many examples. More can be found at SpringFiles or in the Complete Annihilation mod.
Q: Can I reload a script without restarting Spring?
Yes, you can type "/luaui reload" or ".luarules reload". If you just need to check for syntax error, you can do it without having to load Spring by compiling the code. You can find a Lua compiler here. This is the download for Windows users..
Q: Why does the print function seem to do nothing?
A: Its output is displayed in stdout. If you have no easy way to see it, you can is Spring.Echo which prints to the ingame chat and infolog.txt.
Q: How do I print the "UnitDefs[unitDefID]" or "WeaponDefs[weaponDefID]" tables? "for k, v in ipairs(t) do print(k, v) end" does not behave as expected.
A: Use "for k,v in UnitDefs[unitDefID]:pairs() do print(k, v) end" instead.
Q: Where can I find help?
A: There is a Lua section in the Spring forums. Probably the most effective way, though, is to join #lua on the lobby.
Q: Who implemented LuaUI, LuaRules and LuaGaia?
A: They were written by trepan.