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
Section titled “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 for commands, permissions, the admin window and the config file.
What’s new in 2.8 and 2.9
Section titled “What’s new in 2.8 and 2.9”Latest versions from the changelog:
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.
/ksadminhub (“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.- 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. - 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.
- New NPC shop window and an in-game shop editor. NPC shops now have their own command,
/ksnpcshop. See 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:
/ksadminand/ksadmin reloadneed onlyks.admin;/kscitizenacceptsks.citizen.adminorks.admin. See Permissions.
Modules
Section titled “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
Section titled “Systems Provided”Citizens & NPCs
Section titled “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 for full documentation.
NPC Shops
Section titled “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 for full documentation.
KS Settings
Section titled “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
/kslangsets. - 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
Section titled “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
Section titled “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 for full documentation.
Lootbag System
Section titled “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 for details. The standalone Dropable Lootbags mod is a different product, see Lootbags.
Developer Tools and Web Editor
Section titled “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 for full documentation.
Admin Hub — /ksadmin
Section titled “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
Section titled “/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 |
Player Commands
Section titled “Player Commands”/kslang — Language
Section titled “/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
Section titled “/kssettings — KS Settings”Opens the shared settings window, see KS Settings.
/ksnpcshop — NPC Shops
Section titled “/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.
/ksitemupdate — Item Update
Section titled “/ksitemupdate — Item Update”Opens the item update window, see Item Update Window.
Other Admin Commands
Section titled “Other Admin Commands”| Command | Permission | Description |
|---|---|---|
/kscitizen ... (alias /npc) | ks.citizen.admin or ks.admin | NPC management, see 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.
Permissions
Section titled “Permissions”See 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
Section titled “Configuration”The main config file is mods/kyuubisoft_core/config.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
Section titled “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 |
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
Section titled “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
Section titled “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
Section titled “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 outputmods/kslang/ prefs.json # Language choices shared by all KS modsBundled language files are replaced on update, with a backup (*.json.backup-v<old>). Put your own texts into custom_<lang>.json.