MosswartMassacre/AGENTS.md

AGENTS.md

Guidance for coding agents working in MosswartMassacre (DECAL plugin).

See shared cross-repo guidance first: ../AGENTS.md.

Scope and architecture

• This repo is a C# plugin for Asheron's Call using DECAL + VirindiViewService.
• Main projects in solution mossy.sln:
• MosswartMassacre/MosswartMassacre.csproj (primary plugin)
• MosswartMassacre.Loader/MosswartMassacre.Loader.csproj (loader)
• Target framework is .NET Framework 4.8 (net48), x86 runtime expectations.
• The plugin emits WebSocket events consumed by MosswartOverlord.

Rule sources discovered

• Cursor rules: none found (.cursor/rules/ missing, .cursorrules missing).
• Copilot rules: none found (.github/copilot-instructions.md missing).
• Follow cross-repo protocol rules in ../AGENTS.md for payload compatibility.

Build commands

Solution build

• Build Debug solution (recommended during development):
• msbuild "mossy.sln" /p:Configuration=Debug /p:Platform="Any CPU"
• Build Release solution:
• msbuild "mossy.sln" /p:Configuration=Release /p:Platform="Any CPU"

Project build

• Build primary plugin project:
• msbuild "MosswartMassacre/MosswartMassacre.csproj" /p:Configuration=Debug /p:Platform="AnyCPU"
• Build loader project:
• msbuild "MosswartMassacre.Loader/MosswartMassacre.Loader.csproj" /p:Configuration=Debug /p:Platform="AnyCPU"

Restore dependencies

• Legacy packages restore (when needed):
• nuget restore "mossy.sln"
• If package restore issues appear, verify packages/ and packages.config state.

Lint/format/test status

• No repository-wide C# linter/formatter config was found (.editorconfig, StyleCop, dotnet-format config not present).
• No automated unit/integration test project was found in this repo.
• Validation is primarily build + in-game runtime verification.

Single-test guidance (practical)

• Because no automated test suite exists, "single test" means targeted manual verification.
• Preferred single-scenario checks:
• Toggle one plugin command and validate behavior (example: /mm ws enable or /mm report).
• Trigger one event path (example: spawn or chat) and verify backend receives it.
• For backend-coupled checks, also tail backend logs in MosswartOverlord.

Runtime/integration quick checks

• Verify plugin loads in DECAL and opens the VVS tabbed UI.
• Confirm settings persist per character via YAML file.
• Confirm WebSocket registration and periodic telemetry emission.
• Confirm one inventory/full-inventory or delta message reaches backend.
• Confirm no repeated event handler subscriptions after hot reload.

Important coupling points

• WebSocket endpoint currently defined in MosswartMassacre/WebSocket.cs.
• Shared secret header logic also in MosswartMassacre/WebSocket.cs.
• Event envelope fields and type values must stay backend-compatible.
• Avoid unilateral changes to JSON keys (character_name, coords, timestamps, etc.).

Code style conventions observed

Language and formatting

• Use C# 8-compatible syntax; do not rely on newer language-only features.
• Use 4-space indentation and braces on new lines (existing style).
• Keep files UTF-8 and preserve existing BOM behavior where present.
• Keep methods focused; prefer extracting helpers over deeply nested blocks.

Imports/usings

• Group using statements at top of file.
• Order with System* namespaces first, then third-party, then project namespaces.
• Remove unused using directives when touching a file.

Naming and structure

• Public types/methods/properties: PascalCase.
• Local variables/private fields: camelCase; private static fields commonly _prefixed.
• Constants: UPPER_SNAKE_CASE or PascalCase according to existing file style.
• Keep event handler names descriptive (OnX, HandleX, ..._LoginComplete).

Error handling and logging

• Guard plugin startup/shutdown with robust exception handling.
• For external boundaries (WebSocket, file I/O, DECAL hooks), catch and log failures.
• Prefer non-crashing failure behavior with clear in-chat or logger diagnostics.
• Preserve existing logging patterns (IPluginLogger, plugin chat output) in touched files.

Concurrency and event safety

• Be careful with timers, event subscriptions, and hot-reload lifecycle.
• Always unsubscribe handlers during cleanup to prevent duplicate callbacks.
• Avoid blocking calls on game/UI event threads.
• Keep thread-affinity concerns explicit when interacting with UI/game APIs.

Settings and persistence

• Settings are YAML-backed and character-specific (PluginSettings).
• Preserve atomic save behavior (temp file + replace/move pattern).
• Add new settings as optional with safe defaults to keep backward compatibility.

Payload and API conventions

• Emit JSON with stable, snake_case field names expected by backend.
• Include ISO8601 timestamps and parseable coordinate values.
• Keep envelope type values stable unless backend changes in same task.
• Prefer additive changes (new optional fields) over renames/removals.

Repo hygiene for agents

• Keep edits minimal and task-scoped.
• Do not mass-reformat unrelated files.
• Document behavior changes in README or relevant docs when needed.
• If introducing new build/test tooling, add command docs to this file.