Multiplayer Game System: project study and implementation contract

Study started 16 October 2026. This document records the project identity and architecture. All nine gameplay plugins now have runtime implementations and matching menu pages. Current authoring instructions and implementation limits are in GameplaySystems.md, CombatAndMaps.md, QuestsAndStory.md, VehiclesAndNPCs.md and CompanionAI.md.

The initial Unreal Python asset audit completed with zero commandlet errors and no asset lookup errors. ProjectAssetAudit.json records the original Data Asset values and Blueprint subobject templates: selectable entries and fallback used Mover, the controller was PC_Sandbox, the single-player map was DefaultLevel, and the menu was WBP_NLS_ServerBrowser. The UI asset matches the source palette. Mover's templates include CharacterMover, NavMover, traversal, motion warping, Foley, visual overrides and Smart Object animation. The later BlueprintGraphAudit.json records original controller/editor-tool graphs. Integration now uses new child pawns for both movement families and adds a separate Gameplay Systems map; see GameplaySetupReport.json.

Existing project

Unreal Engine association: 5.8. The audit commandlet reports 5.8.3.
Source/NiceLobbySystem is the small project module. Existing gameplay/front-end C++ lives in Plugins/NiceLobby, split into runtime, EOS, and editor modules.
The project is based on Epic's Game Animation Sample. Both CMC and Mover character Blueprints exist, with animation Blueprints, motion matching, traversal, camera assets, retargeting, and visual overrides. The setup script selects SandboxCharacter_Mover and PC_Sandbox; actual Data Asset values must take precedence over setup defaults.
Existing reusable components include AC_TraversalLogic, AC_VisualOverrideManager, Smart Object animation support, and pre/post animation ticks. Presence does not establish that every behavior is network-safe.
NiceLobby uses Primary Data Assets for characters, levels, UI, and game settings. Runtime defaults are resolved through UNLSDeveloperSettings.
ANLSGameMode already handles selection-based pawn spawning, controller configuration, teams, travel, rounds, damage permission, and kill reporting. Extend it; do not create a competing game loop.
ANLSPlayerState already owns selected character, team/leader state, round state, and scoreboard statistics. Its CopyProperties is the starting point for seamless travel integration.
UNLSCloudSaveSubsystem synchronizes the existing profile. That is not yet a persistent RPG inventory or authoritative world-save service.
Existing Config/DefaultGame.ini changes predate this work and must be preserved.

Visual and interaction identity

Source defaults in NLSUIData.cpp use cool graphite panels (10151C), raised surfaces (1A212B), amber accent (F2A93B), near-white text (EEF2F6), muted slate text (8E9AAB), and rounded corners. These are defaults; the current UI Data Asset can override them.

Reuse UNLSWidgetBase, FNLSUIStyle, the current font assets, focus highlights, navigation sounds, and localization conventions. Existing labels use spaced uppercase text; panels and cards have restrained outlines. Do not introduce a second theme system.

WBP_NLS_ServerBrowser is the existing in-game menu. Its native base originally clamped page selection to indices 0–5. It now retains those indices and appends registered feature pages, with a scrolling header and shoulder-button cycling across the combined list. Existing Widget Blueprint layouts receive the native extension pages. Inventory contains Armor and Backpack as subpages.

Gamepad requirements include shoulder cycling, directional focus, confirm/cancel, right-stick scrolling, restored focus after updates, gamepad-friendly marker naming, and visible input prompts. Fifteen menu tabs cannot simply be squeezed into the current header.

Character integration

Avoid reparenting the existing Blueprint characters to a new native ACharacter without an asset-graph audit. Mover and CMC have different movement assumptions. Introduce a new game-specific Blueprint base as a child of the selected existing character, attach gameplay components, and let selectable descendants inherit it. Keep movement, traversal, camera, animation, and visual overrides in their existing owners. A native gameplay component/interface supplies common behavior across both pawn families where needed.

Use an ANLSPlayerState subclass for durable character progression and inventory ownership, with replicated components. Pawn components hold transient health/combat/interaction state and resolve their persistent owner after possession. A game mode subclass extends existing hooks while retaining PC_Sandbox and selection-based spawning.

