rgl_framework/docs/LIB_REFERENCE.md

Standard Library Reference

Analysis of the shared Lua library at ../lib (/home/regela/Workspace/lua/lib/). Contains ~163 files across 17 directories (6.4MB total).

Currently Used by Project

Module	Import	Purpose
ffi	Built-in LuaJIT	FFI to load libarz_core.so, imgui bindings
encoding	require("encoding")	UTF-8 / CP1251 conversion
cjson	require("cjson")	JSON encode/decode
mimgui	require("mimgui")	ImGui binding for in-game UI
samp.events	require("samp.events")	SA-MP event hooking (RPC/packets)
lua_thread	Global	Coroutine-based threading (MonetLoader built-in)

---

High-Value Unused Libraries

SAMemory — Game Memory Access

Path: lib/SAMemory/ Size: 50+ files covering all game entity types

Direct FFI-based access to GTA SA game structures: CPed, CVehicle, CEntity, CCamera, CWorld, etc. Read player position, health, vehicle state, weapon data directly from memory.

Use cases for modules:

• Read player coordinates for location-based automation
• Check vehicle state (speed, health, passengers)
• Access weapon/ammo data
• Read game time, weather, gravity

Key files:

• SAMemory/init.lua — main entry point
• SAMemory/game/CPed.lua — player/NPC structures
• SAMemory/game/CVehicle.lua — vehicle structures
• SAMemory/game/CCamera.lua — camera state

requests.lua — HTTP Client

Path: lib/requests.lua (~270 lines)

Full HTTP/HTTPS client built on LuaSocket + LuaSec. Supports:

• GET, POST, PUT, DELETE methods
• Basic and Digest authentication
• Automatic HTTPS
• Cookie handling
• Custom headers

Use cases: External API calls, webhooks, data sync with remote servers.

inicfg.lua — INI Config Files

Path: lib/inicfg.lua (~150 lines)

Read/write .ini config files with sections. Auto-creates defaults.

local inicfg = require("inicfg")
local cfg = inicfg.load({section = {key = "default"}}, "mymod.ini")
cfg.section.key = "new_value"
inicfg.save(cfg, "mymod.ini")

Note: The framework already has DB persistence, but inicfg is useful for human-editable config files.

jsoncfg.lua — JSON Config Files

Path: lib/jsoncfg.lua (~150 lines)

Similar to inicfg but uses JSON format. Supports deep merge of defaults.

game/ — Game Constants

Path: lib/game/

File	Content
globals.lua (~650 lines)	Script variables $0-$2000
models.lua (~500 lines)	Object/vehicle model IDs
weapons.lua (~100 lines)	Weapon IDs and names
keys.lua (~50 lines)	Control key constants

Use cases: Reference weapon names, vehicle model IDs, key bindings in modules.

Crypto & Encoding

Module	Path	Purpose
md5.lua	lib/md5.lua	MD5 hashing
sha1/	lib/sha1/	SHA-1 hashing + HMAC (multiple implementations)
basexx.lua	lib/basexx.lua	Base16, Base32, Base64 encoding/decoding

Use cases: Data integrity checks, API signatures, obfuscation.

copas.lua — Async I/O

Path: lib/copas.lua (~1500 lines) + submodules

Coroutine-based async TCP/IP dispatcher. Non-blocking HTTP, FTP, SMTP.

Submodules:

• copas/http.lua — async HTTP client
• copas/smtp.lua — async email sending
• copas/ftp.lua — async FTP
• copas/timer.lua — timer support
• copas/lock.lua, queue.lua, semaphore.lua — async primitives

Note: The framework already uses Rust's tokio for async. Copas is an alternative for pure-Lua async if needed.

timerwheel.lua — Efficient Timers

Path: lib/timerwheel.lua (~300 lines)

O(1) timer wheel for managing many concurrent timers efficiently. Better than individual lua_thread coroutines when you have dozens of timers.

monethook.lua — Function Hooking

Path: lib/monethook.lua (~80 lines)

Inline function hooking for MonetLoader >= 2.8.0. Intercept game function calls at the assembly level.

---

Medium-Value Libraries

Math

Module	Path	Purpose
vector3d.lua	lib/vector3d.lua	3D vector ops (normalize, dot, cross)
matrix3x3.lua	lib/matrix3x3.lua	3x3 matrix ops

Networking Stack

Module	Path	Purpose
socket.lua	lib/socket.lua	LuaSocket TCP wrapper
ssl.lua	lib/ssl.lua	LuaSec TLS/SSL
socket/http.lua	lib/socket/http.lua	Low-level HTTP client
socket/url.lua	lib/socket/url.lua	URL parsing (RFC 3986)
socket/ftp.lua	lib/socket/ftp.lua	FTP client
socket/smtp.lua	lib/socket/smtp.lua	SMTP client
socket/headers.lua	lib/socket/headers.lua	HTTP header utils

Prefer requests.lua over raw socket modules for HTTP.

Data Processing

Module	Path	Purpose
ltn12.lua	lib/ltn12.lua	Source/sink/pump data streaming
mime.lua	lib/mime.lua	Base64, quoted-printable MIME encoding
binaryheap.lua	lib/binaryheap.lua	Priority queue (O(log n))

---

Low-Value / Specialized

Android-Specific

Module	Path	Purpose
android/arizona.lua	MonetLoader Arizona RP API	Only on Android
android/jnienv.lua	JNI environment helpers	Java/Lua interop
android/jni-raw.lua	Raw JNI access	Low-level
android/jar/arzapi.jar	Arizona API JAR	Binary

Platform / Runtime

Module	Path	Purpose
MoonMonet/	Material Design 3 color generation	Theming
monetloader.lua	MonetLoader constants	TAG types
moonloader.lua	MoonLoader compat layer	Logging codes
sa_renderfix.lua	Screen scaling fixes	Rendering
bitex.lua	Bit extraction utilities	Bit manipulation
widgets.lua	SAMP widget constants	Vehicle/player keys
sampfuncs.lua	RPC/packet ID constants	SAMP protocol

UI

Module	Path	Purpose
imgui_piemenu.lua	Circular pie menu for imgui	Alternative menu
webviews/	WebView integration	Android WebView + JAR

---

SAMP Event System Deep Dive

Path: lib/samp/

The framework hooks all SAMP events via samp.events. Key files:

File	Purpose
samp/events.lua	Main entry point, event registration
samp/events/core.lua	Event dispatcher (~200 lines)
samp/events/handlers.lua	Specialized RPC handlers (~150 lines)
samp/events/bitstream_io.lua	Binary data serialization (~300 lines)
samp/events/utils.lua	Helper functions
samp/events/extra_types.lua	Extended data types
samp/raknet.lua	RakNet protocol constants
samp/synchronization.lua	Player/vehicle sync state
sampfuncs.lua	RPC and packet ID constants

The framework's setup_event_hooks() iterates over all entries in sampev.INTERFACE (OUTCOMING_RPCS, INCOMING_RPCS, OUTCOMING_PACKETS, INCOMING_PACKETS) and creates hooks for each event name. This gives modules access to all ~200+ SAMP events without manual registration.

Summary: Recommended for Integration

Priority order for adding to new modules:

1. SAMemory — most powerful, enables location/state-aware automation
2. game/* — essential constants for any game-interacting module
3. requests.lua — if modules need external HTTP APIs
4. md5/sha1/basexx — if data integrity or encoding needed
5. inicfg/jsoncfg — if human-editable config files needed
6. timerwheel — if module manages many concurrent timers