# rimpack

`rimpack` is a Python CLI for building, validating, and launching RimWorld modpacks from
human-authored project files.

It treats a modpack as a normal project directory:

- `pack.toml` is the root manifest.
- `mods/*.list` files define authored mod intent.
- `rules/` contains optional activation and ordering rules.
- `generated/` contains outputs that can be regenerated.
- launch state stays machine-local instead of mutating the real RimWorld install.

The repository is spec-driven. The authoritative behavior and file-format definitions live in
[`specs/`](./specs).

## Current Capabilities

Today, `rimpack` can:

- initialize a new modpack project with `rimpack init`
- inspect RimWorld mods with `rimpack load-mods`
- resolve Steam Workshop items with `rimpack resolve steam`
- subscribe and unsubscribe Workshop mods
- add mod references to a declared `.list` file with `rimpack add`
- append ordering rules with `rimpack add-ordering-rule`
- validate a modpack before launch with `rimpack validate`
- launch a modpack through a symlinked runtime tree with `rimpack launch`

Activation rule files are supported by the project format and validation pipeline, but there is
not yet a dedicated CLI command to author them.

## Install

The project uses Python 3.12+ and `uv`.

```powershell
uv sync --dev
uv run rimpack --help
```

You can also run the console script directly after syncing:

```powershell
rimpack --help
```

## First Run

Running `rimpack` with no command creates a user-local config file if one does not already exist.
That config stores absolute machine-local paths such as:

- the RimWorld install directory
- the Steam Workshop content directory for app `294100`

You can also provide them through environment variables:

- `RIMWORLD_FOLDER`
- `STEAM_WORKSHOP_FOLDER`

## Quick Start

Initialize a new pack:

```powershell
uv run rimpack init .\MyPack
```

Add a Workshop mod to the `@libraries` list:

```powershell
uv run rimpack add @libraries steam:2009463077
```

Validate the pack:

```powershell
uv run rimpack validate
```

Launch it:

```powershell
uv run rimpack launch
```

## Documentation

Browsable project documentation lives in [`docs/`](./docs):

- [`docs/index.md`](./docs/index.md)
- [`docs/getting-started.md`](./docs/getting-started.md)
- [`docs/cli.md`](./docs/cli.md)
- [`docs/modpack-format.md`](./docs/modpack-format.md)
- [`docs/configuration.md`](./docs/configuration.md)

A GitHub Actions workflow publishes those docs to GitHub Pages on pushes to `main`.

## Development

The expected local checks are:

```powershell
uv run ruff check .
uv run basedpyright
uv run pytest
```
