servuo-plugins/CONTRIBUTING.md

Contributing to Runic Gateway — ServUO Plugin

Thanks for your interest in contributing! This repo is the C# ServUO side of the game bridge. The shard emits newline-delimited JSON over a loopback TCP socket to the Rust sidecar (RunicGateway/link).

By participating you agree to abide by our Code of Conduct.

Ways to contribute

• Report a bug or request a feature through the issue tracker (issue templates are provided).
• Improve the code or docs by opening a pull request (see below).
• Never report a security vulnerability in a public issue — see SECURITY.md.

Development setup

This plugin is deployed as source and compiled by ServUO at boot — there is no standalone build artifact and no CI build (it needs the ServUO reference assemblies to compile). See the README for the full model.

Key rule: anything under overlay/ is authoritative and mirrors the ServUO server root. Do not edit files in a deployed server tree directly — edit here under overlay/ (or patches/ for changes to stock ServUO files) and deploy:

# Show what would change, then write it into a ServUO install:
.\deploy.ps1 -ServerPath C:\path\to\servuo -Verify
.\deploy.ps1 -ServerPath C:\path\to\servuo

• overlay/ — copied over an install (the only thing deploy.ps1 deploys).
• patches/ — unified diffs against stock ServUO for files we must modify.
• tools/ — never deployed: test scaffolding and stub sidecars.

Testing

tools/stub_sidecar.ps1 is a loopback listener that logs every line the shard sends — run it, boot the shard, and watch events arrive:

.\tools\stub_sidecar.ps1 -Port 7788 -Log .\sidecar.log

tools/stub_sidecar_request.ps1 additionally sends inbound requests to exercise the request/response handlers. For real end-to-end testing, run against the Rust sidecar rather than the throwaway PowerShell stubs.

Protocol compatibility

The loopback JSON protocol is a compatibility contract shared with the sidecar. The canonical event/command catalog lives in the docs repo (PLAN.md §5/§7 and INTEGRATION.md). If you add or change an event or command, keep the plugin, the sidecar, and the spec in sync.

Branch & PR workflow

1. Branch from main with a descriptive name (feature/…, fix/…, docs/…, chore/…).
2. Keep changes focused; small PRs are easier to review.
3. Push and open a pull request against main. Fill out the PR template, including the AI-assisted contributions disclosure.
4. A maintainer will review; address feedback with follow-up commits.

Commit messages

We use Conventional Commits — type(scope): summary (e.g. feat(bridge): add vendor.sale event).

AI-assisted contributions (disclosure required)

This project is developed openly with AI assistance, and we ask the same transparency of everyone. If you used an AI tool (Claude, Copilot, ChatGPT, Cursor, etc.) to help produce a contribution, you must disclose it:

• Tick the AI-usage box in the pull-request template and name the tool(s).
• Mark AI-authored commits with a trailer, e.g. Co-Authored-By: Claude <noreply@anthropic.com> or Assisted-By: <tool>.
• You remain responsible for every line you submit: review it, understand it, and make sure it is correct and that you have the right to contribute it.

Disclosed AI assistance is welcome. Undisclosed AI-generated contributions are not, and may be closed.

License

Runic Gateway is licensed under the GNU General Public License v3.0 or later (see LICENSE.md). By submitting a contribution you agree that it is licensed under the same terms (inbound = outbound) and that you have the right to contribute it.