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 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 in 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 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.
• Comminicate 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.

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: Why does the print function seem to do nothing?

A: It's 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.

Q: How do I print the "UnitDefs[unitDefID]" or "WeaponDefs[weaponDefID]" tables? "for k, v in ipairs(t) do print(k, v) end" doesn't 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.