andrew
8c09e91534
Add optional movement-state fields (isMoving, isSprinting, isSneaking, isJumping, weaponDrawn, movementSpeed) to transform packets and wire them end-to-end. Plugin changes: extend F4TNetworking API and RemotePlayerState, derive movement speed/jump state on the game-thread, validate values, include fields when formatting transform JSON, and add throttled remote movement-state logging. main.cpp adds sampling, speed/vertical calculations, jump hold logic, and change-detection to avoid extra sends. Networking parsing (F4TNetworking.cpp) reads optional booleans/floats safely, preserves backwards compatibility, and clears movement-state logs on disconnect. Proxy controller includes a TODO note for future animation use. Server and docs: update protocol and packet docs, dev-log, server README, and fake_client.py to parse/display optional fields safely. Also add several .cursor rule files for coding, documentation, protocol, project overview, and testing guidance. This milestone prepares the data model for later animation/behavior work while keeping existing relay behavior unchanged.
156 lines
3.9 KiB
Markdown
156 lines
3.9 KiB
Markdown
# Packet Types
|
|
|
|
This document describes the currently implemented local prototype packet types
|
|
for Fallout 4 Together.
|
|
|
|
The current protocol is newline-separated JSON over a local TCP connection to
|
|
`127.0.0.1:7777`.
|
|
|
|
Implemented packet types:
|
|
|
|
- `welcome`
|
|
- `transform`
|
|
- `disconnect`
|
|
|
|
The current system is still a local networking prototype. It is not playable
|
|
multiplayer yet.
|
|
|
|
## Implemented
|
|
|
|
### Welcome Packet
|
|
|
|
Sent from the server to a newly connected client after the server assigns a
|
|
`playerId`.
|
|
|
|
Example:
|
|
|
|
```json
|
|
{
|
|
"type": "welcome",
|
|
"playerId": 1,
|
|
"serverTime": 1780212098.457079
|
|
}
|
|
```
|
|
|
|
Fields:
|
|
|
|
```text
|
|
type Packet type. Always "welcome".
|
|
playerId Server-assigned player ID for this connection.
|
|
serverTime Server timestamp when the welcome packet was created.
|
|
```
|
|
|
|
The Fallout 4 plugin and `server/fake_client.py` receive this packet. The plugin
|
|
stores the assigned `playerId` for filtering its own future transform echoes.
|
|
|
|
### Transform Packet
|
|
|
|
Sent by the Fallout 4 plugin to the local server when the local player's
|
|
transform changes. The server adds `playerId` and `serverTime`, then broadcasts
|
|
the processed packet to other connected clients.
|
|
|
|
Example after server processing:
|
|
|
|
```json
|
|
{
|
|
"type": "transform",
|
|
"playerId": 2,
|
|
"x": -81781.26,
|
|
"y": 87962.61,
|
|
"z": 7696.05,
|
|
"angleZ": 3.20,
|
|
"movementType": "normal",
|
|
"cellId": "0000DD60",
|
|
"worldspaceId": "0000003C",
|
|
"clientTime": 1780212128.301,
|
|
"isMoving": true,
|
|
"isSprinting": false,
|
|
"isSneaking": false,
|
|
"isJumping": false,
|
|
"weaponDrawn": false,
|
|
"movementSpeed": 186.4,
|
|
"serverTime": 1780212128.3011043
|
|
}
|
|
```
|
|
|
|
Fields:
|
|
|
|
```text
|
|
type Packet type. Always "transform".
|
|
playerId Server-assigned player ID for the sender.
|
|
x Local player X position.
|
|
y Local player Y position.
|
|
z Local player Z position.
|
|
angleZ Local player Z rotation angle.
|
|
movementType Movement classification for this transform update.
|
|
cellId Current cell form ID as a string.
|
|
worldspaceId Current worldspace form ID as a string.
|
|
clientTime Timestamp generated by the sending plugin.
|
|
isMoving Optional movement-state flag; defaults to false when missing.
|
|
isSprinting Optional movement-state flag; defaults to false when missing.
|
|
isSneaking Optional movement-state flag; defaults to false when missing.
|
|
isJumping Optional movement-state flag; defaults to false when missing.
|
|
weaponDrawn Optional weapon drawn state; defaults to false when missing.
|
|
movementSpeed Optional derived movement speed in game units per second; defaults to 0.0 when missing.
|
|
serverTime Timestamp added by the server before broadcast.
|
|
```
|
|
|
|
Possible `movementType` values:
|
|
|
|
```text
|
|
normal
|
|
cell_change
|
|
worldspace_change
|
|
teleport
|
|
```
|
|
|
|
`cell_change` and `worldspace_change` are currently represented through
|
|
`movementType` inside transform packets. They are not separate packet types yet.
|
|
|
|
Movement state fields are data-only for now. Receivers must treat them as
|
|
optional and must not reject older transform packets when they are absent.
|
|
|
|
### Disconnect Packet
|
|
|
|
Sent by the server to remaining connected clients when a client disconnects.
|
|
|
|
Example:
|
|
|
|
```json
|
|
{
|
|
"type": "disconnect",
|
|
"playerId": 2,
|
|
"serverTime": 1780212134.0
|
|
}
|
|
```
|
|
|
|
Fields:
|
|
|
|
```text
|
|
type Packet type. Always "disconnect".
|
|
playerId Server-assigned player ID that disconnected.
|
|
serverTime Server timestamp when the disconnect packet was created.
|
|
```
|
|
|
|
The Fallout 4 plugin and `server/fake_client.py` use this packet to remove
|
|
remote players from their in-memory state tables.
|
|
|
|
## Receiver Behavior
|
|
|
|
The Fallout 4 plugin and fake client both receive:
|
|
|
|
```text
|
|
welcome
|
|
transform
|
|
disconnect
|
|
```
|
|
|
|
The plugin receive loop runs on a background networking thread. It stores plain
|
|
remote-player state only and does not spawn actors or touch Fallout 4 game
|
|
objects.
|
|
|
|
## Planned Later
|
|
|
|
- Remote actor spawning.
|
|
- Gameplay synchronization.
|