archipelago_rs/event.rs
1use std::{collections::HashSet, sync::Arc, time::SystemTime};
2
3use ustr::UstrSet;
4
5use crate::{Error, Location, Player, Print, protocol::Permission};
6
7/// Events from the Archipelago server that clients may want to handle.
8///
9/// This only encompasses events that can be spontaneously sent by the server.
10/// Events that are only ever sent as replies to client requests are represented
11/// as [Future]s instead.
12pub enum Event {
13 /// The client has established a successful connection. This is only emitted
14 /// from [Connection.update] and only once, always as the first event.
15 Connected,
16
17 /// An event indicating that some information about the room or the current
18 /// connection was updated by the server. It contains all the updates that
19 /// occurred.
20 Updated(Vec<UpdatedField>),
21
22 /// A message for the client to display to the player.
23 Print(Print),
24
25 /// Items have been received from the server (usually another world,
26 /// although the specifics of which items will be sent depends on the
27 /// [crate::ItemHandling] you pass in [crate::ConnectionOptions]).
28 ///
29 /// This is typically the first event this will be emitted (after
30 /// [Connected](Event::Connected), if applicable). It contains the index of
31 /// the first newly-received item in the global list of all items this
32 /// client has received, available from [Client.received_items].
33 ///
34 /// When the index is 0, that indicates that all the items the player has
35 /// ever received have been re-sent.
36 ReceivedItems(usize),
37
38 /// The client has encountered an error.
39 ///
40 /// Once this event has been emitted, the client should be considered
41 /// closed. It will emit no more events and any attempts to send requests
42 /// will fail.
43 ///
44 /// When emitted from [Connection.update], this will be [Error::Elsewhere]
45 /// and the actual error will be available from [Connection.state] or
46 /// [Connection.into_err].
47 Error(Error),
48
49 /// An event sent by other clients in the multiworld. The specific meaning
50 /// of this is determined by those clients.
51 Bounce {
52 /// The set of games this is targeting. If this is `None`, it's not
53 /// limited to specific games.
54 games: Option<UstrSet>,
55
56 /// The set of all slots this is targeting. If this is `None`, it's not
57 /// limited to specific slots.
58 slots: Option<HashSet<u32>>,
59
60 /// The set of all tags this is targeting. If this is `None`, it's not
61 /// limited to specific tags.
62 tags: Option<UstrSet>,
63
64 /// Data attached to the event, if any.
65 data: Option<serde_json::Value>,
66 },
67
68 /// A death link event, indicating that participating clients should kill
69 /// the player because another player died. This is only received if
70 /// `"DeathLink"` is passed to [ConnectionOptions.tags].
71 DeathLink {
72 /// The set of games this is targeting. If this is `None`, it's not
73 /// limited to specific games.
74 games: Option<UstrSet>,
75
76 /// The set of all slots this is targeting. If this is `None`, it's not
77 /// limited to specific slots.
78 slots: Option<HashSet<u32>>,
79
80 /// The set of all tags this is targeting. This will always contain at
81 /// least `"DeathLink"`.
82 tags: UstrSet,
83
84 /// The time the death link was sent, according to the sender. There's
85 /// no guarantee that this has any particular relationship to the
86 /// current system's time.
87 time: SystemTime,
88
89 /// Text to explain the cause of death. This is expected to contain the
90 /// name of the player who died.
91 cause: Option<String>,
92
93 /// The name of the player who first died. This can be a slot name or a
94 /// name from within a multiplayer game.
95 source: String,
96 },
97
98 /// The value associated with a key in the server's data storage was
99 /// updated. This is only emitted after [Client.watch] is called, or if
100 /// [Client.set] or [Client.change] is called with `emit_event` set to
101 /// `true`.
102 KeyChanged {
103 /// The name of the key whose value changed.
104 key: String,
105
106 /// The value before the change. This is `None` for special server keys.
107 old_value: Option<serde_json::Value>,
108
109 /// The value after the change.
110 new_value: serde_json::Value,
111
112 /// The player who updated this key. This is omitted for the special
113 /// `_read_hints_...` and `_read_client_status_...` keys.
114 player: Option<Arc<Player>>,
115 },
116}
117
118/// An enum that indicates exactly what in a [Client](crate::Client) was
119/// updated.
120pub enum UpdatedField {
121 /// [Client.server_tags] changed.
122 ///
123 /// This contains the previous tags.
124 ServerTags(UstrSet),
125
126 /// [Client.release_permission], [Client.collect_permission], and/or
127 /// [Client.remaining_permission] changed.
128 ///
129 /// This contains the old values for each permission.
130 Permissions {
131 release: Permission,
132 collect: Permission,
133 remaining: Permission,
134 },
135
136 /// [Client.points_per_hint] and/or [Client.hint_points_per_check] changed.
137 ///
138 /// This contains the previous values for each field.
139 HintEconomy {
140 points_per_hint: u64,
141 hint_points_per_check: u64,
142 },
143
144 /// [Client.hint_points] has changed.
145 ///
146 /// This contains the previous value for the field.
147 HintPoints(u64),
148
149 /// One or more players' aliases have changed.
150 ///
151 /// This includes the *previous* [Player] structs. Use
152 /// [Client.assert_player] to access the new ones.
153 Players(Vec<Arc<Player>>),
154
155 /// Additional locations have been checked, usually from a co-op player in
156 /// the same slot.
157 ///
158 /// This includes all newly-checked locations.
159 CheckedLocations(Vec<Location>),
160}