AgrarianGameArchive/Docs/MultiplayerNetworkingDesign.md

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:

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?