Skip to content
T1KTheOneKit

t1k:nakama:mock

FieldValue
Modulebase
Version1.6.2
Effortlow
Tools—

Keywords: development, endpoint, gameplay, mock, nakama, stub, testing

How to invoke

Section titled “How to invoke”
/t1k:nakama:mock

Nakama Mock System

Section titled “Nakama Mock System”

Overview

Section titled “Overview”

When MOCK_GAMEPLAY_ENDPOINTS=true, all gameplay RPCs return static mock responses instead of calling the real gRPC service. This enables frontend development without a running Gameplay backend.

Key Patterns

Section titled “Key Patterns”

Enabling Mocks

Section titled “Enabling Mocks”

Set env var MOCK_GAMEPLAY_ENDPOINTS=true in config.yml.tmpl or docker-compose.

Three-Level Resolution Chain

Section titled “Three-Level Resolution Chain”

Per endpoint, mock data resolves in priority order:

  1. TypeScript mock file: <mockDataDir>/<service>/<op>.ts — parsed from orion-contracts
  2. Contract JSON: <contractsDir>/<service>/client/<op>.response.json — examples[0]
  3. Inline fallback: Hardcoded JSON string in Go code

TS Mock File Parser Pipeline

Section titled “TS Mock File Parser Pipeline”

parseTSMockFile() converts TypeScript exports to JSON:

  1. Strip JS comments (string-aware to preserve URLs)
  2. Extract object/array literal after first = { or = [
  3. Replace new Date('...') → "..."
  4. Replace TypeScript enum references → string values
  5. Convert single-quoted strings → double-quoted
  6. Quote unquoted object keys
  7. Remove trailing commas
  8. Validate via json.Compact

Adding a New Mock Endpoint

Section titled “Adding a New Mock Endpoint”
rpcs := []rpc{
    {
        "service_v1_operation_name",
        load("service/operation-name",
            "service/client/operation-name.response.json",
            `{"fallback":"data"}`),
    },
}

Gotchas

Section titled “Gotchas”
  • TS enum values must be registered in tsEnumValues map — missing entries cause JSON parse failures
  • The parser runs reTrailingComma twice to handle nested trailing commas
  • extractFirstLiteral handles balanced braces including those inside string literals
  • Mock RPCs log at DEBUG level — check nakama logs with --log.level=DEBUG
  • ORION_MOCK_DATA_DIR overrides the default mock data path
  • Mock drift: Mock responses can diverge from real API over time. Regenerate mocks from contracts regularly.
  • Contract versioning: When the Gameplay service updates its protobuf, mocks must be updated simultaneously or tests pass with stale data.

Checklist

Section titled “Checklist”
  • Mock RPC name matches real RPC name exactly
  • TS mock file path follows <service>/<operation>.ts convention
  • Contract path follows <service>/client/<operation>.response.json
  • Inline fallback provides minimal valid JSON structure
  • Any new enum values added to tsEnumValues map
  • Mock works without contract files (fallback chain verified)