LuaJIT-based binding for raylib, a simple and easy-to-use library to learn video game programming.
This binding is partially based on raylib-wren/wray.
raylua_s is the script-mode binary of raylib-lua.
Without any argument, raylua_s gets you into the REPL (the read-eval-print loop, i.e. the interactive interpretor) which gives you a minimal Lua
shell that allows you to run Lua code from a terminal (aka command prompt, console, or shell).
You can give the name of a Lua file as an argument to raylua_s to run the specified Lua file.
raylua_e is the embedding-mode binary of raylib-lua.
This binary allows you to build standalone raylib applications from Lua code. This is useful both for testing and for packaging and distribution.
There are 3 ways to use it :
-
zip mode : If you specify a zip file as an argument to
raylua_e, this zip file's contents will be used to build the application.raylua_eexpects the zip file to contain amain.luafile, which is the entry point of the application (i.e.main.luais where you want your program to start running).# Windows raylua_e someGame.zip # Unix ./raylua_e someGame.zip -
directory mode : This mode is similar to zip mode, except that it automatically builds the zip file payload from the specified directory and then uses that zip file to build the application.
# project/ is a directory # Windows raylua_e project # Unix ./raylua_e project -
Lua mode : Alternatively, if your program is contained within a single Lua file, then you can build the executable directly from a single Lua file.
# Windows raylua_e core_basic_window.lua # Unix ./raylua_e core_basic_window.lua
Using require in embedded mode works as expected but dofile and loadfile
may not work as expected as these functions load from an external file rather
than from package loaders.
On Windows systems, you may notice that there is an additional executable (named raylua_r) that is included with the pre-built Windows release download of this raylib-lua bindings library (or which you can build yourself). The purpose of raylua_r is to remove the extra terminal window (aka command prompt, console, or shell) that would normally open alongside the graphical raylib window whenever you run it. So, if you don't want that additional text window to show then you can use raylua_r instead of raylua_e to build your project without it.
Other operating systems may not consistently support this mechanism, and so there is currently no corresponding raylua_r for them.
For more information on the origin of raylua_r, see this old pull request where this feature was originally added.
To build raylib-lua from source, you need to take care that submodules are imported. Otherwise, if submodules haven't been imported or if you are unsure:
git submodule init
git submodule updateThis may take some time depending on network bandwidth.
Afterwards, raylib-lua should build as expected using the make tool with a working C compiler.
If you are unfamliar with make, see the wikipedia for Make. It is a widely used build automation tool that is most often used on Unix-like systems (such as Linux and BSD).
Support for make on Windows can sometimes be poor though, so remember that there is a download button at the top of this page for if you just want ready-to-use copies of the raylua_s, raylua_e, and raylua_r executable files for Windows. That may be the easiest way to get started for many users. (It can be easy to overlook the download buttons on GitHub pages if you aren't paying close enough attention, so heads-up on that.)
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 one your system supports.
You can specify the interpreter with the LUA variable.
If you need to update the raylib binding, there are a few tasks you will need to do:
- Update the
tools/api.hfunction signatures. Keep the file clean, with exactly one function per line. - Update the struct definitions in
src/raylib.lua.
Currently, raylib-lua supports loading resources from payloads using the
raylib API. You can also arbitrarily load files from payloads using
raylua.loadfile, which returns a boolean indicating success or failure and the file's content.
To make raylib structs, you need to use the LuaJIT FFI.
local ffi = require "ffi"After importing the necessary package (as above), use ffi.new to make a struct, e.g. ffi.new("Color", r, g, b, a).
However, many functions in raylib won't require the use of such structs, so there's no need to worry until you actually need this.
You can use the rl.ref function to build a pointer from a cdata struct.
The rl.ref function only works with cdata structs. In the case of primitive
(non-struct) cdata in contrast, you will need to make an 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])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()raylib-lua (raylua) currently uses raylib 4.5 API. See compat.lua for more info.
physac and rlgl modules are also 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 on the #raylib-lua subchannel of the raylib Discord server. To find the #raylib-lua page, join the raylib Discord server by clicking the above link, then scroll down on the left side of Discord's list of channels until you find #raylib-lua and click it. You can chat and ask questions there.
You can make raylib-lua (raylua) partially compatible with
original raylib-lua or
raylib-lua-sol with the 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 through the rl table.
You have an example of this in lua_global_api.lua.
There is limited autocompletion support for VSCode and other EmmyLua frontends using this definition file.
Check this page for more information.
It may also be possible to get auto-complete working in ZeroBrane Studio (a popular IDE exclusively designed for Lua) according to the information on this page written by a different Lua raylib binding author, which mentions that their own autocomplete implementation (raylua) coincedentally has some compatibility with this binding (raylib-lua) too.
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 the 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 at arbitrary unspecified points. You will need to place a breakpoint before executing your code to get an actual steppable debug working. Otherwise, an error will need to be thrown in the application to get the debugging to trigger.
This debugger has significant overhead, expect a potentially large performance loss in intensive projects if you use it.
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.
Copyright (C) 2023 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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent