flatland-protocol 0.1.0

Flatland3 wire protocol types and codecs
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

use serde::{Deserialize, Serialize};
use uuid::Uuid;

pub type EntityId = u64;
pub type Tick = u64;
pub type Seq = u32;
pub type SessionId = u64;

/// World position `(x, y, z, w, t)` — `t` reserved at 0.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct WorldCoord {
    pub x: f32,
    pub y: f32,
    pub z: f32,
    pub w: u32,
    pub t: u32,
}

impl WorldCoord {
    pub fn surface(x: f32, y: f32) -> Self {
        Self {
            x,
            y,
            z: 0.0,
            w: 0,
            t: 0,
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct Velocity2D {
    pub vx: f32,
    pub vy: f32,
}

#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct Transform {
    pub position: WorldCoord,
    pub yaw: f32,
    pub velocity: Velocity2D,
}

#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct EntityState {
    pub id: EntityId,
    pub transform: Transform,
}

/// Client → server gameplay input (reliable, sequenced per entity).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum Intent {
    Move {
        entity_id: EntityId,
        forward: f32,
        strafe: f32,
        seq: Seq,
    },
    Stop {
        entity_id: EntityId,
        seq: Seq,
    },
}

/// Server → client AOI-filtered entity updates for one sim tick.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TickDelta {
    pub tick: Tick,
    pub entities: Vec<EntityState>,
}

/// Full state on region enter or reconnect.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Snapshot {
    pub tick: Tick,
    pub chunk_rev: u64,
    pub entities: Vec<EntityState>,
}

/// Every on-wire payload is wrapped for versioning and codec uniformity.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Envelope<T> {
    pub protocol_version: u16,
    pub payload: T,
}

impl<T> Envelope<T> {
    pub fn new(payload: T) -> Self {
        Self {
            protocol_version: crate::PROTOCOL_VERSION,
            payload,
        }
    }
}

/// Session handshake after transport connect.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Hello {
    pub client_name: String,
    pub protocol_version: u16,
    #[serde(default)]
    pub auth: AuthCredential,
    /// Required for session auth; embedded in `ApiToken` variant otherwise.
    #[serde(default)]
    pub character_id: Option<Uuid>,
}

/// How the client authenticates to the game gateway.
/// Uses default serde enum encoding (postcard-compatible; not internally tagged).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AuthCredential {
    DevLocal,
    Session { token: String },
    ApiToken { token: String, character_id: Uuid },
}

impl Default for AuthCredential {
    fn default() -> Self {
        Self::DevLocal
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Welcome {
    pub session_id: SessionId,
    pub entity_id: EntityId,
    pub snapshot: Snapshot,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum ServerMessage {
    Welcome(Welcome),
    Tick(TickDelta),
    IntentAck { entity_id: EntityId, seq: Seq, tick: Tick },
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum ClientMessage {
    Hello(Hello),
    Intent(Intent),
    Disconnect,
}