Fantome Format Specification

Learn more about Mintlify

Enter your email to receive updates about new features and product releases.

Overview
File Structure
Directory Requirements
Metadata: info.json
Schema
Field Specifications
Complete Example
WAD Files
Naming Convention
File Content
Optimization
Preview Image
Specifications
Best Practices
Loading in cslol-manager
Creating Fantome Files
Using cslol-manager UI
Using mod-tools CLI
Manual Creation
Installing Fantome Files
Supported Methods
Installation Process
File Dialog Filters
Compatibility
Supported Managers
Version Compatibility
Game Version
Advanced Topics
Conflict Resolution
Overlay Generation
Rebasing
Validation Checklist
Resources

Overview

Fantome is the industry-standard mod format for League of Legends custom content. A .fantome file is a ZIP archive containing:

Metadata: Mod information (name, version, author, description)
WAD files: Game asset modifications
Preview image: Optional thumbnail for mod managers

The format is designed to be:

Portable: Single-file distribution
Human-readable: Standard ZIP format
Validated: Required structure for compatibility
Optimized: Only modified files included

The Fantome format was created by the League Toolkit organization and is used by all major League of Legends mod managers.

File Structure

A .fantome file is a ZIP archive with the following structure:

MyMod.fantome (ZIP archive)
├── META/
│   ├── info.json          # Required: Mod metadata
│   └── image.png          # Optional: Preview image
└── WAD/
    ├── champion.wad.client
    ├── skin.wad.client
    └── effects.wad.client

Directory Requirements

Directory	Required	Purpose
`META/`	Yes	Contains mod metadata and assets
`META/info.json`	Yes	Mod information and versioning
`META/image.png`	No	Preview thumbnail (recommended)
`WAD/`	Yes*	Contains game asset modifications

While WAD/ is technically optional, a mod without WAD files won’t modify the game.

Metadata: info.json

The META/info.json file contains structured metadata:

Schema

{
  "Name": "string (required)",
  "Version": "string (required)",
  "Author": "string (required)",
  "Description": "string (optional)",
  "Home": "string (optional, URL)",
  "Heart": "string (optional, URL)"
}

Field Specifications

Name (required)

Type: String
Length: 3-50 characters
Pattern: [\p{L}\p{M}\p{Pd}\p{Z}\p{N}\w]{3,50}
Description: Display name of the modExamples:

"Name": "Star Guardian Lux"
"Name": "High Noon Yasuo - Custom VFX"
"Name": "UI Overhaul 2024"

Cannot be empty. Must contain at least 3 characters.

Version (required)

Type: String
Format: Semantic versioning
Pattern: ([0-9]{1,3})(\.[0-9]{1,3}){0,3}
Description: Mod version numberValid formats:

"Version": "1.0"
"Version": "2.5.1"
"Version": "1.0.0"
"Version": "3.2.1.0"

Invalid formats:

"Version": "v1.0"        // No 'v' prefix
"Version": "1.0-beta"    // No suffixes
"Version": "1234.0"      // Max 3 digits per segment

Author (required)

Type: String
Length: 3-50 characters
Pattern: Same as Name
Description: Creator’s name or usernameExamples:

"Author": "SkinModder123"
"Author": "Jane Doe"
"Author": "Team Awesome"

Description (optional)

Type: String
Length: No strict limit (recommend < 500 chars)
Description: Brief description of the modExample:

"Description": "Custom Star Guardian skin for Lux with new VFX and animations. Includes recall animation and updated ability effects."

Display: Shown in mod managers, typically with 2-line limit in list views.

Home (optional)

Type: String (URL)
Pattern: ^(http(s)?:\/\/).+$
Description: Homepage, update page, or documentation URLExamples:

"Home": "https://github.com/user/my-lol-mod"
"Home": "https://www.leagueoflegends.com/mods/my-mod"
"Home": "https://example.com/updates"

Usage: Displayed as a clickable link in mod managers (question mark icon).

Heart (optional)

Type: String (URL)
Pattern: ^(http(s)?:\/\/).+$
Description: Support/donation link or author’s social mediaExamples:

"Heart": "https://ko-fi.com/modauthor"
"Heart": "https://patreon.com/modauthor"
"Heart": "https://twitter.com/modauthor"

