Hypersomnia

Hypersomnia is a community‑driven, multiplayer first‑person shooter written entirely in modern C++ without the aid of a commercial game engine. Its core engine is built on top of low‑level libraries such as SDL2 for windowing and input, OpenGL/Vulkan for rendering, and a custom networking stack that leverages UDP with reliable sequencing layers. The game’s architecture follows a modular Entity‑Component System (ECS) pattern, enabling rapid addition of new gameplay mechanics while keeping the runtime footprint minimal. This design choice makes Hypersomnia an attractive target for developers who want to understand and tweak the inner workings of a full‑scale shooter without the abstraction layers that typical engines impose.

Technical Stack

• Language & Build: C++20, compiled with GCC/Clang/MSVC; uses CMake for cross‑platform builds.
• Rendering: Dual backend support—OpenGL 4.5 and Vulkan—selected at runtime to accommodate a wide range of hardware.
• Audio: OpenAL Soft for 3D positional audio, with a custom mixing pipeline that supports spatialization and real‑time DSP.
• Networking: Proprietary UDP protocol with custom packet framing, out‑of‑order handling, and optional encryption via libsodium.
• Physics: Bullet Physics for collision detection and rigid‑body dynamics, exposed through a lightweight wrapper.
• Scripting & Extensibility: Lua 5.4 embedded for map scripting and modding; the engine exposes a C++ API that can be wrapped into higher‑level languages if needed.
• Data Persistence: JSON for configuration, SQLite3 for local player statistics and mod metadata.

Core Capabilities

• Real‑time Multiplayer: Peer‑to‑peer architecture with optional dedicated server mode; supports up to 64 concurrent players on a single host.
• Map Editor: Web‑based editor built with React and Three.js, enabling designers to create levels that compile into the game’s binary format.
• Modding API: Lua bindings allow mods to hook into events such as OnPlayerSpawn, OnWeaponFire, and OnMapLoad. Mods can also register custom assets (textures, models) via a simple ZIP manifest.
• Webhooks & REST: A lightweight HTTP server exposes endpoints for matchmaking, player stats retrieval, and dynamic content updates.
• Plugin System: At startup the engine scans a plugins/ directory; each plugin is a shared library (.dll/.so/.dylib) exposing an extern "C" initialization function.

Deployment & Infrastructure

Hypersomnia is designed for self‑hosting with minimal infrastructure overhead. The server component can run as a single binary on any Linux distribution, macOS, or Windows machine. For larger deployments, Docker images are available (see the CI pipeline badges in the README) and can be orchestrated via Kubernetes or Docker‑Compose. The networking stack is stateless except for the server’s player registry, making horizontal scaling straightforward: multiple instances can be load‑balanced behind a UDP‑aware proxy such as nginx with the stream module or a dedicated game server manager like GameLift.

Integration & Extensibility

The embedded Lua engine and exposed C++ hooks make Hypersomnia highly extensible. Developers can write server‑side plugins to integrate with external services (Discord bots, telemetry dashboards) or client‑side mods to add new weapons and visual effects. The RESTful API allows integration with custom matchmaking services, leaderboards, or continuous‑deployment pipelines that push new map packs automatically. Webhooks enable real‑time notifications for events such as player joins, kills, or match completions, which can be consumed by third‑party analytics tools.

Developer Experience

The project’s documentation is hosted on the official website and includes a comprehensive API reference, build guides, and a modding tutorial. The community is active on Discord and Telegram, providing quick support for both beginners and seasoned C++ developers. The use of standard open‑source libraries ensures that contributors can pull the code, inspect performance bottlenecks, and propose improvements through GitHub PRs. Licensing under AGPL v3 guarantees that any derivative work remains open, fostering a healthy ecosystem of shared mods and server tools.

Use Cases

• Academic Research: Students can study real‑time networking protocols, ECS design patterns, and low‑level rendering techniques by examining the source.
• Modding Communities: Hobbyist developers can create custom game modes, weapon skins, or entirely new maps using the Lua API and map editor.
• Self‑Hosted Gaming Clans: Teams can run private servers with full control over matchmaking, anti‑cheat policies, and data retention.
• Game Server Hosting Providers: The lightweight server binary and Docker support make it ideal for hosting services that want to offer dedicated FPS servers without the overhead of commercial engines.

Advantages

Hypersomnia offers a rare combination of performance, flexibility, and open licensing. By avoiding heavyweight engines, it delivers low latency gameplay on modest hardware while keeping the codebase approachable for contributors. The dual rendering backends ensure compatibility across legacy GPUs and modern Vulkan‑capable systems. Its plugin architecture and embedded scripting provide a robust modding pipeline that can be extended to integrate with external services or custom analytics. For developers seeking a fully open, self‑hosted FPS platform that