# MVP QA Gates

Version `0.1.Q` turns the current survival MVP into a repeatable test target.
Each gate must have either automation, a documented manual test, or build
evidence before it is marked complete.

## Packaged Client Launch

The packaged client launch gate proves the Windows investor/demo package can be
created, opened through a known launcher, and checked through the real-GPU
visual QA path.

Required evidence:

- `Scripts/PackageWindowsDevelopment.bat` completes successfully.
- `Builds/WindowsDevelopment/AgrarianGame.exe` exists.
- `Scripts/InstallWindowsDemoLaunchers.bat` installs:
  - `Start Agrarian Demo.cmd`
  - `Start Agrarian Demo - DX12.cmd`
  - `Start Agrarian Demo - Compatibility DX11.cmd`
- `Scripts/RunWindowsInvestorVisualQACheck.bat --check-tools` reports the
  packaged demo exists and `SunshineService` is running.
- Any full visual pass stores notes under `Saved\VisualQA\InvestorDemo`.

This gate is client-only. It does not require multiplayer server deployment.

## Server Launch

The server launch gate proves the MVP gameplay host can start the current
server-compatible package and expose the Unreal gameplay port.

Current MVP launch path:

- Prefer the true Linux dedicated-server target when a server-capable Unreal
  engine is available:
  `Scripts/BuildLinuxDedicatedServer-Windows.bat`
- Until then, use the binary-engine fallback:
  `Scripts/PackageLinuxGameServerFallback-Windows.bat`
- Deploy the produced package to `/opt/agrarian/server`.
- Launch through `/opt/agrarian/server/AgrarianGameServer.sh`.
- Manage the host with `agrarian-game-server.service`.

Required evidence:

- `systemctl is-active agrarian-game-server.service` reports `active`.
- `ss -lunp` shows `AgrarianGame` listening on `0.0.0.0:7777/udp`.
- The journal shows the Ground Zero map browse started.
- The runbook explains the true dedicated target and fallback path.

This gate is server-relevant and requires multiplayer server verification when
server launch tooling or deployed package contents change.

## Two-Client Connection

The two-client connection gate proves the MVP can be tested as a multiplayer
session with two packaged Windows clients connected to the same Ground Zero
server.

Required evidence:

- The server launch gate is passing.
- `Scripts/RunTwoClientConnectionSmoke-Windows.bat --check-tools` confirms the
  packaged client exists.
- The helper launches two clients against the same endpoint:
  `play.agrariangame.com:7777` by default, or a supplied LAN endpoint such as
  `192.168.5.15:7777`.
- Both clients reach the same Ground Zero session.
- Testers confirm both clients see the same time/weather and can remain
  connected long enough to begin the smoke test.

The manual observation steps continue in
`Docs/Ops/MultiplayerLatencyTestPlan.md` until gameplay automation can drive
two clients directly.

## Resource Gathering

The resource gathering gate proves a player can interact with placed Ground
Zero resource nodes and receive authoritative resource inventory changes.

Required evidence:

- Ground Zero includes placed wood and fiber resource nodes.
- `AAgrarianResourceNode` exposes `Gather` or `Gather by hand` prompts.
- Gathering runs only with server authority.
- Successful gathering decrements replicated `RemainingHarvests`.
- The gathered item stack is granted through the character inventory path.
- Resource depletion persistence is covered by the save/load gate.
- `Scripts/verify_playable_loop_smoke.py` includes wood and fiber gathering in
  the natural shelter loop smoke test.

This gate is gameplay/server-relevant and should be covered by the next server
package deployment.

## Craft Shelter

The craft-shelter gate proves the MVP can build a primitive shelter path from
resources through recipes and world placement.

Required evidence:

- Primitive frame, wall panel, roof panel, and shelter recipes exist.
- `BP_PrimitiveShelter` derives from the native shelter actor.
- Building placement consumes active buildable cost on the server.
- Shelter actors persist through the world-actor persistence path.
- `Scripts/verify_playable_loop_smoke.py` runs the natural shelter loop using
  wood, fiber, wildlife, shelter-piece recipes, and the primitive shelter class.

This gate is gameplay/server-relevant and should be covered by the next server
package deployment.

## Craft Fire

The craft-fire gate proves the MVP can produce or use a campfire through the
crafting/building loop, then interact with that fire in the world.

Required evidence:

- `DA_Recipe_Campfire` exists with the `campfire` recipe ID.
- The campfire item/buildable path is available to the player blueprint setup.
- `BP_Campfire` derives from `AAgrarianCampfire`.
- `AAgrarianCampfire` supports `Light fire` and `Maintain fire` interaction
  prompts.
- Campfire lit/fuel state is replicated.
- Campfire persistence and fire-risk QA verifiers pass.

This gate is gameplay/server-relevant and should be covered by the next server
package deployment.

## Full Day/Night Survival

The full day/night survival gate proves one player can remain alive through one
complete compressed Agrarian day while the server advances time, weather, and
survival pressure.

MVP timing:

- The gameplay calendar target is `4 real hours = 1 in-game day`.
- `AAgrarianGameState` advances and replicates `WorldHours`, day/year state,
  solar bounds, `IsNight`, weather, and ambient temperature.
- The pass starts at a known hour, preferably dawn or morning, and ends after
  `WorldHours` reaches the same solar phase on the next in-game day.

