From 97977a333c96476df891d294b557803dd9740204 Mon Sep 17 00:00:00 2001 From: Marvin <52848568+mleem97@users.noreply.github.com> Date: Fri, 10 Apr 2026 16:41:04 +0200 Subject: [PATCH] update: docs to new architecture --- docs/framework/architecture.md | 23 ++++- docs/framework/greg-hooks-and-events.md | 35 ++++++- docs/framework/hexmod.md | 23 +++-- docs/mods/fmf-hex-label-mod.md | 92 +++++++++++-------- .../reference/modding-language-requirement.md | 68 ++++++++++---- docs/topics/ffi-and-hooks/overview.md | 43 ++++++++- 6 files changed, 218 insertions(+), 66 deletions(-) diff --git a/docs/framework/architecture.md b/docs/framework/architecture.md index 443d22e..7db46e8 100644 --- a/docs/framework/architecture.md +++ b/docs/framework/architecture.md @@ -4,9 +4,21 @@ sidebar_label: Repository architecture description: Current multi-repo layout with `gregFramework` as a local wrapper and clear repository boundaries. --- -## Modding language +## Modding languages -Mods, MelonLoader plugins, and extensions ship their **logic in C# only** (MelonLoader / .NET). Scope vs framework core (e.g. Rust bridge): [Modding language (C# only)](/wiki/reference/modding-language-requirement). +gregCore supports **three modding languages** through its Language Bridge system: + +| Language | Bridge | Runtime | Mod format | +|----------|--------|---------|------------| +| **C#** | MelonLoader / .NET | Direct IL2CPP interop | `.dll` assemblies in `Mods/` | +| **Lua** | `LuaLanguageBridge` (MoonSharp VM) | `greg.*` API with handle-based Unity access | `.lua` scripts in `Mods/ScriptMods/lua/` | +| **Rust / native** | `RustLanguageBridgeAdapter` → `FFIBridge` | C ABI exports (`mod_init`, `mod_update`, `mod_on_event`) | `.dll`/`.greg` in `Mods/RustMods/` | + +**Lua scripts** interact with the game exclusively through the `greg.*` API surface — a set of C#-backed modules that expose Unity/IL2CPP operations via integer handles. This includes `greg.unity.*` (object manipulation), `greg.on()`/`greg.hook.*` (event and Harmony patch subscriptions), `greg.gui.*` (IMGUI), `greg.io.*` (file system), and `greg.input.*` (keyboard). See [Greg hooks & events](/wiki/framework/greg-hooks-and-events) for the event API and the [Language Bridges README](https://github.com/mleem97/gregFramework/blob/main/gregCore/framework/ModLoader/LanguageBridges/README.md) for the full Lua API reference. + +**Rust/native mods** receive a `GameAPITable` function-pointer table on `mod_init` and numeric `EventIds` via `mod_on_event`. The `FFIBridge` handles shadow-copying, lifecycle dispatch, and hot-reload. + +Policy details: [Modding language support](/wiki/reference/modding-language-requirement). ## Target runtime layers @@ -25,7 +37,8 @@ Above the raw repositories, the **logical** model is **ModManager → Framework | ------ | ------ | | **Wrapper** | `gregFramework/` holds local checkouts of individual repositories. | | **Core** | `gregCore/` — **framework core**: translation, hooks, Harmony/event runtime, MCP, templates, and related core features. | -| **Rust / native FFI** | Loads native mod exports inside the **framework** assembly: `gregCore/framework/src/ModLoader/FfiBridge.cs`; Melon host remains **`DataCenterModLoader.Core`** in `Core.cs` (Melon display name **RustBridge**). | +| **Language Bridges** | `gregCore/framework/ModLoader/LanguageBridges/` — Lua (MoonSharp), TypeScript/JS (planned), Rust/native (`FFIBridge`). Lua modules under `LuaModules/` provide the `greg.*` API. | +| **Rust / native FFI** | Loads native mod exports: `gregCore/framework/ModLoader/FfiBridge.cs`; adapter: `RustLanguageBridgeAdapter.cs`. Full lifecycle: init, update, scene load, event dispatch, shutdown. | | **Mods** | `gregMod./` — one repo each, directly under `gregFramework/`. | | **Extensions** | `gregExt./` — one repo each, directly under `gregFramework/`. | | **Docs** | `gregWiki/` — documentation site repository. | @@ -43,3 +56,7 @@ Hook naming and the registry are owned by core; when repos split, **core** remai ## Steam & Workshop Workshop templates and deployment scripts live in the core repo under `gregCore/Templates/` and `gregCore/scripts/`. + +## Lua handle system + +Lua cannot hold direct references to Il2Cpp objects. gregCore uses an **integer handle registry** (`LuaObjectHandleRegistry`) that maps `int` handles to live .NET objects via weak references. Lua scripts receive handles from `greg.unity.find()`, `greg.unity.get_component()`, etc. and pass them back to `greg.unity.*` functions. Handles are automatically pruned when the underlying Unity objects are destroyed. diff --git a/docs/framework/greg-hooks-and-events.md b/docs/framework/greg-hooks-and-events.md index d6aaf4b..e25d952 100644 --- a/docs/framework/greg-hooks-and-events.md +++ b/docs/framework/greg-hooks-and-events.md @@ -37,9 +37,42 @@ Build stable hook strings with **`GregHookName.Create(GregDomain.*, "Action")`** - **Mapping → `greg.*`:** **`GregNativeEventHooks`** (`gregCore/framework/src/Sdk/GregNativeEventHooks.cs`); emission via **`GregHookIntegration`** in the same ModLoader tree. - **Wiki table:** [greg hooks catalog](/wiki/reference/greg-hooks-catalog) (generator: `gregCore/tools/Generate-GregHookCatalog.ps1`). +## Lua event & hook subscriptions + +Lua scripts subscribe to the same event surfaces through the `greg.*` API injected by `GregHooksLuaModule`: + +| Lua API | C# backend | Purpose | +|---------|-----------|---------| +| `greg.on(hookName, fn)` | `GregEventDispatcher.On()` | Subscribe to any `greg.*` event — receives payload as Lua table | +| `greg.off(hookName)` | `GregEventDispatcher.Off()` | Unsubscribe all Lua handlers for a hook | +| `greg.emit(hookName, payload)` | `GregEventDispatcher.Emit()` | Emit a custom event (other Lua/C# listeners receive it) | +| `greg.hook.before(hookName, fn)` | `HookBinder.OnBefore()` | Harmony **prefix** — fn receives `{hook_name, type_name, method_name, instance_handle, arg_count}` | +| `greg.hook.after(hookName, fn)` | `HookBinder.OnAfter()` | Harmony **postfix** — same context table | +| `greg.hook.off(hookName)` | `HookBinder.Unregister()` | Remove all handlers for a Harmony hook | + +**Example** — react to CableSpinner.Start in Lua: + +```lua +greg.hook.after("greg.Misc.OnStart", function(ctx) + if ctx.type_name and ctx.type_name:find("CableSpinner") then + greg.log("new spinner spawned, handle: " .. tostring(ctx.instance_handle)) + end +end) +``` + +**Example** — listen to game events: + +```lua +greg.on("greg.PLAYER.CoinChanged", function(payload) + greg.log("coins changed by " .. tostring(payload.coinChangeAmount)) +end) +``` + +All hook names from `GregNativeEventHooks` (e.g. `greg.PLAYER.CoinChanged`, `greg.SERVER.PowerButton`) and `HookBinder` aliases (e.g. `greg.Misc.OnStart`) are available to Lua. + ## Rust FFI -Rust/native mods receive **numeric** event ids; C# mirrors the same moments as **`greg.*`** through **`GregHookIntegration`** while the game runs (including when the FFI connection is down for the managed **`greg.*` surface). Bridge code: **`FfiBridge` / `FFIBridge`** under `framework/src/ModLoader/`. +Rust/native mods receive **numeric** event ids; C# mirrors the same moments as **`greg.*`** through **`GregHookIntegration`** while the game runs. The `RustLanguageBridgeAdapter` fully delegates all lifecycle calls (`OnUpdate`, `OnSceneLoaded`, `Shutdown`, event dispatch) to `FFIBridge`. Bridge code: **`FfiBridge.cs`** / **`RustLanguageBridgeAdapter.cs`** under `framework/ModLoader/`. ## MelonLoader entry points (one DLL) diff --git a/docs/framework/hexmod.md b/docs/framework/hexmod.md index 704c682..9583782 100644 --- a/docs/framework/hexmod.md +++ b/docs/framework/hexmod.md @@ -1,19 +1,22 @@ --- title: HexMod sidebar_label: HexMod -description: Hex label mod — in-world hex color labels for cable spinners and racks. +description: Hex label mod — in-world hex color labels for cable spinners and racks, now powered by Lua. --- # HexMod The **Hex Label** mod adds in-world hex color labels for cable spinners and racks. +Since **v00.02**, HexLabel is a **pure Lua mod** powered by gregCore's Lua runtime. All mod logic lives in `lua/hexlabel/main.lua`; the C# assembly is a thin metadata-only bootstrap. + ## Steamworks Info | Field | Value | |-------|-------| -| **Assembly** | `FMF.HexLabelMod.dll` | -| **Version** | `00.01.0009` | +| **Assembly** | `FMF.HexLabelMod.dll` (bootstrap only) | +| **Lua script** | `Mods/ScriptMods/lua/hexlabel/main.lua` | +| **Version** | `00.02.0000` | | **Author** | mleem97 | | **Game** | Data Center (App 4170200) | | **Workshop Tags** | `modded`, `melonloader`, `mod` | @@ -21,11 +24,19 @@ The **Hex Label** mod adds in-world hex color labels for cable spinners and rack ## Downloads - **Steam Workshop:** [FMF.HexLabelMod — workshop item](https://steamcommunity.com/sharedfiles/filedetails/?id=3701404621) (subscribe in-game or via GregModManager) -- **GitHub:** [Latest release](https://github.com/mleem97/gregModHexLabelMod/releases/latest) (`FMF.HexLabelMod.dll`) -- **Manual:** Drop `FMF.HexLabelMod.dll` into `/Mods/` +- **GitHub:** [Latest release](https://github.com/mleem97/gregModHexLabelMod/releases/latest) +- **Manual:** Copy `lua/hexlabel/` to `Mods/ScriptMods/lua/hexlabel/` + +## Architecture + +| Component | Location | Role | +|-----------|----------|------| +| **Lua script** | `lua/hexlabel/main.lua` | All mod logic: labeling, HUD, hex viewer, config | +| **C# bootstrap** | `Main.cs` → `FMF.HexLabelMod.dll` | MelonLoader metadata only | +| **gregCore APIs** | `greg.unity.*`, `greg.hook.*`, `greg.gui.*`, `greg.io.*`, `greg.input.*` | Generic framework services used by the Lua script | ## Source & layout -- **Repository:** [`mleem97/gregModHexLabelMod`](https://github.com/mleem97/gregModHexLabelMod) (assembly `FMF.HexLabelMod.dll`) +- **Repository:** [`mleem97/gregModHexLabelMod`](https://github.com/mleem97/gregModHexLabelMod) See also the detailed wiki article [FMF.HexLabelMod](/wiki/mods/fmf-hex-label-mod). diff --git a/docs/mods/fmf-hex-label-mod.md b/docs/mods/fmf-hex-label-mod.md index a5480e9..5af15f4 100644 --- a/docs/mods/fmf-hex-label-mod.md +++ b/docs/mods/fmf-hex-label-mod.md @@ -5,7 +5,7 @@ sidebar_label: FMF.HexLabelMod -[`gregModHexLabelMod`](https://github.com/mleem97/gregModHexLabelMod) (assembly `FMF.HexLabelMod.dll`) +[`gregModHexLabelMod`](https://github.com/mleem97/gregModHexLabelMod) — pure Lua mod powered by gregCore ## Release @@ -16,36 +16,64 @@ sidebar_label: FMF.HexLabelMod ## Purpose -Standalone MelonLoader mod for **Data Center** that overlays the hex color code of each `CableSpinner` and `Rack` directly in-world, so you can identify cable and rack colors at a glance without opening any menu. +Overlays the hex color code (`#RRGGBB`) of each `CableSpinner` and `Rack` directly in-world in **Data Center**, so you can identify cable and rack colors at a glance. Includes an IMGUI HUD (top-right) with crosshair-aimed color detection and a full hex viewer (F2). -Rewritten from the former root `HexLabelMod` for the FrikaModdingFramework workflow, now running fully standalone. +## Architecture (v00.02+) + +Since v00.02, HexLabel is a **pure Lua mod**. The C# assembly (`FMF.HexLabelMod.dll`) is a thin MelonLoader bootstrap that provides metadata only. All mod logic lives in `lua/hexlabel/main.lua` and uses the `greg.*` API provided by gregCore's Lua runtime. + +### gregCore APIs used + +| API | Purpose | +|-----|---------| +| `greg.unity.find("CableSpinner")` | Find all spinner objects in scene | +| `greg.unity.find("Rack")` | Find all rack objects in scene | +| `greg.unity.get_string(h, "rgbColor")` | Read spinner color property | +| `greg.unity.material_hex(h, "_BaseColor")` | Read material hex color | +| `greg.unity.instantiate(h, parent)` | Clone source TMPro label for spinner | +| `greg.unity.tmpro_set(...)` | Configure cloned TMPro label text/size/color | +| `greg.unity.create_gameobject(name, parent)` | Create rack label container | +| `greg.unity.add_component(h, "TextMesh")` | Add world-space TextMesh to rack | +| `greg.unity.textmesh_set(...)` | Configure rack label | +| `greg.unity.raycast(...)` / `camera_ray()` | HUD crosshair aim detection | +| `greg.unity.get_parent_component(h, type)` | Resolve aimed object type | +| `greg.hook.after(hookName, fn)` | Hook CableSpinner.Start for instant labeling | +| `greg.config.load(path)` | Load `hexposition.cfg` | +| `greg.input.key_pressed("F2")` | Toggle hex viewer | +| `greg.gui.*` | IMGUI HUD and viewer window | +| `greg.io.read_head(path, n)` | Steam log scanning for startup gating | + +### Project structure + +```text +gregMod.HexLabelMod/ +├── lua/hexlabel/main.lua ← All mod logic (pure Lua, ~300 lines) +├── Main.cs ← Thin C# bootstrap (metadata only) +├── FMF.HexLabelMod.csproj ← Build config +└── README.md +``` ## Requirements | Dependency | Notes | | --- | --- | | [MelonLoader](https://melonwiki.xyz/) | With generated IL2CPP assemblies | - -This mod runs standalone and does **not** require FMF runtime APIs. +| **gregCore** | Provides Lua runtime and `greg.*` API | ## Installation -1. **Recommended:** Subscribe on the [Steam Workshop](https://steamcommunity.com/sharedfiles/filedetails/?id=3701404621), or download `FMF.HexLabelMod.dll` from the [latest GitHub release](https://github.com/mleem97/gregModHexLabelMod/releases/latest). -2. If you use a manual DLL, drop `FMF.HexLabelMod.dll` into your `Mods/` folder. -3. Launch the game — the config file is created automatically on first run at: - -```text -UserData/hexposition.cfg -``` +1. Ensure **gregCore** is installed and up to date. +2. Copy `lua/hexlabel/` to `Mods/ScriptMods/lua/hexlabel/`. +3. Optionally place `FMF.HexLabelMod.dll` in `Mods/` (for MelonLoader metadata). +4. Launch the game — the config file is created automatically on first run. ## Configuration -Edit `UserData/hexposition.cfg` to adjust label positioning and font sizes. The file is auto-generated with defaults on first launch and regenerated if any keys are missing. +Edit `UserData/hexposition.cfg` to adjust label positioning and font sizes. The file is auto-generated with defaults on first launch. ```ini # Hex Label Position Config # File: UserData/hexposition.cfg -# Edit values, then restart game. # Spinner (UI text near cable spool) spinner_offset_x=0 @@ -79,32 +107,24 @@ rack_scale=1 | `rack_character_size` | float | `0.05` | Character size for the world-space `TextMesh` label | | `rack_scale` | float | `1` | Uniform world-space scale of the rack label object | -## Live Reload *(restricted)* - -Pressing **Ctrl+F1** toggles live config reload (6-second interval), allowing you to tune label positions without restarting the game. This feature is restricted to a specific Steam account and will silently do nothing for all other users. - -## Build - -```powershell -dotnet build .\gregModHexLabelMod\FMF.HexLabelMod.csproj -``` - -Output lands in the standard MelonLoader `Mods/` folder as configured in the `.csproj`. - ## How It Works -1. **Startup** — The mod defers full initialization until MelonLoader's `Latest.log` confirms the Steam runtime is ready (SteamID or Steam marker detected). -2. **Spinner labels** — Every `CableSpinner` gets a cloned `TextMeshProUGUI` label injected into its UI hierarchy, displaying the resolved hex code in white. Color is read from `rgbColor`, then from the `_BaseColor`/`_Color` material property as fallback. -3. **Rack labels** — Every `Rack` gets a world-space `TextMesh` label positioned at its back-right-bottom corner, facing away from the rack front. -4. **Scan loop** — Active spinners and racks are re-checked every 1.5 seconds to catch newly spawned objects. -5. **Harmony patch** — `CableSpinner.Start` is patched to inject the label immediately on spawn, before the first scan cycle runs. +1. **Startup** — The Lua script defers initialization until MelonLoader's `Latest.log` confirms the Steam runtime is ready (scans via `greg.io.read_head`). +2. **Spinner labels** — For each `CableSpinner`, the script clones the source `TextMeshProUGUI` label via `greg.unity.instantiate()` and configures it with the resolved hex code using `greg.unity.tmpro_set()`. +3. **Rack labels** — For each `Rack`, a new `TextMesh` component is created via `greg.unity.create_gameobject()` + `greg.unity.add_component()` and positioned at the rack. +4. **Scan loop** — Active spinners and racks are re-checked every 1.5 seconds; deep refresh every 10 seconds. +5. **Harmony hook** — `greg.hook.after()` subscribes to `CableSpinner.Start` to label new spinners immediately on spawn. +6. **HUD** — IMGUI overlay drawn via `greg.gui.*` in `on_gui()`, showing crosshair-aimed hex color detected via `greg.unity.raycast()`. +7. **Hex viewer** — F2 toggles a full-screen color list collected from scene CableSpinners. -## Notes +## Migration from v00.01 -- Original gameplay behavior is unaffected. -- Source lives in the split repo [`gregModHexLabelMod`](https://github.com/mleem97/gregModHexLabelMod), not under a legacy `mods/` tree. -- The config file is fully rewritten if any expected keys are missing (for example, after an update adds new keys). -- FMF assembly presence is no longer required as a startup gate. +If upgrading from the standalone C# version: + +1. Remove the old `FMF.HexLabelMod.dll` (or keep it — the new version is just a bootstrap stub). +2. Install gregCore. +3. Deploy `lua/hexlabel/main.lua` to `Mods/ScriptMods/lua/hexlabel/`. +4. Your `hexposition.cfg` is fully compatible. ## Sources diff --git a/docs/reference/modding-language-requirement.md b/docs/reference/modding-language-requirement.md index 3069760..14b3468 100644 --- a/docs/reference/modding-language-requirement.md +++ b/docs/reference/modding-language-requirement.md @@ -1,31 +1,67 @@ --- id: modding-language-requirement -title: Modding language (C# only) +title: Modding language support slug: /reference/modding-language-requirement -description: Mandatory language for mods, MelonLoader plugins, and extensions — C# only. +description: Supported languages for mods, MelonLoader plugins, and extensions — C#, Lua, and Rust/native. --- -# Modding language (C# only) +# Modding language support -## Requirement +## Supported languages -**All logic for mods, MelonLoader plugins, and framework extensions must be implemented in C#.** +gregCore supports **three modding languages** through its Language Bridge system: -That applies to anything shipped as a **`gregMod.*`**, **`gregExt.*`**, or **`FFM.Plugin.*`** / **`FMF.*`** module that loads through the MelonLoader / IL2CPP stack: gameplay code, Harmony patches, UI, networking hooks, and data handling belong in **C#** (typically targeting **.NET** compatible with your MelonLoader build). +| Language | Runtime | Mod location | Best for | +|----------|---------|-------------|----------| +| **C#** | MelonLoader / .NET (direct IL2CPP interop) | `Mods/*.dll` | Plugins, deep framework extensions, performance-critical code | +| **Lua** | MoonSharp VM in `LuaLanguageBridge` | `Mods/ScriptMods/lua//` | Gameplay mods, UI overlays, event-driven logic, rapid prototyping | +| **Rust / native** | `FFIBridge` (C ABI) | `Mods/RustMods/*.dll` or `.greg` | Native performance, existing Rust codebases | + +## C# (primary) + +All logic for MelonLoader plugins and framework extensions ships in **C#** (`.NET` compatible with MelonLoader). This is the traditional path and gives direct access to Harmony, IL2CPP interop, and all Unity APIs. + +## Lua + +Lua scripts run inside gregCore's **MoonSharp VM** and interact with the game through the `greg.*` API: + +- **`greg.unity.*`** — handle-based Unity object manipulation (FindObjectsOfType, GetComponent, Instantiate, TMPro, TextMesh, Transform, Material, Physics) +- **`greg.on()` / `greg.hook.before()` / `greg.hook.after()`** — subscribe to game events and Harmony patches +- **`greg.gui.*`** — IMGUI drawing (OnGUI) +- **`greg.io.*`** — file system access +- **`greg.input.*`** — keyboard input +- **`greg.config.*`** — key=value config files +- **`greg.color.*`** — hex color utilities + +Lua mods are deployed as `.lua` files under `Mods/ScriptMods/lua/`. They do not require compilation or IL2CPP assemblies. gregCore discovers and loads them automatically. + +**Lifecycle:** Lua scripts define optional global functions `on_update(dt)`, `on_scene(name)`, and `on_gui()` that gregCore calls at the appropriate Unity lifecycle points. + +**Example:** [FMF.HexLabelMod](/wiki/mods/fmf-hex-label-mod) is a pure Lua mod (~300 lines) that uses `greg.unity.*` and `greg.hook.*` to add hex color labels to game objects. + +## Rust / native + +Native mods (Rust, C, C++) are loaded by `FFIBridge` and communicate through a C ABI: + +- `mod_info()` — returns mod metadata +- `mod_init(api_table)` — receives a `GameAPITable` with function pointers +- `mod_update(dt)` — called per frame +- `mod_on_scene_loaded(name)` — scene transitions +- `mod_on_event(id, data, size)` — game events (numeric `EventIds`) +- `mod_shutdown()` — cleanup + +The `RustLanguageBridgeAdapter` fully delegates lifecycle calls to `FFIBridge`, including hot-reload support for non-DLL formats (`.greg`, `.gregr`). ## Rationale -- **MelonLoader** loads managed **.NET** assemblies; Harmony and the interop layer are built around C#. -- A single language keeps reviews, debugging, and CI consistent for contributors. - -## What this does *not* restrict - -- **Framework core** (`gregCore`) may still ship **native** loading paths maintained by core maintainers (Rust/other natives als **vorkompilierte** `.dll`/`.greg`/…-Module, geladen über **`FFIBridge`** in `gregCore/framework/src/ModLoader/`), plus build scripts and tooling. Those are **not** substitutes for implementing mod/plugin/extension **logic** outside C#. -- **Documentation**, **config** (JSON/YAML), and **assets** are not “logic” in this sense. -- **gregStore**, **gregWiki**, and other non–in-game stacks may use other languages as appropriate. +- **C#** remains the primary language because MelonLoader, Harmony, and IL2CPP interop are built around it. +- **Lua** lowers the barrier for mod authors who don't want to set up a C# build chain. The `greg.*` API handles all Il2Cpp bridging safely. +- **Rust/native** serves performance-critical use cases and mods already written in Rust. +- A single framework (`gregCore`) manages all three runtimes, keeping reviews, debugging, and CI consistent. ## See also -- [System architecture & documentation principles](/wiki/meta/system-architecture-principles) — stack model and documentation rules +- [Repository architecture](/wiki/framework/architecture) — language bridges and handle system +- [Greg hooks & events](/wiki/framework/greg-hooks-and-events) — Lua event subscriptions +- [System architecture & documentation principles](/wiki/meta/system-architecture-principles) — stack model - [Framework](/wiki/mods/framework) — runtime surface for mod authors -- [FMF hook naming](/wiki/reference/fmf-hook-naming) diff --git a/docs/topics/ffi-and-hooks/overview.md b/docs/topics/ffi-and-hooks/overview.md index 62d25a9..758cce2 100644 --- a/docs/topics/ffi-and-hooks/overview.md +++ b/docs/topics/ffi-and-hooks/overview.md @@ -1,16 +1,51 @@ --- title: FFI, hooks & Lua sidebar_label: FFI, hooks & Lua (hub) -description: FFI, hook lists, naming — curated reference for mod and plugin authors. +description: FFI, hook lists, Lua runtime, naming — curated reference for mod and plugin authors. --- # FFI, hooks & Lua -The framework is intended to act as a **hook proxy**: Unity / IL2CPP events are surfaced as **stable framework events** for mods — see [System architecture & documentation principles](/wiki/meta/system-architecture-principles). +The framework acts as a **hook proxy**: Unity / IL2CPP events are surfaced as **stable framework events** for mods in all supported languages — see [System architecture & documentation principles](/wiki/meta/system-architecture-principles). + +## Hook & event references - [FMF hooks](/wiki/framework/fmf-hooks) — generated hook surface - [FMF hooks catalog](/wiki/reference/fmf-hooks-catalog) — strings from core sources - [FMF hook naming](/wiki/reference/fmf-hook-naming) — `FMF.*` vs legacy `FFM.*` - [greg hooks registry (IL2CPP)](/wiki/reference/greg-hooks-registry) — `greg_hooks.json`, `Greg*Hooks` Harmony emitters, regeneration script -- [Framework architecture](/wiki/framework/architecture) — bridges (including Rust) and runtime layout -- [Modding language requirement](/wiki/reference/modding-language-requirement) — C# policy for mods/plugins +- [Greg hooks & events](/wiki/framework/greg-hooks-and-events) — `GregEventDispatcher`, Lua subscriptions, native pipeline + +## Lua runtime + +gregCore embeds a **MoonSharp** Lua VM (`LuaLanguageBridge`) that provides the `greg.*` API to Lua scripts: + +| API group | Key functions | Purpose | +|-----------|--------------|---------| +| **Events** | `greg.on(hook, fn)`, `greg.off(hook)`, `greg.emit(hook, data)` | Subscribe to `GregEventDispatcher` events | +| **Harmony hooks** | `greg.hook.before(hook, fn)`, `greg.hook.after(hook, fn)` | Prefix/postfix on any Harmony-patched method | +| **Unity objects** | `greg.unity.find(type)`, `get_component()`, `instantiate()`, `destroy()` | Handle-based Il2Cpp object manipulation | +| **Properties** | `greg.unity.get_string(h, m)`, `set_number()`, `get_handle()` | Read/write object members by name | +| **Transform** | `greg.unity.position(h)`, `set_position()`, `set_local_scale()` | Spatial manipulation | +| **Materials** | `greg.unity.material_hex(h, prop)` | Read hex color from material properties | +| **TMPro / TextMesh** | `greg.unity.tmpro_set(...)`, `textmesh_set(...)` | Configure text labels | +| **Physics** | `greg.unity.raycast(...)`, `camera_ray()` | Raycasting | +| **IMGUI** | `greg.gui.box()`, `label()`, `button()`, `toggle()` | OnGUI drawing | +| **Input** | `greg.input.key_pressed(key)`, `key_down()`, `ctrl()` | Keyboard via InputSystem | +| **File I/O** | `greg.io.read_file()`, `write_file()`, `list_files()` | File system access | +| **Config** | `greg.config.load(path)`, `save()` | Key=value config files | +| **Color** | `greg.color.to_hex(r,g,b)`, `normalize_hex()`, `parse()` | Hex color utilities | + +Lua scripts define optional lifecycle functions: `on_update(dt)`, `on_scene(name)`, `on_gui()`. + +Full API reference: [Language Bridges README](https://github.com/mleem97/gregFramework/blob/main/gregCore/framework/ModLoader/LanguageBridges/README.md) + +## Rust / native FFI + +Native mods receive a `GameAPITable` on init and numeric `EventIds` via `mod_on_event`. Full lifecycle (update, scene load, shutdown) is managed by `FFIBridge` through `RustLanguageBridgeAdapter`. + +## Architecture + +- [Repository architecture](/wiki/framework/architecture) — language bridges, handle system, runtime layers +- [Modding language support](/wiki/reference/modding-language-requirement) — C#, Lua, Rust policies +- [Getting started](/wiki/getting-started)