Character Roleplay Engine

GemTavern RPEngine

Not Connected

Runtime Activity Log

RPEngine settings

Downloaded models are stored on this device. They remain installed after you close the app and are available when you reopen it.

Developer documentation

Game and Mod Integration API

Connect your game

  • Start a loopback WebSocket listener at ws://127.0.0.1:PORT/rp-engine/socket.
  • Use the same port in the game integration and RPEngine settings. The default is 38471.
  • Your game may open RPEngine with its port in the URL so the player does not need to enter it manually.
https://rp-engine.gemtavern.com/#port=38471

Connection handshake

RPEngine sends hello after opening the WebSocket. Reply with welcome containing a new sessionId and your integration version. RPEngine repeats this handshake whenever it reconnects.

Messages include protocol, protocolVersion, messageId, sessionId, timestamp, and type. Send ack after receiving a message.

Reply request

{
  "protocol": "gemtavern.rp_engine",
  "protocolVersion": 3,
  "type": "reply.request",
  "messageId": "message-id",
  "sessionId": "session-id",
  "timestamp": "2026-07-14T00:00:00.000Z",
  "requestId": "request-id",
  "eventId": "event-id",
  "integrationId": "my-game",
  "characterId": "character-1",
  "event": {
    "text": "Optional typed context alongside the recording.",
    "audio": {
      "format": "pcm_s16le",
      "sampleRate": 16000,
      "channels": 1,
      "language": "en",
      "data": "BASE64_PCM_DATA"
    }
  },
  "output": {
    "modalities": ["text", "audio"],
    "language": "en",
    "audio": {
      "model": "gemtavern-supertonic-3",
      "voice": "F4",
      "format": "pcm_s16le"
    }
  },
  "player": { "displayName": "Player" },
  "card": {
    "format": "chara_card_v2",
    "mode": "reference",
    "targetHash": "sha256-canonical-card-hash"
  }
}

Provide event.text, event.audio, or both. Audio must be mono, 16 kHz, base64-encoded pcm_s16le or pcm_f32le, and no longer than 30 seconds. Supported audio languages are en, ar, es, ja, ko, vi, uk, and zh.

Games may include interactionMode, promptScene, and promptDirective together. RPEngine uses autoEventGuide only for auto_event, and directUserGuide only for direct_user; sceneContext supplies the shared scene once.

Use ["text"] for a text response. Use ["text", "audio"] with the audio settings shown above when your game also wants speech.

Character card transfer

Character Card V2 is the canonical character format. Send a complete chara_card_v2 document with spec_version: "2.0" and all required fields. Use empty values where your game has no content; unknown fields and extension data are preserved.

  • snapshot: full Character Card V2 plus targetHash.
  • patch: RFC 6902 operations plus baseHash and targetHash.
  • reference: an unchanged session card identified by targetHash.

Hashes are lowercase SHA-256 over RFC 8785 canonical JSON. Begin a connection with a snapshot. If RPEngine returns card_resync_required, resend the request with a snapshot.

Response stream

After reply.accepted, text and audio stream concurrently. RPEngine sends reply.text.delta messages while generation continues and begins sending sentence-level reply.audio.chunk messages as soon as complete sentences are available. Audio may therefore begin before reply.text.completed. The request ends with reply.completed after all requested output is complete.

Audio chunks contain base64-encoded 44.1 kHz mono PCM16. Group chunks by segmentSequence, then play each completed segment in order while later text and audio continue generating. Your game controls volume, subtitles, interruption, and spatial placement.

Cancellation and errors

Send request.cancel with the request ID to cancel a request. RPEngine sends capacity.update, reply.cancelled, and request.error when applicable.