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: Why should I learn Lua?

A: If you are a player, it can allow you to write widgets that automate tedious and mindless tasks, help you organize the information available to you in a a more effective way, or even let you overhaul the user interface. If you are a modder, it gives you the power to manipulate every aspect of the simluation except projectiles. Here are some of the things you can do:

• Create or destroy units.
• Transform units into other units.
• Change game rules.
• Give orders to units.
• Add new buttons to the unit orders panel.
• Manipulate unit physics.
• Upgrade units.
• Create a research system.
• Write a new user interface.
• Directly access OpenGL calls.
• Use your own shaders written in GLSL.
• Write your own custom model format.
• Use 3d textures, bump mapping, relief mapping, normal mapping, and more advanced graphic techniques.
• Use different levels of detail.
• Create single player missions.
• Implement a new resource system.
• Add fauna to a map.
• Create weather effects.
• Communicate with cob scripts.

The possibilites are mostly limited by your creativity.

Q: How do I open ".lua" files?

A: Notepad or any text editor are enough.

Q: Where can I find documentation?

A: There is incomplete documentation for LuaUI in "Spring/LuaUI/API.txt". "Spring/LuaUI/widgets.lua" and "<modname>/LuaRules/gadgets.lua" contain the call-ins and their arguments. You will have to read the Spring source to find the list of call-outs and their arguments. The source of the Lua API can be found here. LuaSyncedCtrl.cpp, LuaSyncedRead.cpp, LuaUnsyncedCtrl.cpp, LuaUnsyncedRead.cpp, LuaOpenGL.cpp and LuaSyncedMoveCtrl.cpp contain most call-outs. (L, 1) usually refers to the first argument, (L, 2) to the second, etc. If you don't know C++, understanding those files will require a little bit of guesswork, but it should'nt be hard. Note that not all calls are available to both LuaUI and LuaRules/LuaCob/LuaGaia.

And there are following wiki articles:

System
Lua_System

Const
Lua_ConstGame (holds game relevant constants)
Lua_ConstEngine (version & buildflags)
Lua_ConstPlatform (Current OS, video driver etc)
Lua_ConstCOB (COB, Explode, EmitSfx)
Lua_CMDs (documents all CMDs and CMDTYPEs)

Defs
Lua_UnitDefs
Lua_WeaponDefs
Lua_FeatureDefs

GameState
Lua_SyncedCtrl
Lua_SyncedRead
Lua_SaveLoad (engine-assisted Lua save/load)

Client
Lua_UnsyncedCtrl
Lua_UnsyncedRead
Lua_Lobby

OpenGL
Lua_OpenGL_Api
Lua_GLSL_Api (OpenGL Shading Language)
Lua_FBO_and_RBO (Framebuffer and Renderbuffer Objects)
Lua_UnitRendering (manage unit LODs and materials)
Lua_ConstGL (some OpenGL constants)
Lua_Fonts

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_MathExtra
Lua_Socket

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 Unknow Files 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 are a windows user, to see it, you need to first unzip this archive in your Spring directory, then open the command promt, navigate to your Spring directory, and run spring by typing "spring.exe | winpipe.exe". The stdout will appear in the command prompt window. You might want to run Spring in windowed mode so the command prompt is visible at all times.
(for the lazy ones: there is also a Spring.Echo(var1,var2,...) that prints into the ingame chatbox)

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, LuaCob and LuaGaia?

A: They were written by trepan.