Events play a pivotal role in decoding the dynamics of a Dojo world. Every time there's an update to a model, the world contract emits events.

What's even more exciting is that you can craft your own custom events to fit specific needs! Moreover, thanks to model's introspection and Torii, all these events are seamlessly indexed, ensuring easy and efficient querying.

Custom Events

Within your game, emitting custom events can be highly beneficial. Fortunately, there's a handy emit_event api that lets you release events directly from your world. These events are indexed by Torii.

There are two kind of Custom Events with different use-cases.

Using dojo::event

These events are acting like 'off-chain' storage and behave like models which allows Torii to easily parse them. Since it mimics models behaviour, a Dojo event must have a least a #[key] and any type used inside it must derive Introspect.

For example we will declare a PlayerMood struct to keep track of player mood.

• We don't need this information onchain.
• We don't want to historize PlayerMood changes, just keep track of the current/latest PlayerMood.

#[derive(Copy, Drop, Introspect)]
struct Mood {
    Happy,
    Angry,
}
 
#[derive(Copy, Drop, Serde)]
#[dojo::event]
struct PlayerMood {
    #[key]
    player: ContractAddress,
    mood: Mood,
 }

Emit the PlayerMood event:

world.emit_event(@PlayerMood { player, mood: Mood::Happy });

Each time a PlayerMood event is emitted, the PlayerMood event indexed by Torii will reflect the lasted mood.

Example

Now a full example using a custom event:

fn move(ref self: ContractState, direction: Direction) {
 
    let player = get_caller_address();
    let mut position: Position = world.read_model(player);
    let mut moves: Moves = world.read_model(player);
 
    moves.remaining -= 1;
    moves.last_direction = direction;
    let next = next_position(position, direction);
 
    world.write_model(@moves);
    world.write_model(@next);
 
    world.emit_event(@Moved { address, direction });
}

Here's a breakdown of the events emitted by the world:

enum Event {
    WorldSpawned: WorldSpawned,
    WorldUpgraded: WorldUpgraded,
    NamespaceRegistered: NamespaceRegistered,
    ModelRegistered: ModelRegistered,
    EventRegistered: EventRegistered,
    ContractRegistered: ContractRegistered,
    ModelUpgraded: ModelUpgraded,
    EventUpgraded: EventUpgraded,
    ContractUpgraded: ContractUpgraded,
    ContractInitialized: ContractInitialized,
    EventEmitted: EventEmitted,
    MetadataUpdate: MetadataUpdate,
    StoreSetRecord: StoreSetRecord,
    StoreUpdateRecord: StoreUpdateRecord,
    StoreUpdateMember: StoreUpdateMember,
    StoreDelRecord: StoreDelRecord,
    WriterUpdated: WriterUpdated,
    OwnerUpdated: OwnerUpdated,
}

WorldSpawned

The WorldSpawned event is emitted when the world is spawned (deployed).

WorldUpgraded

The WorldUpgraded event is emitted when the world is upgraded to a new class hash (the address of the world remains the same).

NamespaceRegistered

The NamespaceRegistered event is emitted when a new namespace is registered in the world, with its name and its hash.

ModelRegistered

The ModelRegistered event is emitted when a model is registered in the world, which contains all the information about the model including it's type layout.

EventRegistered

The EventRegistered event is emitted when an event is registered in the world, which contains all the information about the event including it's type layout.

ContractRegistered

The ContractRegistered event is emitted when a Dojo contract is registered (deployed). The deployment is managed by the world itself.

ModelUpgraded

The ModelUpgraded event is emitted when an existing model is upgraded to a new class hash. Note that the model contract gets a new address when upgraded.

EventUpgraded

The EventUpgraded event is emitted when an existing event is upgraded to a new class hash. Note that the event contract gets a new address when upgraded.

ContractUpgraded

The ContractUpgraded event is emitted when a Dojo contract is upgraded to a new class hash (the address of such Dojo contract remains the same).

ContractInitialized

The ContractInitialized event is emitted when a Dojo contract is initialized with some specific call data. The provided call data are attached to the event.

EventEmitted

The EventEmitted event is emitted when a Dojo event is emitted with the emit_event world function. This event contains the data of the Dojo emitted event such as its selector, its keys and values.

MetadataUpdate

The MetadataUpdate event is emitted when the metadata of a resource (world, Dojo contract, Dojo model) is updated.

StoreSetRecord

The StoreSetRecord event is emitted when a model identified by its keys is updated in the world's store.

StoreUpdateRecord

The StoreUpdateRecord event is emitted when a model identified by its entity_id is updated in the world's store.

StoreUpdateMember

The StoreUpdateMember event is emitted when a model member is updated in the world's store.

StoreDelRecord

The StoreDelRecord event is emitted when a model is deleted from the world's store.

WriterUpdated

The WriterUpdated event is emitted when the writer permission on a model has changed.

OwnerUpdated

The OwnerUpdated event is emitted when the owner permission on a model has changed.