KyuubiSoft 核心

九尾软核

所有九尾软服务器模组的核心基础。提供统一的管理仪表盘、NPC 公民的皮肤和对话、通用商店系统、战利品袋框架、集中追踪、开发者导出工具、多语言支持和共享工具——确保每个模组无缝协作。

---

特色

中央管理仪表盘

• 用 /ksadmin 打开——一个命令即可访问所有内容
• 显示所有已安装的九尾软模组，状态为：ACTIVE、CORE 或 N/A
• 一键导航到每个版主专用管理面板
• 可自定义服务器标题、欢迎信息和描述
• 可配置快速链接（Discord、Wiki 等），并带有自定义颜色
• 全局语言选择器——更改语言，所有模组即时更新
• 现代用户界面，带有彩色强调条和版本页脚

NPC 公民系统

一个完整的 NPC 框架，适用于任务发布者、商人、向导和环境角色。

产卵与外观：

• 生成带有真实玩家皮肤的 NPC（从 PlayerDB 抓取，磁盘缓存）
• 全套装备支持：头盔、胸甲、手套、紧身裤、主手、副手
• 支持所有实体类型（不仅仅是玩家模型）
• 可配置的全息名牌，通过浮动文本
• 生成相对于世界生成点或绝对坐标
• 跨区块卸载和服务器重启时持续存在

行为：

• 8 种移动角色 ——闲置、漫游（半径 2/5/10/15 格）、可互动变体
• 玩家轮换 ——NPC 会顺畅地转向附近的玩家
• 4 个动画触发器 ——定时、定时随机、接近、互动中
• F 键交互 ——玩家按 F 键进行对话、交换或触发动作
• 移动暂停 ——NPC 在对话/商店互动时会冻结
• 死亡与重生 ——可配置伤害、死亡消失、定时重生
• 消息系统 ——互动上的随机、顺序或一次性聊天消息
• 彩色消息 ——18 种命名颜色+聊天消息的十六进制代码
• 指令动作 ——在 NPC 互动时以服务器或玩家身份执行命令

世界地图标记：

• 世界地图和指南针上的自定义任务标记
• 每个玩家的可见性（每个玩家只看到自己的任务标记）
• 自动多世界注册——标记在所有世界和实例中都有效
• 三种标记类型：任务可用（！）、任务交放（？）、任务进度

公民管理小组：

• 完整的游戏内 CRUD 编辑器，来自 /ksadmin → Citizens
• 创建、编辑、克隆、删除 NPC，无需操作配置文件
• 浏览所有字段：身份、外观、位置、交互、行为、设备、动画、消息、命令
• “我的位置”按钮——将 NPC 位置设置为当前位置
• “从玩家处设置物品”——将你装备的物品复制给 NPC
• “用我的皮肤”——把你的皮肤贴在 NPC 身上
• 移动、传送、重生、从面板中消失 NPC

对话系统

• 基于节点的对话树 ——TEXT、CHOICE 和 INPUT 节点
• 条件系统 ——根据任务、成就或自定义条件显示/隐藏对话框选项
• 宏系统 ——在对话事件中执行服务器命令，使用 {player}/{citizen} 占位符
• 打字机效果 ——文本逐字符显示（~40 字/秒），点击跳过
• DecoratedContainer 设计 ——与 Hytale 原生界面风格相匹配
• External providers — Quest and Achievement mods inject their own conditions

通用商店系统

一个可插拔的商店框架，任何模组都可以使用。

• 货币注册 ——模组注册自己的货币（任务代币、成就点数、物品）
• 每日轮换 ——加权随机物品选择，对每个玩家是确定性的
• 购买限制 ——每个物品每日本次数上限
• 物品货币 ——自动从库存中计数和移除物品（例如 item:Ore_Gold）
• 3x3 网格界面，带有分页、动态标题、货币图标和售罄状态
• 持久玩家数据 ——保存每个玩家的购买历史

商店管理面板：

• 完整的游戏内 CRUD 编辑器，来自 /ksadmin → Shops
• 创建、编辑、删除商店及其物品
• 使用搜索、筛选和分页浏览物品
• 编辑所有物品属性：ID、名称、描述、花费、数量、重量、类别、最高购买次数、权限

战利品袋系统

一个完整的战利品袋框架，内置于核心中，随时可供任何模组使用。

三种战利品袋类型：

• 固定 ——总是给予相同的物品。适合新手包或保证奖励。
• 随机池 ——玩家从加权池中获得 X 个随机物品。非常适合神秘盒子。
• 混合 ——保证物品 PLUS 随机池选择。理想用于成就奖励。

