Lua Function Library Access Table

Cours Lua Function Library Access Table, tutoriel & guide de travaux pratiques en pdf.

Virtual File System (VFS)

VFS Overview
Although Spring can access the filesystem directly (via os module) it is more common that you would want to access files included with your mod or Spring. Trouble is, most of these files are compressed into archives (.sdz/.sd7) so random access would generally be a difficult proceedure. Fortunately, the Spring Lua system automatically provides access to mod and base files via the VFS module.
The VFS module doesn’t simply open archives though. What it does is map your mod files, mod dependencies and Spring content onto a virtual file tree. All archives start from the ‘roots’ of the tree and share the same virtual space, meaning that if two or more archives contain the same resource file name the resources overlap and only one of the files will be retreived. Overlapping directories on the other hand are merged so the resulting virtual directory contains the contents of both. Here is an example of how this works:
This raises the question: If both archives have a texture1.png then which texture1.png is retreived via the VFS? The answer depends on the order the archives are loaded and the VFS mode (more on modes in a minute). Generally however, each archive loaded overrides any archives loaded _before_ it. The standard order of loading (from first to last) is:
1.) The main Spring/ game directory.
2.) The automatic dependencies springcontent.sdz and maphelper.sdz.
3.) Dependencies listed in your modinfo.lua (or modinfo.tdf), in the order listed.
4.) Your mod archive.

