Skip to content

Home

Jump to bottom
Crauzer edited this page Nov 23, 2025 · 2 revisions

1. How to Install

Windows (Recommended)

Method 1: Quick Install (PowerShell) For users who want the easiest installation method. This command downloads the latest release, installs it to your local app data folder, and adds it to your PATH.

irm https://raw.githubusercontent.com/LeagueToolkit/league-mod/main/scripts/install-league-mod.ps1 | iex

Method 2: Manual Install via GitHub Releases

  1. Visit the Releases page.
  2. Download the latest league-mod-windows-msvc.zip.
  3. Extract the contents to a folder of your choice.
  4. Add that folder to your PATH environment variable.

Building from Source

For developers who want to contribute or use the latest unreleased features.

Prerequisites:

  • Rust (version 1.70+)
  • Git
git clone https://github.com/LeagueToolkit/league-mod.git
cd league-mod
cargo build --release
# The binary will be at target/release/league-mod.exe

2. Explain Mod Projects

A Mod Project in league-mod is a structured workspace where you develop your mod before packaging it for distribution. It is designed to be version-controlled (e.g., with Git) and supports advanced features like layers and metadata.

Project Structure

A standard mod project looks like this:

my-mod-project/
├── mod.config.json       # The configuration file (metadata, authors, layers)
├── README.md             # (Optional) Documentation shown in mod managers
├── thumbnail.png         # (Optional) Mod icon/thumbnail
├── content/              # Directory containing the actual mod files
│   ├── base/             # The default layer (required)
│   │   └── ...           # Files go here (e.g., data/characters/...)
│   └── [other_layers]/   # Optional additional layers (e.g., "high-res", "no-sound")
└── build/                # (Auto-generated) Where .modpkg files are saved

The mod.config.json File

This file is the heart of your project. It defines:

  • Metadata: Name, version, description, authors.
  • Layers: Which folders in content/ are included and their priority.
  • Transformers: Rules for processing files (e.g., converting images) during packing.

3. How to Create a Mod Project

The easiest way to start is using the init command.

Usage

league-mod init

This interactive command will ask for:

  1. Mod Name: A folder-safe name (e.g., my-cool-mod).
  2. Display Name: The readable name shown to users (e.g., "My Cool Mod").

It will automatically generate the folder structure and a default mod.config.json for you.

Adding Content

Once initialized, place your raw mod files into content/base/. Example: If you are replacing a texture for Aatrox, the path might look like: content/base/assets/characters/aatrox/skins/base/aatrox_base_tx_cm.tex

4. Packaging Mods

When your mod is ready, you need to "pack" it into a single file that users can install.

Basic Packaging

Run this command inside your project folder:

league-mod pack

This creates a .modpkg file in the build/ directory (e.g., my-mod_1.0.0.modpkg).

Packaging Formats

league-mod supports two output formats:

  1. Modpkg (Default): --format modpkg

    • Supports Layers (options/variants).
    • Supports rich metadata.
    • Best for modern mod managers that support the standard.

  2. Fantome: --format fantome

    • Legacy format compatibility.
    • Limitation: Only supports the base layer. Other layers will be ignored.
    • Use this if you need to support older tools like Fantome or LCS-Manager (if they don't support modpkg).
league-mod pack --format fantome

5. Distributing Mods

Which file to share?

  • Share the .modpkg (or .fantome) file found in the build/ folder.
  • Do not share the raw project folder unless you are sharing the source code with other developers.

Best Practices

  • Update Version: Increment the version in mod.config.json before releasing a new update.
  • Thumbnail: Include a thumbnail.png or thumbnail.webp in your project root to make your mod look good in mod managers.
  • README: A README.md in your project root will be embedded in the package and shown to users.

6. Extracting Mods

If you want to inspect an existing mod or convert an old mod into a project, use the extract command.

Usage

league-mod extract --file-path path/to/mod.modpkg --output-dir ./my-extracted-mod

Supported Inputs

  • .modpkg: Full extraction of all layers and metadata.
  • .fantome: Converts a Fantome archive into a league-mod project structure.
    • It will automatically create a mod.config.json based on the internal metadata.
    • It organizes files into content/base/.

This is useful for recovering your own mods or learning how others made theirs.

Clone this wiki locally