Events

Event-driven Architecture and State Updates

Race Protocol utilizes an event-driven architecture to synchronize game state and trigger actions across all participants. This means that the game progresses based on a stream of events that represent player actions, decisions, and other occurrences within the game.

Events play a crucial role in ensuring consistency and fairness:

• State Updates: When an event occurs, the Transactor server updates the game state accordingly. This updated state is then broadcasted to all connected clients and validator servers, ensuring that everyone has a consistent view of the game's progress.

• Triggering Actions: Events can also trigger specific actions within the game handler or on the client side. For example, a RandomnessReady event indicates that the randomness generation process is complete, allowing the game handler to access and use the random values.

Custom vs. Built-in Events

Race Protocol distinguishes between two main types of events:

• Custom Events: These are game-specific events defined by the developer to represent player actions, decisions, and other occurrences within the game. Examples include placing a bet in a poker game or choosing a move in a strategy game. Custom events are implemented as Rust structs and serialized into binary data before being submitted to the Transactor.

• Built-in Events: These are predefined events handled by the Race Protocol itself. They represent system-level actions and state changes, such as game initialization (Init), player joins (Join), randomness generation (RandomnessReady), and settlements (Settle). Built-in events are defined in the SDK and are used by the protocol to manage the overall game flow and ensure synchronization.

Submitting and Handling Events

Submitting Custom Events:

To submit a custom event, you can use the submitEvent function of the AppClient or SubClient, depending on whether you are interacting with the main game or a sub-game. The function takes your custom event data as an argument and handles the serialization and transmission of the event to the Transactor.

Here's an example of submitting a custom event:

// Assuming client is an initialized AppClient or SubClient instance

const customEvent = {
  type: 'playerMove',
  playerId: 1n,
  move: 'rock',
};

client.submitEvent(customEvent);

Handling Events:

Both AppClient and SubClient provide event listeners that allow you to react to incoming events and update the game UI accordingly. You can register callback functions that will be invoked whenever a specific event occurs.

Here's an example of handling both custom and built-in events:

client.onEvent((context, state, event) => {
  if (event instanceof Custom) {
    // Handle custom event based on its type
    if (event.type === 'playerMove') {
      // Update UI to reflect the player's move
    }
  } else if (event instanceof RandomnessReady) {
    // Update UI to indicate that randomness is ready
  } else if (event instanceof Settle) {
    // Update UI to show the game results and settlements
  }
});

This code snippet demonstrates how the SDK facilitates event handling and allows the game UI to stay synchronized with the game state and react to various events occurring within the Race game.

By understanding the event-driven architecture of Race Protocol and utilizing the event handling functionalities of the SDK, developers can build responsive and interactive game frontends that provide a seamless and engaging gameplay experience for their users.