Imported from ERR0RPR0MPT/AquaM2L (
AquaMai.Mods/AGENTS.md). Install upstream withnpx skills add ERR0RPR0MPT/AquaM2L --skill AquaMai.Mods. Copyright stays with the author.
AquaMai.Mods
All mod patches live here, organized by category. Each category has a README defining its scope.
STRUCTURE
AquaMai.Mods/
├── General.cs # General settings section + SectionNameOrder enum
├── DeprecationWarning.cs # Warns about deprecated config keys
├── Fix/ # Bug fixes — defaultOn, no side-effects
│ ├── Stability/ # Crash prevention
│ └── Legacy/ # Version-specific fixes
├── GameSystem/ # Behavior changes not possible in stock game
│ ├── Assets/ # Asset loading (bundles, fonts, images, movies)
│ ├── ExclusiveTouch/ # USB touch panel support
│ └── MaimollerIO/ # Custom IO board support
├── GameSettings/ # Override existing configurable settings
├── Tweaks/ # Stability/robustness patches (no behavior change)
│ └── TimeSaving/ # Skip screens, reduce wait times
├── UX/ # User experience improvements
│ └── PracticeMode/ # Practice mode with custom UI
├── Utils/ # Debug/diagnostic tools — no gameplay impact
├── Fancy/ # Advanced/personalization features — less tested
│ └── GamePlay/ # Gameplay-affecting fancy features
│ └── CustomNoteTypes/ # Custom slide note types (complexity hotspot)
├── Enhancement/ # Server-side enhancements (announcements, resources)
└── Types/ # Shared types (ConditionalMessage, etc.)
HOW TO ADD A NEW MOD
- Create
{Category}/{ModName}.cs - Add
[ConfigSection]attribute on class (setname,en,zh) - Add config fields as
public static readonlywith[ConfigEntry] - Write Harmony patches as static methods with
[HarmonyPrefix/Postfix]+[HarmonyPatch] - Optional lifecycle:
OnBeforePatch(),OnAfterPatch(),OnBeforeEnableCheck() - Update
SectionNameOrderenum inGeneral.csif adding a new top-level section
CATEGORY PLACEMENT RULES
| Category | Scope | Default | Key Rule |
|---|---|---|---|
| Fix | Game bugs, annoying features | ON, hidden | No negative/visual side-effects |
| GameSystem | New behaviors impossible in stock | OFF | Asset patches → Assets/ subdir |
| GameSettings | Override existing game settings | OFF | Stock-configurable only; else → GameSystem |
| Tweaks | Stability, less annoying | OFF | Must NOT change game behavior |
| TimeSaving | Skip screens/waits | OFF | Subset of Tweaks |
| UX | User-triggered experience | OFF | User must perceive or trigger it |
| Utils | Debug/diagnostics | OFF | No gameplay impact, may show UI |
| Fancy | Personalization, uncommon | OFF | Not well-tested, advanced users only |
| Enhancement | Server integrations | OFF | Requires server-side support |
CONVENTIONS
- One class = one feature (with nested helper classes allowed)
- Namespace matches directory:
AquaMai.Mods.Fix,AquaMai.Mods.Tweaks.TimeSaving [EnableIf(nameof(field))]for conditional patches within a class[EnableGameVersion]for version-specific patches- Lifecycle methods are static, discovered by exact name match via reflection
- Harmony
__result+return falsepattern for prefix patches that replace return values
