Expand description
§Horizon Event System
A high-performance, type-safe event system designed for game servers with plugin architecture and advanced Game Object Replication Channels (GORC) for multiplayer state management.
§Core Features
- Type Safety: All events are strongly typed with compile-time guarantees
- Async/Await Support: Built on Tokio for high-performance async operations
- Plugin Architecture: Clean separation between core server and plugin events
- GORC Integration: Advanced object replication with zone-based subscriptions
- Instance Management: Object-specific events with direct instance access
- Network Optimization: Intelligent batching, compression, and priority queuing
- Spatial Awareness: Efficient proximity-based replication and subscriptions
- Performance Monitoring: Comprehensive statistics and health reporting
§Architecture Overview
The system is organized into several integrated components:
§Core Event System
- Core Events (
core:*): Server infrastructure events - Client Events (
client:namespace:event): Messages from game clients - Plugin Events (
plugin:plugin_name:event): Inter-plugin communication - GORC Events (
gorc:object_type:channel:event): Object replication events - Instance Events (
gorc_instance:object_type:channel:event): Instance-specific events
§GORC Replication System
- Object Instances: Individual game objects with unique zones
- Zone Management: Multi-channel proximity-based replication
- Network Engine: Optimized batching and delivery
- Subscription System: Dynamic player subscription management
§Quick Start Example
use horizon_event_system::*;
use std::sync::Arc;
// Mock server context for example
struct MyServerContext;
impl context::ServerContext for MyServerContext {}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create the complete GORC system
let server_context = Arc::new(MyServerContext);
let (events, mut gorc_system) = create_complete_horizon_system(server_context)?;
// Register event handlers
events.on_core("player_connected", |event: PlayerConnectedEvent| {
println!("Player {} connected", event.player_id);
Ok(())
}).await?;
// Register GORC instance handlers with object access
events.on_gorc_instance("Asteroid", 0, "position_update",
|event: GorcEvent, instance: &mut ObjectInstance| {
if let Some(asteroid) = instance.get_object_mut::<gorc::examples::ExampleAsteroid>() {
println!("Asteroid {} moved to {:?}", event.object_id, asteroid.position());
}
Ok(())
}
).await?;
// Register game objects
let asteroid = gorc::examples::ExampleAsteroid::new(Vec3::new(100.0, 0.0, 200.0), gorc::MineralType::Platinum);
let asteroid_id = gorc_system.register_object(asteroid, Vec3::new(100.0, 0.0, 200.0)).await;
// Add players
let player1_id = PlayerId::new();
gorc_system.add_player(player1_id, Vec3::new(50.0, 0.0, 180.0)).await;
// Run the main game loop
loop {
// Process GORC replication
gorc_system.tick().await?;
// Emit core events
events.emit_core("tick", &ServerTickEvent {
tick_number: 12345,
timestamp: current_timestamp(),
}).await?;
tokio::time::sleep(tokio::time::Duration::from_millis(16)).await; // ~60 FPS
}
}§Plugin Development with GORC
use horizon_event_system::*;
use std::sync::Arc;
struct AsteroidMiningPlugin {
gorc_system: Arc<gorc::CompleteGorcSystem>,
}
impl AsteroidMiningPlugin {
fn new(gorc_system: Arc<gorc::CompleteGorcSystem>) -> Self {
Self { gorc_system }
}
}
#[async_trait::async_trait]
impl plugin::SimplePlugin for AsteroidMiningPlugin {
fn name(&self) -> &str { "asteroid_mining" }
fn version(&self) -> &str { "1.0.0" }
async fn register_handlers(&mut self, events: Arc<EventSystem>) -> Result<(), plugin::PluginError> {
// Handle asteroid discovery events
events.on_gorc_instance("Asteroid", 3, "composition_discovered",
|event: GorcEvent, instance: &mut ObjectInstance| {
if let Some(asteroid) = instance.get_object::<gorc::examples::ExampleAsteroid>() {
println!("Discovered {:?} asteroid with {} minerals",
asteroid.mineral_type, asteroid.radius);
}
Ok(())
}
).await?;
// Handle player mining actions
events.on_client("mining", "start_mining", |event: RawClientMessageEvent| {
// Process mining start request
Ok(())
}).await?;
Ok(())
}
}
// create_simple_plugin!(AsteroidMiningPlugin);Re-exports§
pub use api::create_complete_horizon_system;pub use api::create_simple_horizon_system;pub use utils::create_horizon_event_system;pub use utils::current_timestamp;pub use traits::SimpleGorcObject;pub use traits::SimpleReplicationConfig;pub use gorc_macros::GorcZoneData;pub use monitoring::HorizonMonitor;pub use monitoring::HorizonSystemReport;pub use context::LogLevel;pub use context::ServerContext;pub use context::ServerError;pub use plugin::Plugin;pub use plugin::PluginError;pub use plugin::SimplePlugin;pub use shutdown::ShutdownState;pub use events::Event;pub use events::EventError;pub use events::EventHandler;pub use events::GorcEvent;pub use events::Dest;pub use events::PlayerConnectedEvent;pub use events::PlayerDisconnectedEvent;pub use events::PlayerMovementEvent;pub use events::RawClientMessageEvent;pub use events::RegionStartedEvent;pub use events::RegionStoppedEvent;pub use events::TypedEventHandler;pub use events::PluginLoadedEvent;pub use events::PluginUnloadedEvent;pub use events::AuthenticationStatusGetResponseEvent;pub use events::AuthenticationStatusChangedEvent;pub use events::AuthenticationStatusSetEvent;pub use events::AuthenticationStatusGetEvent;pub use events::ClientEventWrapper;pub use system::EventSystem;pub use system::EventSystemStats;pub use system::DetailedEventSystemStats;pub use system::HandlerCategoryStats;pub use system::ClientConnectionRef;pub use system::ClientResponseSender;pub use system::ClientConnectionInfo;pub use gorc::GorcObject;pub use gorc::GorcObjectId;pub use gorc::ObjectInstance;pub use gorc::GorcInstanceManager;pub use gorc::ReplicationChannel;pub use gorc::ReplicationLayer;pub use gorc::ReplicationLayers;pub use gorc::ReplicationPriority;pub use gorc::CompressionType;pub use gorc::GorcManager;pub use gorc::GorcConfig;pub use gorc::GorcStats;pub use gorc::PerformanceReport;pub use gorc::ObjectZone;pub use gorc::ZoneManager;pub use gorc::ZoneAnalysis;pub use gorc::ZoneConfig;pub use gorc::SpatialPartition;pub use gorc::SpatialQuery;pub use gorc::RegionRTree;pub use gorc::NetworkReplicationEngine;pub use gorc::ReplicationCoordinator;pub use gorc::NetworkConfig;pub use gorc::NetworkStats;pub use gorc::ReplicationUpdate;pub use gorc::ReplicationBatch;pub use gorc::ReplicationStats;pub use gorc::Replication;pub use gorc::GorcObjectRegistry;pub use gorc::SubscriptionManager;pub use gorc::SubscriptionType;pub use gorc::ProximitySubscription;pub use gorc::RelationshipSubscription;pub use gorc::InterestSubscription;pub use gorc::InterestLevel;pub use gorc::MulticastManager;pub use gorc::MulticastGroup;pub use gorc::LodRoom;pub use gorc::LodLevel;pub use gorc::MulticastGroupId;pub use gorc::CompleteGorcSystem;pub use gorc::GorcPerformanceReport;pub use gorc::MineralType;pub use gorc::examples::ExampleAsteroid;pub use gorc::examples::ExamplePlayer;pub use gorc::examples::ExampleProjectile;pub use gorc::examples::TypedAsteroid;pub use gorc::examples::TypedPlayer;pub use gorc::examples::TypedProjectile;pub use gorc::defaults;pub use gorc::GORC_VERSION;pub use gorc::MAX_CHANNELS;pub use futures;pub use types::*;
Modules§
- api
- async_
logging - Asynchronous logging system with dedicated thread.
- context
- Server Context Interface
- events
- Event Traits and Core Events
- gorc
- Game Object Replication Channels (GORC)
- gorc_
macros - macros
- Plugin Development Macros
- monitoring
- plugin
- Plugin System Interface
- shutdown
- Shutdown coordination for graceful server shutdown.
- system
- traits
- types
- Core Type Definitions
- utils
- Utility Functions
Macros§
- __
assert_ types_ different - Helper macro to assert two types are different
- __
check_ duplicate_ zone_ types - Helper macro to check for duplicate zone types at compile time
- __
check_ type_ against_ list - Helper macro to check a type against a list of types
- __
extract_ position_ from_ first_ zone - Helper macro to extract position from the first zone
- __
update_ position_ in_ first_ zone - Helper macro to update position in the first zone
- create_
simple_ plugin - Macro to create a plugin with minimal boilerplate and comprehensive panic handling.
- defObject
- Macro to register an object type with the GORC system.
- impl_
gorc_ object - Macro for implementing GorcObject with type-based zone assignment
- on_
event - Simple macro for single handler registration (alternative to the bulk macro).
- register_
handlers - Convenience macro for registering multiple handlers with clean syntax.
Structs§
- Arc
- A thread-safe reference-counting pointer. ‘Arc’ stands for ‘Atomically Reference Counted’.
Constants§
- ABI_
VERSION - ABI version for plugin compatibility validation. This is derived from the crate version and Rust compiler version to ensure plugins are compatible. Format: “major.minor.patch:rust_version” Example: “0.10.0:1.75.0” or “0.10.0:unknown”
Traits§
- Deserialize
- A data structure that can be deserialized from any data format supported by Serde.
- Serialize
- A data structure that can be serialized into any data format supported by Serde.
Functions§
- horizon_
build_ info - Returns build info string with version and Rust compiler version (if available)