OneBit Lua Runtime

Native GDExtension prototype for the 1BitRL v2 Lua runtime contract.

Current Scope

This runtime is intentionally small and breaking:

api_version = 2 scripts only.
No game table.
Explicit ctx and state handler arguments.
Lua emits commands and logs; it does not mutate the Godot world directly.
Queries cross a Godot-owned query host boundary.
Instruction budget is enabled for handler calls.

Initial Lua API:

sense.is_walkable(x, y)
sense.find_nearest(group)
move.step(dx, dy)
log.say(message, duration)

Requirements

Godot 4.6.
godot-cpp master, targeting api_version=4.6.
SCons.
A Lua development package with pkg-config.

This machine currently uses Lua 5.1:

pkg-config lua-5.1 --cflags --libs

Lua 5.1 is explicit for now because it is the installed system package. If the project moves to Lua 5.4, install a Lua 5.4 development package and build with the matching pkg-config name, for example:

scons platform=linux target=template_debug api_version=4.6 lua_pkg=lua5.4

Script semantics differ between Lua 5.1 and 5.4, so do not change the runtime version silently.

Build

Clone godot-cpp as a submodule or checkout at godot-cpp/, then run:

scons platform=linux target=template_debug api_version=4.6 -j4

The demo extension library is written to:

demo/addons/onebit_lua/bin/

Smoke Test

Run the demo project headlessly:

godot --headless --path demo

Expected behavior:

Loads OneBitLuaRuntime.
Loads a tiny api_version = 2 script.
Calls on_update(ctx, state).
Mutates state.count.
Emits one move command.
Emits one log entry.
Calls the GDScript query host for sense.is_walkable and sense.find_nearest.

Safe Lua Libraries

The runtime opens only selected Lua libraries:

base
math
string
table

It does not open:

io
os
package
debug

After opening the base library, the runtime removes dangerous dynamic-loading globals:

dofile
load
loadfile
loadstring
module
require
collectgarbage

2.1 KiB Raw Blame History