Plugin boundaries

Plugin	Responsibilities	Dependencies
NiceGameCore	Attributes, stable IDs, attribution/damage contracts, persistence, gameplay events, shared themed pages	NiceLobby
NiceInventory	Backpack stacks, item instances, armor slots, equip validation, rarity, attribute modifiers	Core
NiceSkillTree	Prerequisite graph, skill points, survivor/profession/combat branches, unlock tags	Core
NiceQuests	Main/side definitions, objectives, progress policies, completion and reward transactions	Core, Inventory, SkillTree
NiceCombat	Weapon definitions, melee/unarmed styles, firing, reload, ammunition, attachments, cosmetics	Core, Inventory, SkillTree
NiceStoryline	Episodes, scenes, events, branching choices, party progression, access unlocks	Core, Quests
NiceVehicles	Seat ownership, enter/exit, possession, riding interfaces, vehicle and animal adapters	Core, Interactables, SkillTree, Combat
NiceInteractables	Focus discovery, server validation, harvest/door/container implementations	Core, Inventory, SkillTree, EnhancedInput
NiceMaps	World map, top-right minimap, discoverable icons, named custom markers, active tracking, walking navigation	Core, Quests
NiceNPC	Factions, reputation, companion ownership, commands, AI controllers, optional guide provider	Core, Inventory, SkillTree, Interactables, Combat, Vehicles, Maps, Storyline, CompanionAI

Keep dependency direction explicit. Features publish tagged events through Core rather than importing one another in cycles. Each feature registers its menu page on startup and unregisters on shutdown. Definitions use Primary Data Assets and soft references with explicit cook/Asset Manager rules.

Required content and rules

Rarity names and colors exactly follow the request: Common grey, Uncommon green, Rare blue, Legendary purple, Exotic orange-gold. Include readable names/icons so color is not the only cue.
Armor modifies health, stamina, agility, strength and extensible secondary attributes. Distinguish flat, additive percentage, and multiplicative modifiers; represent 5% critical chance and 10% healing explicitly. Equipping and unequipping must be reversible without accumulating bonuses.
Survivor skills: harvest, combine, dismantle, hunt, fish, cook, camp. Professions: Builder, Tailor, Medic, Blacksmith, Enchanter, each with its own subgraph. Combat skills share prerequisite validation.
Combat: gun, rifle, machine gun, rocket launcher, extensible melee families; Kung Fu, Street Fight, Kick Boxing, Karate. Visual and functional customization are separately validated. Mesh replacements require compatible sockets/animation contracts. Decals/material colors do not grant functional bonuses.
Quests and story reward XP, items, skills, area access, and boss access through one server-owned reward transaction. Each claim has a stable identity and is idempotent across retries, reconnects, travel, and save reloads.
Interaction examples: door, button, tree chopping, soil digging, plant harvesting, pickups, rocks, locked doors/chests. Server checks range, line of sight, permissions, tools/skills, cooldowns, and depletion.
Maps show rich world icons but only the active tracked quest or custom marker on the minimap. Pathfinding must select a navigation strategy appropriate to walking, flying, water, or large vehicles; one ground NavMesh path is insufficient.
Vehicle support means an extensible riding/seat contract plus adapters. Bicycles, aircraft, tanks, boats, trains, and animals need distinct movement, animation, collision, and exit placement; a generic possession function alone does not fulfill them.
NPC factions respond to validated world actions. Companions support attack, protect, scout, wait, move, interact, fetch, pickup, and drop, with ownership and reachability checks. Large companions can expose the mount contract.
Optional AI dialogue goes through a replaceable server-side provider. Model output cannot directly award items, complete quests, or execute arbitrary commands. Scripted guidance remains usable offline. Provider choice, cost policy, and data-sharing rules are still open.

Multiplayer contract

The same authority path runs in standalone, listen server, and dedicated server. Client requests travel through player-owned replicated actors/components. Clients request an action by stable ID; they never supply final damage, rewards, XP, faction reputation, or item definitions for the server to trust.

