feat: packet handling functions

[andrewgazelka]

I think it makes a lot of sense to have the ability to add handlers for any packets. Why is this useful? There are a couple of reasons. First, we want people to have as much access as possible, as close to the server as possible. If we’re creating events that rely on ingress packets but aren't 1:1 (lose some information), it restricts the ability of the engine.

Examples where handlers could be nice:

• Replay mod: Imagine having a handler that inspects every single packet and serializes it to disk for replay purposes. This would be excellent for capturing every player’s actions. We need a way to add a handler for this scenario. If we were designing a replay system, such a handler might need to operate on a dynamic trait—one that can handle newly added packets in the future. It would be interesting to explore this idea in future designs.

Potential global handler on top of specific handlers

I believe it could be viable to also have single handler for every packet that implements serialization—or to mandate that all packets implement serialization. Packets already implement encode and decode in the current code, so this approach would be quite natural. As the project evolves, we might want to revisit how events are handled. Perhaps providing no default events and implementing them as standalone modules would be more efficient. We could refactor the event system in the server and assign a dedicated handler for each function.

Events and lifetimes

As part of this refactoring, ensuring events are handled safely is critical. Currently, the code converts bytes to a 'static lifetime, but ideally, the handler should use bytes with a lifetime 'a, and the event sender should also produce events tied to 'a rather than 'static. This may require some changes to how decode and encode traits are defined in Valence, but I’m open to adjustments if they align with the broader design goals. Thank you.

flowchart TD
    classDef module fill:#e1f5fe,stroke:#01579b
    classDef handler fill:#fff3e0,stroke:#ff6f00
    classDef feature fill:#f3e5f5,stroke:#7b1fa2
    classDef lifetime fill:#ffebee,stroke:#c62828

    NetworkInput[Incoming Network Packets]
    GlobalHandler[Global Packet Handler]:::handler
    SerializationTrait[Serialization Trait]:::module
    SpecificHandlers[Specific Packet Handlers]:::handler
    ReplayMod[Replay Module]:::feature
    CustomHandler[Custom Event Handler]:::feature
    EventSystem[Event System]:::module
    LifetimeA[Lifetime 'a]:::lifetime
    StaticLifetime[Static Lifetime]:::lifetime

    NetworkInput --> GlobalHandler
    GlobalHandler --> SerializationTrait
    GlobalHandler --> SpecificHandlers
    
    SpecificHandlers --> ReplayMod
    SpecificHandlers --> CustomHandler
    SpecificHandlers --> EventSystem
    
    ReplayMod --> |Serializes to Disk| Storage[(Storage)]
    
    subgraph Lifetimes
        LifetimeA --> |Current Implementation| StaticLifetime
        LifetimeA --> |Proposed Implementation| EventSystem
    end

    subgraph Potential Use Cases
        ReplayMod
        CustomHandler
    end

    subgraph Handlers
        GlobalHandler
        SpecificHandlers
    end

Loading

[github-actions]

Benchmark Results for general

ray_intersection/aabb_size_0.1                     [  22.1 ns ...  22.1 ns ]      -0.04%
ray_intersection/aabb_size_1                       [  22.1 ns ...  22.1 ns ]      +0.10%
ray_intersection/aabb_size_10                      [  22.8 ns ...  22.8 ns ]      -0.10%
ray_intersection/ray_distance_1                    [   5.1 ns ...   5.2 ns ]      +1.98%
ray_intersection/ray_distance_5                    [   9.6 ns ...   9.6 ns ]      -0.00%
ray_intersection/ray_distance_20                   [   9.6 ns ...   9.6 ns ]      +0.10%
overlap/no_overlap                                 [  31.2 ns ...  31.2 ns ]      -0.07%
overlap/partial_overlap                            [  31.1 ns ...  31.1 ns ]      -0.06%
overlap/full_containment                           [  23.8 ns ...  23.8 ns ]      +0.04%
point_containment/inside                           [   5.9 ns ...   5.9 ns ]      +0.09%
point_containment/outside                          [   5.3 ns ...   5.3 ns ]      -0.01%
point_containment/boundary                         [   5.8 ns ...   5.7 ns ]      -0.17%

Comparing to f9788b0

[github-actions]

Benchmark Results for general

ray_intersection/aabb_size_0.1                     [  22.0 ns ...  22.0 ns ]      -0.06%
ray_intersection/aabb_size_1                       [  22.1 ns ...  22.1 ns ]      -0.06%
ray_intersection/aabb_size_10                      [  22.9 ns ...  22.9 ns ]      -0.28%
ray_intersection/ray_distance_1                    [   5.1 ns ...   5.1 ns ]      -0.22%
ray_intersection/ray_distance_5                    [   9.6 ns ...   9.6 ns ]      +0.06%
ray_intersection/ray_distance_20                   [   9.6 ns ...   9.6 ns ]      +0.10%
overlap/no_overlap                                 [  30.1 ns ...  31.0 ns ]      +3.16%
overlap/partial_overlap                            [  31.2 ns ...  30.2 ns ]      -3.11%
overlap/full_containment                           [  22.7 ns ...  22.7 ns ]      -0.06%
point_containment/inside                           [   5.9 ns ...   5.9 ns ]      +0.18%
point_containment/outside                          [   5.3 ns ...   5.3 ns ]      +0.05%
point_containment/boundary                         [   5.7 ns ...   5.8 ns ]      +0.18%

Comparing to f9788b0

[github-actions]

Benchmark Results for general

ray_intersection/aabb_size_0.1                     [  22.0 ns ...  22.1 ns ]      +0.10%
ray_intersection/aabb_size_1                       [  22.1 ns ...  22.1 ns ]      +0.14%
ray_intersection/aabb_size_10                      [  22.8 ns ...  22.7 ns ]      -0.13%
ray_intersection/ray_distance_1                    [   5.1 ns ...   5.1 ns ]      +0.00%
ray_intersection/ray_distance_5                    [   9.6 ns ...   9.6 ns ]      -0.06%
ray_intersection/ray_distance_20                   [   9.6 ns ...   9.6 ns ]      +0.07%
overlap/no_overlap                                 [  31.3 ns ...  31.3 ns ]      +0.01%
overlap/partial_overlap                            [  31.0 ns ...  30.1 ns ]      -2.90%
overlap/full_containment                           [  22.9 ns ...  22.8 ns ]      -0.39%
point_containment/inside                           [   5.9 ns ...   5.9 ns ]      -0.02%
point_containment/outside                          [   5.3 ns ...   5.3 ns ]      -0.21%
point_containment/boundary                         [   5.7 ns ...   5.7 ns ]      -0.04%

Comparing to f9788b0