docs: describe new architecture and event (#915)

TestingPlant · web-flow · commit bdac910ec18f · 2025-07-04T20:59:34.000Z
This reflects the changes made in #882 and #914. I have also adjusted the claim that Hyperion supports 170k+ players to 10k+ players. We do not currently have any benchmarks supporting the 170k+ player claim before or after the Bevy PR. I believe this number was extrapolated from the 5k player ms/tick, where (1.42 ms/tick)/(5k players) = (50 ms/tick)/(176k players [extrapolated]), but we do not have a real benchmark running 170k+ players.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -18,10 +18,6 @@ Essential tools to enhance your development workflow:
   - Debug and analyze Minecraft protocol packets
   - Essential for protocol-related development
 
-### Debugging
-- **[flecs.dev/explorer](https://flecs.dev/explorer)**
-  - View entities in the Entity Component System (ECS)
-
 ### Profiling
 - **[Tracy Profiler](https://github.com/wolfpld/tracy)**
   - Advanced performance profiling
diff --git a/README.md b/README.md
@@ -5,10 +5,10 @@
 [![Issues](https://img.shields.io/github/issues/andrewgazelka/hyperion)](https://github.com/andrewgazelka/hyperion/issues)
 [![Last Commit](https://img.shields.io/github/last-commit/andrewgazelka/hyperion)](https://github.com/andrewgazelka/hyperion/commits)
 
-Hyperion is a **Minecraft game engine** that can have 170,000+ players in one world. Our pilot event hopes to break the PvP Guinness World
+Hyperion is a **Minecraft game engine** that can have 10,000+ players in one world. Our pilot event hopes to break the PvP Guinness World
 Record of ([8825 by
 EVE Online](https://www.guinnessworldrecords.com/world-records/105603-largest-videogame-pvp-battle)). The
-architecture is ECS-driven using [Flecs Rust](https://github.com/Indra-db/Flecs-Rust).
+architecture is ECS-driven using [Bevy](https://bevy.org/).
 
 > [!NOTE]  
 > You can join the test server in 1.20.1 at `hyperion-test.duckdns.org`
@@ -63,13 +63,6 @@ https://github.com/user-attachments/assets/64a4a8c7-f375-4821-a1c7-0efc69c1ae0b
 - Commit hash `faac9117` run with `just release`
 - Bot Launch Command: `just bots {number}`
 
-**Note on Performance:**
-The system's computational costs are primarily fixed due to thread synchronization overhead. Each game tick contains
-several $O(1)$ synchronization points, meaning these operations maintain constant time complexity regardless of player
-count. This architecture explains why performance remains relatively stable even as player count increases
-significantly - the thread synchronization overhead dominates the performance profile rather than player-specific
-computations.
-
 The bulk of player-specific processing occurs in our proxy layer, which handles tasks like regional multicasting and can
 be horizontally scaled to maintain performance as player count grows.
 
@@ -83,7 +76,7 @@ be horizontally scaled to maintain performance as player count grows.
 flowchart TB
     subgraph GameServer["Game Server (↕️ Scaled)"]
         direction TB
-        subgraph FlecsMT["Flecs Multi-threaded ECS"]
+        subgraph BevyMT["Bevy Multi-threaded ECS"]
             direction LR
             IngressSys["Ingress System"] --> |"1 Game Tick (50ms)"| CoreSys["Core Systems (Game Engine)"] --> GameSys["Game Systems (Event Logic)"] --> EgressSys["Egress System"]
         end
@@ -138,7 +131,7 @@ flowchart TB
     classDef async fill:#e7e7e7,stroke:#333,stroke-width:2px
     
     class GameServer server
-    class FlecsMT ecs
+    class BevyMT ecs
     class IngressSys,CoreSys,GameSys,EgressSys system
     class Proxy1,Proxy2,ProxyN proxy
     class Velocity1,Velocity2,VelocityN auth
@@ -203,7 +196,7 @@ docker compose up --build
 
 **Language:** Rust  
 **Goal:** Game engine for massive events  
-**Structure:** flecs ECS
+**Structure:** Bevy ECS
 
 **Platform Details:**
 - Version: Minecraft 1.20.1
diff --git a/docs/architecture/game-server.md b/docs/architecture/game-server.md
@@ -7,16 +7,16 @@ flowchart TD
 subgraph Tokio_Tasks[Tokio Tasks]
 IT[I/O Tokio ingress task]
 ET[I/O Tokio egress task]
-HM[HashMap&lt;PlayerId, BytesMut&gt;]
+HM[HashMap&lt;PlayerId, packet_channel::Sender&gt;]
 IT --> HM
 end
 
 subgraph Processing_Systems[Processing Loop - 50ms]
 IS[Ingress System]
-RS[Run Events System]
+RS[Run packet handling systems]
 ES[Egress System]
 
-IS -->|" Decode & create borrowed events"|RS
+IS -->|" Decode & create Bevy events for each packet"|RS
 RS -->|State changes| ES
 ES -->|" local BytesMut "| ET
 ES -->|" Next tick (50ms) "|IS
@@ -62,83 +62,37 @@ pub struct Unicast<'a> {
 
 ## Ingress
 
-### Tokio Async Task
-The tokio async ingress task creates a data structure
-defined [here](https://github.com/andrewgazelka/hyperion/blob/0c1a0386548d71485c442cf5e9c9ebb2ed58142e/crates/hyperion/src/net/proxy.rs#L16-L23).
+### Packet Channel
 
-```rust
-#[derive(Default)]
-pub struct ReceiveStateInner {
-    /// All players who have recently connected to the server.
-    pub player_connect: Vec<u64>,
-    /// All players who have recently disconnected from the server.
-    pub player_disconnect: Vec<u64>,
-    /// A map of stream ids to the corresponding [`BytesMut`] buffers. This represents data from the client to the server.
-    pub packets: HashMap<u64, BytesMut>,
-}
-```
-
-### Decoding System
-
-Then, when it is time to run the ingress system, we lock the mutex for `ReceiveStateInner` and process the data,
-decoding all the packets until we get
-
-```rust
-#[derive(Copy, Clone)]
-pub struct BorrowedPacketFrame<'a> {
-    pub id: i32,
-    pub body: &'a [u8],
-}
-```
+The packet channel is a linked list of `Fragment`. Each fragment contains:
+- an incremental fragment id
+- a `Box<[u8]>` with zero or more contiguous packets with a `u32` length prefix before each packet
+- a read cursor, where `0..read_cursor` is ready to read and contains whole packets
+- an `ArcSwapOption<Fragment>` pointing to the next fragment if there is one
 
-where the `'a` lifetime is the duration of the entire tick (the `BytesMut` are deallocated at the end of the tick).
+As packets from the client are processed in the proxy thread, the server decodes the `VarInt` length prefix to
+determine the packet size. If there is enough space remaining in the current fragment, the packet bytes are copied to
+the current fragment. Otherwise, a new fragment will be allocated and appended to the linked list.
 
-### Event Generation
+The decoding system, running in separate threads, iterates through the linked list and reads packets up to the read
+cursor. These packets are decoded, sent through Bevy events, and then processed by other systems which read those
+events.
 
-For each entity's packet, we have a switch statement over what we should do for each
-packet [here](https://github.com/andrewgazelka/hyperion/blob/bb30c0680ef3822aa9a30d84e289c8db39e38150/crates/hyperion/src/simulation/handlers.rs#L609-L641).
+When a packet contains a reference to the original packet bytes, such as a chat message packet storing a reference to
+the message, we use `bytes::Bytes` and the variants made in `valence_bytes` (e.g. `valence_bytes::Utf8Bytes` which
+wraps a `bytes::Bytes` while guaranteeing that it is valid UTF-8) to allow the packet event to live for `'static` while
+only performing one copy[^3] throughout the entire ingress system.
 
-Note: all packet-switch logic is done in parallel (based on the number of threads) and which entity is partitioned
-on that thread.
-
-```rust
-pub fn packet_switch(
-    raw: BorrowedPacketFrame<'_>,
-    query: &mut PacketSwitchQuery<'_>,
-) -> anyhow::Result<()> {
-    let packet_id = raw.id;
-    let data = raw.body;
-
-    // ideally we wouldn't have to do this. The lifetime is the same as the entire tick.
-    // as the data is bump-allocated and reset occurs at the end of the tick
-    let data: &'static [u8] = unsafe { core::mem::transmute(data) };
-
-    match packet_id {
-        play::ChatMessageC2s::ID => chat_message(data, query)?,
-        play::ClickSlotC2s::ID => click_slot(data, query)?,
-        play::ClientCommandC2s::ID => client_command(data, query)?,
-        play::CommandExecutionC2s::ID => chat_command(data, query)?,
-        play::CreativeInventoryActionC2s::ID => creative_inventory_action(data, query)?,
-        play::CustomPayloadC2s::ID => custom_payload(data, query)?,
-        play::FullC2s::ID => full(query, data)?,
-        play::HandSwingC2s::ID => hand_swing(data, query)?,
-        play::LookAndOnGroundC2s::ID => look_and_on_ground(data, query)?,
-        play::PlayerActionC2s::ID => player_action(data, query)?,
-        play::PlayerInteractBlockC2s::ID => player_interact_block(data, query)?,
-        play::PlayerInteractEntityC2s::ID => player_interact_entity(data, query)?,
-        play::PlayerInteractItemC2s::ID => player_interact_item(data, query)?,
-        play::PositionAndOnGroundC2s::ID => position_and_on_ground(query, data)?,
-        play::RequestCommandCompletionsC2s::ID => request_command_completions(data, query)?,
-        play::UpdateSelectedSlotC2s::ID => update_selected_slot(data, query)?,
-        _ => trace!("unknown packet id: 0x{:02X}", packet_id),
-    }
-
-    Ok(())
-}
-```
+This custom channel is more performant than a traditional channel of `Box<[u8]>` because it allows reusing the same
+allocation for several packets, and most packets are very small.
 
 [^1]: the actual number is assigned at compile-time for maximum performance and is usually equal to the number of cores
 on the machine.
 
 [^2]: `bytes::BytesMut` re-uses the underlying buffer and tracks allocations and deallocations so allocations each tick
 are not needed.
+
+[^3]: The copy is done when copying from the proxy's `PlayerPackets` packet to the packet channel. Theoretically this
+could be made zero-copy by reading from the TCP stream directly into the packet channel, but this would be less
+performant because it would increase the number of read syscalls by requiring one read syscall per player, and
+syscalls are more expensive than small memory copies.
diff --git a/docs/architecture/introduction.md b/docs/architecture/introduction.md
@@ -19,14 +19,14 @@ approach differs from traditional Minecraft servers that modify vanilla implemen
 
 ### Entity Component System (ECS)
 
-Hyperion utilizes [Flecs](https://github.com/SanderMertens/flecs), an Entity Component System, as its core architecture:
+Hyperion utilizes [Bevy ECS](https://bevy.org/), an Entity Component System, as its core architecture:
 
 - Entities are organized in a table-like structure
     - Rows represent individual entities
     - Columns represent components (e.g., health, position)
 - Systems process entities through efficient iterations
 - Components can be dynamically added (e.g., LastAttacked component for combat)
-- For a more accurate representation of an ECS, see the [ECS FAQ](https://github.com/SanderMertens/ecs-faq)
+- For a more accurate representation of an ECS, see the [Unofficial Bevy Cheat Book](https://bevy-cheatbook.github.io/programming/ecs-intro.html)
 
 ### Performance Optimization
 
@@ -90,7 +90,7 @@ vanilla mechanics can be completely customized to create unique game modes and e
 
 Developers interested in using Hyperion should familiarize themselves with:
 
-- Entity Component Systems (particularly Flecs)
+- Entity Component Systems (particularly Bevy)
 - Minecraft networking protocols
 - Parallel processing concepts
-- Plugin development principles
+- Plugin development principles
diff --git a/docs/bedwars/introduction.md b/docs/bedwars/introduction.md
@@ -0,0 +1,9 @@
+# 10,000 Player PvP Event
+
+Our pilot event is a 10,000 player PvP battle to break the Guinness World Record for the largest PvP battle ever.
+
+We're partnering with [TheMisterEpic](https://www.youtube.com/channel/UCJiFgnnYpwlnadzTzhMnX_Q) to run an initial
+proof-of-concept event with around 2k players. Following its success, we'll host the full-scale 10,000 player PvP battle
+alongside numerous YouTubers and streamers.
+
+Our event will be a massive Bed Wars game consisting of teams with hundreds of players each.
diff --git a/docs/index.md b/docs/index.md
@@ -5,21 +5,19 @@ layout: home
 hero:
   name: "Hyperion"
   text: "The most advanced Minecraft game engine built in Rust"
-  tagline: 170,000 players in one world at 20 TPS
+  tagline: 10,000 players in one world at 20 TPS
   actions:
     - theme: brand
       text: Architecture
       link: /architecture/introduction
     - theme: alt
       text: 10,000 Player PvP
-      link: /tag/introduction
+      link: /bedwars/introduction
 
 features:
   - title: Run massive events with confidence
     details: Built in Rust, you can be highly confident your event will not crash from memory leaks or SEGFAULTS.
   - title: Vertical and horizontal scalability
     details: In our testing I/O is the main bottleneck in massive events. As such, we made it so I/O logic can be offloaded horizontally. The actual core game server is scaled vertically.
-  - title: Easy debugging profiling
-    details: All tasks are easily viewable in a tracing UI. All entities are viewable and modifiable from Flecs Explorer.
 ---
 
diff --git a/docs/tag/classes.png b/docs/tag/classes.png
diff --git a/docs/tag/introduction.md b/docs/tag/introduction.md
