Page 1 of 1

lua script notes

Posted: Fri Mar 20, 2009 10:54 am
by trepan
strayer PM'ed me with some questions regarding bzflag's lua scripts. My
reply turned out to be a page or two of text, so I figured it best to post it
here instead of just sending it to 1 person (NOTE: the original questions
have been edited).

-----------------------------------------------------------------------------------------------

My notes:

1. LuaBZFS no longer exists, it has been renamed to LuaServer.

The current lua scripts for bzflag are:

Code: Select all

           Execution  Source                                             
           --------   ------
LuaServer   server    server file
LuaUser     client    client directory
LuaWorld    client    server directory bundled with the world data      
LuaBzOrg    client    a managed URL link on http://bzflag.org
2. It would probably be best if the lua scripts were not referred to as
"plug-ins", so as to avoid confusion with the current bzfs C plug-ins. For
SpringRTS, I called the client-side scripts "widgets", and the server-side
scripts "gadgets" (actually, unsynced and synced lua code, but that's
something that doesn't really need to be explained here). A similar approach
will probably be used for the various bzflag lua scripting environments.

-----------------------------------------------------------------------------------------------

a) Is there any documentation beside the code itself?
No, but some of the documentation for SpringRTS is relevant
(example: the OpenGL API is very similar)
http://spring.clan-sy.com/wiki/Lua_Scripting
Once I get around to it, I'll post some example scripts (enough to
get you started, after which you can dig through the code for
details.) The lua/c++ interface code is usually pretty easy to read
through. Take a look through src/lua/LuaCallOuts.cxx for starters.

b) Can the plug-in control the client's appearance
Client-side lua modules can change the way everything is drawn
(GUI and viewport). There are call-outs to acquire "graphics blocks",
which block the engine's default rendering (see include/GfxBlock.h).
Note that LuaUser can not use the "world items" blocks, because it
has limited visibility of world state (this was done to forbid path
prediction scripts, etc...)

c) Can the plug-in affect the client's command line behaviour?
Client-side lua can grab almost all key and mouse events. With respect to
overriding chat command messages, you can use the bz.GetCmdToKeys()
call-out to determine which keys the user has bound to chat messaging.

Current input events that can not be grabbed are:
1. "F12" key events
2. Any key events while there's an active HUD element
(that includes the text compose line, menus, etc...)
* see playing.cxx:handleEvent() for the code

d) What is the syntax for the default slash commands?
/luaserver (server-side)
/luauser (client-side)
/luaworld (client-side)
/luabzorg (client-side)

They all have the following syntax:
/luaTAG <status | reload | disable | CUSTOM>
If the command is something other than status, reload, or disable, the
command line is passed to the associated lua script via the RecvCommand()
call-in.

-----------------------------------------------------------------------------------------------

P.S. Both the server-side and client-side scripts can use the new
MsgLuaData and MsgLuaDataFast network protocol packet types to
implement custom messaging. From playing.cxx:

Code: Select all

static void handleLuaData(void *msg)   
{
  PlayerId srcPlayerID;
  int16_t  srcScriptID;
  PlayerId dstPlayerID;
  int16_t  dstScriptID;
  uint8_t  statusBits; 
  std::string data;    

  msg = nboUnpackUByte(msg, srcPlayerID);
  msg = nboUnpackShort(msg, srcScriptID);
  msg = nboUnpackUByte(msg, dstPlayerID);
  msg = nboUnpackShort(msg, dstScriptID);
  msg = nboUnpackUByte(msg, statusBits); 
  msg = nboUnpackStdStringRaw(msg, data);

  eventHandler.RecvLuaData(srcPlayerID, srcScriptID,
                           dstPlayerID, dstScriptID,
                           statusBits,  data);
}
P.P.S. With respect to what level of modification is possible, consider
the following:
- custom MsgLuaData messages could be used for all communications
- the client-side lua scripts can change how everything is rendered
- the client-side lua scripts can grab almost all keyboard and mouse events
- the client-side lua scripts can play sounds

Basically, you could setup a bzfs server with LuaServer and LuaWorld
scripts such that the connected clients play a game that is not bzflag.
You could also set it up so that observers play tic-tac-toe against each
other while watching the tankers do their thing ;-)

Re: lua script notes

Posted: Fri Mar 20, 2009 12:44 pm
by strayer
Thank you very much for the illumination.

If I don't misunderstand you (as long as the Lua implementation is kept up-to-date in future) it's much more promising to implement all further BZFlag plug-in ideas in Lua because compared with regular C/C++ plug-ins you have more possibilities and code is written much faster. The Lua equivalents for the plug-ins RogueGenocide (C/C++ <-> Lua), Phoenix (C/C++ <-> Lua) and airspawn (C/C++ <-> Lua) are pointing this up.
I know there exist a lot of C/C++ libraries that are much easier to use with C/C++ plug-ins and Lua isn't faster in execution...

So everything is just a question of imagination and available time to implement it with Lua...yeay...good job, Trepan!

Re: lua script notes

Posted: Tue May 19, 2009 12:12 am
by trepan
To wrap up this thread ...
All of the lua related code has been removed from the bzflag 2.99 SVN repository.

Re: lua script notes

Posted: Tue May 19, 2009 9:21 am
by strayer
:shock: Why? :shock:

I already started to learn Lua to use the fantastic potential the Lua implementation offers/offered. Would be too bad for the time you invested too.

Re: lua script notes

Posted: Tue May 19, 2009 1:12 pm
by joevano
Great question stayer. Why?

Re: lua script notes

Posted: Tue May 19, 2009 8:00 pm
by JeffM
The main reason was to get the release out. The feature was added very late in development and needed more work to be safe.

2.99.x has been in development for nearly 4 years, it's running the risk of becoming a dead codebase if it is not released.

Re: lua script notes

Posted: Tue May 19, 2009 9:05 pm
by strayer
The current...latest Lua implementation came not that early, indeed.
Unfortunately, Lua seemed to be a real break-through with the potential to be usable for eye-catching effects on server maps and client-view. Now, the Lua implementation will have to wait for the next minor version (major.minor.patch), I guess.

But you are right with the need of a new BZFlag release and if it would had taken too long to guarantee some level of safety it's just...bad luck.

Re: lua script notes

Posted: Tue May 19, 2009 10:48 pm
by trepan
Getting bzflag 3.0 out is but part of the whole. I currently do not
plan to re-commit the lua code that was removed from bzflag.

On the upside, you now have much more flexible teleportation links.
I've also got some uncommitted drawInfo animation code that is
working well (and some fixes for old drawInfo bugs).

Re: lua script notes

Posted: Sat May 15, 2010 8:09 pm
by trepan
I'll note here that I re-added the client-side lua scripts
a few weeks ago. I hadn't planned to, but whatever ;)

A new script has been added to the roster, LuaRules.
It is much like LuaWorld except that it is capable of
adjusting the state of the game by such call-ins as:

ForbidShot(), ForbidJump(), ForbidShotHit(), etc...

Also, clients can not disable LuaRules.

Re: lua script notes

Posted: Thu Jun 24, 2010 3:39 am
by hutty
can lua be used to make custom flags?
multi hit shield?