# Core

> **Mod:** `KyuubiSoftCore-2.9.9.jar` | **Version:** 2.9.9 | **Data folder:** `mods/kyuubisoft_core/` | **Config:** `mods/kyuubisoft_core/config.json`

KyuubiSoft Core is the shared foundation for all KyuubiSoft Hytale mods. It provides the Citizen (NPC) system with its admin windows, NPC shops, the `/ksadmin` hub, the shared KS settings window, the tracking system, lootbag templates, developer tools, the web config editor, the shared language system and common utilities used by every other KyuubiSoft mod.

## Coming with 2.10.0: Kronen

Core 2.10.0 (not released yet, not tested in game) brings **Kronen**, KyuubiSoft's own server currency ("Crowns" in English). It is off by default. Once an admin switches it on and no other economy is installed, every KS mod pays with it: balances, transfers with `/kskronen pay` (also to people who are offline), a **Crowns** tile in the `/ksadmin` hub and an admin window with money sources, accounts, settings and a protocol. KyuubiSoft Bank 2.7.0 can carry the same currency on servers without Core.

See [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/) for commands, permissions, the admin window and the config file.

## What's new in 2.8 and 2.9

Core 2.8.0 and 2.9.x rebuilt almost every window in the KS Premium look and added in-game editors. Nothing in these releases has been tested in game yet.

