Blitz Max

lua-users home

This page briefly describes the author's version of "axe.lua", a Lua API interface for [BlitzMAX] and [MaxGUI]


[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 graphics, 3D graphics (with a module), audio and networking - [MaxGUI] is an add-on for graphical user interfaces in BlitzMAX.

BlitzMAX already contains an interface for the Lua (5.1.1) API (axe.lua, written by Thomas Mayer, Noel Cower and Simon Armstrong). The author's version is an update for Lua 5.1.2 which also contains several bugfixes, additional documentation and a slightly different string handling (see below). Currently (May 5th, 2007), the module has not yet been uploaded to the official BlitzMAX module servers - thus, you will have to download and install it manually. As soon as the module servers offer the new version, a simple "module synchronization" from within the BlitzMAX IDE will be sufficient to update the old axe.lua.

String Handling

Several Lua API functions work on or return C-style strings, containing 8-bit characters and terminated by a null byte (\0). For Lua itself, a string is nothing but a sequence of bytes (including null bytes) with a separately stored length. As a consequence, Lua strings can also be used as a buffer for arbitrary data (images, sound samples etc.)

BlitzMAX offers strong type checking and supports both 8-bit and 16-bit character strings.

In order to combine these two worlds, the actual interface uses the following rules:

lua_pushstring and lua_tostring are examples for these kinds of functions. Most strings are usually passed this way.

lua_pushlstring and lua_tolstring are examples for these kinds of functions. They are useful to pass UTF-encoded Unicode strings between Lua and BlitzMAX.

Additionally, the interface provides two functions

which can be used to pass BlitzMAX byte arrays to and from Lua - on the Lua side, they appear as strings which are, however, never converted by the interface in any way.

Nota bene: please keep in mind, that both the Lua API and the BlitzMAX API have to copy the strings passed between Lua and BlitzMAX. Lua makes a copy in order to avoid "dangling pointers", BlitzMAX makes a copy when converting between a C string and its internal format. Passing large amounts of text could therefore require both memory and processor capacity.

Byte-array-based interface functions still copy their parameters once.

If you want to avoid copies at all, you may have to consider using (light or full) userdata objects.


Almost every Lua API interface type and function have been replicated in BlitzMAX. However, as it seems impossible to define BlitzMAX functions with variable argument lists, the following API functions are not available under BlitzMAX:

Additionally, the following function is also missing

All other functions have been replicated and are therefore available under BlitzMAX.

Download and Installation

Within your BlitzMAX IDE

You are now able to "import axe.lua" into your BlitzMAX code. Additionally, the module documentation now also allows to directly jump to the section within the Lua Reference Manual where a given API function is described.

Related Work

This version of axe.lua is required for BlitzLua, the author's Lua interface for BlitzMAX/MaxGUI modules. BlitzLua allows you to run (embedded or stand-alone) Lua scripts with full access to BlitzMAX's 2D and 3D graphics, sound and networking capabilities.


This work is based on the Lua API Interface written by Thomas Mayer, Noel Cower and Simon Armstrong.



RecentChanges · preferences
edit · history
Last edited November 8, 2011 7:19 am GMT (diff)