diff --git a/AGRARIAN_DEVELOPMENT_ROADMAP.md b/AGRARIAN_DEVELOPMENT_ROADMAP.md index 92ec94d..562964f 100644 --- a/AGRARIAN_DEVELOPMENT_ROADMAP.md +++ b/AGRARIAN_DEVELOPMENT_ROADMAP.md @@ -567,13 +567,13 @@ Target deliverable: A small group can join a server, spawn into one biome, gathe ## 1.12 Basic Multiplayer -- [ ] Confirm listen server vs dedicated server for MVP. +- [x] Confirm listen server vs dedicated server for MVP. Decision: listen server is acceptable for quick internal testing, but dedicated server is the preferred closed-test target. - [ ] Create dedicated server build target if needed. - [ ] Add server travel flow. -- [ ] Define server authority over streamed terrain tiles. -- [ ] Define server response when a client requests a missing tile. -- [ ] Add player join flow. -- [ ] Add player spawn flow. +- [x] Define server authority over streamed terrain tiles. +- [x] Define server response when a client requests a missing tile. +- [x] Add player join flow. +- [x] Add player spawn flow. - [x] Add replicated player stats. - [x] Add replicated inventory. - [x] Add replicated world time. @@ -1431,7 +1431,7 @@ Earliest incomplete foundation items: - [x] Confirm project opens cleanly from a fresh checkout. - [x] Create the core design document. - [x] Create the technical design document. -- [ ] Create the multiplayer/networking design document. +- [x] Create the multiplayer/networking design document. - [ ] Create the persistence design document. - [ ] Create the Earth-scale terrain/tile streaming design document. - [x] Launch near-term MVP map-tile serving cloud VM and prove Ground Zero tile lookup/download/cache flow. @@ -1443,4 +1443,4 @@ Earliest incomplete foundation items: Immediate next item: -- [ ] Create the multiplayer/networking design document. +- [ ] Create the persistence design document. diff --git a/Docs/MultiplayerNetworkingDesign.md b/Docs/MultiplayerNetworkingDesign.md new file mode 100644 index 0000000..425d147 --- /dev/null +++ b/Docs/MultiplayerNetworkingDesign.md @@ -0,0 +1,333 @@ +# Agrarian Multiplayer And Networking Design + +## Purpose + +This document defines Agrarian's multiplayer and networking direction for the +MVP foundation. It focuses on authority, replication, join/spawn flow, tile +delivery interaction, latency expectations, disconnect behavior, and test gates. + +The goal is to prove a small shared survival world without overbuilding the +final MMO-scale architecture too early. + +## MVP Networking Goal + +The first playable MVP must support at least two players joining the same +server, spawning into the Ground Zero tile, and interacting with the same +survival world. + +The multiplayer proof is complete when: + +- both players see the same world time and weather; +- both players can gather resources; +- inventory and survival stats replicate correctly; +- placed campfires/shelters/build pieces replicate; +- basic wildlife/resource state is shared; +- server restart can preserve core state; +- disconnect/reconnect has a defined MVP behavior; +- tile package lookup/download does not depend on clients mutating server + state. + +## Network Model + +MVP model: + +- Unreal server-authoritative gameplay. +- Listen server is acceptable for quick internal testing. +- Dedicated server remains the preferred closed-test target once packaging is + stable. + +Decision: + +- Do not block the current MVP on a polished dedicated server deployment if a + listen-server flow can prove gameplay. +- Do build toward dedicated server compatibility by keeping gameplay authority + on the server and avoiding local-only critical state. + +## Authority Rules + +The server owns gameplay truth. + +Server authoritative systems: + +- player survival values; +- inventory changes; +- crafting validation and outputs; +- resource node depletion/respawn; +- wildlife state; +- world time and gameplay calendar; +- weather state applied to survival; +- placement/build validation; +- persistence writes; +- player spawn/respawn decisions; +- tile package/version selected for the active world. + +Client-owned or client-local systems: + +- input; +- camera; +- UI/HUD; +- local animation presentation; +- local audio/visual effects; +- local tile cache files; +- local settings. + +Clients may request actions, but the server validates and applies results. + +## Replication Scope + +Replicate only what the client needs to render, play, or make decisions. + +Already represented in current foundations: + +- player survival stats; +- inventory; +- world time; +- weather; +- resource nodes; +- build pieces. + +Near-term replication rules: + +- replicate compact snapshots rather than large internal structures; +- replicate item IDs and stack counts, not full item definitions; +- replicate stable actor state, not transient animation-only details; +- keep weather and world time on `GameState` or equivalent global replicated + state; +- make interactable actors responsible for their own meaningful replicated + state; +- avoid Blueprint-only mutation of critical replicated state when C++ authority + code exists. + +## RPC Rules + +RPCs should be narrow, explicit, and server validated. + +Good RPC shape: + +- `ServerRequestGather(TargetActor)` +- `ServerRequestCraft(RecipeId)` +- `ServerRequestPlaceBuildable(BuildableId, Transform)` +- `ServerRequestInteract(TargetActor, InteractionId)` + +RPCs should validate: + +- the requesting player is alive; +- the target exists and is relevant; +- distance and line-of-use are acceptable; +- required items/resources exist; +- placement rules pass; +- cooldown or action timing rules pass; +- the requested item/recipe/buildable exists in authoritative data. + +Avoid broad RPCs that pass arbitrary inventory edits, raw stat values, or +client-authored world changes. + +## Join Flow + +MVP join flow: + +1. Client loads startup/splash flow. +2. Client reaches character selection. +3. Client connects to the selected server. +4. Server validates connection and selected character choice. +5. Server assigns a player record or temporary MVP player identity. +6. Server sends current world state needed for the Ground Zero tile. +7. Client spawns at an approved spawn point. +8. Client UI initializes from replicated survival/inventory/world state. + +The first MVP does not need account services, matchmaking, or full character +persistence. It does need a deterministic flow that can be tested repeatedly. + +## Spawn And Respawn + +Initial MVP spawn: + +- spawn inside Ground Zero at a safe, known starting area; +- avoid spawning inside water, steep terrain, structures, or resource actors; +- provide enough immediate access to water/gatherables for a first survival + test. + +Respawn MVP behavior: + +- may use a simple fixed spawn point or small spawn zone; +- should clear or penalize some carried inventory if death is implemented; +- should not require full generational inheritance yet; +- should record enough information for debugging death/respawn bugs. + +Future respawn design should connect to family, inheritance, settlements, and +legacy. + +## Tile Delivery And Networking + +The tile server is separate from the gameplay server. + +Current MVP tile endpoint: + +```text +http://maps.agrariangame.com:18080 +``` + +The tile server serves static packages. It does not own gameplay state. + +Server responsibilities: + +- select the active tile/package version for the world; +- persist which tile/package version the world uses; +- reject or defer gameplay actions on tiles not active/loaded for that server; +- expose enough tile metadata to clients to request the correct package; +- keep gameplay authority separate from tile file delivery. + +Client responsibilities: + +- download tile packages from the tile endpoint; +- verify checksums; +- store packages in a local cache; +- redownload packages when missing or invalid; +- never decide authoritative tile state by itself. + +Missing tile response: + +- if a client lacks a required tile package, the client should show a loading + or missing-content state and download the package; +- if the server lacks a required active tile package, the server should reject + travel/spawn into that tile and log an operational error; +- if the tile server is unreachable, the client should retry with clear error + messaging rather than silently failing. + +## Network Relevancy + +MVP relevancy can stay simple but should not replicate the entire future world. + +Near-term rules: + +- always relevant: player controller/pawn, player survival/inventory owner + state, global world time/weather; +- spatially relevant: resource nodes, wildlife, build pieces, fire/shelter, + nearby interactables; +- not replicated as gameplay actors: static terrain package files and large + tile metadata payloads. + +Future rules should align with World Partition, tile boundaries, settlement +density, and player population. + +## Latency Expectations + +MVP target: + +- normal gathering/crafting/building should feel acceptable under LAN and + typical residential broadband latency; +- survival stat updates can tolerate low-frequency replication; +- inventory/crafting feedback should feel responsive enough to test the loop; +- combat and precision movement prediction are not the first MVP focus. + +Initial latency testing should cover: + +- join and spawn; +- gather request/response; +- craft request/response; +- place buildable request/response; +- inventory replication; +- survival stat replication; +- disconnect/reconnect. + +## Disconnect And Reconnect + +MVP behavior: + +- disconnect removes the player's pawn from active control; +- player survival/inventory can be preserved by the current persistence + mechanism if available; +- reconnect may respawn the player at the last saved state or MVP spawn point, + depending on persistence maturity; +- server should not crash or leak active interaction/build state when a player + disconnects mid-action. + +Closed testing should document the current reconnect rule explicitly so testers +know what behavior is expected. + +## Security And Abuse Baseline + +Even in MVP, the server should not trust clients with authoritative values. + +Do not accept client-authored: + +- health, hunger, thirst, stamina, or body temperature values; +- item grants or inventory mutations; +- resource depletion results; +- build placement success; +- weather/time changes; +- tile package versions for active gameplay; +- persistence writes. + +MVP anti-cheat is not a complete system, but basic validation should prevent +accidental or obvious client-side authority mistakes. + +## Dedicated Server Direction + +Dedicated server should become the normal closed-test host once: + +- Linux dedicated server build is repeatable; +- Ground Zero map cooks correctly for server; +- server startup can select/load the MVP map; +- server logs are easy to collect; +- persistence path is explicit; +- firewall and port requirements are documented; +- disconnect/reconnect behavior is stable enough for testers. + +Until then, listen server can be used for quick internal validation, provided +code still follows server-authoritative patterns. + +## Testing Gates + +Minimum multiplayer smoke test: + +1. Start server. +2. Connect player A. +3. Connect player B. +4. Confirm both see same world time/weather. +5. Player A gathers a resource. +6. Player B observes the changed resource state. +7. Player A crafts an item. +8. Inventory replication remains correct. +9. Player B places or observes a build piece. +10. Restart server and verify expected persisted state. + +Minimum tile/network proof: + +1. Client resolves `maps.agrariangame.com`. +2. Client downloads `manifest.json`. +3. Client downloads the Ground Zero tile package files. +4. Client verifies checksums. +5. Client deletes one cached file. +6. Client redownloads and revalidates it. + +Minimum latency test: + +- run the smoke test once on LAN; +- run it once through the intended external/public path when available; +- record ping/latency observations and obvious gameplay pain points. + +## Implementation Priorities + +Near-term multiplayer priorities: + +- confirm MVP listen server vs dedicated server operating path; +- define player join and spawn flow in code/data; +- add network relevancy rules for resource/build/wildlife actors; +- add basic latency testing; +- define disconnect/reconnect behavior; +- keep tile package delivery separate from gameplay authority; +- prepare dedicated server as the closed-test target. + +## Open Questions + +- Should the first closed test require a dedicated server, or can it use a + controlled listen-server host? +- What is the minimum acceptable reconnect behavior for the first closed test? +- Which actors need custom relevancy first: wildlife, resource nodes, build + pieces, or fires/shelters? +- How should the server expose active tile/package version to connecting + clients? +- What port layout should be standardized for gameplay server, tile server, + RCON/admin, and future telemetry? +- When do we introduce client prediction for gathering/building interactions?