Diff: BackroomsEngine

{{Infobox project|name=BackroomsEngine|type=Native game engine and dedicated server runtime|status=Pre-public-release development|language=C++20|build system=CMake, vcpkg|platform=Windows client and dedicated server, Linux-oriented server support|main targets=BackroomsMMO, BackroomsServer, BackroomsTests|related=[[BackroomsMMO]], [[BackroomsHost]], [[BackroomsVideo]]}}

'''BackroomsEngine''' is the native C++ game engine, client runtime, dedicated server runtime, and tooling layer used by [[BackroomsMMO]]. It provides the playable game executable, server authority, networking, rendering, world generation, chunk streaming, audio, voice, replay capture, mod support, model tools, launcher components, load testing tools, and regression tests that support the BackroomsMMO platform.

The engine is a C++20 CMake project with vcpkg-managed dependencies. It is structured as a shared common engine library, renderer library, native bridge, multiple applications, server utilities, tools, assets, docs, and tests. The main MMO executable is called '''BackroomsMMO''', while the dedicated server target is called '''BackroomsServer'''. The test target is '''BackroomsTests'''.

BackroomsEngine is not just a rendering experiment. It contains gameplay systems, persistent state structures, world authority, online client and server classes, replay formats, social systems, chat, voice, private instance travel, procedural generation, asset loading, mod package validation, and deployment-facing server setup tools.

== Overview ==

BackroomsEngine is the native side of the BackroomsMMO stack. It is responsible for the realtime work that cannot be handled by the web application: rendering frames, processing input, streaming chunks, simulating gameplay, moving players, connecting to online shards, sending and receiving network messages, recording replays, loading game assets, and running dedicated server authority.

The project builds several executable targets. The important targets include '''BackroomsMMO''' for the main 3D frontend, '''BackroomsServer''' for dedicated shards, '''BackroomsReplayPlayer''' for replay playback, '''BackroomsModels''' for model workflows, '''BackroomsAnimator''' for animation work, '''BackroomsModsTool''' for mod packaging, '''BackroomsLauncher''' and '''BackroomsClientBootstrap''' for client distribution, '''BackroomsAdmin''' and '''BackroomsMessage''' for operator-facing utilities, '''BackroomsLoadBot''' for load testing, '''BackroomsRealbotDashboard''' for realbot monitoring, and '''BackroomsTests''' for regression coverage.

The build also defines static libraries such as '''BackroomsEngineCommon''' and '''BackroomsEngineRendererGame''', plus a native shared library called '''BackroomsEngineNative'''. The common library contains cross-cutting engine systems. The renderer library contains renderer-facing game support. The native library exposes a smaller native API around the engine.

== Build System and Dependencies ==

BackroomsEngine uses CMake 3.20 or newer and requires C++20. Its CMake configuration includes strict warning helpers, optional warning-as-error support, sanitizer switches for non-MSVC builds, Windows header hygiene definitions, runtime asset copying, shader copying, DirectX compiler runtime copying, FBX converter copying, and optional server-only builds.

The vcpkg manifest identifies the project as '''backrooms-engine''' version '''0.1.0-dev'''. Dependencies include GLFW, stb, fmt, spdlog, nlohmann-json, xxHash, Asio, ENet, OpenSSL, libsodium, zstd, LZ4, Protobuf, SQLite3, Recast Navigation, concurrentqueue, jemalloc, GLM, and EnTT. These choices reflect a realtime multiplayer engine with networking, serialisation, compression, crypto, asset loading, navigation, memory and queue performance, and entity or data-oriented systems.

On Windows, the build enables a DirectX 12 path and copies the required DXC runtime DLLs when found in the Windows SDK. Runtime shaders are synchronised into the build directory. Game and replay targets copy runtime assets after build. The project also contains Linux-oriented server support and dedicated server compatibility notes for Ubuntu 24.04.

== Source Tree ==

The source tree is split into application folders, engine core folders, native bridge code, tools, documents, assets, models, materials, textures, audio, mods, prefabs, saved data, and reports. Application folders include game, server, tests, launcher, admin, replay player, models, animator, message, loadbot, mods tool, game wrapper, client bootstrap, desktop shared utilities, and realbot dashboard.

The engine core is divided into systems such as audio, assets, animation, AI, chat, config, game, instances, modding, networking, paranormal events, performance, replay, rendering, save, social, UI, utility code, and world streaming. This layout reflects a broad runtime rather than a narrow renderer-only project.

The docs folder contains implementation ledgers, renderer audits, refactor passes, MMO authority notes, server hardening notes, world generation fixes, client join stability work, website authentication readiness, private download test logs, model usage reports, mod tool documentation, and asset format documentation. These documents show an ongoing hardening and refactoring process.

