88 lines
8.5 KiB
Markdown
88 lines
8.5 KiB
Markdown
## Context
|
|
|
|
`game.scum` currently declares a Windows client-manager package that is built from a Git repository. The replacement is not a user-built executable: it is a publisher-built UE4SS `main.dll` that UE4SS loads into SCUM during the normal server process startup. The supplied RCON project requires UE4SS EngineTick and therefore cannot be loaded by an external EXE or attached safely to an already running SCUM process.
|
|
|
|
The Platform already owns plugin manifest validation, runtime binding selection, lifecycle job dispatch, and safe browser DTOs. Run already owns bounded HTTPS dependency downloads, scoped workspaces, direct executable vectors, and lifecycle process supervision. Neither currently has a typed server DLL extension plan or a real RCON adapter.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
|
|
- Let a plugin declare a prebuilt Windows UE4SS DLL release and update policy without exposing user-side compilation, arbitrary commands, host paths, or secrets.
|
|
- Have Run synchronize the declared release automatically before each SCUM `process.start`, only after Platform has frozen the declaration into the leased job input.
|
|
- Stage the DLL atomically below a logical server workspace, preserve the previous managed DLL for rollback, generate a local-only RCON configuration, and load through the normal UE4SS startup chain.
|
|
- Expose safe declaration and synchronization state to the existing plugin/server management views.
|
|
- Reject Linux for this Windows DLL extension explicitly.
|
|
|
|
**Non-Goals:**
|
|
|
|
- Do not run a compiler, CMake, UE4SS source checkout, or arbitrary executable on an operator machine.
|
|
- Do not inject a live process, use `rundll32`, `LD_PRELOAD`, remote threads, manual mapping, or a generic DLL loader.
|
|
- Do not claim a Linux `.dll` equivalent. A future Linux `.so` loader is a separate, game-specific change.
|
|
- Do not delete or migrate existing client-manager installations automatically.
|
|
- Do not add per-command confirmation or persisted raw-command history for the future RCON console.
|
|
|
|
## Decisions
|
|
|
|
### Decision: Model the payload as a Windows UE4SS DLL extension, not a client manager or executable
|
|
|
|
The manifest adds `runtimeProfiles.dllExtensions`. A ready profile has a fixed release URL/checksum/size/version, Windows amd64 target, compatible SCUM executable checksum, UE4SS ABI marker, logical target key, update policy, and loopback health contract. `kind` is fixed to `ue4ss-dll`, `activation` is fixed to `server-start`, and `supportedTargets` is fixed to Windows amd64. An explicit `unpublished` declaration may document an intended release URL but cannot be selected by a lifecycle profile or frozen into a job; this prevents placeholder hashes from reaching an operator machine.
|
|
|
|
The SCUM manifest declares the extension while retaining legacy client-manager metadata for existing installations. New server starts use the extension profile rather than building a companion executable.
|
|
|
|
Alternative considered: reuse `clientManagers`. Rejected because a UE4SS DLL is loaded by SCUM rather than supervised as an independent component process.
|
|
|
|
### Decision: Synchronize within the existing `process.start` lifecycle job
|
|
|
|
Platform copies the selected DLL extension plan into the fenced start-job execution input. Run performs sync before it launches the server executable. The job is the automatic update check: every start compares the installed managed release checksum/version with the declaration and updates only when necessary.
|
|
|
|
This avoids a new always-on download poller, preserves control/job/log/artifact channel isolation, and means Run never obtains unleased plugin configuration. A version change takes effect at the next normal server start. Future scheduled maintenance can queue an ordinary restart/start lifecycle job.
|
|
|
|
Alternative considered: let Run periodically poll plugin URLs directly. Rejected because it makes Run independently trust mutable plugin configuration and consumes network/resources outside Platform job fencing.
|
|
|
|
### Decision: Use release-pinned, scoped, atomic deployment
|
|
|
|
Run accepts only HTTPS URLs with a declared `sha256:` checksum and a bounded size. It downloads to a per-server extension staging root, verifies bytes before activation, and replaces only the managed DLL path atomically. It records a small local managed-release marker and retains one previous DLL copy for rollback. It never extracts archives, follows unsafe redirects, or accepts arbitrary target paths.
|
|
|
|
The generated `config.ini` contains a locally supplied RCON password reference/value only in the protected server workspace; it is not returned to Platform, plugins, browser DTOs, artifacts, or logs. `mods.txt` is updated idempotently using the exact declared extension key. UE4SS bootstrap files are not silently installed by this first change; the extension reports a blocked health result when the expected UE4SS layout is absent.
|
|
|
|
Alternative considered: download a whole UE4SS/bootstrap package on every server. Rejected for the first release because shared loader ownership and rollback across other mods requires a separate extension-runtime manager.
|
|
|
|
### Decision: Windows-only activation and explicit Linux rejection
|
|
|
|
The supplied module links Windows APIs and produces a `.dll`. Windows activation is the standard UE4SS startup path: the already-installed UE4SS loader reads `mods.txt` and loads the DLL after SCUM starts. Run does not mount or execute the DLL itself.
|
|
|
|
Linux would require a separately built `.so`, an independently verified UE4SS/Linux loader path, and game-specific compatibility. Run returns `unsupported_extension_platform` for this profile on Linux and does not try `LD_PRELOAD`.
|
|
|
|
### Decision: Address compatibility is owned by the DLL release
|
|
|
|
Native SCUM executor addresses are not configured in Platform or Run. The publisher-built DLL holds the vetted resolver table keyed by SCUM executable compatibility data and fails closed when its native probe cannot resolve exactly once. Platform/Run only select the right declared DLL release by compatible SCUM executable checksum.
|
|
|
|
Alternative considered: Run-side signature scanning or automatic generation. Rejected because it would make the executor a reverse-engineering authority and could execute an incorrect native address.
|
|
|
|
### Decision: Safe UI projections and no raw command history
|
|
|
|
Plugin detail and server detail show release version, checksum prefix, loading mode, supported target, update-on-start policy, last safe sync state, and Linux incompatibility. They do not show raw paths, URLs with credentials, RCON passwords, Run sessions, or native signatures. A future RCON console is direct operator input with transient delivery; it is not a confirmation dialog or a persisted command-history feature.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- [A SCUM update changes native code] → DLL fails its internal probe; Run leaves the previous managed release in place and reports extension health unavailable rather than guessing an address.
|
|
- [A malicious/changed CDN response] → checksum, HTTPS validation, bounded size, and staged verification block activation.
|
|
- [UE4SS is not installed or incompatible] → sync completes the managed DLL only when safe, then reports a clear blocked health state; it does not copy proxy DLLs or alter shared loader files.
|
|
- [A server host has multiple instances] → extension target and port are scoped by the existing server workspace/runtime binding; no global path is projected.
|
|
- [Start job fails after update] → previous managed DLL is retained and a retry sees a coherent marker; full SCUM process rollback remains the existing lifecycle responsibility.
|
|
- [Linux host selected] → the job is rejected before download and UI projects the unsupported platform state.
|
|
|
|
## Migration Plan
|
|
|
|
1. Register a new `game.scum` manifest version with a Windows UE4SS extension profile and preserve legacy client-manager declarations.
|
|
2. On the next Windows start, Platform freezes the extension plan into the lifecycle job and Run syncs it before process launch.
|
|
3. Operators ensure the approved UE4SS runtime is already present once; the DLL and generated configuration are then managed automatically.
|
|
4. Roll back by publishing/reselecting the previous pinned DLL declaration and restarting the server; Run restores the previous managed DLL if activation fails.
|
|
5. Existing client-manager installations are not stopped, deleted, or migrated automatically.
|
|
|
|
## Open Questions
|
|
|
|
- A future change may manage the shared UE4SS bootstrap/runtime as a separately owned, reference-counted extension dependency.
|
|
- A future Linux SCUM/UE4SS `.so` implementation requires its own compatibility and loader design.
|