Core

KyuubiSoft Core

Mod: kyuubisoft-core.jar | Version: 2.2.0 | Config: configs/kyuubisoft_core/config.json

KyuubiSoft Core is the shared foundation for all KyuubiSoft Hytale mods. It provides the Citizen (NPC) system, Shop system, Tracking system, Lootbag system, Developer Tools, Web Config Editor, localization framework, and common utilities used by every other KyuubiSoft mod.

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, and world map markers
`dialogs`	`true`	Dialog tree system with choices, conditions, and macros
`shops`	`true`	Multi-currency shop system with daily rotation and sell mode
`lootbags`	`true`	Lootbag definitions and roll logic
`tracking`	`true`	ECS tracking for blocks, kills, damage, distance, crafting, and zone discovery
`webEditor`	`false`	Browser-based Web Config Editor
`dynamicImages`	`true`	Dynamic image asset service
`playerPreferences`	`true`	Per-player language and 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. Citizens integrate with the Quest, Achievement, and Shop systems.

See Citizens & NPCs for full documentation.

Shop System

Configurable in-game shops with support for multiple currencies (quest tokens, achievement points, item-based), daily rotation, buy/sell modes, purchase limits, command purchases, and an in-game admin panel.

See Shop System for full documentation.

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 and Achievement systems.

See Tracking System for full documentation.

Lootbag System

Lootbag definitions with fixed, random pool, and hybrid roll modes. Supports quality tiers, duplicate control, and custom lootbags.

See Lootbag System for full documentation.

Developer Tools

In-game data export commands for items, blocks, entities, citizens, worlds, and emotes. Exports to JSON for use with the Mod Editor.

See Developer Tools for full documentation.

Admin Commands

`/ksadmin` — Core Admin

Opens the central admin panel with access to all module admin pages. Requires kyuubisoft.admin.

Subcommand	Description
(none)	Open the admin panel UI
`reload`	Reload all mod configs (Citizens, Quests, Achievements, InfoHub, etc.)
`cleanup nametags`	Reset all player nameplates (online + offline) — removes orphaned title/level tags
`migrate-storage file-to-mysql`	Import all local JSON player data into MySQL
`migrate-storage mysql-to-file`	Export all MySQL player data to local JSON files
`addxp <player> <amount>`	Grant LevelingCore XP to a player
`removexp <player> <amount>`	Remove LevelingCore XP from a player

`/kslang` — Language Settings

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

Usage	Description
`/kslang`	Open the Language Settings page
`/kslang auto`	Reset to auto-detect language
`/kslang <code>`	Set a specific language (e.g., `de-DE`, `fr-FR`)

Supported languages: en-US, de-DE, es-ES, fr-FR, it-IT, pl-PL, pt-BR, ru-RU, tr-TR

`/kseditor` — Web Config Editor

Opens a browser-based config editor session. Requires kyuubisoft.editor.

Related Command	Description
`/kseditor`	Generate a web editor URL
`/ksapplyconfig <code>`	Manually apply config changes from the editor (fallback when WebSocket is unavailable)
`/kstrusteditor <nonce>`	Confirm a web editor connection

`/ksdev` — Developer Export

Export game data as JSON files for development reference. Requires dev.admin. Alias: /dev.

Subcommand	Description
`items`	Export all items with categories, stack size, durability, etc.
`blocks`	Export all blocks with groups, materials, properties
`entities`	Export all entity types and NPC roles
`citizens`	Export all configured citizens
`worlds`	Export all worlds with config details
`emotes`	Export all emotes and animation slots
`all`	Export everything at once

Permissions

Permission	Description
`kyuubisoft.admin`	`/ksadmin` and all subcommands (reload, cleanup, migrate, addxp, removexp)
`citizen.admin`	`/kscitizen` — all NPC management commands
`kyuubisoft.editor`	`/kseditor`, `/ksapplyconfig`, `/kstrusteditor` — web editor access
`dev.admin`	`/ksdev` — developer data export commands

Configuration

The main config file is configs/kyuubisoft_core/config.json:

{
  "language": "en-US",
  "economyProvider": "auto",
  "logLevel": "info",
  "title": "KyuubiSoft Server",
  "description": "Welcome to the admin area.",
  "links": [
    {
      "name": "Discord",
      "url": "https://dsc.gg/kyuubisoft",
      "description": "Community support"
    }
  ],
  "storage": {
    "type": "file",
    "mysql": {
      "host": "localhost",
      "port": 3306,
      "database": "kyuubisoft",
      "username": "root",
      "password": "",
      "tablePrefix": "ks_",
      "maxPoolSize": 10
    }
  },
  "modules": {
    "citizens": true,
    "dialogs": true,
    "shops": true,
    "lootbags": true,
    "tracking": true,
    "webEditor": false,
    "dynamicImages": true,
    "playerPreferences": true
  },
  "webEditor": {
    "enabled": false,
    "editorUrl": "https://editor.kyuubisoft.com",
    "bytebinUrl": "https://editor.kyuubisoft.com/api/bin",
    "bytesocksUrl": "wss://editor.kyuubisoft.com/api/ws",
    "sessionTimeoutMinutes": 120
  }
}

Configuration Fields

Field	Default	Description
`language`	`en-US`	Default server language
`economyProvider`	`auto`	Economy bridge mode (`auto` detects available providers)
`logLevel`	`info`	Log verbosity: `error`, `warning`, `info`, `all` (debug)
`title`	`KyuubiSoft Server`	Server name shown in the admin panel
`description`	—	Admin panel welcome text
`links`	`[]`	Links shown in the admin panel (Discord, Wiki, etc.)
`storage.type`	`file`	Player data storage: `file` (JSON) or `mysql`
`modules`	—	Enable/disable individual modules

Storage Options

Core supports two storage backends for player data (shop purchases, preferences):

Type	Description
`file`	JSON files in the data directory (default, no setup required)
`mysql`	MySQL database with HikariCP connection pooling

Use /ksadmin migrate-storage file-to-mysql or mysql-to-file to migrate between backends.

Optional Dependencies

Dependency	Purpose
`LevelingCore`	Enables `/ksadmin addxp` and `/ksadmin removexp` commands
`MHUD`	Enables HUD integration for waypoint recording and other overlays

File Structure

configs/kyuubisoft_core/
  config.json                 # Main configuration
  citizens.json               # Base citizen definitions
  custom/                     # Custom overrides (never overwritten)
    custom_citizens.json
    custom_<shopId>.json
  dialogs/                    # Dialog tree JSON files
    example_dialog.json
  shops/                      # Shop definition JSON files
    example_shop.json
    general_store.json
    blacksmith.json
    alchemist.json
    daily_deals.json
    rare_collector.json
  localization/               # Language files
    en-US.json
    de-DE.json
    fr-FR.json
    ...
  data/
    shop_data/                # Player shop purchase data
  dev-export/                 # Developer export output