Replicate private inventory, quest journal, and learned skills only to the owner where possible. Replicate equipped appearance, riding state, health visibility, and world interactions to relevant observers. Shared story and world state belong to a replicated world owner/GameState integration. Split-screen/local players must resolve the correct owning player rather than global player zero.

Define persistence identity separately from selectable character skin. Cover respawn, seamless and classic travel, disconnect/reconnect, and host hand-over explicitly. NiceLobby's hand-over reconnects to a new host; it does not automatically transfer all new world state. Host hand-over needs a world snapshot and restoration protocol before claiming support for persistent co-op worlds.

EOS

Reuse the existing Online Subsystem/EOS transport and identity integration. Gameplay replication does not need a separate EOS API for each feature. Existing source contains session, cloud profile, voice, friends, stats, and moderation integrations; live portal configuration and cross-machine success have not been verified.

Before changing the developer portal, first verify the current login/session/voice/cloud flows and decide persistence hosting. Potential work includes client-policy access for the services actually used, deployment/test account access, and a trusted dedicated-server policy if dedicated servers are selected. Do not expose client secrets in reports or put conversational AI credentials in client builds. Exact portal steps require checking current official documentation and the chosen deployment, not assumptions from old setup notes.

Implementation sequence and acceptance

Asset/Blueprint audit and visual baseline; confirm character family and progression ownership.
Core contracts, derived game framework, registered menu pages, persistence versioning.
Inventory + attributes + skill tree vertical slice: pickup, equip, unlock, save, travel, restore.
Interactions + quests + shared reward transactions, then combat and weapon customization.
Story + maps + world persistence and multiplayer choice resolution.
Vehicle/animal adapters + factions/companions; optional AI provider last.

Every slice needs a usable themed page and gamepad path. Acceptance matrix: standalone offline; listen host plus two clients; dedicated server plus two clients; join in progress; respawn; seamless/classic travel; disconnect/rejoin; simultaneous pickup/equip/quest claims; invalid and repeated RPCs; save migration and interrupted writes; controller-only navigation; low resolution and ultrawide UI. EOS tests need real authorized accounts on separate processes/machines. Passing a C++ build alone does not establish these behaviors.

Suggested additions for consideration: item durability/repair; crafting recipes shared with profession requirements; configurable accessibility and remapping; data validation for missing IDs/cyclic skill graphs; a small functional test map with representative assets for every feature. These are suggestions, not added requirements.

Accepted decisions (16 October 2026)

Inventory and progression persist per character. Shared party story state has a separate party/campaign identity, rather than being duplicated as unrelated personal stories. Character appearance/selection ID must not be the save identity.
Support CMC and Mover through gameplay components. Preserve their existing movement, traversal, cameras, and animation implementations. Game-specific Blueprint children can provide distinct bases for the two pawn families.
AI provider remains selectable through NiceCompanionAI and Services/CompanionAI; setup and extension instructions are in CompanionAI.md. NPC companions now offer owner-only conversation UI and offline guidance. Hosted provider credentials, deployment and public gateway authentication remain operator configuration.
Shared story choices require a strict majority of active party players; ties wait and players can change votes. One co-op party occupies a server.
Replaceable placeholder meshes and animations are accepted for weapons, martial arts, vehicles and mounts.
Keep the existing NiceLobby theme until a game title/setting is supplied.

Open decisions

Final game title/setting and cross-host campaign-transfer policy remain open. Character records and a separate campaign slot currently persist on the authoritative host. Provider credentials and exact models are operator configuration; no provider has been selected or called live.

Verification scope

The UE 5.8.3 NiceLobbySystemEditor Win64 Development build passes with all feature modules. The current native suite passes 23 tests with zero warnings or failures, including authority, invalid requests, reward idempotency, saves, factions and companion inventory. Seventeen Python adapter/gateway tests passed previously, including loopback HTTP; cloud calls were mocked. Runtime reports under Saved/Automation/RuntimeValidation distinguish standalone, rendered, dedicated-server and listen-server runs. These editor-process tests do not establish live EOS, cross-machine, packaged platform, physical-controller or host-migration support. Consult the latest report for each mode rather than treating a native build as full acceptance.