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.

```lua
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