Untitled

Here’s a clean, ready-to-copy summary of the entire 20v20 Captain Mode project, all steps and context — no code, just a structured overview you can drop directly into your new chat:

🧭 Project Overview — 20v20 Captain Mode (YSBCaptain)

Goal:
Enable a true 20v20 Captain Mode for Mount & Blade II: Bannerlord, using a server-side only mod that merges all players’ troops into a single shared formation per side, while maintaining individual player control through sub-formations and command routing.

🧩 Core Concept

Each team (Attacker / Defender) has one real formation that contains all troops.

Each human player has a sub-formation within that shared formation, controlling only their assigned bots.

Players issue orders normally (F1–F3, etc.), but commands are filtered to only affect their bots.

The system must scale up to 20 players per team, each with controlled agents, without exceeding formation or network limits.



MergedCaptainConfig

Central configuration class controlling:

Enabled toggle

MergedSide (Attacker or Defender)

RealFormationIndex (usually 0 for Infantry)

TeamCap (max players per side, default 10)

TestMaxBotsForMergedSide (total bots split evenly among players)

DebugBroadcast (toggle for chat debugging via YSBLogger)

YSBCaptainSpawningBehavior

Replaces native spawning with a custom merged spawn flow.

Handles:

Deterministic player admission by join order.

Controlled agent spawning.

Bot ownership distribution using MergedAssignHelper.

Failsafe logging and error protection during spawn.

Broadcasts in-game and console messages via YSBLogger (for real-time testing).

MergedCaptainBootstrapBehavior

Replaces the default SpawnComponent behavior with YSBCaptainSpawningBehavior via reflection at mission start.

Subformation System

SubformationRegistry: Tracks which bots belong to which player.

SubformationOrderRouter: Intercepts and reroutes player orders so each player only commands their assigned sub-formation.

MergedAssignHelper

After all bots are spawned, evenly distributes bot ownership across all players on the merged side.

Ensures every player gets control over their own subset of the team’s formation.



Key Harmony Patches

OrderController Patches

Intercepts order commands and forwards them to the SubformationOrderRouter.

Ensures formation-wide commands only affect the correct player-owned sub-formation.

Formation.SetMovementOrder Patch

Prevents the entire shared formation from moving when one player issues a movement command.

TeamAIComponent Patch

Disables native team AI when merged mode is active (so AI doesn’t override player orders).



Logging System (YSBLogger)

Unified logger for both console output and in-game chat messages.

Used to trace:

Spawn activity

Formation assignment

Sergeant setup

Bot ownership redistribution

Error handling and null-reference warnings

All logs are prefixed with [YSB][Spawn], [YSB][Formation], [YSB][Error], or [YSB][Merge].

🧪 Testing Procedure

Solo test:

1 attacker player (merged side) vs 1 AI defender formation.

Validate spawn, sergeant assignment, and order UI (F1–F3 should be active).

2-player test:

2 players on the same merged side.

Confirm both get separate bots and control only their own troops.

Orders from one player shouldn’t affect the other’s bots.

Over-cap test:

Join 11th player → should automatically move to spectators with a YSBLogger message.

Crash-tracing:

Added try/catch fences around all risky operations (spawn visuals, formation fetch, bot spawn, redistribution).

Errors are logged visibly to in-game chat and console.



Fixing crash during spawn phase at round start (occurs right after warmup ends).

Current logs confirm agent creation and visuals spawn, but the crash likely happens post-spawn, possibly during formation assignment or bot redistribution.




🧾 Summary of Progress

✅ Stable 20-player server configuration.
✅ Merged formations implemented server-side.
✅ Sub-formation routing functional.
✅ In-game logging via YSBLogger integrated.
✅ Build compiles cleanly.
❌ Crash persists during first spawn wave (under investigation).

🧩 Next Tasks

Analyze crash logs post-spawn using new YSBLogger output.

Verify if crash occurs in DistributeBotsRoundRobin or post-spawn cleanup.

Add conditionals for formation existence and agent validity.

Implement optional delayed wave spawning (if performance requires).

Project name: YSBCaptain
Mode: 20v20 Captain Mode (Server-side only)
Status: Compiles ✅, In-Game Crash 🔧 (Spawn Phase)
Next step: Crash trace + stabilization.





🧱 YSBCaptain – Affected .cs Files Summary
⚙️ Core Module Files
YSBCaptain.cs