五个稀有度等级：

稀有度	颜色
常见	灰色
罕见	绿色
稀有	蓝色
史诗	紫色
传奇	橙色

战利品袋管理面板：

• 完整的游戏内 CRUD 编辑器 —— 无需配置文件，无需重启
• 浏览、按稀有度筛选、搜索、创建、编辑、复制、删除
• 带有搜索、图标和分页的可视物品选择器
• 物品、数量和池权重的实时预览

集中追踪服务

所有游戏内事件在核心中统一追踪，并分发给所有监听的模组。

• 11 种事件类型：方块破坏、方块放置、方块收获、采花、击杀、造成伤害、受到伤害、旅行距离、游戏时间、区域发现、物品制作
• 反作弊：PlacedBlockTracker 防止挖掘自己放置的方块（30 分钟过期）
• 线程安全：所有分派通过 world.execute() 在世界线程上进行
• 监听器 API：模组注册一个 TrackingListener 以接收所有事件

自定义配置系统

• 自定义公民：通过 custom/custom_citizens.json 覆盖或添加 NPC
• 自定义商店：通过 custom/custom_{shopId}.json 覆盖或添加物品
• 禁用 ID：无需删除文件即可移除基本条目
• 首次启动时自动生成示例文件

开发者导出工具

• /ksdev items ——导出所有带有属性的物品 ID（消耗品、堆叠大小、品质等）
• /ksdev blocks ——导出所有带有材料和组数据的方块 ID
• /ksdev entities ——导出所有实体类型和 NPC 角色
• /ksdev citizens ——导出所有带有位置的已配置 NPC
• /ksdev worlds ——导出所有世界名称和设置
• /ksdev emotes ——导出所有可用表情
• /ksdev all ——一次性导出所有内容
• /ksdev export ——打包所有模组配置以供 Mod Editor 使用
• 输出：configs/kyuubisoft_core/exports/ 目录下的 JSON 文件

多语言支持

• 自动发现 ——本地化文件夹中的所有 .json 文件都会被自动加载
• 目前附送：英语 和 德语
• 管理面板中的全局语言选择器 —— 所有模组同时切换语言
• 基于 JSON 的翻译文件 —— 易于添加新语言
• 如果缺少某个键，自动回退到英语

共享工具

• ItemUtils ——给予物品、计数物品、移除物品、格式化物品名称
• CommandUtils ——以玩家或控制台身份执行命令，带有占位符
• RewardGrantHelper ——统一的奖励发放（物品、命令、战利品袋）
• GameDataProvider ——对方块、物品、NPC 和区域数据的缓存访问
• CoreAPI ——用于所有核心服务的跨模组访问的公共门面（10 个 API 组，40+ 个方法）

---

命令

命令	描述	权限
/ksadmin	打开核心管理仪表盘	kyuubisoft.admin
/kscitizen	NPC 管理（列表、创建、移除、传送、重生、重载、信息、标记）	kyuubisoft.admin
/ksshop	打开或列出商店	—
/kslootbags	打开战利品袋库存	—
/ksdev	开发者数据导出工具	kyuubisoft.admin

---

配置

KyuubiSoft-Core/
├── config.json                        # 服务器标题、语言、链接
├── configs/
│   ├── lootbags.json                  # 标准战利品袋定义
│   ├── citizens.json                  # NPC 定义
│   └── shops/
│       ├── example_shop.json          # 示例商店
│       └── quest_token_shop.json      # 任务代币商店
├── custom/
│   ├── custom_lootbags.json           # 你的自定义战利品袋
│   ├── custom_citizens.json           # 你的自定义 NPC
│   └── custom_*.json.example          # 示例模板
├── dialogs/
│   └── example_dialog.json            # 对话树定义
├── skin-cache.json                    # 缓存的 NPC 皮肤
├── shop_data/
│   └── <uuid>.json                    # 每个玩家的商店数据
└── localization/
    ├── en-US.json                     # 英语翻译
    └── de-DE.json                     # 德语翻译

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"
    }
  ]
}

自定义战利品袋示例

{
  "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 }
    ]
  }
}

---

面向模组开发者

通过公共 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);

在核心管理面板注册你的模组：

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

---

兼容性

• Required by：所有九尾软模组
• Integrates with：任务系统、成就系统、信息中心
• 服务器 ：Hytale 专用服务器
• 爪哇 ：21+

---

支持

• Discord：九尾软 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.

九尾软制作