KyuubiSoft Core

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:

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

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