KyuubiSoft Core

kyuubisoft

The central foundation for all KyuubiSoft server mods. Provides a unified admin dashboard, NPC citizens with skins and dialogs, a generic shop system, a lootbag framework, centralized tracking, developer export tools, multi-language support, and shared utilities — so every mod works together seamlessly.

Features

Central Admin Dashboard

Open with /ksadmin — one command to access everything
Shows all installed KyuubiSoft mods with live status: ACTIVE, CORE, or N/A
One-click navigation to each mod's dedicated admin panel
Customizable server title, welcome message, and description
Configurable quick-links (Discord, Wiki, etc.) with custom colors
Global language selector — change the language and all mods update instantly
Modern UI with colored accent bars and version footer

NPC Citizens System

A full NPC framework for quest givers, merchants, guides, and ambient characters.

Spawning & Appearance:

Spawn NPCs with real player skins (fetched from PlayerDB, disk-cached)
Full equipment support: helmet, chest, gloves, leggings, main hand, off hand
Support for all entity types (not just player models)
Configurable hologram nametags via floating text
Spawn relative to world spawn point or at absolute coordinates
Persistent across chunk unloads and server restarts

Behavior:

8 movement roles — idle, wander (radius 2/5/10/15 blocks), interactable variants
Player rotation — NPCs smoothly turn toward nearby players
4 animation triggers — Timed, Timed Random, Proximity, On Interact
F-key interaction — Players press F to talk, trade, or trigger actions
Movement pause — NPCs freeze during dialog/shop interactions
Death & respawn — configurable damage, death despawn, timed respawn
Messages system — Random, Sequential, or All-at-once chat messages on interact
Colored messages — 18 named colors + hex codes for chat messages
Command actions — run commands as server or player on NPC interaction

WorldMap Markers:

Custom quest markers on the world map and compass
Per-player visibility (each player sees only their own quest markers)
Automatic multi-world registration — markers work in all worlds and instances
Three marker types: Quest Available (!), Quest Turn-In (?), Quest Progress

Citizen Admin Panel:

Full in-game CRUD editor via /ksadmin → Citizens
Create, edit, clone, delete NPCs without touching config files
Browse all fields: identity, appearance, position, interaction, behavior, equipment, animations, messages, commands
"My Position" button — set NPC position to your current location
"Set Items From Player" — copy your equipped items to the NPC
"Use My Skin" — apply your skin to the NPC
Move, teleport, respawn, despawn NPCs from the panel

Dialog System

Node-based dialog trees — TEXT, CHOICE, and INPUT nodes
Condition system — show/hide dialog options based on quests, achievements, or custom conditions
Macro system — execute server commands on dialog events with {player}/{citizen} placeholders
Typewriter effect — text appears character by character (~40 chars/sec), click to skip
DecoratedContainer design — matches Hytale's native UI style
External providers — Quest and Achievement mods inject their own conditions

Generic Shop System

A pluggable shop framework any mod can use.

Currency registry — mods register their own currencies (quest tokens, achievement points, items)
Daily rotation — weighted random item selection, deterministic per player
Purchase limits — max purchases per item per day
Item currency — automatically count and remove items from inventory (e.g. item:Ore_Gold)
3x3 grid UI with pagination, dynamic title, currency icon, and sold-out status
Persistent player data — purchase history saved per player

Shop Admin Panel:

Full in-game CRUD editor via /ksadmin → Shops
Create, edit, delete shops and their items
Browse items with search, filter, and pagination
Edit all item properties: ID, name, description, cost, quantity, weight, category, max purchases, permission

Lootbag System

A complete lootbag framework built into Core, ready for any mod to use.

Three Lootbag Types:

Fixed — Always grants the same items. Perfect for starter kits or guaranteed rewards.
Random Pool — Player receives X random items from a weighted pool. Great for mystery boxes.
Hybrid — Guaranteed items PLUS random pool picks. Ideal for achievement rewards.

Five Rarity Tiers:

Rarity	Color
Common	Gray
Uncommon	Green
Rare	Blue
Epic	Purple
Legendary	Orange

Lootbag Admin Panel:

Full in-game CRUD editor — no config files, no restarts
Browse, filter by rarity, search, create, edit, copy, delete
Visual item picker with search, icons, and pagination
Live preview of items, amounts, and pool weights

Centralized Tracking Service

All gameplay events are tracked once in Core and dispatched to all listening mods.

11 event types: Block Break, Block Place, Block Harvest, Flower Pick, Kill, Damage Dealt, Damage Taken, Distance Traveled, Playtime, Zone Discovery, Item Craft
Anti-exploit: PlacedBlockTracker prevents mining self-placed blocks (30min expiry)
Thread-safe: All dispatching via world.execute() on the world thread
Listener API: Mods register a single TrackingListener to receive all events

Custom Config System