Entry point (SubModule class).

Loads Harmony patches when the module is initialized.

Calls Harmony.PatchAll() to register all custom patches across the project.

Responsible for enabling merged mode logic (MergedCaptainConfig.Enabled).

Triggers the replacement of native spawn behavior with YSBCaptainSpawningBehavior.

MergedCaptainConfig.cs

Global static config class used everywhere.

Controls all tuning options and debugging toggles:

Enabled – whether merged mode logic is active.

MergedSide – which side (Attacker or Defender) is being merged.

RealFormationIndex – which formation is the “true” one.

TeamCap – maximum allowed players per side.

TestMaxBotsForMergedSide – total bots for merged side, divided per player.

(Optional debug toggle coming soon) DebugBroadcast.

🪖 Spawning & Mission Behaviors
YSBCaptainSpawningBehavior.cs

Central logic hub for the project.

Overrides Bannerlord’s spawn process to implement shared formation spawning.

Performs:

Admission control (team player caps, join order).

Custom agent and bot spawning logic.

Bot ownership redistribution using MergedAssignHelper.

Spectator reassignment for over-cap or late-joining players.

Integrates YSBLogger messages for every spawn step.

Adds multiple crash-safety fences (formation null checks, spawn try/catch).

Ends by setting up sergeants and assigning players to the single shared formation.

YSBCaptainSpawningBehaviorBase.cs

Original base class the custom spawning behavior inherits from.

Provides the default structure for Captain mode spawning (used as reference).

Contains utility methods like SpawnBotVisualsInPlayerFormation, GetMPHeroClassForPeer, and GetOnSpawnPerkHandler.

Not directly modified — serves as the template for safe overriding in YSBCaptainSpawningBehavior.

TeamJoinAnnouncerWithCap.cs

Tracks player join times and team caps.

Maintains a dictionary of NetworkCommunicator → FirstSeenTime.

Used to enforce “first come, first serve” logic when teams reach capacity.

Provides static helper GetFirstSeenTime() used in spawn admission sorting.


🪶 Subformation System
SubformationRegistry.cs

Tracks which player owns which sub-formation.

Maintains a mapping:
MissionPeer → SubformationId

Ensures bots spawned for each player are assigned correctly.

Referenced by SubformationOrderRouter and MergedAssignHelper.

SubformationOrderRouter.cs

Intercepts and reroutes player orders (e.g., F1–F3 commands).

Ensures that only the player’s assigned bots receive the command.

Prevents global formation orders from affecting other players’ units.

Core of the “shared formation but individual control” logic.

Replaces OrderController flow server-side using Harmony patches.

⚔️ Merged Formation Utilities
MergedAssignHelper.cs

Distributes bots across all players on the merged side after spawning.

Uses a round-robin or even-split assignment.

Prevents duplicate control assignments or bots left unassigned.

Called at the end of YSBCaptainSpawningBehavior.SpawnAgents().

Now wrapped in a try/catch with YSBLogger output for crash diagnostics.

🧠 Harmony Patch Classes
TeamAIPatches.cs

Harmony patch targeting TeamAIComponent.OnTickAsAI().

Fully disables team AI when merged mode is active, preventing the native AI from giving conflicting formation orders.

FormationPatches.cs

Harmony patch targeting Formation.SetMovementOrder().

Cancels formation-wide movement orders for the shared “real formation.”

Ensures only subformation-level commands apply.


💬 Logging & Debugging
Logger.cs

Unified logging utility used throughout the project.

Provides:

SendMessageToAll(string message) — sends in-game system chat messages to all connected players.

Log(string message, LogLevel level) — prints to server console.

Used extensively in YSBCaptainSpawningBehavior and the Harmony patches.

Supports multiple levels (Info, Warning, Error).

Allows easy future toggle between silent or verbose modes.

🧩 Supporting Logic (Integrated)
MergedCaptainBootstrapBehavior.cs

Injected during mission initialization.

Detects mission type and replaces the native spawn behavior with YSBCaptainSpawningBehavior.

Ensures compatibility with Captain mode and prevents duplication of behaviors.

⚠️ Crash Focus Areas

YSBCaptainSpawningBehavior:

Crashes occur during or immediately after spawn.

Potential causes: null formation, invalid agent ownership, or redistribution issues.

Protected with new try/catch + YSBLogger traces.

MergedAssignHelper:

Can crash if called before bots or players are fully initialized.