Lua Beginners FAQ: Difference between revisions
dead link, tutorial links more clear |
Silentwings (talk | contribs) cleaned up lua beginners faq |
||
| Line 7: | Line 7: | ||
==Q: I'm interested in learning to use Lua with Spring. Where should I start?== | ==Q: I'm interested in learning to use Lua with Spring. Where should I start?== | ||
You can start by reading general Lua tutorials [http://lua-users.org/wiki/LuaTutorial here]. | |||
After that, you could look at the example widget [[Lua:Tutorial_GettingStarted|here]], and try to add some functionality of your own! | |||
==Q: Where can I find help?== | |||
You can find documentation on the [[Lua_Scripting|Lua_Scripting]] page. Discussion of lua coding takes place on the lobby in #moddev and #lua. | |||
==Q: How do I open ".lua" files?== | ==Q: How do I open ".lua" files?== | ||
Any text editor is enough. [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] is free, multi-platform and highly recommended. There are also IDEs able to work with Lua, such as Eclipse, if you look for them. | |||
| Line 30: | Line 29: | ||
==Q: What is the difference between a | ==Q: What is the difference between a unsynced and synced lua code?== | ||
Synced code is code that runs, identically and at the same time, on every connected client. In practice, this means code which controls the game state. Unsynced code is code that will run differently (or maybe not at all) on each connected client. Typically, this means the user interface. | |||
For example, lua code to make units explode if they fell down a cliff would need to be synced. But, code that warned a players when one of their own units was getting near a cliff edge, would need to be unsynced. | |||
==Q: What is the difference between LuaUI, LuaRules, widgets and gadgets?== | |||
There are two so-called [[Lua_System|Lua States]] that are primarily used by game developers. Inside each of these states, the developer can write addons, which are self-contained pieces of code. They are: | |||
* <b>LuaUI</b>: Used for unsynced GUI related code. Addons in here are often called widgets. Clients can (if the game permits it) control which widgets are running. Widgets contain only unsynced code. They can be bundled inside the game, or loaded from the users "Spring/LuaUI/Wigets" directory. | |||
* <b>LuaRules</b>: Addons in here are often called gadgets. Clients cannot choose which gadgets run. Gadgets can include both synced and unsynced code, and must be bundled inside the game. | |||
Intended for mappers, there is also LuaGaia, which behaves like LuaRules but is seperated from it. To see which of the lua states has access to which data/functionality, see [[Lua_System|Lua States]] and [[Lua:Callins]]. | |||
==Q: What can't Lua do in the current version of Spring?== | |||
Springs Lua interface is very powerful. To work out if some idea is possible you need to ask | |||
* When do I need the engine to tell me something has happened? Check against [[Lua:Callins|Callins]]. | |||
* What information will I need to know about the game state? Check against [[Lua_SyncedRead]] (synced) and [[Lua_UnsyncedRead]] (unsynced). | |||
* What do I then need to do about it? Check against [[Lua_SyncedCtrl]] (synced) and[[Lua_UnsyncedCtrl]] (unsynced). | |||
Sometimes you need special functionality, like disk access or OpenGL calls, in which case check against [[Lua_Scripting#Interfaces|Interfaces]]. | |||
For completeness, some examples of things you (currently) can't do: | |||
*control the ground LOS - but you can set the los status of units! | |||
*add custom parameters to CEG definitions. | |||
==Q: Where can I find/edit examples?== | |||
The best source of exmaples is inside games themselves, in the LuaUI/widgets and Luarules/gadgets directories. See [[Gamedev:PublicRepos]] for a list of repositories. | |||
To make your own widgets, simply individual .lua files into your Spring/LuaUI/widgets dir (create the dir if it is not present). Game repositories can be checked out into a folder named "SomeAwesomeGame.sdd", placed in your "/Spring/games" dir; this shoudl give a local copy of the game, recognized by Spring, where you can edit files. Make sure to check the licenses before doing this! | |||
==Q: | ==Q: Can I reload a script without restarting Spring?== | ||
Yes, you can type "/luaui reload" to reload widgets, and if you have "cheats" enabled you can also "/luarules reload". | |||
==Q: | ==Q: Why does the print function seem to do nothing?== | ||
Its output is displayed in stdout. If you have no easy way to see it, you can Spring.Echo("some text") which prints to the ingame chat and infolog.txt. | |||
[[Category: Lua]] | [[Category: Lua]] | ||
Revision as of 13:58, 13 August 2015
Development < Lua Scripting < Lua Beginners FAQ
This page only tries to answer general questions, for more specific Questions please ask in the forum.
Q: I'm interested in learning to use Lua with Spring. Where should I start?
You can start by reading general Lua tutorials here.
After that, you could look at the example widget here, and try to add some functionality of your own!
Q: Where can I find help?
You can find documentation on the Lua_Scripting page. Discussion of lua coding takes place on the lobby in #moddev and #lua.
Q: How do I open ".lua" files?
Any text editor is enough. Notepad++ is free, multi-platform and highly recommended. There are also IDEs able to work with Lua, such as Eclipse, if you look for them.
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 unsynced and synced lua code?
Synced code is code that runs, identically and at the same time, on every connected client. In practice, this means code which controls the game state. Unsynced code is code that will run differently (or maybe not at all) on each connected client. Typically, this means the user interface.
For example, lua code to make units explode if they fell down a cliff would need to be synced. But, code that warned a players when one of their own units was getting near a cliff edge, would need to be unsynced.
Q: What is the difference between LuaUI, LuaRules, widgets and gadgets?
There are two so-called Lua States that are primarily used by game developers. Inside each of these states, the developer can write addons, which are self-contained pieces of code. They are:
- LuaUI: Used for unsynced GUI related code. Addons in here are often called widgets. Clients can (if the game permits it) control which widgets are running. Widgets contain only unsynced code. They can be bundled inside the game, or loaded from the users "Spring/LuaUI/Wigets" directory.
- LuaRules: Addons in here are often called gadgets. Clients cannot choose which gadgets run. Gadgets can include both synced and unsynced code, and must be bundled inside the game.
Intended for mappers, there is also LuaGaia, which behaves like LuaRules but is seperated from it. To see which of the lua states has access to which data/functionality, see Lua States and Lua:Callins.
Q: What can't Lua do in the current version of Spring?
Springs Lua interface is very powerful. To work out if some idea is possible you need to ask
- When do I need the engine to tell me something has happened? Check against Callins.
- What information will I need to know about the game state? Check against Lua_SyncedRead (synced) and Lua_UnsyncedRead (unsynced).
- What do I then need to do about it? Check against Lua_SyncedCtrl (synced) andLua_UnsyncedCtrl (unsynced).
Sometimes you need special functionality, like disk access or OpenGL calls, in which case check against Interfaces.
For completeness, some examples of things you (currently) can't do:
- control the ground LOS - but you can set the los status of units!
- add custom parameters to CEG definitions.
Q: Where can I find/edit examples?
The best source of exmaples is inside games themselves, in the LuaUI/widgets and Luarules/gadgets directories. See Gamedev:PublicRepos for a list of repositories.
To make your own widgets, simply individual .lua files into your Spring/LuaUI/widgets dir (create the dir if it is not present). Game repositories can be checked out into a folder named "SomeAwesomeGame.sdd", placed in your "/Spring/games" dir; this shoudl give a local copy of the game, recognized by Spring, where you can edit files. Make sure to check the licenses before doing this!
Q: Can I reload a script without restarting Spring?
Yes, you can type "/luaui reload" to reload widgets, and if you have "cheats" enabled you can also "/luarules reload".
Q: Why does the print function seem to do nothing?
Its output is displayed in stdout. If you have no easy way to see it, you can Spring.Echo("some text") which prints to the ingame chat and infolog.txt.
