# Moving over: importers for EssentialsX, LuckPerms, FTB Ranks, the game's lists and CoreProtect

> /keystone import reads the files of the plugin or mod you used before, shows what would come over, and brings homes, warps, nicks, kits, groups, permissions, ranks and bans into Keystone - once, however often you run it. New in 0.4.

Source: https://stygion.eu/docs/keystone/import
Updated: 2026-11-16

## Why

A server that has run for a year holds people's homes, a permission tree and a ban list. Typing them in again is the reason nobody switches. `/keystone import` reads the files the old plugin or mod left, translates them, **shows you the result first**, and only then writes it.

It is for every server: where the old files are, what the old worlds were called, which old permission means which here, which group an operator level becomes and which command pays a balance are all settings. Nothing is sent anywhere.

## The command

All need `keystone.import` (the owner and operators have it through `keystone.*`).

| Command | What it does |
|---|---|
| `/keystone import` | lists the sources |
| `/keystone import <source> --dry-run` | **preview**: reads, translates, asks the modules what they would do, prints it. Changes nothing |
| `/keystone import <source>` | does it |
| `... --from <folder>` | reads another folder, which must be **inside the server's folder** |

Sources: `essentialsx`, `luckperms`, `ftbranks`, `vanilla`, `coreprotect` (also `essentials`, `lp`, `ops`, `cp`).

Put the old folder where Keystone looks, or leave it where the old plugin kept it:

| Source | Looked for in (in this order) |
|---|---|
| `essentialsx` | `import/essentialsx`, `plugins/Essentials` |
| `luckperms` | `import/luckperms`, `plugins/LuckPerms` |
| `ftbranks` | `import/ftbranks`, `config/ftbranks` (and the world's `serverconfig/ftbranks` for players) |
| `vanilla` | `import/vanilla`, otherwise the server's folder itself |
| `coreprotect` | `import/coreprotect`, `plugins/CoreProtect` |

## Run it twice, get it once

Every thing is checked against what is already here: the group exists, the player already holds it, the home is already set. A second run finds everything *already here* and changes nothing. **Nothing you already have is overwritten or removed** - a group of the same name keeps its weight, prefix and parents (the imported permission lines are added to it); a line your group says the opposite of stays yours; a kit, home, warp, nick or ban that exists stays as it is. If you delete something imported and run again, it comes back.

## What comes over

| Source | Comes over | Does not |
|---|---|---|
| **EssentialsX** | homes (world names mapped), warps, nicknames (colour codes removed, then the nick rules apply), kits (items by this server's ids, `/commands` as kit commands, delay as the kit's cadence, `-1` as once), balances | mail (Keystone has none), enchantments, names and lore on kit items (the item comes plain), who may take a kit |
| **LuckPerms** (file storage: `yaml-storage` or `json-storage`) | groups with weight, prefix, suffix and parents; permission lines (allowed or refused, per world); players' memberships, with the end of a temporary one | database storage (H2, SQL) and HOCON - set `storage-method` to `yaml` or `json` in the old plugin, restart it once, import the folder it writes; tracks; permission lines given straight to a player; anything limited to another server or to a context other than a world |
| **FTB Ranks** (`ranks.snbt` / `ranks.json5`, `players.snbt` / `players.json5`) | ranks as groups (power is the weight, text around `{name}` in `ftbranks.name_format` is the prefix and suffix), allow/deny lines, players' ranks | values that are not allow/deny (claim limits and the like belong to other mods); a rank that was automatic (op, playtime...) becomes a group with nobody in it |
| **The game's lists** (`vanilla`) | `banned-players.json` into the ban ledger (reason, author, end), `ops.json` into the group `import.operators` names for that level | `whitelist.json` and `banned-ips.json` stay where they are: the game enforces them itself |
| **CoreProtect** (SQLite `database.db`) | block and container changes, into Keystone's [block audit](/docs/keystone/audit) | clicks and kills; a MySQL CoreProtect. With the `audit` module off, the import counts the rows, says so and loses nothing - run it again once the audit is on |

A permission line **limited by something Keystone cannot keep is left out, not widened**: a LuckPerms line for another server would otherwise become a line for this one. A temporary line is not made permanent either. Both are counted in the report.

### Permissions are translated

LuckPerms and FTB Ranks lines go through `import.permissions`, a table of `old=new`. The default knows the EssentialsX nodes that mean something here (`essentials.home` becomes `keystone.home`, `essentials.kits.*` becomes `keystone.kit.*`, `essentials.warp` becomes `keystone.warp`, and so on); a line with no rule is kept exactly as it was, because other mods read Keystone's permissions too.

## The report

A preview and an import both print the report in chat and keep it: **Import** in the editor shows the table (new, already here, refused per kind), the notes, and every refusal with its reason. The last thirty reports are kept. Reports name players and homes, so only the owner's key reads them.

## Settings

`import.toml`, or **Settings** in the editor.

| Setting | Default | What it does |
|---|---|---|
| `worlds` | `world=minecraft:overworld`, `world_nether=minecraft:the_nether`, `world_the_end=minecraft:the_end` | what the old server called its worlds. A home in a world nobody maps is refused, not guessed |
| `permissions` | the EssentialsX table above | `old=new` rules for permission lines; a trailing `*` carries the rest; an empty right side drops the line |
| `operators` | `4=admin` | which group an operator level becomes when `ops.json` is imported. Level 4 may do everything here anyway; the group is for the day you take their operator status away. A level with no line is left alone |
| `economy.command` | empty | the console command that pays a balance, with `{player}`, `{uuid}` and `{amount}`. Keystone keeps no balances; your currency mod does. Empty: balances are listed and not paid. **Each balance is paid once**, however often the import is run (owner only) |

## The API

Both are the owner's: the report names players and homes, and an import writes groups and bans.

| Route | Scope | |
|---|---|---|
| `GET /v1/import` | `import.read` | the sources, whether their files were found, and the last reports |
| `POST /v1/import/run` | `import.run` | `source`, `dryRun` (default `true`), `from`; answers with the report |

## What it reads, and what it does not

It reads files inside the server's folder and writes to Keystone's own database and settings, plus - for balances only - the one console command you set. It never changes the old plugin's files, never deletes anything, and sends nothing out. A file it cannot read is named in the report with its line; the rest still import. Report notes and refusal reasons are written in English whatever language the players use.
