# Hypersomnia **Repository Path**: chenbin2121/Hypersomnia ## Basic Information - **Project Name**: Hypersomnia - **Description**: No description available - **Primary Language**: Unknown - **License**: AGPL-3.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-12-02 - **Last Updated**: 2025-12-02 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
# ![Hypersomnia](hypersomnia/content/gfx/necessary/menu_game_logo.png) image # [▶ Play in the Browser!](https://hypersomnia.io/) [![Windows Build](https://github.com/TeamHypersomnia/Hypersomnia/actions/workflows/Windows_build.yml/badge.svg)](https://github.com/TeamHypersomnia/Hypersomnia/actions/workflows/Windows_build.yml) [![Linux build](https://github.com/TeamHypersomnia/Hypersomnia/actions/workflows/Linux_build.yml/badge.svg)](https://github.com/TeamHypersomnia/Hypersomnia/actions/workflows/Linux_build.yml) [![MacOS build](https://github.com/TeamHypersomnia/Hypersomnia/actions/workflows/MacOS_build.yml/badge.svg)](https://github.com/TeamHypersomnia/Hypersomnia/actions/workflows/MacOS_build.yml) [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) [![Telegram](https://img.shields.io/badge/Telegram-Join%20Chat-blue?logo=telegram)](https://t.me/hypersomnia_io) **The community-driven multiplayer shooter.** Challenge your friend to an intense duel, or gather two clans to fight a spectacular war. ### [▶ Watch Trailer](https://www.youtube.com/watch?v=L4zSA34fD_E "Video Title") Written in modern C++, **without a game engine!** Forever free and open-source :heart: *Comes with an [in-game map Editor!](https://hypersomnia.io/editor/official)* # Download the game | | | | | |:--:|:--:|:--:|:--:| | [Steam](https://store.steampowered.com/app/2660970/Hypersomnia) | [Windows](https://hypersomnia.xyz/builds/latest/Hypersomnia-for-Windows.zip) | [Linux](https://hypersomnia.xyz/builds/latest/Hypersomnia.AppImage) | [macOS](https://hypersomnia.xyz/builds/latest/Hypersomnia-for-MacOS.dmg) | Only 29 MB! The game will start with an **interactive Tutorial!** Run the [Server Docker](./README_SERVER.md#docker-setup) Or download Server AppImage *All archives are [digitally signed.](https://github.com/TeamHypersomnia/Hypersomnia/blob/master/src/signing_keys.h) You can [verify signatures.](https://hypersomnia.xyz/builds/latest/)* # Press | [](https://mastodon.social/@gamingonlinux/112609228144158828) | [GitHub Blog](https://github.blog/2024-01-18-game-bytes-january-2024/#hypersomnia-release-on-steam) | [](https://www.scribd.com/document/763273177/Linux-Magazine-October-2023-USA#page=89) | [](https://news.ycombinator.com/item?id=36469297) | |:--:|:--:|:--:|:--:| | [Liam @ GamingOnLinux](https://mastodon.social/@gamingonlinux/112609228144158828) | [GitHub Blog](https://github.blog/2024-01-18-game-bytes-january-2024/#hypersomnia-release-on-steam) | [Linux Magazine, Issue 275](https://www.scribd.com/document/763273177/Linux-Magazine-October-2023-USA#page=89) | [Hacker News Discussion](https://news.ycombinator.com/item?id=36469297) | #### *📰 Are you a journalist? [Click here!](https://github.com/TeamHypersomnia/PressKit/blob/main/README.md#intro)* ## Latest developer journals | | | |:--:|:--:| ## Join the community!
# Table of contents - [Introduction](#introduction) - [Tech highlights](#tech-highlights) - [Game guide](#game-guide) - [How to build](#how-to-build) - [Contributing](#contributing) - [Credits 🇵🇱](https://teamhypersomnia.github.io/PressKit/credits) - [The story behind the code](#the-story-behind-the-code) # Introduction ![Hypersomnia_discordthread](https://github.com/TeamHypersomnia/Hypersomnia/assets/3588717/1365f4a0-a517-4257-8148-8d01c3231635) Hypersomnia has been online and playable **since 2017**. It brings together: - the tactics of *Counter-Strike*, - the dynamics of *Hotline Miami*, - the pixel art nostalgia of oldschool RPGs... - ...and an **in-game map editor** lets you instantly playtest a **work-in-progress map** with your friends, **even behind a router!** - [▶ Learn how to make maps!](https://www.youtube.com/watch?v=q1rfIy06_xo) Today, we have **[24 unique firearms](https://hypersomnia.xyz/weapons)**, **[10 community maps](https://hypersomnia.xyz/arenas)**, and two game modes: *Bomb defusal* and *Gun game*. We aim to become ***the ultimate open-source shooter*** - a grand community project extensible without limit. Declare allegiance to one of the three factions whose apple of discord is a disparity between prevailing notions of moral excellence: **Metropolis. Atlantis. Resistance.** Will you take revenge for the unethical simulation of an inferior universe? Will you support the cruel experiments to win total control over metempsychosis? Or will you join the underground civilization that awaits the end of war in this dangerous afterlife reality? # Tech highlights - **[rectpack2D,](https://github.com/TeamHypersomnia/rectpack2D) written for packing textures, became famous and was used in [Assassin's Creed: Valhalla.](https://www.youtube.com/watch?v=2KnjDL4DnwM&t=2382s)** - Used also by [a drone manufacturing company](https://pages.skydio.com/rs/784-TUF-591/images/Open%20Source%20Software%20Notice%20v0.2.html) and in [2 scientific papers.](https://scholar.google.com/scholar?hl=en&as_sdt=0%2C5&q=teamhypersomnia&btnG=) - My Entity-Component-System **[idea from 2013](https://gamedev.stackexchange.com/questions/58693/grouping-entities-of-the-same-component-set-into-linear-memory/)** describes techniques similar to **[Unity Engine patent from 2018.](https://patents.google.com/patent/US10599560B2/en)** - **[See this discussion.](https://github.com/TeamHypersomnia/Hypersomnia/issues/264)** - Networking is based on **cross-platform simulation determinism**. It is 100% deterministic **even across browser** ***and*** **native clients** (Windows, Linux, MacOS) and that includes **native ARM builds (aarch64)!** - This technique is traditionally used by RTS games with hundreds of continuously moving soldier units. - It is impractical to continuously update every single one of them through the network. - Instead, only the player inputs are transmitted ("I moved mouse here", "I pressed this button") - the clients simulate *everything else* locally, on their own. Think playing chess with your friend over the phone. You won't ever say aloud the entire state of the chessboard, only the movements ("Queen to H5"). - But *Hypersomnia* is not an RTS - since it's physics-based, it uses *floats* heavily, not just *integers*. - When floating point calculations are involved, simulation determinism becomes **extremely hard.** - See why in this [excellent article by Glenn Fiedler.](https://gafferongames.com/post/floating_point_determinism/) - To achieve it in *Hypersomnia*, I had to: - Use the same compiler - ``clang`` - on **all** OSes. It's very nice of LLVM to be ieee754-compliant by default. - Pass ``/fp:strict`` for Windows builds. - Pass ``-ffp-model=strict`` for the ARM builds. - Replace all math functions like ``std::sin``, ``std::sqrt`` by these from [STREFLOP.](https://nicolas.brodu.net/programmation/streflop/index.html) - ..after which ``streflop::sqrt`` became a huge bottleneck - thankfully, I found another efficient [ieee754-compliant implementation.](https://github.com/TeamHypersomnia/Hypersomnia/blob/master/src/3rdparty/streflop/libm/flt-32/e_sqrtf.cpp) - Apart from worrying about floats.. - I had to watch out even when iterating ``std::unordered_map`` - often replacing them with deterministically ordered ``std::map``. - I had to use a [portable RNG (xorshift)](https://github.com/TeamHypersomnia/Hypersomnia/blob/master/src/augs/misc/xorshift.hpp), ditching the entire ```` header (its implementation differs across OSes). - Another magical trick was needed to ensure the **physics itself is fully deterministic:** - Problem: when a new client connects, it receives the initial physics state - but the packets contain just the body positions, rotations and velocities. - In particular, it doesn't contain the "hot" physics state such as the already tracked contacts, or the already built/balanced quadtree for fast collision detection. - What if there are already some players on the server, and several bodies overlap the moment a new player joins? - The new client will recreate the entire internal physics state on its own, using just the pos/vel/rotation data, but the contacts might be created in a different order than that of the existing clients! The fresh quadtree might end up completely different too from the one that has already seen many insertions/deletions during a long gaming session - so it might later report collisions in different order. - My solution was one of the greatest stroke of epiphany I ever experienced: - When a new client connects, **force already connected clients to completely rebuild the physics state from the positions, rotations and velocities as if they have just connected themselves.** *drops the mic* - As long as building the internal physics data from pos/vel/rotation data is deterministic, the in-game clients will have the *exact same state* as the newly connected client. - I apply the same principle in many other areas of networking. Throughout my codebase, I call this process *[cache reinference.](https://wiki.hypersomnia.xyz/reinference)* - All this would be very hard to pull off in a commercial engine, or straight impossible in a closed source one. - Yet in *Hypersomnia*, you can have thousands of dynamic crates or bullets on the map - as long as there are e.g. two player-controlled characters, the traffic will be around ``40 kbit/s (= 5 KB/s)`` under a tickrate of 60 Hz. **Only player-controlled characters** contribute to traffic. - Even the silliest details like bullet shells are fully synchronized *without* paying for it with network traffic. - As a bonus, lag is hidden exceptionally well as the game doesn't just mindlessly "extrapolate" frames visually - rather, it simulates the entire game world forward *offscreen* to accurately predict the future. - For the very curious - here's an [article from my old abandoned blog](https://teamhypersomnia.github.io/newscast/full-blown-networking-with-latency-hiding-for-physics), showing how I achieved this as early as in 2016. - Browser clients and native clients **can play on the same servers**, thanks to [libdatachannel](https://github.com/paullouisageneau/libdatachannel) and [datachannel-wasm](https://github.com/paullouisageneau/datachannel-wasm). - You can [host a server in the browser](https://hypersomnia.xyz/host) and connect to it with a native client... - ...and vice versa: host a server in the native client and send anyone the link to join from the browser! - In the browser version, you can **sign in with Discord** and play ranked matches to compete on the [global Leaderboards](https://hypersomnia.xyz/leaderboards)! - You can also [associate your Discord account with Steam account](https://hypersomnia.xyz/profile) so that the Steam version and web version **share the same rating!** - You can host a working game server *from the main menu* - the game is able to **forward ports out of the box!** - Cute fish and insect AI **[with flocking behaviors.](https://www.youtube.com/watch?v=0vlUOO5l0jw)** Full source: [movement_path_system.cpp.](https://github.com/TeamHypersomnia/Hypersomnia/blob/master/src/game/stateless_systems/movement_path_system.cpp) - These too are synchronized through the network! - Other players see fish and insects in the same positions, even though they **do not contribute to network traffic.** - Fish and insects react to shots and explosions! - And once they're scared, they keep closer to members of the same species. - Anyone can host **[the entire *Hypersomnia* server infrastructure.](https://github.com/TeamHypersomnia/Hypersomnia-admin-shell)** - The Editor, the game server *and* the masterserver (server list keeper) are **all embedded in the same game executable**, on every OS. - You could run a separate server list for your own community around a completely modded version of *Hypersomnia*! - Memory pool [implementation](https://github.com/TeamHypersomnia/Hypersomnia/blob/master/src/augs/misc/pool/pool.h) with: - **Contiguous storage**. - All game objects in existence are kept **linearly in memory** (in a simple ``std::vector``). - It means blazing-fast iteration of all game objects of the same type, as well as trivial pool serialization. - **O(1)** allocation (mostly a glorified ``push_back``). - **O(1)** free (via ``std::swap`` with the last element and ``pop_back`` - a very known idiom). - **O(1)** dereference. - The *only* caveat being: a dereference involves **four** reads from memory (instead of just **one** with a direct pointer and **two** with a pointer + array index): - It has to first read the ``indirection_array`` pointer **(1)**. - The indirection array contains the current index of the requested object within the vector of all allocated objects. - This index is located at ``indirection_array[identifier]`` **(2)**. - Then it reads the actual ``objects`` vector pointer **(3)**. - Finally, it reads the object itself at ``objects[indirection_array[identifier]]`` **(4)**. - (Note that the ``objects`` and ``indirection_array`` will usually be cached already so subsequent dereferences will be reduced to two fetches from RAM at most). - This works because ``indirection_array`` is kept up-to-date whenever objects are allocated or removed. - **Fully resizable**. You don't have to pass a maximum pool size. It will expand on its own. - **Fully deterministic.** Given the same sequence of allocations and frees starting from a given initial pool state, the allocations will produce the same integer identifiers and objects will have exactly the same order in the linear memory. - When a client connects and the server sends it the initial world state, it includes the entire **internal state** of the game object pools. - It means the pools themselves are *a part of the game simulation* - I don't have to send any "creation" notification events through the network whenever entities are created as the clients **deterministically simulate allocations on their own** resulting in identical object identifiers as well as their orders in memory. - **Perfectly undoable allocations and frees.** - The Editor requires all commands to implement a deterministic undo/redo, especially ones that create or delete a resource. - Suppose you create a custom Material in the editor and it now has an integer identifier ``I``. - You later set this Material to some walls on the scene. The walls now refer to identifier ``I``. - Now you want to undo all the way back to before you even created the Material. - The Material gets deleted from the pool. - Now you actually want to *redo* all of these commands back. - You first redo the Material allocation command. - But if the pool uses a non-undoable allocation scheme, the material could now be allocated with the id ``I+1``. - This means that the subsequent commands (that alter the walls material) will set an identifier that is now invalid - ``I``. - To solve this problem, my memory pool implementation provides ``undo_last_allocate`` apart from the standard ``free``. It's used by the commands that have to undo creating a resource (which means deleting it). It will free the object in a way that the next allocation will result in an identical integer id and internal pool state (with allocated objects order) as before freeing the resource. It is an optional feature for the sake of editor commands that is never used during actual gameplay. Analogously, there is an ``undo_last_free``. - Built-in self-updater: the game will download and apply updates automatically. ![image](https://github.com/TeamHypersomnia/Hypersomnia/assets/3588717/0479fca0-f836-4f6a-b5a5-dc2317bb4b95) - Not only that, [it will verify](https://github.com/TeamHypersomnia/Hypersomnia/blob/master/src/application/main/verify_signature.h) that the update came from the hardcoded [developer public key](https://github.com/TeamHypersomnia/Hypersomnia/blob/master/src/signing_keys.h), with a call to ``ssh-keygen``. - If the [build hosting](https://hypersomnia.xyz/builds/latest/) were hacked and a malicious game version uploaded, the existing game clients **will refuse** to apply the updates. - ..and I'm signing builds **offline with a [Trezor hardware wallet](https://github.com/TeamHypersomnia/Hypersomnia-admin-shell/blob/master/developer_sign_file.sh).** This is how *every* update looks like on my end: https://github.com/TeamHypersomnia/Hypersomnia-admin-shell/assets/3588717/c4d0764e-382f-45db-bc13-c626723e47e1 - **Discord** and **Telegram** notifications when: - a new game version is deployed, ![image](https://github.com/TeamHypersomnia/Hypersomnia/assets/3588717/0725d856-0b9d-47c8-a76a-ea3a887318e9) - players connect, - a 1v1 "duel of honor" begins (auto-detected whenever there's only 1 player per faction), ![image](https://github.com/TeamHypersomnia/Hypersomnia/assets/3588717/ca286048-989a-4289-afd0-bb991c63b8ad) - community server is hosted, ![image](https://github.com/TeamHypersomnia/Hypersomnia/assets/3588717/7c543b0c-7239-4cd9-947b-503001c7f2b6) - or a match comes to an end. This includes full player stats and the MVP. ![image](https://github.com/TeamHypersomnia/Hypersomnia/assets/3588717/2cc549f4-3dc7-4b6d-aca4-85c60bb6cafc) - Beautifully simple JSON format for the game maps. This short json: ```json { "settings": { "ambient_light_color": [53, 25, 102, 255] }, "nodes": [ { "id": "floor", "type": "dev_floor_128", "pos": [640, 0], "size": [1536, 1536] }, { "id": "light", "type": "point_light", "color": [255, 165, 0, 255], "pos": [100, 100], "radius": 700 }, { "id": "wall", "type": "dev_wall_128", "pos": [-384, 0], "size": [512, 1536] }, { "id": "crate", "type": "crate", "pos": [64, 448] }, { "id": "wood1", "type": "hard_wooden_wall", "pos": [192, -192] }, { "id": "wood2", "type": "hard_wooden_wall", "pos": [561.819, 206.436], "size": [384, 128], "rotation": -15 }, { "id": "aquarium", "type": "aquarium", "pos": [1408, 0], "rotation": 90 }, { "id": "baka1", "type": "baka47", "pos": [698, -8] }, { "id": "baka2", "type": "baka47", "pos": [454, -264] } ] } ``` Instantly produces: ![image](https://github.com/TeamHypersomnia/Hypersomnia/assets/3588717/b108f985-fe79-4a7d-8708-4f1d1da7b93e) - And speaking of the Editor.. - It's created with the excellent [ImGui](https://github.com/ocornut/imgui). - You're working *directly* on the game world. 100% WYSIWYG. - Supports custom resources. It's enough to paste folders with PNGs, WAVs, OGGs to the map directory.. - ..alt-tab back to the game and it will automatically pick it up! ![image](https://github.com/TeamHypersomnia/Hypersomnia/assets/3588717/8d5300fa-18cc-4979-9487-88f3b05a517a) - Supports GIFs as well! Just drag&drop them on the scene and they will be animated in-game, right out of the box! - It's possible to playtest a *work-in-progress map* with **a single click**: ![image](https://github.com/TeamHypersomnia/Hypersomnia/assets/3588717/1744ed72-612a-4af1-afbc-1a9d0c5750b3) - After which you instantly appear in the game's server browser: ![image](https://github.com/TeamHypersomnia/Hypersomnia/assets/3588717/3d8dbd53-3f84-40fe-9847-1c3ac0df1780) - You will enter the game as the host. - The connecting clients will automatically download the map in its current version with all its custom resources *(like in CS 1.6)*. - And they can later **create their own remake** - maps are saved in JSON, after all! - ESC will let you stop the session and go back to the Editor **exactly as you left it**, enabling ultra-efficient iteration cycles. - This is possible because the server, the game and the editor are **all within the same executable.** - The official Discord will also be notified that you're playtesting a map, so others can join in on the fun! - The Editor took well over a year to implement. - It paid off big time - there is now a neat [catalogue of community maps](https://hypersomnia.xyz/arenas) - every one of them downloadable. # Game guide *(Main article: [GUIDE.md](GUIDE.md))* # How to build *(Main article: [BUILDING.md](BUILDING.md))* # Contributing *(Also check out the [AGENTS.md](AGENTS.md) file - while a guide for the machines, humans should respect it just as well!)* Pull requests are welcomed, should they even be typo fixes or missing const guarantees. If you plan to add a completely new feature, create a relevant [issue](https://github.com/TeamHypersomnia/Hypersomnia/issues) so that everybody knows about it, because the project is continuously in a very, very active development and may undergo a revolution when it is the least expected. A WIP documentation can be found at [wiki](https://wiki.hypersomnia.xyz). Make sure to check out [TeamHypersomnia](https://github.com/TeamHypersomnia) for other repositories that are useful when setting up your own custom servers. If you have questions or you fail to build *Hypersomnia*, reach out on [Discord](https://discord.gg/YC49E4G). Or if you just can't wait to utter some brilliant ideas with regard to the game, please do so, too! # The story behind the code *Hypersomnia* has been in development **since 2013** (as seen in the commit history). It didn't take 10 years of uninterrupted coding, though - in the meantime, I worked commercially to cover my costs of living. I saved money to be able to work less and focus on *Hypersomnia*. My financial decisions now let me develop the game full-time. I use a lot of 3rdparty libraries like ``Box2D`` (physics) or ``yojimbo`` (transport layer) - [everything not on this list,](https://github.com/TeamHypersomnia/Hypersomnia/tree/master/src/3rdparty) however, is written pretty much from scratch, in pure C++. Many believe that writing games without an engine is no more than *reinventing the wheel*, or put more bluntly, a complete waste of time. **I hope this project serves as a great testament to the opposite.** Had I never embarked on this journey, I would have never made some of the interesting discoveries detailed in [Tech highlights section.](#tech-highlights) Video game internals are just so vast and interdisciplinary that they have limitless potential for creative breakthroughs, and it is a waste to never even entertain the idea that some widely used solutions can be replaced by something absolutely ingenious. ### Contact [Email](mailto:patryk.czachurski@gmail.com) To reach me on **Matrix**, you can hop onto [FOSSGralnia chat](https://matrix.to/#/#FOSSGralnia.gamedev:noevil.pl) (I'm friends with them) and ping `@pythagoras`.