# RuneTopic vote integration guide

This guide connects verified RuneTopic vote rewards to an RSPS. Store delivery
remains disabled while RuneTopic completes payment and fulfilment testing.

## Before you begin

- A RuneTopic server-owner account with a server listing
- Java 8 or newer on the private game-server process
- Access to the server files and startup configuration
- A server-scoped key from **Dashboard → Voting & callbacks**

Never place the server key in a launcher, client cache, website JavaScript,
Discord message or public repository. Regenerate it immediately if exposed.

## 1. Install the JAR

1. Stop a test game-server node.
2. Copy `runetopic-integration.jar` into `lib/`, `libs/` or the folder your core
   uses for server-side plugins.
3. Add the JAR to the server process classpath.
4. Start the node and confirm there are no missing-class errors.

Generate a safe starter configuration with:

```text
java -jar runetopic-integration.jar init
```

## 2. Add private settings

Set these through the hosting panel or private startup script:

```text
RUNETOPIC_SERVER_KEY=<server-scoped key>
RUNETOPIC_SERVER_ID=<RuneTopic listing ID>
```

The API address is `https://www.runetopic.com/api/v1`. Keep test mode enabled
until the owner-dashboard test succeeds.

## 3. Create one shared client

```java
RuneTopicClient runeTopic = RuneTopicClient.builder()
    .apiToken(System.getenv("RUNETOPIC_SERVER_KEY"))
    .serverId(Integer.parseInt(System.getenv("RUNETOPIC_SERVER_ID")))
    .testMode(Boolean.getBoolean("runetopic.testMode"))
    .build();
```

Create this once during server startup and close it during graceful shutdown.

## 4. Connect a vote-claim hook

Call the SDK after login or from an existing `::claim` or `::vote` command:

```java
runeTopic.votes().claim(player.getUsername()).thenAccept(result -> {
    result.rewards().forEach(reward ->
        reward.grantWith(command -> server.execute(command))
    );
});
```

Replace `server.execute(command)` with the command executor used by the RSPS
core. The API call is asynchronous and must not block the main game tick.

The JAR leases each pending reward, executes the owner-configured commands and
acknowledges only after command execution succeeds. An unacknowledged lease
expires for a safe retry; an acknowledged reward is not returned again.

## 5. Configure and test rewards

1. Open **Dashboard → Voting & callbacks**.
2. Select the server listing.
3. Generate and privately save a server key.
4. Select API or Both and configure vote-reward commands.
5. Test on a non-production game node.
6. Confirm a repeat test does not duplicate the reward.

## Callback alternative

Owners can use a normal callback instead of the JAR. Save a public HTTPS URL,
choose GET or POST, and use RuneTopic's signed-in callback tester. Only the
selected owned server is tested. The tester shows the request, response, HTTP
status and timing without creating a public vote.

## Store status

Store-delivery classes are reserved in the SDK for compatibility with the
future release, but live store purchase claims are disabled. Do not build a
production purchase flow against them yet.

## Troubleshooting

- `401`: key missing or invalid—regenerate it and restart the node.
- `403`: credential revoked or listing disabled.
- `409`: reward already claimed—do not grant it again.
- `422`: invalid player name or incomplete server configuration.
- `429`: rate limited—back off before retrying.
- Empty result: no eligible vote reward is waiting for that player.

Use the returned request ID when contacting RuneTopic support. Logs must never
include the complete server key.