Lua-LuaCOB

2008-11-12T14:13:01Z

Brathering: a small extra note to use LuaRules/main.lua instead of LuaCOB/main.lua. I've needed some hours to find this error in my tests.

'''NOTE LuaCob will merged with LuaRules in 76b2'''

=Introduction=
To use Lua code in your BOS/COB files, you can either include the gadgetHandler (include it in the mod, see the CA mod or include it from the springcontent.sdz) or you create your own enviroment:
*create a mod-level directory LuaCOB/,
*make a LuaCOB/main.lua file. (Note: it's LuaRules/main.lua now)
Any additional files need to be included with a

include("LuaCOB/additional_file.lua" [, fenvTable])

If you don't know what a fenvTable is, don't worry, you probably don't need it anyway.
More information can be found on [http://www.lua.org the Lua site]. It it highly recommended to read the manual and the tutorials found there. Note that Spring 76b1 used Lua version is 5.1.2, so please take note which version of the manual you're reading.

Also note that the usual Lua functions for executing code in other files (<tt>dofiles()</tt>, <tt>require()</tt>) are disabled for technical reasons.

=Interfacing COB->Lua=
All Lua functions that are called by COB are given three parameters:
*unitID - ID of the unit calling the function,
*unitDefID - ID of the unitDef,
*teamID - self-explanatory.
You can call scripts with any (enough for all practical purpouses) amount of additional arguments.

Example functions:

function GetNearestEnemy(unitID, unitDefID, teamID, radius)
local px, py, pz = Spring.GetUnitPosition(unitID)
if (px == nil) then
return
end

local nearDist = 1.0e20
local nearUnit
local units = Spring.GetUnitsInCylinder(px, pz, radius)
for _,enemyID in ipairs(units) do
if (not Sim.IsUnitAllied(enemyID)) then
local ex, ey, ez = Spring.GetUnitPosition(enemyID)
if (ex ~= nil) then
local dx, dy, dz = (px - ex), (py - ey), (pz - ez)
local dist = (dx * dx) + (dy * dy) + (dz + dz)
if (dist < nearDist) then
nearUnit = enemyID
nearDist = dist
end
end
end
end

if (nearUnit == nil) then
return -1
else
return nearUnit
end
end

Please note that returning tables doesn't currently work as one could expect. ''(Description what it does here)'' If you want to return multiple values from a table, you need to do it like this:

function ReturnSomeValues(u, ud, t, ...)
return arg[1], arg[2], arg[3] -- instead of arg
end

==Calling Lua from BOS==
To call a Lua function from BOS code, you need to declare it first:
// BOS
lua_MyFunction() { return 0; }
Then just call this script. The <tt>lua_</tt> prefix does its magic and routes the call to Lua code instead of calling the usual BOS code. Note that arguments don't matter, they are passed anyway:
call-script lua_MyFunction(arg1, arg2);
===Getting output===
If you wish to print out some debugging info, please note that <tt>print</tt> and <tt>io.write</tt> don't quite work in Windows versions of Spring, since stdout isn't availible (or is well-hidden.) Use <tt>Spring.Echo("a string")</tt>, this will print a message to the Spring console and into the infolog.

===LUA0..9===
// the GET/SET constants
#define LUA0 110
#define LUA1 111
#define LUA2 112
#define LUA3 113
#define LUA4 114
#define LUA5 115
#define LUA6 116
#define LUA7 117
#define LUA8 118
#define LUA9 119

<tt>get LUA0</tt> is used to check whether call succeeded (1 if true, 0 otherwise.) LUA1..9 store return values, e.g. <tt>lua_ReturnSomeValues</tt> above would put its first argument into <tt>get LUA1</tt>, second into <tt>get LUA2</tt>, and so on.

==Summary==
Steps needed to call a Lua function in a BOS call-script call:
*define a Lua function <tt>MyFunction(unitID, unitDefID, teamID, ...)</tt> in LuaCOB/main.lua or a file included by it
*define a BOS/COB script <tt>lua_MyFunction() { return 0; }</tt> so the compiler knows about it
*call your function with <tt>call-script lua_MyFunction()</tt>
*return values can be found in <tt>get LUA1..9</tt>
*<tt>get LUA0</tt> returns 1 when call was successful (regardless of its return values) and 0 in case of failure.

===Examples of code===
*[http://neoteric.pl/~imbaczek/spring/messages_lua.zip Inter-unit communication] (shameless plug ;p) - a library that allows passing messages between units and reading/writing of public variables exposed by them.Included is a tech demo involving modified [[Nanoblobs]] 0.64. Patch, start the game, make a sheep and see for yourself.
* <big>Your own!</big>

=Interfacing Lua->COB=

Lua:
Spring.CallCOBScript(unitID, "CustomScript", retArgCount, arg1, ..., argN)
Spring.CallCOBScriptCB(unitID, "CustomScript", retArgCount, callbackData, arg1, ..., argN)

'''retArgCount:''' the number of arguments expected to be returned'''
'''callbackData:''' number passed to CobCallback() when the cob call completes

COB:
CustomScript(arg1, ..., argN) { ... }

One particularly useful COB script, since Lua doesn't seem to have a way of making <tt>get SOMETHING(args)</tt> requests (but it may provide other ways of getting the same information):
LuaGet(r, cmd, p1, p2, p3, p4)
{
if (r == 0) { r = get cmd; return r }
if (r == 1) { r = get cmd(p1, 0, 0, 0); return r }
if (r == 2) { r = get cmd(p1, p2, 0, 0); return r }
if (r == 3) { r = get cmd(p1, p2, p3, 0); return r }
if (r == 4) { r = get cmd(p1, p2, p3, p4); return r }

return 1234;
}

=References=
#[http://spring.clan-sy.com/phpbb/viewforum.php?f=23 Spring Lua Scripts forum]
#[http://spring.clan-sy.com/phpbb/viewtopic.php?t=9329 trepan's description of Lua-COB interface] - a little bit outdated, but still worth a read

=Thanks=
trepan for doing the hard work of integrating Lua into Spring!

NOTE from trepan:
Thanks, but there were lua startscripts before I started doing
any Spring coding. The benefits of the new LuaCob, LuaGaia, and
LuaRules scripts are that they can be loaded from map/mod archives,
and that they all use the same base libraries (as does LuaUI).
They also have significantly more features then the current
startscript code (ex: more call-ins and call-outs, the ability to
render graphics in several different modes, play sounds, etc...)

Spring - User contributions [en]

Lua-LuaCOB