init

AGENTS.md

@@ -0,0 +1,79 @@
+# Development guide
+
+This repository is a UE4SS C++ mod for a SCUM dedicated server. Its purpose is
+to provide a password-protected Source RCON endpoint while keeping all Unreal
+object work on the game's thread.
+
+## Runtime architecture
+
+```text
+RCON TCP worker
+  -> CommandQueue
+  -> EngineTick game-thread drain
+  -> ScumBridge
+       -> RealChatDispatcher       (ordinary SendChat)
+       -> OfflineAdminExecutor     (AdminCommand path)
+       -> server console fallback  (non-AdminCommand console commands)
+```
+
+- `RconServer` owns sockets, Source-RCON framing, authentication, and response
+  splitting. It must never create Unreal objects or call Unreal APIs.
+- `CommandQueue` is the sole boundary between RCON threads and the game thread.
+  Keep all `UObject` lookup, `ProcessEvent`, object creation, and command
+  execution inside its EngineTick drain.
+- `SimpleRconMod` exposes the internal diagnostics: `rcon.status`,
+  `rcon.admins`, `rcon.dispatch`, and `rcon.chat`.
+- `ScumBridge` routes `SendChat` before checking `AdminUsers.ini`; all other
+  game commands follow the admin/offline-dispatch route.
+
+## Admin-command route
+
+- `OfflineAdminExecutor` may create and reuse the synthetic
+  `BP_ConZPlayerController` and `ConZCharacter`. This exists only so native
+  SCUM `AdminCommand` execution can run with no human administrator online.
+- Read valid administrator SteamID64 values from
+  `SCUM/Saved/Config/WindowsServer/AdminUsers.ini`. Never hard-code one and
+  never substitute an arbitrary connected player or `PlayerRpcChannel`.
+- The selected ID must come from that file (the optional preferred ID is valid
+  only when also present there). Refresh a cached synthetic caller if the file
+  changes.
+- Resolve the native executor only through its exact, build-specific signature.
+  On zero or multiple matches, fail closed and report the problem; do not call a
+  guessed address or weaken the game's authorization check.
+
+## Ordinary-chat route
+
+`SendChat <type 0-7> "message" [SteamID64]` is deliberately not an
+`AdminCommand`.
+
+- It requires RCON authentication, but not `AdminUsers.ini`.
+- Resolve SCUM's real server-side entry point at runtime:
+  `MiscStatics:SendChatLineToPlayer`, its `Default__MiscStatics`, and
+  `ConZPlayerController:GetUserId`.
+- A targeted send must match the supplied SteamID64 against an actual loaded
+  `ConZPlayerController` whose inherited `Player` is a live `UNetConnection`.
+  A missing/offline target is an error.
+- A broadcast is a separate send to each such real online controller. `type`
+  controls the SCUM chat style; recipient scope comes from the optional
+  SteamID64, not from `type`.
+- Do not construct a chat controller, fabricate a network/RPC channel, use the
+  first `PlayerRpcChannel`, or impersonate a player. The SCUM helper receives
+  the real target controller and uses the game's own delivery path.
+- Inspect the UFunction parameter schema through reflection before calling it.
+  If SCUM changes the schema, reject the command and log the discovered schema
+  instead of guessing parameter offsets.
+
+## Change and test rules
+
+- Keep command parsing and messages UTF-8-safe. Quoted RCON arguments contain
+  spaces; do not append shell-style inline comments to command examples.
+- Keep `SendChat` semantics separate from notifications and admin commands.
+  An administrator may be offline; a chat recipient cannot be offline.
+- Update `README.md` and `INSTALL.md` with every externally visible behavior
+  change. Describe what this repository does; do not retain stale feature
+  comparison or proprietary-bundle claims.
+- Before committing, run `git diff --check`. On a Windows server built against
+  the deployed UE4SS ABI, test `rcon.status`, `rcon.admins`, `rcon.dispatch`,
+  `rcon.chat`, one targeted `SendChat`, and one broadcast `SendChat`.
+- macOS-only checks cannot validate the final DLL/SCUM ABI. Do not claim a
+  Windows runtime test passed until it has run on the target server.