Development setup

This guide covers setting up a development environment for hacking on RSMM itself. If you just want to use the mod manager, see Installation.

Note about paths: throughout this document, ./rsmm <name> refers to the repo-root entry point. The equivalent Python module lives at src/rsmm/cli/<name>.py or src/rsmm/engine/<name>.py.

---

Prerequisites

Tool	Version	Notes
Node	>= 20.11	nvm install 22 recommended
pnpm	9.x	corepack enable && corepack prepare pnpm@9.12.0 --activate
Docker	any modern	For local Postgres via docker compose
Rust	stable	Only for desktop (Tauri) builds. Install via rustup
Python	>= 3.11	The desktop app shells out to the Python CLI
CMake	>= 3.20	For building the native loader DLL
Git	any

Platform extras for Tauri 2 desktop builds: see tauri.app/start/prerequisites.

---

First-time bootstrap

# 1. Clone
git clone https://github.com/Ovilli/RavenswatchModManager.git
cd RavenswatchModManager

# 2. Python virtual env (for the rsmm CLI)
python3 -m venv .venv
source .venv/bin/activate       # Linux
# .venv\Scripts\activate        # Windows
pip install -e .

# 3. Workspace deps (TypeScript monorepo)
corepack enable
pnpm install

# 4. Local Postgres
cp .env.example .env
sed -i "s/replace-me-32-bytes-hex/$(openssl rand -hex 32)/" .env
pnpm db:up        # docker compose up -d postgres
pnpm db:push      # Create tables via Drizzle
pnpm db:seed      # Optional sample data

Daily commands

Command	Description
pnpm dev	Desktop app (Tauri + Vite)
pnpm dev:with-cli	Desktop app (uses system rsmm Python CLI from repo root)
pnpm api:dev	Hono API on :3001
pnpm www:dev	Next.js website + registry on :3000
pnpm docs:dev	Astro Starlight docs on :4321
pnpm lint / pnpm lint:fix	Biome lint
pnpm format	Biome format
pnpm check-types	TypeScript across all packages
pnpm db:push	Push schema to local DB
pnpm db:migrate	Apply migrations
pnpm build	Build every package + app

Platform-specific desktop dev

Command	Platform	Use case
pnpm --filter desktop dev	All	Standard development
pnpm --filter desktop dev:linux	Linux	If WebKit DMA-BUF errors occur
pnpm --filter desktop dev:linux-soft	Linux	Software GL fallback (last resort)

Production builds

Command	Output
pnpm --filter desktop build	Native platform installer (MSI/AppImage)
pnpm --filter desktop build:linux	Linux x86_64 build
pnpm --filter desktop build:windows	Windows x64 build

Sidecar (Python CLI binary)

For production builds, the Python CLI must be bundled as a standalone executable:

python3 scripts/build-sidecar.py              # Build for current platform
python3 scripts/build-sidecar.py --target linux
python3 scripts/build-sidecar.py --target windows
python3 scripts/build-sidecar.py --all         # Build for all platforms

Requires PyInstaller (pip install pyinstaller). The output binary is placed at apps/desktop/src-tauri/binaries/rsmm-<target-triple> where Tauri’s sidecar resolver expects it.

For development, you can use the system Python CLI instead (rsmm on PATH from pip install -e .). The desktop app falls back to the system command if the sidecar binary is not found.

Building the native loader

# Linux (cross-compile for Windows via MinGW)
cd src/loader
./build.sh

# Windows (auto-detects Visual Studio or MinGW)
cd src\loader
fetch_deps.bat
build.bat

The compiled winhttp.dll appears in dist/.

Testing

# Python tests
pytest -q                                    # From repo root

# Regenerate dev artifacts (optional, not committed)
pip install --user texture2ddecoder Pillow capstone
python3 scripts/extract_uncooked.py           # Uncooked asset mirror
python3 scripts/decode_gen_sidecars.py        # .gen sidecars
bash docs/_re/run_dump_symbols.sh             # Ghidra symbol dump
python3 scripts/gen_function_patterns.py      # Pattern DB
python3 scripts/test_pattern_resolve.py --all # Validate patterns

IDE setup

Open the workspace in VS Code. Install the CMake Tools and Python extensions. Point the Python interpreter to .venv.

Architecture

apps/desktop    Tauri 2 shell. Vite + React. Spawns `rsmm` CLI as sidecar.
apps/www        Next.js 15 marketing site + registry browser.
apps/api        Hono on Node. Better Auth + /mods + /telemetry endpoints.
apps/docs       Astro Starlight documentation site.
packages/db     Drizzle schema + migrations (Neon / pg dual driver).
packages/ui     Shared React components + Tailwind preset.
packages/api-client  Typed fetch client for apps/api.
packages/schemas     Zod schemas shared by client + server.
src/rsmm/       Python CLI + SDK. Untouched by the TypeScript monorepo.
src/loader/     Native DLL source (winhttp proxy + Lua VM).

Python bridge

The desktop app calls the Python CLI via the Tauri shell plugin:

import { rsmm } from './lib/rsmm';
const mods = await rsmm<LocalMod[]>(['list', '--json']);

The rsmm executable must be on PATH. For devs, the repo-root ./rsmm wrapper works.

Local vs production database

Local: Docker Postgres via docker compose up -d postgres. Connection string in .env.

Production: Neon serverless Postgres. Set DATABASE_URL and DB_DRIVER=neon in your deployment environment. Run pnpm db:migrate once after deploy.

Drizzle is configured for both drivers — the switch is the DB_DRIVER env var.

Tauri icons

The committed apps/desktop/src-tauri/icons/icon.png is a placeholder. Replace with a real 1024×1024 PNG, then:

cd apps/desktop
pnpm tauri icon icons/icon.png

This regenerates every required size + .ico + .icns + mobile variants.

Linux + NVIDIA

If pnpm desktop:dev prints GBM/DRM errors and the window never appears:

pnpm --filter desktop dev:linux          # Disable DMA-BUF + compositing
pnpm --filter desktop dev:linux-soft     # Last resort: software GL

---

Contributing

Reporting issues

• Search existing issues first.
• Provide reproduction steps, OS, game version, and relevant logs.

Code style

• Follow existing formatting in src/ and apps/.
• Use clang-format for C++ and black for Python where applicable.

Pull requests

• Fork the repo and create a focused topic branch.
• Include a clear description, related issue, and testing steps.
• Ensure CI passes before requesting review.

Communication

• Be responsive to review comments and keep PRs small.