sdv-mp-gamepad-audit

This skill should be used when the user asks to "check multiplayer support", "audit gamepad navigation", "verify split-screen", or before committing changes to menu code. Also use when working on per-player state, mutex locking, PerScreen usage, controller navigation, or any file in the Managers/ or Menus/ directories.

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 1, 2026⬇️2downloads

When & Why to Use This Skill

The SDV Multiplayer & Gamepad Audit skill is a specialized static analysis tool designed to ensure code compatibility for multiplayer and gamepad environments. It automates the detection of common pitfalls in game development, such as improper state sharing in split-screen modes, missing mutex locks for shared resources, and incomplete gamepad navigation logic. By providing a comprehensive checklist-based audit, it helps developers catch critical bugs before manual testing, ensuring a seamless experience for all players.

Use Cases

  • Pre-commit Audit: Automatically review changes in Managers or Menus directories to prevent breaking multiplayer synchronization or menu navigation.
  • Split-screen Compatibility: Identify static fields that need to be wrapped in PerScreen<T> to prevent state leaking between local players.
  • Gamepad Accessibility Check: Verify that all UI components have unique IDs and proper neighbor mappings for consistent controller navigation.
  • Concurrency Safety: Audit shared furniture and resource access to ensure mutex locks are correctly requested and released, preventing deadlocks or data corruption.
  • Data Integrity Verification: Ensure per-player save data is uniquely keyed with multiplayer IDs to prevent data overwrites in shared sessions.
namesdv-mp-gamepad-audit
descriptionThis skill should be used when the user asks to "check multiplayer support", "audit gamepad navigation", "verify split-screen", or before committing changes to menu code. Also use when working on per-player state, mutex locking, PerScreen usage, controller navigation, or any file in the Managers/ or Menus/ directories.
version1.0.0

SDV Multiplayer & Gamepad Audit

Static analysis for multiplayer and gamepad support. Since runtime testing of these features is difficult, this skill provides comprehensive code auditing to catch issues before manual testing.

When to Run This Audit

  1. Before committing changes to any file in Managers/ or Menus/
  2. After adding new state variables (fields, properties)
  3. When implementing features that affect multiple players
  4. Before PR creation

Multiplayer Audit Checklist

1. PerScreen Wrapper Audit

All per-player mutable state MUST use PerScreen<T>:

// WRONG: Static state shared across split-screen players
private static MenuManager menuManager;
private static int currentTab = 0;

// CORRECT: Per-screen state
private static readonly PerScreen<MenuManager> menuManager = new();
private static readonly PerScreen<int> currentTab = new(() => 0);

// Access via .Value
menuManager.Value.DoSomething();
int tab = currentTab.Value;

Audit Points:

  • All static fields with mutable state use PerScreen
  • PerScreen fields are readonly (prevents clearing all screens)
  • PerScreen initialized with proper factory if needed: new(() => defaultValue)
  • Manager classes use PerScreen in the entry point

2. Context Checks

Verify proper context gating:

// Required before accessing world state
if (!Context.IsWorldReady) return;

// Required before player interaction logic
if (!Context.IsPlayerFree) return;

// Required for host-only operations
if (!Context.IsMainPlayer) return;

// Required for save operations
if (Context.IsMainPlayer)
{
    Helper.Data.WriteSaveData("key", data);
}

