196 lines
7.2 KiB
Markdown
196 lines
7.2 KiB
Markdown
**NOTE:** This is a clone of [raylib-lua from TSnake41](https://github.com/TSnake41/raylib-lua), but using LuaJIT 2.0 instead of 2.1+, to support CPUs without SSE2.
|
|
|
|
|
|
|
|
[](https://github.com/TSnake41/raylib-lua/releases/latest)
|
|
[](https://github.com/TSnake41/raylib-lua/releases)
|
|
|
|
## raylib-lua
|
|
|
|
[LuaJIT](https://luajit.org/)-based binding for [raylib](https://www.raylib.com/), a simple and easy-to-use
|
|
library to learn videogames programming.
|
|
|
|
This binding is partially based on [raylib-wren/wray](https://github.com/TSnake41/raylib-wren).
|
|
|
|
### 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 :
|
|
|
|
```shell
|
|
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.
|
|
```lua
|
|
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 :
|
|
```lua
|
|
local int_ptr = ffi.new "int [1]"
|
|
local data = tostring(rl.LoadFileData("test.txt", int_ptr))
|
|
local count = tonumber(int_ptr[0])
|
|
```
|
|
|
|
### Example
|
|
|
|
```lua
|
|
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](https://github.com/TSnake41/raylib-lua/blob/master/src/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](https://github.com/raysan5/raylib-lua) or
|
|
[raylib-lua-sol](https://github.com/RobLoach/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](https://github.com/Rabios/raylua/tree/master/zerobrane)
|
|
for [ZeroBrane Studio](https://studio.zerobrane.com/) by [Rabios](https://github.com/Rabios).
|
|
|
|
#### Debugging
|
|
|
|
You can use [Local Lua Debugger for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=tomblind.local-lua-debugger-vscode)
|
|
to provide debugging support with Visual Studio Code.
|
|
You need to add this at the beginning of your code to use it :
|
|
```lua
|
|
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
|
|
```json
|
|
{
|
|
"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](https://github.com/RobLoach/raylib-lua-sol)
|
|
|
|
[raysan5/raylib-lua](https://github.com/raysan5/raylib-lua/)
|
|
|
|
[HDPLocust/raylib-luamore](https://github.com/HDPLocust/raylib-luamore)
|
|
|
|
[alexander-matz ffi binding](https://gist.github.com/alexander-matz/f8ee4eb9fdf676203d70c1e5e329a6ec)
|
|
|
|
[darltrash/raylib-luajit](https://github.com/darltrash/raylib-luajit)
|
|
|
|
[Rabios/raylua](https://github.com/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.
|