scum_simple_rcon_ue4ss/AGENTS.md

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

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.