Audit Points:

  • Event handlers check Context.IsWorldReady before accessing Game1.player
  • Save operations check Context.IsMainPlayer (farmhands can't use save API)
  • Menu operations check Context.IsPlayerFree when appropriate

3. Mutex Locking (Shared Furniture)

Dressers and other shared furniture require mutex:

// CORRECT: Request lock before opening menu
if (!dresser.mutex.IsLocked())
{
    dresser.mutex.RequestLock(delegate {
        Game1.activeClickableMenu = new WardrobeMenu();
    });
}

// CRITICAL: Release on menu close
public override void emergencyShutDown()
{
    base.emergencyShutDown();
    dresserObject?.mutex?.ReleaseLock();
}

protected override void cleanupBeforeExit()
{
    base.cleanupBeforeExit();
    dresserObject?.mutex?.ReleaseLock();
}

Audit Points:

  • Shared furniture access uses mutex.RequestLock()
  • Menu emergencyShutDown() releases mutex
  • Menu cleanupBeforeExit() releases mutex
  • Null checks on mutex before release

4. Player Data Keying

Per-player save data must be uniquely keyed:

// CORRECT: Unique key per player, per save, per multiplayer session
string dataPath = $"data/favoritesData/{Game1.player.Name}_{Constants.SaveFolderName}_{Game1.player.UniqueMultiplayerID}.json";

// Also valid for modData (always prefix with mod ID)
Game1.player.modData[$"{ModId}/PlayerFlag"] = "true";

Audit Points:

  • Save paths include player identifier AND save folder AND multiplayer ID
  • modData keys prefixed with mod's UniqueID
  • No assumptions that data paths are unique without proper keying

5. Location Iteration

Use utilities that work for farmhands:

// WRONG: Misses some locations for farmhands
foreach (var loc in Game1.locations) { }

// CORRECT: Works for all players
Utility.ForAllLocations(loc => {
    // process location
});

Gamepad Audit Checklist

1. ClickableComponent Navigation

Every clickable element needs navigation IDs:

var button = new ClickableComponent(bounds, "name");
button.myID = 1001;                    // REQUIRED: Unique ID
button.leftNeighborID = 1000;          // Left neighbor (or -99999 for none)
button.rightNeighborID = 1002;         // Right neighbor
button.upNeighborID = 900;             // Up neighbor
button.downNeighborID = 1100;          // Down neighbor

Audit Points:

  • Every ClickableComponent has myID set
  • Every ClickableComponent has all four neighborIDs set
  • IDs are unique within the menu
  • Navigation forms logical grid (no dead ends)
  • Use -99999 for "no neighbor" (not 0 or -1)

2. Component List Population

public override void populateClickableComponentList()
{
    base.populateClickableComponentList();
    allClickableComponents.AddRange(labels);
    allClickableComponents.AddRange(buttons);
    allClickableComponents.AddRange(equipmentIcons);
    // Add ALL clickable elements
}

Audit Points:

  • populateClickableComponentList() adds all components
  • snapToDefaultClickableComponent() called after population
  • Components not added after initial setup (or list repopulated)

3. Focus Management

public override void snapToDefaultClickableComponent()
{
    base.snapToDefaultClickableComponent();
    currentlySnappedComponent = getComponentWithID(defaultFocusId);
    snapCursorToCurrentSnappedComponent();
}

Audit Points:

  • Menu has a logical default focus element
  • Focus returns to sensible element after actions
  • Child menus properly handle focus transfer

4. Button Hints

For important actions, show controller button hints:

// In draw():
if (Game1.options.gamepadControls)
{
    // Draw A button hint next to action button
    b.Draw(Game1.controllerMaps, position, sourceRect, Color.White);
}

Audit Output Format

When running this audit, report findings as:

## Multiplayer Audit Results

### Issues Found

1. **PerScreen Missing** - `Managers/MenuManager.cs:45`
   - Field `currentCategory` is static but not wrapped in PerScreen<T>
   - Fix: Change to `private static readonly PerScreen<string> currentCategory = new();`

2. **Mutex Not Released** - `Menus/WardrobeMenu.cs:312`
   - `emergencyShutDown()` doesn't release mutex
   - Fix: Add `dresserObject?.mutex?.ReleaseLock();`

### Gamepad Navigation Issues

1. **Missing neighborID** - `Menus/FavoritesMenu.cs:189`
   - `deleteButton` has no `upNeighborID` set
   - Fix: Add `deleteButton.upNeighborID = renameButton.myID;`

### Passed Checks
- [x] All PerScreen fields are readonly
- [x] Context.IsWorldReady checks present in event handlers
- [x] Save operations check Context.IsMainPlayer

Quick Reference

Split-Screen Player Access

// Current screen's value
var current = perScreenField.Value;

// Specific screen's value
var screen0 = perScreenField.GetValueForScreen(0);

// Current screen ID
int screenId = Context.ScreenId;

Common Navigation ID Ranges

// Use ranges to organize IDs
const int LABELS = 10000;
const int BUTTONS = 20000;
const int CATEGORIES = 30000;
const int OUTFIT_CARDS = 40000;

// Then: button.myID = BUTTONS + index;