Repository files navigation

LuaJIT-based binding forraylib, a simple and easy-to-uselibrary to learn video game programming.

This binding is partially based onraylib-wren/wray.

raylua_s is thescript-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 Luashell 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 toraylua_s to run the specified Lua file.

raylua_e is theembedding-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 toraylua_e, this zip file's contentswill be used to build the application.raylua_e expects the zip file to containamain.lua file, which is the entry point of the application (i.e.main.lua iswhere 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 filepayload 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 canbuild the executable directly from a single Lua file.

   # Windows raylua_e core_basic_window.lua # Unix ./raylua_e core_basic_window.lua

Usingrequire in embedded mode works as expected butdofile andloadfilemay not work as expected as these functions load from an external file ratherthan frompackage loaders.

On Windows systems, you may notice that there is an additional executable (namedraylua_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 ofraylua_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 useraylua_r instead ofraylua_e to build your project without it.

Other operating systems may not consistently support this mechanism, and so there is currently no correspondingraylua_r for them.

For more information on the origin ofraylua_r, seethis old pull request where this feature was originally added.

To build raylib-lua from source, you need to take care that submodules areimported. Otherwise, if submodules haven't been imported or if you are unsure:

git submodule initgit submodule update

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

If you are unfamliar withmake, seethe 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 formake 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 theraylua_s,raylua_e, andraylua_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 builtalong withlibluajit.a is used. In case of cross-compiling, you may want tochange which Lua interpreter is used to one your system supports.You can specify the interpreter with theLUA variable.

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

• Update thetools/api.h function signatures. Keep the file clean, with exactly one function per line.
• Update the struct definitions insrc/raylib.lua.

Currently, raylib-lua supports loading resources from payloads using theraylib API. You can also arbitrarily load files from payloads usingraylua.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.

localffi=require"ffi"

After importing the necessary package (as above), useffi.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 therl.ref function to build a pointer from a cdata struct.Therl.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 :

localint_ptr=ffi.new"int [1]"localdata=tostring(rl.LoadFileData("test.txt",int_ptr))localcount=tonumber(int_ptr[0])

rl.SetConfigFlags(rl.FLAG_VSYNC_HINT)rl.InitWindow(800,450,"raylib [core] example - basic window")whilenotrl.WindowShouldClose()dorl.BeginDrawing()rl.ClearBackground(rl.RAYWHITE)rl.DrawText("Congrats! You created your first window!",190,200,20,rl.LIGHTGRAY)rl.EndDrawing()endrl.CloseWindow()

raylib-lua (raylua) currently uses raylib 5.5 API. Seecompat.lua for more info.

physac andrlgl 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 ofthe 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 withoriginal raylib-lua orraylib-lua-sol with the global API byaddingsetmetatable(_G, { __index = rl }) on the first line.

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

You have an example of this inlua_global_api.lua.

There is limited autocompletion support for VSCode and other EmmyLua frontends usingthis definition file.

Checkthis page for more information.

It may also be possible to get auto-complete working inZeroBrane Studio (a popular IDE exclusively designed for Lua) according to the information onthis 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 useLocal Lua Debugger for Visual Studio Codeto provide debugging support with Visual Studio Code.You need to add this at the beginning of your code to use it :

dolocalf=getmetatable(rl).__index;rawset(rl,"__index",function (_,k)returnselect(2,pcall(f,_,k))end)endpackage.path=package.path..os.getenv"LUA_PATH"locallldebugger=require"lldebugger";lldebugger.start()

You also need to setup a launch configuration in Visual Studio Code to runraylua_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 codeto 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.

RobLoach/raylib-lua-sol

raysan5/raylib-lua

HDPLocust/raylib-luamore

alexander-matz ffi binding

darltrash/raylib-luajit

Rabios/raylua

Copyright (C) 2023 Astie Teddy

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

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