Developer‐Guide

Developer Guide

This section covers integration points, API concepts, message contracts (NATS & Redis), local development, testing, and recommended practices for extending EndSectors.

Integration points

• NATS subjects: EndSectors uses NATS for command and event distribution. Subscribe/publish to defined subjects to interact programmatically.
• Redis keys: Player snapshots and sector metadata are stored in Redis. Use a defined schema when writing auxiliary tools.
• Plugin API: The Tools plugin demonstrates how to call EndSectors API from other plugins (hook into transfer lifecycle, query sector meta, force transfers).

Recommended tooling for development

• Local NATS + Redis via Docker for fast iteration.
• A small harness Paper server (headless) to simulate sectors for automated tests.
• nats.java / nats.go clients for integration tests.
• Mocked Redis (or real one) for end-to-end tests (avoid flaky tests).

Local docker-compose (example)

version: "3.8"
services:
  nats:
    image: nats:2.9.20
    ports:
      - "4222:4222"
  redis:
    image: redis:7
    ports:
      - "6379:6379"

Message contracts & examples

• Registration event (published by Paper on startup)
  • Subject: endsectors.registration
  • Payload:

    {
      "sectorId": "spawn_1",
      "type": "SPAWN",
      "address": "127.0.0.1:30001",
      "world": "world"
    }

• Player transfer request
  • Subject: endsectors.transfer.request
  • Payload:

    {
      "playerUuid": "uuid",
      "fromSector": "s1",
      "toSector": "w1",
      "requestedAt": 1670000000000
    }

• Player snapshot stored in Redis
  • Key: endsectors:player:{uuid}
  • Value: serialized JSON or binary snapshot containing inventory, health, location, effects.

Best practices

• Use idempotent handlers for message subscribers to avoid double processing.
• Validate payloads strictly. Reject malformed messages with clear logs and metrics.
• Implement backpressure: if Redis is slow, queue or throttle transfers.
• Use separate NATS connection names for each process for traceable logs.

Versioning & compatibility

• Maintain backwards compatibility between minor versions; include a protocolVersion in messages if breaking changes are necessary.
• Plugins should check the Common service version on connect and warn on mismatches.

Testing

• Unit tests: isolate serialization/deserialization and boundary logic.
• Integration tests: use Dockerized NATS + Redis and at least two Paper instances to validate transfers.
• Performance tests: simulate large numbers of transfers to evaluate Redis and NATS load.

Extending EndSectors

• Suggested extension points:
  • Custom queue strategies (e.g., priority queue for donors)
  • Integration with external auth or player economy (use public events)
  • Custom monitoring exporters

If you plan to contribute code, follow the Contributing guidelines and use the PR templates.