Required evidence:

- Hunger, thirst, stamina, body temperature, and health update over time on
  server authority.
- A player can gather resources, craft or use a fire, craft or use shelter,
  and recover enough food/water/warmth to avoid death for the full cycle.
- Day/night state changes at least once and returns to the original phase.
- The critical survival HUD can show alive/dead state and core stat pressure.
- World time and player survival state are covered by save/load persistence.
- The result is recorded as either a completed manual run or a captured test
  log before external MVP demos treat the gate as fully play-proven.

This gate is gameplay/server-relevant and should be covered by the next server
package deployment.

## Survival Pressure Death

The survival-pressure death gate proves the MVP does not merely display hunger,
thirst, exposure, illness, or injury as cosmetic stats. Sustained pressure must
be able to reduce health, mark the character dead, replicate the death state,
and expose a clear respawn path.

Required evidence:

- Starvation, dehydration, cold exposure, sickness, and bleeding can reduce
  `Survival.Health` on server authority.
- `ClampSurvival` calls `UpdateDeathState`, clamps health to zero, clears
  stamina, sets `bIsDead`, and records `LastDeathReason`.
- The replicated survival snapshot includes the death state and last death
  reason.
- The critical survival HUD and death/respawn panel display the dead state and
  cause.
- The player controller exposes the MVP respawn path and revives the survival
  component on the server.
- Death/respawn behavior remains persistence-safe through the player stat
  save/load path.

This gate is gameplay/server-relevant and should be covered by the next server
package deployment.

## Reconnect State Retention

The reconnect state retention gate proves a player can disconnect, reconnect,
and recover the MVP state that matters for a continuing survival session instead
of starting over from a blank pawn.

Required evidence:

- `AAgrarianGameGameMode::Logout` captures a player snapshot before the pawn is
  released.
- `AAgrarianGameGameMode::RestartPlayer` restores a matching snapshot after the
  normal MVP spawn path.
- `UAgrarianPersistenceSubsystem::SavePlayerSnapshot` and
  `RestorePlayerSnapshot` preserve transform, safe player identity, survival,
  care history, and inventory.
- Inventory restore uses `RestoreSavedItems` so derived carry weight and
  inventory listeners refresh after reconnect.
- If no matching snapshot exists, the player falls back to the normal MVP spawn
  point instead of failing the join.
- The manual two-client test records reconnect evidence alongside world
  time/weather consistency.

This gate is server-relevant and must be rechecked after multiplayer package
deployment.

## Server Restart Shelter Persistence

The server restart shelter persistence gate proves a placed primitive shelter is
not merely a runtime actor. It must be captured into the world save, restored by
the server on startup, and remain available for weather protection after a
restart.

Required evidence:

- `AAgrarianShelterActor` owns a persistent actor component with
  `ActorTypeId = primitive_shelter`.
- The game mode registers `primitive_shelter` with the persistence subsystem
  before loading current world state.
- `SaveCurrentWorld` captures world actors and `LoadCurrentWorld` restores
  registered world actors.
- Server startup uses `bLoadWorldOnServerStart`, checks `DoesSaveExist`, and
  calls `LoadCurrentWorld` without clearing existing map actors.
- Shelter weather-protection verification remains tied to the restored shelter
  actor.
- A release smoke run should place a shelter, save, restart the server, and
  confirm the shelter remains at the same transform.

This gate is server-relevant and must be rechecked after the final 0.1.Q server
package/deploy if server code or package contents changed.

## Thirty-Minute Critical Log Soak

The 30-minute critical log soak gate proves the MVP can run through a short
investor/tester session without noisy fatal, crash, assertion, ensure, or
critical error spam hiding real problems.

Required evidence:

- Run a packaged client and the target server for at least 30 minutes.
- Exercise the normal MVP loop during the soak: join, gather, craft/use fire,
  craft/place shelter, wait through time/weather pressure, disconnect, and
  reconnect if possible.
- Preserve client logs, server logs, and any visual QA summary under `Saved`
  or the release evidence folder.
- Run `Scripts/scan_critical_log_spam.py` against those logs.
- A passing scan reports zero fatal/crash/assert/ensure/critical-error matches.
- Any known noisy-but-harmless line must be added to the scanner allowlist with
  a short comment in the commit that introduced the allowlist entry.

This gate is both client and server relevant. It must be re-run for final
milestone packages before sending an investor demo as stable.

## Target Player Count Server Stability

The target player count server stability gate proves the MVP server can hold
the defined early test population long enough to exercise the core survival loop
without a crash, disconnect cascade, or critical log spam.

MVP target:

- minimum proof: 2 players connected to the same server;
- target closed-test smoke group: 4 players on one server;
- stretch test: 8 players only after the dedicated/listen server path is
  stable.

Required evidence:

- The server launch gate passes on the target host.
- The two-client connection gate passes at minimum.
- For closed-test readiness, repeat the same smoke with 4 connected clients.
- During the run, connected clients exercise join, gather, craft/use fire,
  craft/place shelter, survival pressure, disconnect, and reconnect where
  possible.
- Run the critical log scanner on the captured client and server logs.
- Server-side UDP `7777` remains listening and the service remains active after
  the smoke.

This gate is server-relevant and should be re-run after every server package
deployment that changes gameplay, persistence, networking, map content, or
server startup behavior.
