{"id":23408468,"url":"https://github.com/hyperion-mc/hyperion","last_synced_at":"2025-04-10T14:20:43.429Z","repository":{"id":225726157,"uuid":"765572754","full_name":"hyperion-mc/hyperion","owner":"hyperion-mc","description":"Minecraft game engine for massive custom events","archived":false,"fork":false,"pushed_at":"2025-03-31T22:21:37.000Z","size":5814,"stargazers_count":672,"open_issues_count":24,"forks_count":27,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-05T12:02:35.680Z","etag":null,"topics":["ecs","flecs","game-server","high-performance","minecraft","multiplayer","rust"],"latest_commit_sha":null,"homepage":"http://hyperion.rs","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperion-mc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"andrewgazelka","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2024-03-01T07:28:41.000Z","updated_at":"2025-04-04T14:41:31.000Z","dependencies_parsed_at":"2024-11-09T03:22:49.324Z","dependency_job_id":"024accd2-5169-4022-a489-5700c4bc7d76","html_url":"https://github.com/hyperion-mc/hyperion","commit_stats":null,"previous_names":["andrewgazelka/mc-server","andrewgazelka/hyperion","hyperion-mc/hyperion"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperion-mc%2Fhyperion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperion-mc%2Fhyperion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperion-mc%2Fhyperion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperion-mc%2Fhyperion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperion-mc","download_url":"https://codeload.github.com/hyperion-mc/hyperion/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248233935,"owners_count":21069493,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ecs","flecs","game-server","high-performance","minecraft","multiplayer","rust"],"created_at":"2024-12-22T15:06:21.259Z","updated_at":"2025-04-10T14:20:43.421Z","avatar_url":"https://github.com/hyperion-mc.png","language":"Rust","readme":"# Hyperion\n\n[![Discord invite link](https://dcbadge.vercel.app/api/server/PBfnDtj5Wb)](https://discord.gg/PBfnDtj5Wb)\n[![Discord invite link](https://dcbadge.vercel.app/api/server/GxtzEJfSQe)](https://discord.gg/GxtzEJfSQe)\n[![Documentation](https://img.shields.io/badge/docs-online-green)](https://hyperion.rs/)\n[![Issues](https://img.shields.io/github/issues/andrewgazelka/hyperion)](https://github.com/andrewgazelka/hyperion/issues)\n[![Last Commit](https://img.shields.io/github/last-commit/andrewgazelka/hyperion)](https://github.com/andrewgazelka/hyperion/commits)\n\nHyperion is a **Minecraft game engine** that can have 170,000+ players in one world. Our pilot event hopes to break the PvP Guinness World\nRecord of ([8825 by\nEVE Online](https://www.guinnessworldrecords.com/world-records/105603-largest-videogame-pvp-battle)). The\narchitecture is ECS-driven using [Flecs Rust](https://github.com/Indra-db/Flecs-Rust).\n\n\u003e [!NOTE]  \n\u003e You can join the test server in 1.20.1 at `hyperion-test.duckdns.org`\n\nhttps://github.com/user-attachments/assets/64a4a8c7-f375-4821-a1c7-0efc69c1ae0b\n\n\n## Feature Status\n\n| Feature                      | Status                                                                                                                                                                                        | Notes                                                                                                        |\n|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|\n| **Technical Infrastructure** |                                                                                                                                                                                               |                                                                                                              |\n| 🧵 Multi-threading           | ✅ Implemented                                                                                                                                                                                 | Vertical scaling                                                                                             |\n| 🔄 Proxy Layer               | ✅ Implemented                                                                                                                                                                                 | Horizontal scaling                                                                                           |\n| 📊 Performance Tracing       | ✅ Implemented                                                                                                                                                                                 | Using Tracy profiler                                                                                         |\n| 🛡️ Basic Anti-Cheat         | ✅ Implemented                                                                                                                                                                                 | Core anti-cheat functionality                                                                                |\n| 🔧 Moderator Tools           | 🚧 WIP [#425](https://github.com/andrewgazelka/hyperion/issues/425), [@Kumpelinus](https://github.com/Kumpelinus)                                                                             | Admin controls and monitoring                                                                                |\n| 🔌 Plugin API                | ✅ Implemented                                                                                                                                                                                 | Extensible plugin system; see [`events/tag`](https://github.com/andrewgazelka/hyperion/tree/main/events/tag) |\n| **Core Game Mechanics**      |                                                                                                                                                                                               |                                                                                                              |\n| 🧱 Block Breaking/Placing    | ✅ Implemented                                                                                                                                                                                 | Including physics simulation                                                                                 |\n| 💫 Entity Collisions         | ✅ Implemented                                                                                                                                                                                 | Both entity-entity and block-entity                                                                          |\n| 💡 Lighting Engine           | ✅ Implemented                                                                                                                                                                                 | Dynamic lighting updates                                                                                     |\n| 🌐 World Borders             | ✅ Implemented                                                                                                                                                                                 | Configurable boundaries                                                                                      |\n| 🛠️ Block Edit API           | ✅ Implemented                                                                                                                                                                                 | WorldEdit-like functionality                                                                                 |\n| ⚔️ PvP Combat                | ✅ Implemented                                                                                                                                                                                 | Custom combat mechanics                                                                                      |\n| 🎒 Inventory System          | ✅ Implemented                                                                                                                                                                                 | Full item management                                                                                         |\n| 🎯 Raycasting                | ✅ Implemented | Required for ranged combat/arrows                                                                            |\n| **Player Experience**        |                                                                                                                                                                                               |                                                                                                              |\n| ✨ Particle Effects           | ✅ Implemented                                                                                                                                                                                 | Full particle support                                                                                        |\n| 💬 Chat System               | ✅ Implemented                                                                                                                                                                                 | Global and proximity chat                                                                                    |\n| ⌨️ Commands                  | ✅ Implemented                                                                                                                                                                                 | Custom command framework                                                                                     |\n| 🎤 Proximity Voice           | ✅ Implemented                                                                                                                                                                                 | Using Simple Voice Chat                                                                                      |\n\n## Benchmarks\n\n| Players | Tick Time (ms) | Core Usage (%) | Total CPU Utilization (%) |\n|---------|----------------|----------------|---------------------------|\n| 1       | 0.24           | 4.3            | 0.31                      |\n| 10      | 0.30           | 10.3           | 0.74                      |\n| 100     | 0.46           | 10.7           | 0.76                      |\n| 1000    | 0.40           | 15.3           | 1.09                      |\n| 5000    | 1.42           | 35.6           | 2.54                      |\n\n\n![performance](https://github.com/user-attachments/assets/d15f2e72-eeef-4cfd-af39-e90d72732968)\n\n\n**Test Environment:**\n\n- Machine: 2023 MacBook Pro Max 16\" (14-cores)\n- Chunk Render Distance: 32 (4225 total)\n- Commit hash `faac9117` run with `just release`\n- Bot Launch Command: `just bots {number}`\n\n**Note on Performance:**\nThe system's computational costs are primarily fixed due to thread synchronization overhead. Each game tick contains\nseveral $O(1)$ synchronization points, meaning these operations maintain constant time complexity regardless of player\ncount. This architecture explains why performance remains relatively stable even as player count increases\nsignificantly - the thread synchronization overhead dominates the performance profile rather than player-specific\ncomputations.\n\nThe bulk of player-specific processing occurs in our proxy layer, which handles tasks like regional multicasting and can\nbe horizontally scaled to maintain performance as player count grows.\n\n![image](https://github.com/user-attachments/assets/65fc6d7b-7e73-44e0-afac-cae928d443b6)\n\n\n## Architecture\n\n### Overview\n```mermaid\nflowchart TB\n    subgraph GameServer[\"Game Server (↕️ Scaled)\"]\n        direction TB\n        subgraph FlecsMT[\"Flecs Multi-threaded ECS\"]\n            direction LR\n            IngressSys[\"Ingress System\"] --\u003e |\"1 Game Tick (50ms)\"| CoreSys[\"Core Systems (Game Engine)\"] --\u003e GameSys[\"Game Systems (Event Logic)\"] --\u003e EgressSys[\"Egress System\"]\n        end\n        \n        TokioIO[\"Tokio Async I/O\"]\n        TokioIO --\u003e IngressSys\n        EgressSys --\u003e TokioIO\n    end\n    \n    subgraph ProxyLayer[\"Proxy Layer (↔️ Scaled)\"]\n        direction TB\n        Proxy1[\"Hyperion Proxy\"]\n        Proxy2[\"Hyperion Proxy\"]\n        ProxyN[\"Hyperion Proxy\"]\n        \n        MulticastLogic[\"Regional Multicasting\"]\n    end\n    \n    subgraph AuthLayer[\"Authentication\"]\n        Velocity1[\"Velocity + ViaVersion\"]\n        Velocity2[\"Velocity + ViaVersion\"]\n        VelocityN[\"Velocity + ViaVersion\"]\n    end\n    \n    Player1_1((Player 1))\n    Player1_2((Player 2))\n    Player2_1((Player 3))\n    Player2_2((Player 4))\n    PlayerN_1((Player N-1))\n    PlayerN_2((Player N))\n    \n    TokioIO \u003c--\u003e |\"Rkyv-encoded\"| Proxy1\n    TokioIO \u003c--\u003e |\"Rkyv-encoded\"| Proxy2\n    TokioIO \u003c--\u003e |\"Rkyv-encoded\"| ProxyN\n    \n    Proxy1 \u003c--\u003e Velocity1\n    Proxy2 \u003c--\u003e Velocity2\n    ProxyN \u003c--\u003e VelocityN\n    \n    Velocity1 --\u003e Player1_1\n    Velocity1 --\u003e Player1_2\n    Velocity2 --\u003e Player2_1\n    Velocity2 --\u003e Player2_2\n    VelocityN --\u003e PlayerN_1\n    VelocityN --\u003e PlayerN_2\n    \n    classDef server fill:#f96,stroke:#333,stroke-width:4px\n    classDef proxy fill:#9cf,stroke:#333,stroke-width:2px\n    classDef auth fill:#fcf,stroke:#333,stroke-width:2px\n    classDef ecs fill:#ff9,stroke:#333,stroke-width:3px\n    classDef system fill:#ffd,stroke:#333,stroke-width:2px\n    classDef async fill:#e7e7e7,stroke:#333,stroke-width:2px\n    \n    class GameServer server\n    class FlecsMT ecs\n    class IngressSys,CoreSys,GameSys,EgressSys system\n    class Proxy1,Proxy2,ProxyN proxy\n    class Velocity1,Velocity2,VelocityN auth\n    class TokioIO async\n```\n\n### Proxy\n\n```mermaid\nsequenceDiagram\n    participant P as Player\n    participant PH as Proxy Handler\n    participant SB as Server Buffer\n    participant R as Reorderer\n    participant B as Broadcast System\n    participant S as Game Server\n\n    Note over P,S: Player → Server Flow (Direct)\n    P-\u003e\u003ePH: Player Packet\n    PH-\u003e\u003eS: Forward Immediately\n    \n    Note over P,S: Server → Player Flow (Buffered)\n    S-\u003e\u003eSB: Server Packets\n    SB--\u003e\u003eSB: Accumulate Packets\n    S-\u003e\u003eSB: Flush Signal\n    SB-\u003e\u003eR: Batch Transfer\n    R--\u003e\u003eR: Reorder by Packet ID\n    R-\u003e\u003eB: Ordered Packets\n    \n    Note over B: Broadcasting Decision\n    alt Local Broadcast\n        B-\u003e\u003eP: Send to nearby players (BVH)\n    else Global Broadcast\n        B-\u003e\u003eP: Send to all players\n    else Unicast\n        B-\u003e\u003eP: Send to specific player\n    end\n```\n\n\n## Running\n\n### Without cloning\n\n```bash\ncurl -L https://raw.githubusercontent.com/hyperion-mc/hyperion/main/docker-compose.yml | docker compose -f - up --pull always\n```\n\n### `main` branch\n\n```bash\ndocker compose up --pull always\n```\n\n### With local build (for development)\n\n```bash\ndocker compose up --build\n```\n\n## Features\n\n**Language:** Rust  \n**Goal:** Game engine for massive events  \n**Structure:** flecs ECS\n\n**Platform Details:**\n- Version: Minecraft 1.20.1\n- Proxy Support: Velocity\n- Proximity Voice: Simple Voice Chat\n- Max estimated player count: ~176,056\n\n**Note:** This feature list represents core functionality. Hyperion is designed to be modular meaning you can implement\nyour own mechanics and replace the core mechanics with your own.\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=andrewgazelka/hyperion\u0026type=Date)](https://star-history.com/#andrewgazelka/hyperion\u0026Date)\n\n\nThank you for your hard work[^1] [@CuzImClicks](https://github.com/CuzImClicks), [@Indra-db](https://github.com/Indra-db), [@james-j-obrien](https://github.com/james-j-obrien), [@Ruben2424](https://github.com/Ruben2424), [@SanderMertens](https://github.com/SanderMertens), [@Tebarem](https://github.com/Tebarem), and [@TestingPlant](https://github.com/TestingPlant).\n\n\n[^1]: alphabetically ordered\n\n","funding_links":["https://github.com/sponsors/andrewgazelka"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperion-mc%2Fhyperion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperion-mc%2Fhyperion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperion-mc%2Fhyperion/lists"}