raylib-lua

LuaJIT-based binding for raylib, a simple and easy-to-use library to learn videogames programming.

This binding is partially based on raylib-wren/wray.

Usage (raylua_s)

raylua_s is the script-mode binary of raylib-lua. Without any argument, you get into the REPL which gives you a minimal Lua] shell that allows you to run Lua code from terminal.]

You can specify a Lua file as argument to run the specified Lua file.

Usage (raylua_e)

raylua_e is the embedding-mode binary of raylib-lua.

This binary allows you to build standalone raylib applications from Lua code.

There are 3 ways to use it :

• zip mode : If you specify a zip file as argument, this zip will be used as payload application, this file expects to have a main.lua which is the entry point of the application.
• directory mode : Similar to zip mode except that it automatically build the zip payload from the specified directory.
• lua mode : Build the executable from a single Lua file.

Using require in embedded mode works as expected but dofile and loadfile may not work as expected as these functions load from a external file rather than from package loaders.

Building / Updating raylib / Contribution

To build raylib-lua from source, you need to take care that submodules are imported, if not or you are unsure :

git submodule init
git submodule update

This make take some time depending on network bandwidth. Then, raylib-lua should build as expected using make tool with a working C compiler.

A working Lua interpreter is needed, by default the luajit interpreter built along with libluajit.a is used. In case of cross-compiling, you may want to change which Lua interpreter is used to a one your system supports. You can specify the interpreter with the LUA variable.

If you need to update raylib binding, there are few tasks to do :

• update tools/api.h functions signatures, keep file clean with exactly one function per line.
• update struct definitions in src/raylib.lua

Loading embedded ressources

Currently, raylib-lua support loading ressources from payload using raylib API. You can also arbitrarily load files from payload using raylua.loadfile which returns a boolean indicating success and file content.

Making structs

To make raylib structs, you need to use the LuaJIT FFI.

local ffi = require "ffi"

Then use ffi.new to make a struct, e.g ffi.new("Color", r, g, b, a)

Note concerning pointers

You can use rl.ref to build a pointer from a struct cdata. This functions only work struct cdata, in case of primitive cdata, you need to make a array and pass it directly.

e.g :

local int_ptr = ffi.new "int [1]"
local data = tostring(rl.LoadFileData("test.txt", int_ptr))
local count = tonumber(int_ptr[0])

Example

rl.SetConfigFlags(rl.FLAG_VSYNC_HINT)

rl.InitWindow(800, 450, "raylib [core] example - basic window")

while not rl.WindowShouldClose() do
	rl.BeginDrawing()

	rl.ClearBackground(rl.RAYWHITE)
	rl.DrawText("Congrats! You created your first window!", 190, 200, 20, rl.LIGHTGRAY)

	rl.EndDrawing()
end

rl.CloseWindow()

Compatibility

raylib-lua (raylua) currently uses raylib 3.5 API. (see compat.lua). physac and rlgl modules are built-in by default. raygui is supported, but is minimally tested, please report any issues you have with raygui with raylib-lua (raylua) on GitHub or raylib Discord (#raylib-lua channel)

Global API

You can make raylib-lua (raylua) partially compatible with original raylib-lua or raylib-lua-sol with global API by adding setmetatable(_G, { __index = rl }) on the first line.

This will allow direct use of the raylib binding through globals instead of rl table.

You have an example of this in lua_global_api.lua.

Editor support

Currently, there is no editor autocompletion/integration support for most editors, but there is a third-party autocompletion support for ZeroBrane Studio by Rabios.

Debugging

You can use Local Lua Debugger for Visual Studio Code to provide debugging support with Visual Studio Code. You need to add this at the beginning of your code to use it :

do local f = getmetatable(rl).__index;rawset(rl, "__index", function (_, k) return select(2, pcall(f, _, k)) end) end
package.path = package.path .. os.getenv "LUA_PATH"
local lldebugger = require "lldebugger"; lldebugger.start()

You also need to setup a launch configuration in Visual Studio Code to run raylua_s with debugger attached, e.g

{
    "type": "lua-local",
    "request": "launch",
    "name": "(Lua) Launch",
    "cwd": "${workspaceFolder}",
    "program": { "command": "PATH TO raylua_s" },
    "args": [ "main.lua OR ${file} OR WHATEVER" ]
}

This debugger doesn't support pausing, you need to place a breakpoint before executing to get a actual debug, otherwise, a error needs to be thrown in the application to get the debugging. This debugger has a significant overhead, expect a performance loss in intensive projects.

Other bindings

raylib-lua (raylua) is not the only Lua binding for raylib.

There are some other bindings, which may or may not be up to date.

RobLoach/raylib-lua-sol

raysan5/raylib-lua

HDPLocust/raylib-luamore

alexander-matz ffi binding

darltrash/raylib-luajit

Rabios/raylua

Licence

Copyright (C) 2020 Astie Teddy

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.