Crate geese

source ·
Expand description

Geese is a game event system for Rust, built to allow modular game engine design.

In Geese, a system is a struct with internal state and a collection of associated event handlers. Systems can raise events and react to events raised by other systems. Systems may also declare dependencies on other systems, which allow them to borrow those systems during event processing. Geese automatically loads all system dependencies. Any struct can act as an event type, and any struct that implements GeeseSystem can act as a system type.

The following is an example of how to use Geese to load multiple dependent systems, and propogate events between them. The example creates a Geese context, and requests that system B be loaded. When flush is called, system A is loaded first (because it is a dependency of B), and then system B is loaded. B receives the typed event, and responds by querying system A for some information.

struct A;

impl A {
    pub fn answer(&self) -> bool {
        true
    }
}

impl GeeseSystem for A {
    fn new(_: GeeseContextHandle<Self>) -> Self {
        Self
    }
}

struct B {
    ctx: GeeseContextHandle<Self>
}

impl B {
    fn test_answer(&mut self, event: &Arc<AtomicBool>) {
        event.store(self.ctx.get::<A>().answer(), Ordering::Relaxed);
    }
}

impl GeeseSystem for B {
    const DEPENDENCIES: Dependencies = dependencies()
        .with::<A>();

    const EVENT_HANDLERS: EventHandlers<Self> = event_handlers()
        .with(Self::test_answer);

    fn new(ctx: GeeseContextHandle<Self>) -> Self {
        Self { ctx }
    }
}

let ab = Arc::new(AtomicBool::new(false));
let mut ctx = GeeseContext::default();
ctx.flush()
    .with(notify::add_system::<B>())
    .with(ab.clone());
assert!(ab.load(Ordering::Relaxed));

A working game of Pong using geese can be found in the examples folder.

§Event processing

The following invariants are always upheld during event processing, making it easy to reason about order of execution:

  • If multiple events are raised, they are processed in first-in-first-out (FIFO) order. The notify::flush command can be used for fine-grained control over ordering by starting embedded event cycles.
  • Multiple handlers for the same event on the same system are invoked in the order that they appear in the handlers list.
  • When processing a single event, dependencies’ event handlers are always invoked before those of dependents.

§Concurrency

Geese can use multithreading to parallelize over work, allowing independent systems to execute event handlers in tandem. Even during multithreading, all invariants of event processing are upheld - from the perspective of a single system, events still execute serially. The more systems one defines, the more parallelism is achieved.

To use Geese with multithreading, employ either the builtin HardwareThreadPool or implement a custom threadpool with the GeeseThreadPool trait.

Modules§

  • notify
    Provides events to which the Geese context responds.
  • on
    The set of events which this module raises.

Structs§

  • Dependencies
    Denotes a list of system dependencies.
  • Dependency
    Describes a system dependency.
  • EventBuffer
    Holds a series of events that the context should execute.
  • EventHandler
    Wraps an event handler function for a system.
  • EventHandlers
    Denotes a list of system methods that respond to events.
  • GeeseContext
    Represents a collection of systems that can create and respond to events.
  • GeeseContextHandle
    Represents a system-specific handle to a Geese context.
  • HardwareThreadPool
    A threadpool which executes Geese work on both the main thread and background threads. This threadpool controls the lifetime of its background threads, and they are cancelled upon drop.
  • Mut
    Marks that a dependency may be mutably borrowed.
  • Store
    Provides the ability to store data of an arbitrary type as a system.
  • SystemRef
    Represents an immutable reference to a system.
  • SystemRefMut
    Represents a mutable reference to a system.

Traits§

  • EventQueue
    Describes a series of events that the context should execute.
  • GeeseSystem
    Represents a collection of event handlers with internal state.
  • GeeseThreadPool
    Provides a backing implementation for multithreaded Geese contexts. This trait allows for defining and customizing how multiple threads complete the work of a context.

Functions§