Patchwork

Patchwork is an experimental source-level modding platform for Rust software. Instead of loading binary plugins at runtime, it composes the selected mods into a normal Cargo project and then compiles the complete application.

The core idea is that every mechanic or object can be a distinct Rust crate. Mods depend on other mods or abstract APIs, modpacks choose the concrete implementations, and Rust type-checks the final generated program.

Components

modding_system/
  patchwork/            core composition library
  patchwork-cli/        `patchwork compose` command
  patchwork-app/        Leptos + Tauri desktop launcher
  patchwork-ui/         shared Leptos components
  patchwork-registry-types/ shared registry API DTOs
  patchwork-web/        Leptos website + Actix backend
  patchwork-database/   Diesel models and migrations
  template/             base generated Cargo project
  documentation/        mdBook documentation

Documentation

The mdBook summary links the complete documentation for the composition model, metadata, desktop launcher, web configuration, accounts, OAuth, GitHub integration, database, and backend API.

Build or serve it locally with:

mdbook build documentation
mdbook serve documentation

Compose from the CLI

patchwork compose \
  --mods-folder mods \
  --modpacks-folder modpacks \
  --modpack client \
  --cache build \
  --name client

The output is a regular Cargo project:

cargo check --manifest-path build/client/Cargo.toml

Desktop app

Desktop development and installation use the same Rust helper on Linux and Windows, with no repository shell wrappers:

cd patchwork-app
cargo run --manifest-path tools/desktop-tool/Cargo.toml -- dev
cargo run --manifest-path tools/desktop-tool/Cargo.toml -- build-debug

Install Patchwork with the same command on both supported desktop platforms:

cargo run --manifest-path tools/desktop-tool/Cargo.toml -- install

On Windows, install builds the NSIS package and launches its installer. On Linux, it installs the release build for the current user under ~/.local; set PATCHWORK_INSTALL_PREFIX to another absolute prefix when needed. The usual Tauri system prerequisites plus the wasm32-unknown-unknown target, cargo-leptos, and the Tauri CLI must be installed first.

Start the website

Create a private server configuration, fill in the Resend and GitHub App credentials, then build the Leptos assets and run Actix:

cd patchwork-web
cp patchwork.example.toml patchwork.toml
cargo leptos build
cargo run --features server -- --config patchwork.toml

The default bind address is 0.0.0.0:8080. Server, email, database, and GitHub backend configuration are read from the TOML file. Embedded migrations run automatically when the server connects.

During early development the database uses a single baseline migration. Delete the local SQLite file and sign in again after schema changes; the mdBook's database chapter documents this policy.

Authenticated users with a linked GitHub account can scan and publish mods and loose versioned modpack TOMLs from Upload on either client. Patchwork pins the default branch to an exact commit, walks GitHub trees without cloning, previews immutable versions, and publishes only selected server-side scan entries. The complete contract is in Registry publication.

Mod metadata

A lifecycle mod declares an entry type and its dependencies:

[package.metadata.mod]
entry = "EntryType"
provides = "optional-api-name"

[package.metadata.mod.dependencies]
init = []
run = []
ownership = []

An API contract with no lifecycle object uses:

[package.metadata.mod]
api = true

An asset-only, codegen-only, or other selected mod with no lifecycle object instead uses support = true. Both are real selected mods and Cargo dependencies, but Patchwork does not generate init() or run() calls for them. The flags are mutually exclusive, and every API mod requires exactly one selected normal provider declared with provides = "<api-id>". See the metadata reference for the complete format, providers, modpacks, codegen, assets, and favicons.

Dependencies between selected Patchwork mods should use sibling Cargo paths so Compose and domain codegen can inspect their manifests. Plain helper libraries should use a distributable Git or registry source; local development can patch that source back to the checkout with .cargo/config.toml. Generated crates preserve these library sources instead of requiring every dependency to be a downloaded Patchwork mod. See Mods and Cargo metadata and Generic codegen.