RMU Engine Tactical API

REST API for combat management. Each combat (tacticalGame) is associated to a campaign (strategicGame) of the Strategic API module.

This API allows to import characters from the strategic API or to create NPC characters. Once the characters are defined, it allow the declaration of actions such as maneuvers or attacks.

This project is part of RMU Online: https://github.com/labcabrera/rmu-platform

Warning

This application is an independent project developed by fans of Rolemaster Unified. It is not affiliated with, endorsed by, or licensed by Iron Crown Enterprises (ICE), the owners of the Rolemaster intellectual property. All Rolemaster trademarks, game systems, and materials are the property of Iron Crown Enterprises. This software is provided for personal, non-commercial use only. If you enjoy Rolemaster, please support the official publications and content from ICE.

Technologies

• NestJS

• DDD

• CQRS

• MongoDB

• Kafka

Development

This API follows the platform and conventions of rmu-api-core (workspace spec 020): Node.js 24 (nvm use), pnpm 10 through corepack, native ESM with relative .js imports, SWC build, Vitest and the hexagonal + CQRS layout of core’s README (Project layout, HTTP contract).

cp .env.example .env   # host ports of the rmu-platform infrastructure (make up-infra)
pnpm install
pnpm start:dev         # http://localhost:3003, Swagger UI on /api-docs, OpenAPI JSON on /api-spec
make check             # lint, typecheck, unit and e2e tests

Command	What it does
pnpm build / pnpm typecheck	SWC build to dist/ / tsc --noEmit
pnpm lint / pnpm format	typed ESLint + Prettier / Prettier over src and test
pnpm test	unit tests (test/unit)
pnpm test:e2e	one file per resource booting AppModule against mongodb-memory-server, with tokens signed against a local JWKS; calls to other APIs and the Kafka producer are replaced (test/e2e/support)
pnpm test:cov	unit and e2e tests with the coverage thresholds of vitest.config.ts (what CI runs)
make docker-build / make docker-run	image labcabrera/rmu-api-tactical:latest (node:24-bookworm-slim, node user, HEALTHCHECK); docker-run needs .env.docker
make create-release	semantic-release from a clean develop into master

The Joi schema in src/config/env.schema.ts fails startup on a missing required variable. Besides PORT (3003), LOG_LEVEL (info) and RMU_MONGO_TACTICAL_URI, the HTTP layer reads RMU_CORS_ORIGINS (empty: no CORS, browsers come through the gateway), RMU_THROTTLE_LIMIT / RMU_THROTTLE_TTL_MS (300 per 60000 ms and client IP, 0 turns it off) and RMU_TRUST_PROXY (loopback, linklocal, uniquelocal). Calls to the other APIs and to Keycloak go through the shared HttpClient and TokenService with a timeout of RMU_HTTP_TIMEOUT_MS (10000): an API that does not answer in time is a 504 upstream-timeout, one that is down a 502. /v1/health checks only Mongo and memory (spec 021, decision 8).

Errors answer { statusCode, error, code, message, timestamp, path } (path without the query string). A missing game, actor round or action is a 404. Responses carry the version of the entity and a PATCH may send it back: a stale one is a 409 version-conflict. size goes up to 100. GET /v1/actions accepts up to 1000 (CatalogPagedQueryDto), because rmu-mfe-tactical loads a round whole. Error bodies may also carry details. The deprecated errorCode alias was removed in workspace spec 021: rmu-mfe-tactical reads code. == Permissions

Workspace spec 021, decision 2, over the BaseEntityGuard of every API (shared/infrastructure/security):

• A tactical game is managed (changed, played, finished, deleted, its factions and actors) by its owner, the owner of its strategic game or a rmu-admin. Creating one needs rmu-user or rmu-admin.

• It is read as its strategic game says (accessType): a public one by everybody, a private one by its managers, the owners of its actors and the admins. Listings of games, actor rounds and actions only return what the user reads.

• The owner of a character acts for its actor: declares and resolves its actions and changes its actor round. A defender declares a parry on the attacker’s action as long as it owns an actor of the game.

The checks run at the HTTP edge (GameAccessGuard, ActorRoundAccessGuard, ActionAccessGuard over the GameGuardPort), not in the command handlers: a handler runs commands of its own on actors the caller does not own (an attack damages its target). The service account token carries rmu-admin.

The game stores strategicGameOwner and accessType, copied from the strategic game when the game is created, so the checks make no call to strategic. Games created before spec 021 have neither: until they are migrated, only their owner and the admins manage them, and they read as private. The migration is a mongosh script run from rmu-platform:

# in rmu-platform, after make mongo-backup
make mongo-migrate f=../rmu-api-tactical/scripts/migrations/021-tactical-game-strategic-owner.js DRY_RUN=1
make mongo-migrate f=../rmu-api-tactical/scripts/migrations/021-tactical-game-strategic-owner.js

Open problems found during the migration are listed in docs/reports/api-template-rollout-findings.md of the workspace.