Usage: Displayed as a clickable link in mod managers (heart icon).

Complete Example

{
  "Name": "PROJECT: Yasuo Enhanced",
  "Version": "2.1.0",
  "Author": "CoolModder",
  "Description": "Enhanced PROJECT: Yasuo skin with custom VFX, animations, and sound effects. Features include: neon windwall, cyberpunk recall, and updated ability particles.",
  "Home": "https://github.com/coolmodder/project-yasuo",
  "Heart": "https://ko-fi.com/coolmodder"
}

WAD Files

WAD (“Where’s All the Data”) files contain game assets:

Naming Convention

WAD files must use the .wad.client extension:

character_base.wad.client     ✓ Valid
lux_skin15.wad.client          ✓ Valid
mymod.wad                      ✗ Invalid (missing .client)
custom.wad.server              ✗ Invalid (wrong suffix)

File Content

WAD files contain:

Textures: .dds image files
Models: .skn, .sco mesh files
Animations: .anm animation data
VFX: .bin effect files
Audio: .wem, .bnk sound files
Other: Configuration, scripts, etc.

WAD files should only contain modified assets, not entire base game files. Use rebasing/optimization to strip unmodified entries.

Optimization

Before packaging, WAD files should be optimized:

# Using mod-tools CLI
mod-tools copy ./MyMod ./MyMod.optimized --game:"C:/Riot Games/League of Legends"
mod-tools export ./MyMod.optimized ./MyMod.fantome

Optimization:

Rebases against game WADs (finds base mount)
Removes unmodified files (identical to base game)
Strips unknown files (if --removeUNK is set)
Resolves internal conflicts
Normalizes file paths and naming

Preview Image

Specifications

Property	Requirement
Location	`META/image.png`
Format	PNG (required)
Resolution	512x512 or higher (recommended)
Aspect Ratio	Square (1:1) or 16:9
File Size	< 1 MB (recommended)
Color Space	sRGB

Best Practices

Use high-quality screenshots

Capture in-game footage at high resolution
Show the most impactful visual changes
Avoid UI elements unless they’re part of the mod

Optimize file size

Use PNG compression (pngquant, TinyPNG)
Target 200-500 KB for best balance
Avoid transparency unless necessary

Maintain aspect ratio

Square (1:1) works best in list views
16:9 works for detailed preview dialogs
Avoid extreme aspect ratios

Loading in cslol-manager

// From CSLOLModsView.qml:45
Image: CSLOLUtils.toFile("./installed/" + fileName + "/META/image.png")

Images are cached and displayed in the mods list.

Creating Fantome Files

Using cslol-manager UI

Create or edit mod

Use the mod creation/editing interface to set up your mod.

Click 'Export Mod'

Click the export button (folder icon) next to your mod.

Choose save location

Select where to save the .fantome file.

Automatic optimization

cslol-manager automatically optimizes before export (if game path is set).

// From main.qml:204-210
onModExport: function(fileName) {
    if (checkGamePath()) {
        cslolDialogSaveZipFantome.modName = fileName
        cslolDialogSaveZipFantome.currentFiles = [ "file:///" + fileName + ".fantome" ]
        cslolDialogSaveZipFantome.open()
    }
}

Signal: CSLOLTools.exportMod(name, dest)

Using mod-tools CLI

# Export with optimization
mod-tools export <mod_dir> <output.fantome> --game:<game_path>

# Example
mod-tools export ./MySkin ./MySkin.fantome --game:"C:/Riot Games/League of Legends"

Manual Creation

You can manually create a .fantome file:

Prepare directory structure

MyMod/
├── META/
│   ├── info.json
│   └── image.png
└── WAD/
    └── *.wad.client

Create ZIP archive

# Linux/Mac
cd MyMod
zip -r ../MyMod.fantome META/ WAD/

# Windows (PowerShell)
Compress-Archive -Path META, WAD -DestinationPath MyMod.fantome

Rename to .fantome

mv MyMod.zip MyMod.fantome

Manual creation skips optimization. Use mod-tools export for best results.

Installing Fantome Files

Supported Methods

Import Button

Click the import button in mod manager and select the .fantome file.

Drag and Drop

Drag .fantome file directly into the mod list.

Installation Process

