# 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 telemetry on`).
- 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.