Loading lua files with VFS.Include()
VFS.Include(‘LuaUI/includes/filename.lua’, [env], [vfsmode])
This loads and compiles the lua code from a file in the VFS.
The path is relative to the main Spring directory.
Env can be a table or nil. This is used as the starting environment. If nil then the env will be _G (global environment)
The vfsmode parameter defines the order in which archives are searched (see VFS Modes below)
Using VFS.Include() with a custom environment
env = { table = table, string = string, …} VFS.Include(‘filename.lua’,env)
If the optional env argument is provided any non-local variables and functions defined in filename.lua are then accessable via env or _G. Vise-versa, any variables defined in env prior to passing to VFS.Include are available to code in the included file. Code running in filename.lua will see the contents of env in place of the normal _G environment.
Using the include() utility function (widgets only) include(‘filename.lua’)
The include() function is a thin wrapper around VFS.Include. It changes the search root to LuaUI/ or LuaUI/Headers/ for filenames ending in ‘.h.lua’.
VFS Modes
As stated earlier, the « stacking » behaviour of VFS is configurable at each call to a VFS retreival or listing function via a mode argument. All modes and their effects are listed in the reference section of this guide however as a rule a mode either restricts or prioritises files from certains types of archives (for example, VFS.RAW_FIRST will prioritise uncompressed files over compressed ones regardless of the order the archives were loaded.
Widget Config Data
Spring widgets have two callins that you can use to read/write a lua table to a shared config file. The configs are stored in [spring]/LuaUI/Config/[modshortname].lua which means widget configuration data is stored per-mod. If the names of the callins seem backwards to you try to remember that it is the widget handler getting or setting the configuration from your widget. Therefore GetConfigData is actually called to update the config file and SetConfigData is for setting values in the running widget.
GetConfigData
This optional callin is called when the widget handler wants to unload your widget and save its data. The return value is the data the handler (and therefore the config file) will get. In other words, the return value is saved to the config file.
SetConfigData
This is called when the widget handler loads or reloads your widget. The data argument passed in is the table that was stored in the config file (or an empty table).
—— — –
local my_var = ‘default value’
function widget:SetConfigData(data)
my_var = data.my_saved_var or my_var
end
—— — –
SOUNDS
Spring supports 3D sound, meaning you can ‘place’ a sound at a map position that gets louder when the camera is near it. You can also play global sounds that always play at the same volume regardless of the camera position.
PlaySoundFile() path is Spring/Sounds if you provide a filename with no path (eg. ‘Sound.wav’), otherwise it is relative to YourMod/ (eg. ‘Sounds/Custom/Sound.wav’)
UNITS
Team vs. Allied Units
Don’t get these confused. Your ‘team’ is all of the units directly under your control or part of an army when you are « comm sharing » (more than one player controlling the same army). Allied is when you are in a team with other players but each controls their own units (the units are different colors).
Unit IDs
Every individual unit in the game is given a unique integer ID. Many call-ins and unit functions use these IDs.
Unit Definitions (UnitDefs)
The engine automatically provides a read- only table called UnitDefs which is used to find a range of properties for each unit type. UnitDefs isn’t exactly a normal table because it uses a metatable for access to its properties. Looping over the properties requires using the pairs class method like so:
—— — –
for id,unitDef in pairs(UnitDefs) do
for name,param in unitDef:pairs() do
Spring.Echo(name,param)
end
end
—— — –
If you have a unitID and you want to get its unitdef use the following:
—— — –
local defID = Spring.GetUnitDefID(unitID)
local def = UnitDefs[ defID ]
–- same as above in 1 line:
local def = UnitDefs[ Spring.GetUnitDefID(unitID) ]
—— — –
Very useful is UnitDefs[i][« customParams »], since you can access any custom .FBI (unit file) param with it and use it in your Lua scripts. The descriptions of unit params can be found in the Reference Section of this manual.
Unit Animation / Scripting
About
Unit scripts replace the obsolete COB animation files. Unit scripts contain call-ins that are run when certain events happen to a unit. Events include the unit aiming, exploding, loading/unloading, etc. The primary purpose of catching these events is to perform animations, however you are not entirely limited to that.
Wiki Page: http://springrts.com/wiki/Animation-LuaScripting
Forum Thread: http://springrts.com/phpbb/viewtopic.php?f=12&t=20047
Example Scripts:
http://spring1944.svn.sourceforge.net/viewvc/spring1944/branches/MemberFolders/Tobi/S44LuaUn itScript.sdd/scripts/
Setup
Lua unit animation is implemented partially in the engine, and partially in a Lua gadget which is shipped with Spring in springcontent.sdz. By default, this gadget is not loaded, so a bit of setup is required to enable Lua unit scripts.
To enable Lua unit scripts, create a file LuaRules/Gadgets/unit_script.lua, and paste the following into it:
—— — –
— Enables Lua unit scripts by including the gadget from springcontent.sdz
— Uncomment to override the directory which is scanned for *.lua unit scripts. –UNITSCRIPT_DIR = « scripts/ »
return VFS.Include(« LuaGadgets/Gadgets/unit_script.lua »)
—— — –
Also, do check whether your LuaRules/system.lua is up to date, if you copied this verbatim into your game. (Must be newer then from 5 september 2009)
Now this is done, you can start putting *.lua files in your scripts/ folder.
Unit Categories
TODO
what is the difference between « TEDClass » and « Category »?
Unit Commands (Orders)
TODO
Forum Thread: http://springrts.com/phpbb/viewtopic.php?f=23&t=12020
WEAPONS
Weapon Definitions (WeaponDefs)
The properties of all weapons are passed to Lua in the table ‘WeaponDefs’. As with unitdefs each weapondef has a metatable so your must use the pairs() method to access them. The params are calculated from information stored in the mod. BA uses the file weapons.tdf and CA

INTRODUCTION
About this guide
What it covers
What it does not cover
License
GLOSSARY
CONVENTIONS
Filenames and Paths
Code
TUTORIALS
Creating a basic widget
GENERAL
Local variables
INPUT
Keyboard
Mouse
FILESYSTEM
Virtual File System (VFS)
Widget Config Data
SOUNDS
UNITS
Team vs. Allied Units
Unit IDs
Unit Definitions (UnitDefs)
Unit Animation / Scripting
Unit Categories
Unit Commands (Orders)
WEAPONS
Weapon Definitions (WeaponDefs)
Damage and Armor
LIBRARIES
Using built-in libraries
Custom libraries written in Lua
Custom libraries in other languages (advanced)
GADGETS (LuaRules)
Info
Synced versus unsynced code
Synced / Unsynced Protection
Transfering variables between synced and unsynced c
Call-ins
MAP SCRIPTS (LuaGaia)
WIDGETS (LuaUI)
Info
Installing widgets
Activating and deactivating widgets
Logging
Stop on errors
Debug commands
Reloading scripts
Bigger console
Advanced debugging
PERFORMANCE
REFERENCE
Lua Class Tree
Access Modes Table
Function Library Access Table
Debugging Functions
Unit States
Call-in Access Quick Reference
Widget Handler Actions List
Widget Call-in List
Gadget Handler Actions List
Gadget Call-in List
Call-in Functions
Unit Script Call-ins
Unit Script Call-outs
Lua FeatureDefs
Lua WeaponDefs
Lua UnitDefs
Game.armorTypes
Keysyms (Keyboard Input Codes)
VFS Modes
Official Lua documentation
CREDITS