- **`/ksadmin` hub ("KyuubiSoft Management")** with the tabs Mods, Status and Language. It only shows KS mods that are loaded on this server, with their real version. See [Admin Hub](#admin-hub----ksadmin).
- **KS settings window** (`/kssettings`): one language choice for every KS mod plus a page per installed mod with its own options.
- **NPC admin windows**: NPC management (`/kscitizen edit`), a skin editor, the NPC viewer and a dialog editor. See [NPC Admin Windows](https://wiki.kyuubisoft.com/hytale/citizens/admin-windows/).
- **New dialog window** with a 3D speaker, numbered answers, a history with "Step back", and **dialog actions** that need no commands (give or take items or coins, start a quest, open a shop, teleport, play a sound, set a fact). See [Dialog System](https://wiki.kyuubisoft.com/hytale/citizens/dialog-system/).
- **New NPC shop window and an in-game shop editor.** NPC shops now have their own command, `/ksnpcshop`. See [Shop System](https://wiki.kyuubisoft.com/hytale/shop-system/).
- **Item update window** (`/ksitemupdate`).
- **NPCs in several worlds** work properly: animations, reactions and schedules run in every world that has players.
- **Console commands are protected:** adding, changing or removing anything that runs as the console (NPC commands, dialog commands, shop entries, web editor imports) needs `ks.core.admin.dialog.console`.
- **2.9.3 (playtest fixes):** the skin editor's tabs stand out and point to the other areas, the item picker opens as a framed window, and player data can no longer be lost when the game reports a logout twice.
- **Simpler permissions:** `/ksadmin` and `/ksadmin reload` need only `ks.admin`; `/kscitizen` accepts `ks.citizen.admin` or `ks.admin`. See [Permissions](https://wiki.kyuubisoft.com/hytale/core/permissions/).

## Modules

Core is organized into toggleable modules. Each module can be enabled or disabled in `config.json`:

| Module | Default | Description |
|---|---|---|
| `citizens` | `true` | NPC system with skins, dialogs, animations, world map markers and the NPC admin windows. Registers `/kscitizen`. |
| `dialogs` | `true` | Dialog trees with choices, conditions, actions and commands |
| `shops` | `true` | NPC shops with several currencies, daily rotation and sell mode. Registers `/ksnpcshop` (and `/ksshop`, see below). |
| `lootbags` | `true` | Lootbag definitions and roll logic used by quests and achievements |
| `tracking` | `true` | Tracking for blocks, kills, damage, distance, crafting and zone discovery |
| `webEditor` | `false` | Browser-based web config editor. Registers `/kseditor`, `/kstrusteditor` and `/ksapplyconfig`. Applies after a restart. |
| `dynamicImages` | `true` | Dynamic image asset service |
| `playerPreferences` | `true` | Per-player preference storage |

## Systems Provided

### Citizens & NPCs

Spawn and manage custom NPCs with skins, equipment, dialog trees, waypoint paths, proximity reactions, time-of-day schedules, emote reactions and world map markers. Since 2.9.0 most of this can be edited in game: NPC management window, skin editor, NPC viewer and dialog editor. Citizens integrate with the Quest, Achievement and Shop systems.

See [Citizens & NPCs](https://wiki.kyuubisoft.com/hytale/citizens/) for full documentation.

### NPC Shops

Configurable server-owned shops with several currencies (economy coins, quest tokens, achievement points, items), daily rotation, buy and sell modes, purchase limits and command purchases. Players open them at an NPC or with `/ksnpcshop open <shop>`. Admins edit them in game with the shop editor from the `/ksadmin` hub.

See [Shop System](https://wiki.kyuubisoft.com/hytale/shop-system/) for full documentation.

### KS Settings

`/kssettings` opens one settings window shared by all KS mods:

- **Language**: "Automatic" or one of 9 languages. The choice applies to every KS mod and is the same one `/kslang` sets.
- **A page per installed mod** with its own options, for example toggles or choices, plus "Reset". Changes apply at once.

`/kssettings <mod>` opens the window on that mod's page (for example `/kssettings quests`). Every player may use it; admins can deny `ks.core.user.settings`.

### Item Update Window

`/ksitemupdate` (alias `/itemupdate`) lists items in your inventory that are older than the current item definitions, shows their old and new durability as bars and warns when durability will be reduced. Update items one by one or with "Update all"; every click is checked against your current inventory. An NPC with `itemUpdateEnabled` opens the same window. Permission: `ks.itemupdate.user.use` (granted by default).

### Tracking System

Central event dispatcher for player activity tracking. Feeds block break/place, kills, damage, distance, crafting, zone discovery and playtime data into the Quest, Achievement and Season Pass systems.

See [Tracking System](https://wiki.kyuubisoft.com/hytale/tracking/) for full documentation.

### Lootbag System

Lootbag definitions with fixed, random pool and hybrid roll modes, used as rewards by quests and achievements. Supports quality tiers, duplicate control and custom lootbags. Other mods can register their own lootbags; Core's standard and custom bags always win.

See [Lootbag Templates](https://wiki.kyuubisoft.com/hytale/achievement-system/lootbags/) for details. The standalone **Dropable Lootbags** mod is a different product, see [Lootbags](https://wiki.kyuubisoft.com/hytale/lootbags/).

### Developer Tools and Web Editor

In-game data export commands for items, blocks, entities, citizens, worlds and emotes, plus the browser-based web config editor.

See [Developer Tools](https://wiki.kyuubisoft.com/hytale/dev-tools/) for full documentation.

## Admin Hub -- `/ksadmin`

`/ksadmin` opens **KyuubiSoft Management**, the central admin window. It needs `ks.admin`.

| Tab | What it shows |
|---|---|
| **Mods** | One tile per KS mod that is loaded and enabled on this server, with its real version. Mods with their own admin window open it; mods without one get a "Config file" tile. Core's own tools (NPCs, NPC shops, NPC viewer) appear only when their module is on. Live search. |
| **Status** | Locked NPC files with a "Reload" button, Core translation coverage, paused player saves, the storage backend, the UI kit, the web editor switch (applies after a restart) and the result of "Reload all". |
| **Language** | The server/console language, a default language for players, and whether players may choose their own language. These settings are shared by every KS mod. |

Most mod tiles also check that mod's own admin permission (for example `ks.pet.admin` or `ks.bank.admin`). "Back to Core" in other mods' admin windows also needs `ks.admin`.

### `/ksadmin` subcommands

| Subcommand | Permission | Description |
|---|---|---|
| *(none)* | `ks.admin` | Open the admin hub |
| `reload` | `ks.admin` | Reload all mod configs (Citizens, Dialogs, Shops, Quests, Achievements, InfoHub, ...). Same run as "Reload all" in the hub. |
| `testsound` | `ks.admin` | Open Hytale's sound test page to browse and preview sounds |
| `cleanup nametags` | `ks.admin.cleanup` | Reset all player nameplates (online and offline) to remove orphaned title or level tags. In game only. |
| `migrate-storage file-to-mysql` | `ks.admin.migrate` | Import all local JSON player data into MySQL |
| `migrate-storage mysql-to-file` | `ks.admin.migrate` | Export all MySQL player data to local JSON files (existing files are kept as `.bak`) |
| `addxp <player> <amount>` | `ks.admin.xp` | Grant LevelingCore XP to a player |
| `removexp <player> <amount>` | `ks.admin.xp` | Remove LevelingCore XP from a player |

:::note
`cleanup`, `migrate-storage`, `addxp` and `removexp` still also check the old node `kyuubisoft.admin` when run by a player in game. Grant it together with the specific node, or run the command from the console. `migrate-storage` runs from the console, or in game only while you are the only player online.
:::

## Player Commands

### `/kslang` -- Language

Set the display language for all KyuubiSoft mods. No permission required.

| Usage | Description |
|---|---|
| `/kslang` | Show your language and the available languages in chat |
| `/kslang <code>` | Set a specific language (e.g. `de-DE`, `fr-FR`) |
| `/kslang auto` | Follow your game language again |

**Supported languages:** en-US, de-DE, es-ES, fr-FR, it-IT, pl-PL, pt-BR, ru-RU, tr-TR. Core ships language files for all 9, so the game keeps them even without other mods. Players with Portuguese (Portugal) get the Brazilian Portuguese texts.

The language chosen with `/kslang`, `/kssettings` or in any KS window is the same everywhere. If an admin turned off "players may choose" in the hub's Language tab, `/kslang` only shows the language the server set. The order is: the player's own choice (if allowed), then the server's default player language, then the game language, then English.

### `/kssettings` -- KS Settings

Opens the shared settings window, see [KS Settings](#ks-settings).

### `/ksnpcshop` -- NPC Shops

| Usage | Description |
|---|---|
| `/ksnpcshop open <shop>` | Open a shop |
| `/ksnpcshop sell <shop>` | Open a shop in sell mode |
| `/ksnpcshop list` | List the shops |

Core also registers `/ksshop` with the same subcommands. When the player shop mod (KyuubiSoft Shops) is installed, `/ksshop` belongs to that mod; use `/ksnpcshop` for Core's NPC shops. See [Shop System](https://wiki.kyuubisoft.com/hytale/shop-system/).

### `/ksitemupdate` -- Item Update

Opens the item update window, see [Item Update Window](#item-update-window).

## Other Admin Commands

| Command | Permission | Description |
|---|---|---|
| `/kscitizen ...` (alias `/npc`) | `ks.citizen.admin` or `ks.admin` | NPC management, see [Citizens Commands](https://wiki.kyuubisoft.com/hytale/citizens/commands/) |
| `/kseditor` | `ks.admin.editor` (+ `kyuubisoft.editor` in game) | Start a web editor session |
| `/kstrusteditor <code>` | `ks.admin.editor` (+ `kyuubisoft.editor` in game) | Confirm your web editor session with the code shown in the browser |
| `/ksapplyconfig <code>` | `ks.admin.editor` (+ `kyuubisoft.editor`) | Apply changes from your own confirmed editor session manually (fallback when the live connection is unavailable) |
| `/ksdev <type>` (alias `/dev`) | `ks.admin.dev` (+ `dev.admin` in game) | Export game data as JSON: `items`, `blocks`, `entities`, `citizens`, `worlds`, `emotes`, `all` |

The web editor commands only exist while `modules.webEditor` is `true`. Changes from the web editor apply only after the session was confirmed in game with `/kstrusteditor <code>`; a confirmed session needs a new confirmation after 30 minutes without applied changes. See [Developer Tools](https://wiki.kyuubisoft.com/hytale/dev-tools/).

## Permissions

See [Core Permissions](https://wiki.kyuubisoft.com/hytale/core/permissions/) for the full list. The most important nodes:

| Permission | Description |
|---|---|
| `ks.admin` | `/ksadmin` hub, `/ksadmin reload`, the NPC shop editor, and all NPC admin tools |
| `ks.citizen.admin` | `/kscitizen` subcommands and the NPC windows (NPC management, skin editor, NPC viewer, dialog editor) |
| `ks.core.admin.dialog.console` | Add, change or remove anything that runs as the server console (NPC and dialog commands, shop entries, web editor imports) |
| `ks.admin.editor` | Web config editor |

## Configuration

The main config file is `mods/kyuubisoft_core/config.json`:

```json
{
  "language": "en-US",
  "economyProvider": "auto",
  "logLevel": "info",
  "title": "KyuubiSoft Server",
  "storage": {
    "type": "file",
    "mysql": {
      "host": "localhost",
      "port": 3306,
      "database": "kyuubisoft",
      "username": "root",
      "password": "",
      "tablePrefix": "ks_",
      "maxPoolSize": 10
    }
  },
  "webEditor": {
    "editorUrl": "https://editor.kyuubisoft.com",
    "bytebinUrl": "https://editor.kyuubisoft.com/api/bin",
    "bytesocksUrl": "wss://editor.kyuubisoft.com/api/ws",
    "sessionTimeoutMinutes": 120,
    "trustIdleTimeoutMinutes": 30
  },
  "modules": {
    "citizens": true,
    "dialogs": true,
    "shops": true,
    "lootbags": true,
    "tracking": true,
    "webEditor": false,
    "dynamicImages": true,
    "playerPreferences": true
  }
}
```

### Configuration Fields

| Field | Default | Description |
|---|---|---|
| `language` | `en-US` | Core's own server language. The shared server and player languages are set in the hub's Language tab. |
| `economyProvider` | `auto` | Economy bridge mode (`auto` detects an installed economy plugin). From 2.10.0 (not released yet) the value `kronen` always uses Kronen, see [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/#cores-economyprovider) |
| `logLevel` | `info` | Log verbosity: `error`, `warning`, `info`, `all` (debug) |
| `title` | `KyuubiSoft Server` | Server name shown in the web editor |
| `storage.type` | `file` | Player data storage: `file` (JSON) or `mysql` |
| `webEditor.sessionTimeoutMinutes` | `120` | How long a web editor session lives |
| `webEditor.trustIdleTimeoutMinutes` | `30` | Minutes without applied changes after which a confirmed editor session needs `/kstrusteditor` again (added automatically) |
| `modules` | -- | Enable or disable individual modules. `modules.webEditor` switches the web editor. |

Older config files may still contain `description` and `links`; the current hub does not show them.

### Storage Options

Core supports two storage backends for player data (shop purchases, preferences, dialog answers and dialog action state):

| Type | Description |
|---|---|
| `file` | JSON files in the data directory (default, no setup required). Written safely; a broken file is kept as `.corrupt-<time>` and the `.bak` copy is loaded. |
| `mysql` | MySQL database with connection pooling |

Use `/ksadmin migrate-storage file-to-mysql` or `mysql-to-file` to move between backends. The migration includes the data of other KS mods that register their tables (for example Season Pass), player preferences, dialog answers and dialog actions.

If player data cannot be read (for example a MySQL timeout or a broken file), saving for that player pauses until the data can be read again, so nothing is overwritten. The hub's Status tab lists paused saves.

## Optional Dependencies

| Dependency | Purpose |
|---|---|
| `LevelingCore` | Enables `/ksadmin addxp` and `/ksadmin removexp` |
| `VaultUnlocked` / `Ecotale` | Economy plugins for coin prices, coin rewards and the "give/take coins" dialog actions. The bridge also finds an economy plugin that starts after Core. |

## File Structure

```
mods/kyuubisoft_core/
  config.json                 # Main configuration
  citizens.json               # Base NPC definitions
  citizen-backups/            # Last 10 timestamped backups of the NPC files
  custom/                     # Your own files (never overwritten)
    custom_citizens.json
    custom_lootbags.json
    custom_<shopId>.json
  dialogs/                    # Dialog tree JSON files
  shops/                      # Shop definition JSON files
    .removed_defaults         # Shipped shops you deleted or renamed (not extracted again)
  configs/
    lootbags.json             # Standard lootbags
  localization/               # Language files (9 languages)
  shop_data/                  # Player shop purchase data
  dev-export/                 # Developer export output
mods/kslang/
  prefs.json                  # Language choices shared by all KS mods
```

Bundled language files are replaced on update, with a backup (`*.json.backup-v<old>`). Put your own texts into `custom_<lang>.json`.