20V20 CAPTAIN MODE v4

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

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.

Now has log tracing to isolate issues.

🧾 Summary
Category 	Purpose 	Files
Core 	Module entry + global config 	YSBCaptain.cs, MergedCaptainConfig.cs
Spawning 	Handles custom spawn logic 	YSBCaptainSpawningBehavior.cs, YSBCaptainSpawningBehaviorBase.cs, TeamJoinAnnouncerWithCap.cs
Subformations 	Player-bot command routing 	SubformationRegistry.cs, SubformationOrderRouter.cs
Helpers 	Bot distribution 	MergedAssignHelper.cs
AI & Formation Control 	Disable default AI, block global orders 	TeamAIPatches.cs, FormationPatches.cs
Utilities 	Logging + server feedback 	Logger.cs
Bootstrap 	Mission behavior injection 	MergedCaptainBootstrapBehavior.cs


/////////////////////////////////////////////////////////////////////////////////////


YSBCaptain (Main Module Entry)
│
├──► MergedCaptainConfig.cs
│     ├── Provides global config values
│     ├── Accessed by almost every other system
│     └── Determines enabled side, caps, debug mode, etc.
│
├──► YSBCaptainSpawningBehavior.cs
│     ├── Core of merged Captain spawn system
│     ├── Reads settings from MergedCaptainConfig
│     ├── Calls:
│     │    ├── TeamJoinAnnouncerWithCap.GetFirstSeenTime()
│     │    ├── MergedAssignHelper.DistributeBotsRoundRobin()
│     │    ├── YSBLogger.SendMessageToAll()  ← Debug broadcast
│     │    └── SubformationRegistry / SubformationOrderRouter indirectly
│     ├── Invoked by:
│     │    └── MergedCaptainBootstrapBehavior (at mission start)
│     └── Replaces native Captain spawn logic
│
├──► TeamJoinAnnouncerWithCap.cs
│     ├── Tracks join times & admission order
│     └── Referenced only by YSBCaptainSpawningBehavior
│
├──► MergedAssignHelper.cs
│     ├── Called after all bots are spawned
│     ├── Distributes bot ownership evenly
│     ├── Uses:
│     │    ├── SubformationRegistry
│     │    └── YSBLogger for output
│     └── Called by YSBCaptainSpawningBehavior (end of SpawnAgents)
│
├──► SubformationRegistry.cs
│     ├── Global mapping: Peer → SubFormationID
│     ├── Queried and updated by:
│     │    ├── MergedAssignHelper
│     │    └── SubformationOrderRouter
│     └── Ensures each player controls only their assigned bots
│
├──► SubformationOrderRouter.cs
│     ├── Intercepts player orders (Harmony)
│     ├── Routes commands only to bots belonging to that player
│     ├── References:
│     │    ├── SubformationRegistry (ownership check)
│     │    └── MergedCaptainConfig (mode enable)
│     └── Activated when player issues F1–F3 orders
│
├──► FormationPatches.cs
│     ├── Harmony patch for Formation.SetMovementOrder()
│     ├── Prevents global formation movement when merged mode enabled
│     └── Depends on MergedCaptainConfig.Enabled
│
├──► TeamAIPatches.cs
│     ├── Harmony patch for TeamAIComponent
│     ├── Disables native AI control in merged mode
│     └── Prevents double-commanding of the shared formation
│
├──► Logger.cs (YSBLogger)
│     ├── Used everywhere for debugging and in-game chat broadcast
│     ├── Provides:
│     │    ├── SendMessageToAll(string message)
│     │    └── Log(string message, LogLevel)
│     └── Central for runtime diagnostics
│
└──► MergedCaptainBootstrapBehavior.cs
      ├── Replaces Bannerlord’s spawn behavior at mission start
      ├── Instantiates YSBCaptainSpawningBehavior
      ├── Checks if Captain Mode and MergedCaptainConfig.Enabled
      └── Sets up mission behaviors before round begins