Add documentation for LoadStaticZone

src/auth/client.rs

@@ -27,10 +27,9 @@ pub enum ClientMessage {
 }
 
 /**
-	Login response.
+	Responds to a login request.
 
-	### Purpose
-	Reporting the result of a login request, including session key and redirect address in case of success.
+	Sends session key and redirect address in case of success.
 
 	### Trigger
 	Receipt of [`LoginRequest`](super::server::LoginRequest).

src/auth/server.rs

@@ -26,10 +26,9 @@ pub enum AuthMessage {
 }
 
 /**
-	Login request.
+	Provides username and password to authenticate the client.
 
-	### Purpose
-	Providing username and password to authenticate the client, providing system stats for analytics.
+	Also provides system stats for analytics.
 
 	### Trigger
 	Receipt of [`Handshake`](crate::general::client::Handshake) with a [`service_id`](crate::general::client::Handshake`::service_id) of [`ServiceId::Auth`].

src/general/client/mod.rs

@@ -50,19 +50,16 @@ impl<C> From<DisconnectNotify> for Message<C> {
 }
 
 /**
-	Server network version info.
-
-	### Purpose
-	Completing a version handshake initiated by the client.
+	Completes a version handshake initiated by the client.
 
 	### Trigger
 	Receipt of a client-sent [`Handshake`](super::server::Handshake) packet that was acceptable to the server.
 
 	### Handling
-	Optionally check if the server's [`network_version`](Handshake::network_version) matches your own. You can usually assume that the server will check this itself and disconnect if it doesn't match, but you can check again to be sure.
+	Optionally check if the server's [`network_version`](Self::network_version) matches your own. You can usually assume that the server will check this itself and disconnect if it doesn't match, but you can check again to be sure.
 
 	### Response
-	If the server's [`service_id`](Handshake::service_id) is [`ServiceId::Auth`], respond with a [`LoginRequest`](crate::auth::server::LoginRequest) with your username and password. If it is [`ServiceId::World`], send a [`ClientValidation`](crate::world::server::ClientValidation) with your username and the session key provided by auth.
+	If the server's [`service_id`](Self::service_id) is [`ServiceId::Auth`], respond with a [`LoginRequest`](crate::auth::server::LoginRequest) with your username and password. If it is [`ServiceId::World`], send a [`ClientValidation`](crate::world::server::ClientValidation) with your username and the session key provided by auth.
 
 	### Notes
 	As the version confirm process was designed with more than just client-server in mind, it sends the server's network version and service id as well, even though this isn't really needed by the client (even the service id isn't needed, since you usually only connect to auth once, and it's the very first connection). This could be simplified if the protocol is ever revised.
@@ -78,10 +75,7 @@ pub struct Handshake {
 }
 
 /**
-	Disconnect notification.
-
-	### Purpose
-	Notifying the client when it was actively disconnected by the server.
+	Notifies the client when it was actively disconnected by the server.
 
 	### Trigger
 	Being disconnected by the server, the exact trigger depends on the variant.

src/general/server/mod.rs

@@ -12,16 +12,15 @@ pub enum GeneralMessage {
 }
 
 /**
-	Client network version info.
+	Provides the client's network version.
 
-	### Purpose
-	Providing the client's network version to identify outdated clients and disconnect them early.
+	Allows to identify outdated clients and disconnect them early.
 
 	### Trigger
 	Establishment of raknet connection (receipt of [`ConnectionRequestAccepted`](crate::raknet::client::ConnectionRequestAccepted)).
 
 	### Handling
-	Check if [`network_version`](Handshake::network_version) matches the version you expect. Otherwise, disconnect the client, ideally with a [`DisconnectNotify::InvalidGameVersion`](super::client::DisconnectNotify::WrongGameVersion) specifying the expected version.
+	Check if [`network_version`](Self::network_version) matches the version you expect. Otherwise, disconnect the client, ideally with a [`DisconnectNotify::InvalidGameVersion`](super::client::DisconnectNotify::WrongGameVersion) specifying the expected version.
 
 	### Response
 	Respond with a server-sent [`Handshake`](super::client::Handshake) providing the server's network version and service ID.

src/world/client/mod.rs

@@ -46,13 +46,38 @@ pub enum InstanceType {
 	Match,
 }
 
+/**
+	Tells the client to load a zone.
+
+	### Trigger
+	May be sent at any time. However, in a typical server instance architecture, this message will usually be sent as the first message directly after the client has validated itself with [`ClientValidation`](super::server::ClientValidation).
+
+	### Handling
+	Load the zone specified in [`zone_id`](Self::zone_id), whatever that may entail for your client implementation.
+
+	### Response
+	Respond with [`LevelLoadComplete`](super::server::LevelLoadComplete) once you're done loading.
+
+	### Notes
+	Server instances are usually statically assigned to host a "parallel universe" of a certain zone (world), which means that this message will be sent directly after client validation. However, other instance architectures are theoretically possible:
+
+	- Dynamic changing of the instance's zone, in which case additional [`LoadStaticZone`] messages could be sent (when the zone is changed).
+
+	- Shared/overlapping instances, where the instance connection changes as the player moves around in the world, or where instances take over from others (e.g. in the event of a reboot), with mobs and all other state being carried over. In this case the client would be instructed to connect to the new instance via [`TransferToWorld`], but would not receive a [`LoadStaticZone`] afterwards. If done correctly, the player wouldn't even notice the transfer at all.
+
+	However, these are quite advanced architectures, and for now it is unlikely that any server project will actually pull these off.
+*/
 #[derive(Debug, Deserialize, PartialEq, Serialize)]
 pub struct LoadStaticZone {
+	/// ID of the zone to be loaded.
 	pub zone_id: ZoneId,
+	/// Checksum on the map on the server side. The original LU client will refuse to load any map where the client side checksum doesn't match the server checksum, to prevent inconsistencies and cheating.
 	pub map_checksum: u32,
 	// editor enabled and editor level, unused
 	#[padding=2]
+	/// The position of the player in the new world, likely used to be able to load the right part of the world.
 	pub player_position: Vector3,
+	/// The instance type of the zone being loaded.
 	pub instance_type: InstanceType,
 }
 

src/world/server/mod.rs

@@ -1,4 +1,4 @@
-//! All packets a world server can receive.
+//! Server-received world messages.
 use std::io::{Read, Write};
 use std::io::Result as Res;
 
@@ -41,18 +41,15 @@ pub enum WorldMessage {
 }
 
 /**
-	Client session info.
-
-	### Purpose
-	Providing session info for authentication.
+	Provides session info for authentication.
 
 	### Trigger
-	[Server handshake](crate::general::client::Handshake).
+	Receipt of [Server handshake](crate::general::client::Handshake).
 
 	### Handling
 	Verify with your auth server that the `(username, session_key)` combination is valid. If not, immediately disconnect the client, ideally with a [`DisconnectNotify::InvalidSessionKey`](crate::general::client::DisconnectNotify::InvalidSessionKey).
 
-	If you are concerned about players modding their client DB, also check the `fdb_checksum`. Note that players can still change their client to send a fake checksum, but this requires exe modding, which most players are presumably not familiar with.
+	If you are concerned about players modding their client DB, also check the [`fdb_checksum`](Self::fdb_checksum). Note that players can still change their client to send a fake checksum, but this requires exe modding, which most players are presumably not familiar with.
 
 	If all validation checks pass, store the connection -> username association, as this is the only packet that references the username.