game-engine-core-node

TypeScript/Node.js client SDK for the game-engine-core gRPC server.

npm: https://www.npmjs.com/package/game-engine-core-node GitHub: https://github.com/stevenlundy/game-engine-core

Install

npm install game-engine-core-node

Pinning to a specific version

npm install [email protected]

Quick start

import { GameClient, StateUpdate, Action, drawCard, playCard } from "game-engine-core-node";

class MyAgent extends GameClient {
  onStateUpdate(state: StateUpdate): Action {
    return drawCard(); // replace with real logic
  }
}

const agent = new MyAgent("localhost:50051", "my-player");
const sessionId = await agent.joinLobby("crazy-eights");
await agent.run();
agent.close();

See examples/randomAgent.ts for a complete runnable example.

API

GameClient (abstract)

| Member | Description | |--------|-------------| | constructor(serverUrl, playerId) | Creates client with gRPC target and player identifier | | joinLobby(gameType): Promise<string> | Joins matchmaking lobby; resolves with session_id when game starts | | run(): Promise<void> | Opens bidirectional Play stream; resolves when game ends | | onStateUpdate(state): Action \| Promise<Action> | Abstract — implement your game logic here | | close(): void | Closes all open gRPC channels |

Helper functions

| Function | Description | |----------|-------------| | playCard(rank, suit, declaredSuit?) | Build a play-card Action | | drawCard() | Build a draw-card Action | | parseRichState(update) | Decode a StateUpdate into a RichState with parsed JSON payload |

Testing helpers

import { startTestServer, stopTestServer, withTestServer } from "game-engine-core-node";

// Start a CountdownGame test server (builds cmd/testserver from source)
const server = await startTestServer({ countdownSteps: 5 });
const bot = new MyBot(server.url, "p1");
await bot.run();
stopTestServer(server);

// Or with a convenience wrapper
await withTestServer({ countdownSteps: 10 }, async (srv) => {
  const bot = new MyBot(srv.url, "p1");
  await bot.run();
});

Requires go on PATH and the game-engine-core source available (set GAME_ENGINE_CORE_ROOT env var if needed).

Migration from ts-web

The Node and Web clients have identical public APIs. To move a bot to the browser:

-import { GameClient } from "game-engine-core-node";
+import { GameWebClient as GameClient } from "game-engine-core-web";

Project layout

clients/ts-node/
  src/
    client.ts              GameClient abstract base class
    actions.ts             playCard / drawCard helpers
    state.ts               RichState / parseRichState
    index.ts               public exports
    testing/server.ts      Test server helper (exported)
    client.test.ts         Jest unit tests
    integration/           Integration tests (real Go server)
    proto/                 Generated by npm run proto
  examples/
    randomAgent.ts         Minimal subclass example
  dist/                    Compiled output (after npm run build)

Development

Requirements

| Tool | Version | |------|---------| | Node | 20.x (see .nvmrc) | | npm | 10.x | | protoc | 34.x |

Commands

make install      # npm install
make build        # tsc → dist/
make test         # Jest unit tests
make test-all     # unit + integration tests (requires go on PATH)
make lint         # Biome lint
make fmt          # Biome format
make type-check   # tsc --noEmit

Regenerating protobuf stubs

npm run proto

Requires protoc and ts-proto (npm install handles ts-proto).