== Client Runtime ==

The BackroomsMMO executable is the main 3D game frontend. Its sources include game bootstrap, renderer bootstrap, graphics profile handling, frontend storage, bodyguard behaviour, door and instance logic, input and UI handling, replay capture, online login, online server browser, challenge mode, environmental devices, BackroomsVideo RTMP publishing, and admin runtime command handling.

The client connects to BackroomsMMO.com for login, bootstrap, server lists, join tickets, characters, social data, assets, and runtime metadata. It then connects to a BackroomsServer shard for gameplay. Client stats track authentication state, server name, MOTD, version, reject reasons, admin flags, authority flags, persistent state, synced characters, join shard data, UDP state transport, authoritative world config, and online runtime timings.

The client also receives online representations of remote players, mimic entities, noclip events, paranormal events, biotic orb snapshots, state broadcasts, and authority corrections. This makes the client a realtime renderer and input surface for a server-directed world rather than a standalone owner of MMO state.

== Dedicated Server Runtime ==

BackroomsServer is the dedicated server target. Its source includes setup, bootstrap, runtime, install, config, and local control panel code. The server runtime class is described in source comments as a transitional dedicated-server runtime for the website-backed MMO flow. It enforces stricter authority and content validation than earlier local test code while remaining lightweight compared with a large-scale production shard runtime.

The server can start and stop from online settings, pump network work, track active clients, distinguish authenticated gameplay clients from load-test clients, manage worker counts, report pending chunk builds and authority jobs, apply runtime settings, and expose runtime status. It supports local console administration and website-mediated moderation actions.

Administrative controls include listing clients, kicking, banning, unbanning, freezing, unfreezing, teleporting one player or all players, setting client vitals, damaging clients, applying or stopping bleeding, igniting or extinguishing players, killing clients, finding clients, and changing spawn position. These controls are also represented in website command structures so web admin tools can control shards without exposing a separate public admin port.

The server also captures player snapshots for the website. Snapshots include account id, username, instance id, position, rotation, avatar id, flashlight state, frozen state, admin flag, map visibility flags, floor, level key, level name, zone name, chunk key, safe room id, and permissions. Atlas chunk snapshots support live map and exploration-style features.

== Website Authentication Integration ==

BackroomsEngine integrates with BackroomsMMO.com through online website authentication structures and helper code. The native client can send website credentials to the web service, receive session data, and use it for online play. The dedicated server can verify tokens and consume join tickets with the website before accepting a player.

The engine's website auth structures include bootstrap shard data, server browser data, heartbeat configuration, runtime metrics, heartbeat players, atlas chunks, server commands, website characters, persistent state, voice consent snapshots, and related online responses. This gives the native runtime a typed view of the web control plane.

The authentication flow is designed so the dedicated server does not trust locally fabricated account identifiers. Admin status and permissions come from the website. This is important for game moderation, access gating, official shard integrity, and private server membership.

== Networking and Authority ==

The engine uses online client and server classes, ENet-oriented transport support, network messages, socket abstractions, anti-cheat helpers, admin structures, content sync, online auth caches, website auth operations, and online server modules. The online server contains modules for pumping clients, synthetic load, persistence and room state, logging and identity, inventory and characters, voice mimic and noclip, and other authority work.

Authority flags cover loot, persistence, inventory, vitals, chat, movement, combat, currency, trade, party systems, clan chat, and voice runtime behaviour. The client tracks whether movement or vitals corrections were received. The server tracks metrics such as movement corrections, chat accept or reject counts, state patches, persists, loot requests, loot grants, combat accept or reject counts, trade requests, and completed trades.

The engine includes a UDP state transport path with TCP fallback counters. It tracks UDP state packets, broadcasts, send failures, bytes sent, and bytes received. This allows realtime state to be delivered efficiently while retaining fallback behaviour and diagnostics.

BackroomsEngine has a deterministic world generation system. World configuration supports basic levels and infinite deterministic generation. The configuration includes seed, instance doors, shared-edge door openings, loot spots, props, edge corridors, biome control, chunk size, render distance, simulation distance, visual prefetch distance, commit budgets, predictive forward streaming, and data-driven world assets.

World assets include floor, ceiling, wall, door, light, and prop tokens. World generation templates provide a higher-level authoring preset that can swap structural assets, clutter, and loot spots per level or biome. The generator can fill missing assets with built-in Backrooms defaults and can serialise configurations to JSON or binary.

