RMU API Attack

Table of Contents

• Description
• Architecture
• Requirements
• Quick Start
• Configuration
• API Overview
• Domain Model Summary
• Development
• Docker
• Release
• RMU Modifiers Reference
  • Source skills
  • Source statuses
  • Target statuses
  • Attack features
• Technology Stack
• Roadmap

REST API for managing Rolemaster Unified attack resolution. The service stores attack state in MongoDB and delegates attack, critical and fumble table lookups to the RMU attack tables API.

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.

Description

RMU API Attack owns the lifecycle of an attack:

• Create an attack with tactical modifiers.

• Calculate roll, critical and fumble modifiers.

• Resolve attack table results using the external attack tables API.

• Track pending rolls and apply final results.

• Persist attack state in MongoDB.

Architecture

The code follows a layered, ports-and-adapters style:

Layer	Package	Responsibility
HTTP interface	app/interfaces/http	FastAPI routers and Pydantic DTOs.
Application	app/application	Commands, ports and use cases.
Domain	app/domain	Attack entities, value objects, services and domain exceptions.
Infrastructure	app/infrastructure	MongoDB repository, REST clients, configuration, logging and dependency container.

Requirements

• Python 3.11+

• uv

• MongoDB

• RMU attack tables API, by default expected at http://localhost:3005/v1

Quick Start

uv sync --all-groups
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Interactive API documentation:

• Swagger UI: http://localhost:8000/docs

• ReDoc: http://localhost:8000/redoc

• Health check: http://localhost:8000/health

Configuration

Environment variables:

Variable	Default	Description
RMU_MONGO_ATTACK_URI	mongodb://admin:admin@localhost:27017/rmu-attack?authSource=admin	MongoDB connection string. MONGO_URI and MONGODB_URL are also accepted for compatibility.
RMU_MONGO_ATTACK_DATABASE	rmu-attack	MongoDB database name for legacy repository mode. MONGO_DATABASE and MONGODB_DATABASE are also accepted.
RMU_API_ATTACK_TABLES_URL	http://localhost:3005/v1	Base URL of the attack tables API.
RMU_API_ATTACK_TABLES_TIMEOUT	30.0	HTTP timeout in seconds for attack table requests.
RMU_API_ATTACK_TABLES_ENABLE_RETRY	false	Enables retry wrapper for the attack tables API client.
RMU_API_ATTACK_TABLES_MAX_RETRIES	3	Maximum retries when retry support is enabled.
RMU_API_ATTACK_TABLES_RETRY_DELAY	1.0	Base retry delay in seconds.
RMU_API_ATTACK_TABLES_KEY	empty	Optional bearer token for the attack tables API.
LOG_LEVEL	INFO	Application log level.
DEBUG	false	Enables development debug mode.

API Overview

Method	Path	Description
GET	/	Service metadata.
GET	/health	API and MongoDB connectivity status.
GET	/v1/attacks	Search attacks using an optional RSQL query.
GET	/v1/attacks/{attack_id}	Retrieve one attack by id.
POST	/v1/attacks	Create a new attack.
PATCH	/v1/attacks/{attack_id}	Update attack modifiers.
DELETE	/v1/attacks/{attack_id}	Delete an attack.
PATCH	/v1/attacks/{attack_id}/parry	Update parry value.
PATCH	/v1/attacks/{attack_id}/roll	Apply attack roll.
PATCH	/v1/attacks/{attack_id}/critical-roll	Apply one critical roll.
PATCH	/v1/attacks/{attack_id}/fumble-roll	Apply fumble roll.
POST	/v1/attacks/{attack_id}/apply	Apply attack result to the tactical module.

Domain Model Summary

The main aggregate is Attack. It is intentionally split into stable blocks:

Block	Purpose
modifiers	Tactical input used to calculate the attack: attack type, table, size, armor, roll modifiers, situational modifiers, features and source skills.
roll	Dice roll data for the attack, criticals and fumbles.
calculated	Derived modifier breakdowns and totals.
results	Attack table entry, critical results and fumble result.

Attack status flow:

Development

Install dependencies:

uv sync --all-groups

Run checks:

./local-test.sh

Run individual commands:

uv run pytest tests/ -v
uv run ruff format app tests
uv run ruff check app

Docker

Build the image:

docker build -t labcabrera/rmu-api-attack:latest .

Run locally on the RMU Docker network:

./docker-run.sh

Release

Releases are created with git-flow:

./create-release.sh 0.4.0

The release script:

• starts a release/<version> branch from develop;

• updates the version in pyproject.toml;

• refreshes uv.lock;

• runs local checks;

• finishes the release and pushes main, develop and tags.

RMU Modifiers Reference

Source skills

Skill	Description
footwork	Reduces melee pace modifier.
reverse-strike	Reduces positional source penalty when attacking from flank or rear.
restricted-quarters	Reduces restricted quarters penalty.

Source statuses

Status	Description
prone	Applies a source penalty.
ambidextrous	Reduces off-hand penalty.

Target statuses

Status	Description
stunned	Applies an attack bonus.
surprised	Applies an attack bonus.
prone	Applies a melee bonus or ranged penalty.
melee	Penalizes ranged attacks made while engaged in melee.

Attack features

Feature	Description
slaying-attack	Adds critical roll bonuses according to feature value.

Technology Stack

• FastAPI

• Pydantic v2

• MongoDB with Motor

• httpx

• dependency-injector

• uv

• pytest

• Ruff

Roadmap

• Called shots.

• Disarm attacks.

• Katas modifiers.

• Protecting others.

• Mounted combat.

• Subdual attacks.