Validation: Checks for required META/info.json
Extraction: Unzips to installed/{Name} V{Version} by {Author}/
Metadata loading: Reads info.json and image.png
Registration: Adds mod to the mods list (disabled by default)

// Signal: installFantomeZip(QString path)
onInstalledMod: function(fileName, infoData) {
    cslolModsView.addMod(fileName, infoData, false)
}

File Dialog Filters

// From CSLOLDialogOpenZipFantome.qml:11
nameFilters: "Fantome Mod files (*.fantome *.zip)"

Both .fantome and .zip extensions are accepted.

Compatibility

Supported Managers

cslol-manager: Full support (reference implementation)
LTK Manager: Full support (successor project)
Fantome: Original mod manager (deprecated)

Version Compatibility

The Fantome format is forward compatible:

Older managers can read newer .fantome files (if they follow the spec)
Newer managers fully support older .fantome files

Game Version

Fantome mods are game version specific. WAD files from older patches may not work with newer game versions due to:

Asset path changes
File format updates
New game features
WAD structure reorganization

Best practices:

Test mods after game updates
Rebuild/rebase mods against new game files
Update mod version when rebuilding
Document compatible game versions

Advanced Topics

Conflict Resolution

When multiple mods modify the same file:

Within a mod: Later WAD in alphabetical order wins
Across mods: Mod order in profile determines priority
Manager behavior: Can warn or auto-resolve based on settings

// From main.qml:104
cslolTools.saveProfile(name, mods, run, settings.suppressInstallConflicts, 
                       settings.verbosePatcher)

suppressInstallConflicts: Skip conflict warnings (use with caution)

Overlay Generation

The mod-tools CLI can create overlays from multiple mods:

mod-tools mkoverlay <mods_dir> <overlay_dir> --game:<path> --mods:<mod1>/<mod2>/...

Overlay process:

Indexes game WADs
Loads each mod in order
Resolves conflicts (later mod wins)
Removes unsafe entries (e.g., *.SubChunkTOC)
Writes merged overlay WADs

Rebasing

Rebasing aligns mod WAD filenames to base game mounts: Without rebasing:

WAD/
└── mymod.wad.client          # Generic name

With rebasing:

WAD/
└── ezreal_base_tx_cm.wad.client   # Aligned to base mount

Benefits:

Smaller file sizes (strips unmodified entries)
Better compatibility
Clearer file purpose
Easier conflict detection

Validation Checklist

Before distributing a .fantome mod:

Resources

League Toolkit

Official organization for LoL modding tools

Fantome Wiki

Original Fantome format specification

mod-tools CLI

Command-line tools for mod management

Mod Creation Guide

Learn how to create mods in cslol-manager

Mod Creation

Installing Mods

⌘I

Build docs developers (and LLMs) love

Get started for free Talk to us

Get Started

Core Features

Guides

​Overview

​File Structure

​Directory Requirements

​Metadata: info.json

​Schema

​Field Specifications

​Complete Example

​WAD Files

​Naming Convention

​File Content

​Optimization

​Preview Image

​Specifications

​Best Practices

​Loading in cslol-manager

​Creating Fantome Files

​Using cslol-manager UI

​Using mod-tools CLI

​Manual Creation

​Installing Fantome Files

​Supported Methods

Import Button

Drag and Drop

​Installation Process

​File Dialog Filters

​Compatibility

​Supported Managers

​Version Compatibility

​Game Version

​Advanced Topics

​Conflict Resolution

​Overlay Generation

​Rebasing

​Validation Checklist

​Resources

League Toolkit

Fantome Wiki

mod-tools CLI

Mod Creation Guide

Build docs developers (and LLMs) love

Overview

File Structure

Directory Requirements

Metadata: info.json

Schema

Field Specifications

Complete Example

WAD Files

Naming Convention

File Content

Optimization

Preview Image

Specifications

Best Practices

Loading in cslol-manager

Creating Fantome Files

Using cslol-manager UI

Using mod-tools CLI

Manual Creation

Installing Fantome Files

Supported Methods

Installation Process

File Dialog Filters

Compatibility

Supported Managers

Version Compatibility

Game Version

Advanced Topics

Conflict Resolution

Overlay Generation

Rebasing

Validation Checklist

Resources