The world generator produces chunk data with tile types, placed objects, biome ids, floors, doors, instance doors, loot markers, props, and deterministic edge plans. It is designed so edge doors and edge corridors match from either side of a chunk boundary. That keeps corridors and doors consistent across streamed chunks.

The world streaming system controls loaded chunks around the player. It computes priority rings, submits generation and mesh-building jobs, commits finished chunks on the main thread under strict budgets, evicts old chunks, tracks pending jobs, supports simulation and visual-only requests, supports floor layers, and can operate in authoritative mode.

World streaming includes render distance, simulation distance, visual prefetch distance, priority radius, predictive lookahead, max commits per frame, eviction limits, LRU age limits, request throttles, pending job soft and hard limits, deferred collider installation, and listeners for chunk commit or eviction. This lets other systems mirror chunk lifetime for GPU uploads, navigation caches, physics colliders, or gameplay state.

Authoritative mode allows the server or streamed authority payloads to upsert or remove chunks. Recent stability work kept world stream maintenance active during authoritative mode, added proximity filtering for streamed upserts, filtered chunk rendering near the player, hardened mesh extraction, rejected invalid GPU uploads, and adjusted scene resource retirement to reduce device loss during heavy chunk churn.

== Rendering ==

BackroomsEngine contains a renderer facade focused on the game and editor runtime. On Windows, the build uses DirectX 12 and copies shader compiler runtime components. The renderer code is split into modules for frame lifecycle, scene passes, post passes, UI compositing, renderer configuration, public API, and private state.

The renderer has been hardened around raster rendering, shadows, lighting, reflections, hybrid ray tracing and replay path-tracing wiring, shader compile startup behaviour, safe startup fallback behaviour, and device-lost prevention during heavy streaming. The project documentation describes a preference for a coherent single DirectX 12 code path for the primary runtime rather than maintaining multiple partial graphics paths.

BackroomsEngine also has graphics profile handling and test tooling for singleplayer graphics tests and graphics settings matrices. This matters because BackroomsMMO needs a client that can adjust graphics settings while preserving stable runtime behaviour.

== Assets and Model Pipeline ==

The engine's preferred runtime model format is GLB. GLTF is also supported for loose development assets with external buffers or textures. FBX is accepted as an import format through a bundled FBX2glTF converter. When the engine receives an FBX path, it converts the asset once, stores the generated GLB in a per-user cache, and then loads the cached GLB through the normal model loader.

Asset code includes an asset database, asset manager, asset resolver, model loader, texture preload cache, GLTF loader modules, material parsing, transform and accessor parsing, scene geometry extraction, and IO or buffer handling. Tools in the repository import and normalise asset packs, repair poolrooms assets, split GLB files by mesh, reduce large GLB assets, generate quality coverage, and optimise player avatar runtime models.

The engine includes applications for model browsing and animation work. The BackroomsModels and BackroomsAnimator targets share the common engine and renderer libraries, giving the project internal tools for asset iteration rather than forcing every check through the full game client.

BackroomsEngine's game state includes gameplay config, world config, dungeon templates, ambience, director state, players, identities, account saves, account and character progression, missions, alignment state, reputation state, stashes, challenges, safe hubs, clan state, safe rooms, respawn anchors, map exploration, discovered doors, searched loot spots, chalk marks, blood traces, investigation evidence, waypoints, chat, safety tracking, admin world effects, and paranormal triggers.

This state shows the kind of game BackroomsMMO is building: exploration, survival, support roles, persistent characters, safe rooms, clues, routes, missions, factions, reputation, clans, loot, combat, social play, and world events. The native engine owns the immediate simulation and serialisation logic, while the website and server authority decide how much of that state is persisted or validated online.

The game code also contains bodyguard AI and support behaviour. Bodyguard systems include movement, survival, search, doors, target selection, room search, completion, behaviour, lifecycle, and HUD support. Challenge mode includes lobby, run, objectives, rewards, summary, player scoring, difficulty, and observed life state structures.

== Audio, Chat, and Voice ==

BackroomsEngine includes audio systems, audio banks, acoustics, lightweight audio decoding, runtime audio output, and voice systems. Chat supports channels such as world, local, party, and clan. Voice structures include voice frames, voice config, voice state, playback, runtime capture, remote speaker state, voice mimic consent snapshots, and mimic clip storage.

Voice matters in BackroomsMMO because it can cross into personal data. The engine can capture and represent voice frames, but website services manage consent, clip uploads, clip selection, usage reporting, and consent refresh. This split allows the runtime to provide a feature while the account service stores user-facing consent state.

