Blitz Lua
 |
||
|
Blitz Lua |
|
With BlitzLua, it is possible to run (embedded or stand-alone) Lua scripts with full access to graphical user interfaces, 2D and 3D graphics, sound and networking. BlitzLua uses the author's version of the BlitzMAX Lua API interface [1].
[BlitzMAX] is a fast cross-platform BASIC compiler and run-time system for Windows 98/ME/2000/XP, MacOS X and Linux. Primarily intended for game development, it offers support for 2D and 3D graphics, audio and networking - [MaxGUI] is an add-on for graphical user interfaces in BlitzMAX.
BlitzLua makes the power of BlitzMAX, MaxGUI (and MiniB3D) available to Lua. As a consequence, a Lua programmer may create complete cross-platform applications (including real-time 3D games) with neat multimedia and networking capabilities.
BlitzLua comes in three "flavours": a "function interface", an "object interface" and an "objective interface" - all of them are concurrently available and may safely coexist, as long as they are not mixed. The following diagram illustrates their relationship:
BlitzMAX uses a convention which closely resembles the way Lua handles "methods": while BlitzMAX also supports true objects (with properties and methods), most modules primarily export functions whose first argument is the object which the function is expected to act on - just like Lua functions with a leading "self" argument.
The "function interface" directly maps these BlitzMax functions to corresponding Lua counterparts. On top of it, the "object interface" directly maps BlitzMax types to Lua "classes" (i.e., tables with an associated metatable). Alternatively, the "objective interface" provides Lua "prototypes" (again, on top of the "function interface") which only roughly resemble their BlitzMax counterparts, but offer additional functionality (such as an automatic layouting facility for graphical user interfaces)
Which kind of interface you should use, depends on your BlitzMax knowledge: experienced BlitzMax programmers should consider one of the first two interfaces, as the resulting Lua code will look very similar to their BlitzMax programs. Lua Programmers without any BlitzMax knowledge, however, should choose the "objective interface" instead, which is the most comfortable one.
The Details of every "flavour" are described in separate documents:
Current Status
BlitzLua should currently be considered as "pre-alpha": it has only roughly been tested, and this will not change until the "objective interface" has been fully implemented. It is just because of the number of requests why the author has decided to publish his BlitzMax interface in such an early state.
Especially the OpenGL interface should not be taken seriously: it has been automatically created from the BlitzMax source - but that source is so "C-like" (with pointers everywhere) that it will take a lot of effort to go through every function and (manually) decide which pointer represents a variable parameter or the start of an array.
The "function interface" is available and fully usable, the "object interface" is planned for May 18th, 2007, while the "objective interface" will hopefully be published around May 25th, 2007.
If you intend to use Lua in order to script a BlitzMax application, you should first import the BlitzLua module
import lua.environment
and then create a new Lua state using
local LuaState:byte ptr = createLuaVM()
rather than with luaL_newstate or similar. CreateLuaVM creates a new Lua state, loads all intrinsic Lua libraries and initializes the BlitzMax interface (in all three "flavours"). The resulting LuaState may then be used as "usual".
The BlitzLua package also includes a precompiled executable (called "BlitzLua"), which can be used to run stand-alone Lua scripts requiring the Lua.Environment. In fact, all examples in this documentation (regardless of the employed "flavour") need the BlitzLua executable to be run.
BlitzLua can be invoked as follows
BlitzLua <lua-script> <script-arguments> ...
The concrete name of the executable depends on your platform (under Windows, the full name is BlitzLua.exe; under Linux, it is called BlitzMax; under MacOS X, it is part of the BlitzLua.app bundle). <lua-script> stands for the name (or access path) of the Lua script to be evaluated. Any other arguments are passed to the given Lua script - use the global table ArgList[i] to access the i-th command line argument.
If you plan to use BlitzLua for stand-alone scripts only, the simplest approach is to download the executable for your platform, copy it to whereever you want it to be and invoke it with the file (path and) name of the script to be evaluated as the first argument - that's all: there is no installation required.
Precompiled executables are available for
If you are interested in the source code or want to use the interface for your own BlitzMAX/MaxGUI applications, you need to download the full package:
You should create a new folder named lua.mod within the module area of your BlitzMAX installation (i.e., <blitzmax-installation-folder>/mod/lua.mod) and unpack the contents of the ZIP archive into that folder.
After unpacking, you should rebuild your modules from within the BlitzMAX IDE:
You are now able to import the Lua interface modules.
BlitzLua is not yet complete, although the most important features have already been implemented. For the near future, the author plans the following extensions (some of them require the extension of BlitzMAX itself, which may take a little longer)
