# ntcd-lol/pse-lua architecture

> Architecture diagram of the GitHub repository ntcd-lol/pse-lua, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ntcd-lol/pse-lua
- Repository: https://github.com/ntcd-lol/pse-lua

## Overview

PSE SDK Lua embeds Lua 5.4 and provides a Fluent Lua interface to Portal Solver Editor (PSE), with an offline mock mode. The main workflow is to start the host, load the Lua SDK, issue game or object commands, and receive results or events through the bridge. The repository also documents game control, player and third-party objects, events, registers, and REPL/mock initialization. These capabilities are represented, but their internal Lua call paths are not asserted: the Lua SDK sources were not excerpted. The graph distinguishes the documented workflow from source-confirmed bridge behavior.

Main entry points: [`lua/sdk/api.lua`](https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/api.lua) (Fluent API), [`src/lua_core.cpp`](https://github.com/ntcd-lol/pse-lua/blob/main/src/lua_core.cpp) (Core Lua bridge), [`src/main.cpp`](https://github.com/ntcd-lol/pse-lua/blob/main/src/main.cpp) (Interpreter host), [`lua/sdk/init.lua`](https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/init.lua) (SDK initialization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Lua host"]
  node_host["Interpreter host<br/>[main.cpp]"]
  node_core["Core Lua bridge<br/>[lua_core.cpp]"]
end

subgraph group_sdk["Lua SDK"]
  node_sdkinit["SDK initialization<br/>[init.lua]"]
  node_api["Fluent API<br/>[api.lua]"]
  node_schema["Schemas<br/>[schema.lua]"]
  node_packing["Command packing<br/>[pack.lua]"]
  node_enums["Enums<br/>[enums.lua]"]
  node_logger["Logging<br/>[logger.lua]"]
  node_sdkcore["SDK core<br/>[core.lua]"]
  node_sdkregisters["Register API<br/>[registers.lua]"]
end

subgraph group_bridge["PSE connection"]
  node_mock[("Mock world<br/>[lua_core.cpp]")]
  node_bridgeimpl["Shared-memory bridge<br/>[pse_bridge.cpp]"]
  node_pse["PSE SDK"]
end

subgraph group_capabilities["SDK capabilities"]
  node_game["Game control<br/>[game.md]"]
  node_objects["Game objects"]
  node_events["Events<br/>[events.md]"]
  node_registers["Registers<br/>[registers.md]"]
end

node_user(("Script author"))
node_gameext(("Portal Solver"))

node_user -->|"runs script"| node_host
node_host -->|"loads SDK"| node_sdkinit
node_host -->|"registers core"| node_core
node_sdkinit -.->|"provides API"| node_api
node_api -.->|"controls"| node_game
node_api -.->|"builds objects"| node_objects
node_api -.->|"handles events"| node_events
node_api -.->|"accesses registers"| node_registers
node_core -->|"sends commands"| node_bridgeimpl
node_core -->|"simulates commands"| node_mock
node_bridgeimpl -->|"uses buffers"| node_pse
node_pse -->|"shares data"| node_gameext
node_core -.->|"exchanges commands"| node_gameext

click node_host "https://github.com/ntcd-lol/pse-lua/blob/main/src/main.cpp"
click node_core "https://github.com/ntcd-lol/pse-lua/blob/main/src/lua_core.cpp"
click node_sdkinit "https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/init.lua"
click node_api "https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/api.lua"
click node_game "https://github.com/ntcd-lol/pse-lua/blob/main/docs/game.md"
click node_objects "https://github.com/ntcd-lol/pse-lua/tree/main/docs/objects"
click node_events "https://github.com/ntcd-lol/pse-lua/blob/main/docs/events.md"
click node_registers "https://github.com/ntcd-lol/pse-lua/blob/main/docs/registers.md"
click node_schema "https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/schema.lua"
click node_packing "https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/pack.lua"
click node_enums "https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/enums.lua"
click node_logger "https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/logger.lua"
click node_sdkcore "https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/core.lua"
click node_sdkregisters "https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/registers.lua"
click node_mock "https://github.com/ntcd-lol/pse-lua/blob/main/src/lua_core.cpp"
click node_bridgeimpl "https://github.com/ntcd-lol/pse-lua/blob/main/src/pse_bridge.cpp"
click node_pse "https://github.com/ntcd-lol/pse-lua/tree/main/third_party/pse-sdk"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_host,node_core toneBlue
class node_sdkinit,node_api,node_schema,node_packing,node_enums,node_logger,node_sdkcore,node_sdkregisters toneAmber
class node_mock,node_bridgeimpl,node_pse toneMint
class node_game,node_objects,node_events,node_registers toneRose
class node_user,node_gameext toneIndigo
```

## Components

### Lua host

- [Interpreter host](https://github.com/ntcd-lol/pse-lua/blob/main/src/main.cpp): `src/main.cpp`
- [Core Lua bridge](https://github.com/ntcd-lol/pse-lua/blob/main/src/lua_core.cpp): `src/lua_core.cpp`

### Lua SDK

- [SDK initialization](https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/init.lua): `lua/sdk/init.lua`
- [Fluent API](https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/api.lua): `lua/sdk/api.lua`
- [Schemas](https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/schema.lua): `lua/sdk/schema.lua`
- [Command packing](https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/pack.lua): `lua/sdk/pack.lua`
- [Enums](https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/enums.lua): `lua/sdk/enums.lua`
- [Logging](https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/logger.lua): `lua/sdk/logger.lua`
- [SDK core](https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/core.lua): `lua/sdk/core.lua`
- [Register API](https://github.com/ntcd-lol/pse-lua/blob/main/lua/sdk/registers.lua): `lua/sdk/registers.lua`

### PSE connection

- [Mock world](https://github.com/ntcd-lol/pse-lua/blob/main/src/lua_core.cpp): `src/lua_core.cpp`
- [Shared-memory bridge](https://github.com/ntcd-lol/pse-lua/blob/main/src/pse_bridge.cpp): `src/pse_bridge.cpp`
- [PSE SDK](https://github.com/ntcd-lol/pse-lua/tree/main/third_party/pse-sdk): `third_party/pse-sdk`

### SDK capabilities

- [Game control](https://github.com/ntcd-lol/pse-lua/blob/main/docs/game.md): `docs/game.md`
- [Game objects](https://github.com/ntcd-lol/pse-lua/tree/main/docs/objects): `docs/objects`
- [Events](https://github.com/ntcd-lol/pse-lua/blob/main/docs/events.md): `docs/events.md`
- [Registers](https://github.com/ntcd-lol/pse-lua/blob/main/docs/registers.md): `docs/registers.md`

### Other components

- **Script author**
- **Portal Solver**

## Connections

- Script author → Interpreter host: runs script (evidence: `README.md`)
- Interpreter host → SDK initialization: loads SDK (evidence: `src/main.cpp`)
- Interpreter host → Core Lua bridge: registers core (evidence: `src/main.cpp`)
- SDK initialization → Fluent API: provides API
- Fluent API → Game control: controls
- Fluent API → Game objects: builds objects
- Fluent API → Events: handles events
- Fluent API → Registers: accesses registers
- Core Lua bridge → Shared-memory bridge: sends commands (evidence: `src/lua_core.cpp`)
- Core Lua bridge → Mock world: simulates commands (evidence: `src/lua_core.cpp`)
- Shared-memory bridge → PSE SDK: uses buffers (evidence: `src/pse_bridge.cpp`)
- PSE SDK → Portal Solver: shares data (evidence: `README.md`)
- Core Lua bridge → Portal Solver: exchanges commands