The engine includes replay capture and replay playback. The replay ring stores recent snapshots at a configured capture rate and time window. Snapshots include fixed tick, time, floor index, instance id, camera pose, player positions, velocities, health, stamina, sanity, hunger, thirst, shields, armour, life state, selected hotbar slot, flashlight state, and biotic orb snapshots.

The replay system can also append audio events and voice frames. Audio events store event id, asset path, bus, position, volume, pitch, pan, spatial state, and loop state. Voice frames store account id, timestamp, sample rate, channels, gain, pan, echo values, radio state, and payload. The website then stores, converts, publishes, or exports these replay files through BackroomsMMO.com and BackroomsVideo integrations.

== Modding ==

BackroomsEngine contains a modding system and a dedicated BackroomsModsTool executable. The tool can create, validate, pack, install, list, enable, disable, and self-test `.brmod` packages. Mods can include scripts, models, textures, audio, and prefabs.

The built-in script format is intentionally small. Supported commands include logging, healing, damage, food and water changes, and paranormal triggers such as walkby, peek, whisper, thump, and flicker. Content-only mods are valid.

The mod runtime policy is context-aware. Singleplayer and private servers can allow mods if configured. Official BackroomsMMO servers block mods even if local configuration is edited. Native binary mods remain blocked unless explicitly enabled because they execute trusted code. Packages reject unsafe paths, installers, shell scripts, path escapes, and undeclared native binaries, and installation uses staging so failed installs do not partially overwrite an existing mod.

== Server Setup and Deployment Tools ==

BackroomsEngine includes dedicated server setup and install tools. Server code can prepare local paths, generate runtime configuration, run local control panels, install or update runtime files, and cooperate with website-provided manifests. PowerShell and shell tools support human demo recording, local online performance profiling, distributed realbot load, graphics setting matrices, private download packaging, Linux server installer smoke tests, and singleplayer graphics tests.

BackroomsMMO.com handles the web deployment and control-plane packaging side. The engine handles the native executable and server runtime side. Together, they support a workflow where a website can manage host nodes, generate a control-plane package, deploy supporting services, provide runtime manifests, and keep dedicated servers reporting back through heartbeats.

== Performance and Load Testing ==

BackroomsEngine contains performance and load-testing infrastructure. The server tracks worker threads, authority jobs, async chunk builds, pending jobs, submitted and completed work, tick timing, packet jitter, network bytes, CPU migrations, context switches, softirq counts, movement corrections, chat outcomes, state patches, loot grants, combat outcomes, and trade outcomes.

Synthetic load support can configure target client count, chunk radius, floor spread, movement speed, and related counters. The BackroomsLoadBot target and distributed realbot tooling support broader online testing. Local online performance profile scripts build and run both the dedicated server and game client to exercise auth, connection, streaming, and runtime behaviour.

== Security and Validation ==

BackroomsEngine has several validation and hardening points. Website auth prevents a client from inventing trusted account identity. Dedicated server verification derives admin state and permissions from the website. Runtime authority reduces the amount of gameplay state trusted from clients. Content manifest enforcement and asset delivery checks reduce mismatch risk. Mod policy blocks official server modding. Replay sanitisation and package validation protect files and outputs.

The renderer and streaming systems also include defensive checks. Recent work rejects invalid chunk surfaces and unsafe GPU mesh uploads before creating buffers. World stream filtering prevents stale or distant chunks from flooding runtime scene caches. These are not security features in the account sense, but they are important hardening measures for stability.

== Testing and QA ==

The BackroomsTests target contains regression tests for world seeds, doors, themed generation, poolrooms and dungeon generation, runtime AI and audio, props and stairs, gameplay saves, chunk world runtime, avatar models, trade, party, clan systems, voice, TAudio, materials and audio, local online performance harnesses, camera audio animation, bodyguard AI, acoustic systems, and more.

The wider repository contains QA and predeploy scripts that build selected engine targets and run targeted regressions before release work. BackroomsMMO.com also has website smoke tests for access gates, respawn authority, control-plane packaging, private server export, and private server seed handling. This reflects the cross-boundary nature of the project: the engine can pass native tests, the website can pass web tests, and the product still needs integrated checks.

BackroomsEngine is under active pre-public-release development. The source and docs show frequent refactor passes, renderer hardening, online authority upgrades, server diagnostics, control-plane sync work, world streaming fixes, Ubuntu server compatibility work, and client join stability improvements.

The project should be understood as a current-format engine for BackroomsMMO, not as a compatibility layer for older public releases. Its own workspace instructions state that pre-public-release work should prefer clean current formats and remove stale paths rather than keeping backwards-compatibility branches unless specifically requested.

* [[BackroomsHost]]

* [[BackroomsVideo]]