Custom Citizens: Override or add NPCs via custom/custom_citizens.json
Custom Shops: Override or add items via custom/custom_{shopId}.json
Disabled IDs: Remove base entries without deleting files
Example files auto-generated on first start

Developer Export Tools

/ksdev items — Export all item IDs with properties (consumable, stack size, quality, etc.)
/ksdev blocks — Export all block IDs with material and group data
/ksdev entities — Export all entity types and NPC roles
/ksdev citizens — Export all configured NPCs with positions
/ksdev worlds — Export all world names and settings
/ksdev emotes — Export all available emotes
/ksdev all — Export everything at once
/ksdev export — Package all mod configs for the Mod Editor
Output: JSON files in configs/kyuubisoft_core/exports/

Multi-Language Support

Auto-discovery — all .json files in the localization folder are automatically loaded
Currently shipped: English and German
Global language selector in the admin panel — all mods switch language at once
JSON-based translation files — easy to add new languages
Automatic fallback to English if a key is missing

Shared Utilities

ItemUtils — Grant items, count items, remove items, format item names
CommandUtils — Execute commands as player or console with placeholders
RewardGrantHelper — Unified reward granting (items, commands, lootbags)
GameDataProvider — Cached access to block, item, NPC, and zone data
CoreAPI — Public facade for cross-mod access to all Core services (10 API groups, 40+ methods)

Commands

Command	Description	Permission
`/ksadmin`	Open the Core Admin Dashboard	`kyuubisoft.admin`
`/kscitizen`	NPC management (list, create, remove, tp, respawn, reload, info, marker)	`kyuubisoft.admin`
`/ksshop`	Open or list shops	—
`/kslootbags`	Open lootbag inventory	—
`/ksdev`	Developer data export tools	`kyuubisoft.admin`

Configuration

KyuubiSoft-Core/
├── config.json                        # Server title, language, links
├── configs/
│   ├── lootbags.json                  # Standard lootbag definitions
│   ├── citizens.json                  # NPC definitions
│   └── shops/
│       ├── example_shop.json          # Example shop
│       └── quest_token_shop.json      # Quest token shop
├── custom/
│   ├── custom_lootbags.json           # Your custom lootbags
│   ├── custom_citizens.json           # Your custom NPCs
│   └── custom_*.json.example          # Example templates
├── dialogs/
│   └── example_dialog.json            # Dialog tree definitions
├── skin-cache.json                    # Cached NPC skins
├── shop_data/
│   └── <uuid>.json                    # Per-player shop data
└── localization/
    ├── en-US.json                     # English translations
    └── de-DE.json                     # German translations

config.json

{
  "language": "en-US",
  "title": "My Server",
  "description": "Welcome to the admin area. Choose a tool from the list.",
  "links": [
    {
      "name": "Discord",
      "url": "https://discord.gg/example",
      "description": "Get help or leave feedback",
      "color": "#7289DA"
    }
  ]
}

Custom Lootbag Example

{
  "my_reward_box": {
    "name": "Reward Box",
    "description": "A box full of surprises",
    "icon": "Misc_GiftBox",
    "rarity": "rare",
    "type": "hybrid",
    "pickCount": 2,
    "allowDuplicates": false,
    "guaranteedItems": [
      { "itemId": "Consumable_Potion_Health_Greater", "amount": 3 }
    ],
    "pool": [
      { "itemId": "Weapon_Sword_Iron", "amount": 1, "weight": 30 },
      { "itemId": "Armor_Chest_Iron", "amount": 1, "weight": 25 },
      { "itemId": "Ore_Gold", "amount": 10, "weight": 45 }
    ]
  }
}

For Mod Developers

Access all Core services through the public API:

CoreAPI api = CoreAPI.getInstance();

// Citizens
api.getCitizenData("merchant_aldric");
api.addCitizenListener(myListener);

// Lootbags
api.grantLootbag(player, playerRef, "my_reward_box");
api.lootbagExists("my_reward_box");

// Shops
api.openShop(player, playerRef, ref, store, "quest_token_shop");
api.registerCurrency("my_currency", myProvider);

// Tracking
api.addTrackingListener(myListener);

// i18n
String text = api.translate("my.key", player);

Register your mod in the Core Admin Panel:

ModMenuRegistry.register(new ModMenuEntry(
    "mymod", "My Mod", "Does cool things", "1.0.0",
    (player, playerRef, ref, store) -> {
        player.getPageManager().openCustomPage(ref, store, new MyAdminPage(...));
    }
));

Compatibility

Required by: All KyuubiSoft mods
Integrates with: Quest System, Achievement System, InfoHub
Server: Hytale Dedicated Server
Java: 21+

Support

Discord: KyuubiSoft Discord

Attribution: The initial citizen system (v1.0.0) was built using https://github.com/ElectroGamesDev/HyCitizens (MIT License) as a starting point. See NOTICE.md for details.

Made with Love by KyuubiSoft

KyuubiSoft Core (NPCs, NPC Shops and more)