模拟聊天

模拟聊天

我的世界内的一款聊天客户端,具备数据驱动模拟对话与对话功能

Sim Chat

一个 Minecraft Forge 模组,为对话添加 Slack/Discord 风格的聊天界面。面向整合包作者,可通过数据包和命令编写对话脚本。

特性

  • Slack/Discord 风格界面:带有会话列表的侧边栏,以及带消息气泡的聊天历史面板
  • 基于队伍的会话:玩家在队伍内共享会话历史
  • 数据包驱动的对话:以 JSON 定义对话树,作为数据包资源加载
  • 操作按钮:可点击的回复选项,触发命令或继续对话
  • 条件操作:基于数据、计分板或 KubeJS 回调显示/隐藏按钮
  • 模板系统:动态文本,支持玩家名称、队伍数据、世界信息
  • 输入中指示器:消息出现前模拟输入延迟
  • Toast 通知:新消息到达时显示非侵入式弹窗
  • 自定义头像:从配置文件夹加载 PNG 图片作为发送者头像
  • 队伍数据存储:按队伍存储值、状态和分数
  • KubeJS 集成:为条件和模板注册自定义回调
  • SQLite 存储:持久化消息历史,大型会话采用懒加载
  • 可扩展:可处理 10 万+ 消息,滚动流畅且界面响应即时

依赖

  • 客户端和服务端均需要 sqlite_jdbc 库模组(minecraft-sqlite-jdbc)

存储

会话历史存储在 SQLite 数据库 <world>/data/simchat/simchat.db 中。这提供了:

  • 可扩展性:通过懒加载高效处理 10 万+ 消息
  • 持久性:数据在服务端重启和世界重新加载后依然保留
  • 可检查性:消息以人类可读的 JSON 存储(可在任意 SQLite 浏览器中查看)

命令

基础命令

/simchat send <player> <dialogueId>    - 向玩家发送对话
/simchat system <player> <entityId> <message>  - 发送系统消息
/simchat clear <player> [entityId]     - 清除聊天历史
/simchat open <player> [entityId]      - 为玩家打开聊天界面
/simchat openmessage <messageId>       - 打开聊天并定位到指定消息
/simchat reload                        - 重新加载 KubeJS 回调

队伍命令

/simchat team create <name>            - 创建新队伍
/simchat team invite [player]          - 邀请玩家(省略则向所有玩家广播)
/simchat team join <teamId>            - 通过 ID 加入队伍
/simchat team list                     - 列出所有队伍
/simchat team info                     - 显示当前队伍信息
/simchat team title <newTitle>         - 更改队伍名称
/simchat team color <color>            - 更改队伍颜色(仅名称)

可用颜色:black、dark_blue、dark_green、dark_aqua、dark_red、dark_purple、gold、gray、dark_gray、blue、green、aqua、red、light_purple、yellow、white

数据命令

按队伍存储值,用于跟踪进度、分数、状态。所有命令都接受可选的 [target] 参数(玩家名或队伍 ID/名称)以操作指定队伍:

/simchat data get <key> [target]       - 获取值
/simchat data set <key> <value> [target]   - 设置值(自动识别数字)
/simchat data add <key> <amount> [target]  - 向数值添加
/simchat data remove <key> [target]    - 移除键
/simchat data list [target]            - 列出所有数据

示例:

/simchat data get gold                 - 获取你队伍的金币
/simchat data get gold Steve           - 获取 Steve 队伍的金币
/simchat data set rank vip "Team Alpha"    - 在 Team Alpha 上设置字符串
/simchat data set gold 100             - 设置数字(自动识别)
/simchat data add points 10 abc1234    - 向队伍 abc1234 添加 10 点

回调命令

/simchat callback list                 - 列出已注册的 KubeJS 回调
/simchat callback run <name> [player]  - 执行回调并显示结果

数据包格式

对话从以下位置加载:data/<namespace>/simchat/<path>.json

示例:data/mypack/simchat/contractor/greeting.json

{
  "entityId": "contractor",
  "entityName": "Director Vex",
  "entitySubtitle": "Helion Industries",
  "text": "Hello {player:name}! Your team ({team:title}) has completed {data:contracts_done} contracts.",
  "actions": [
    {
      "label": "Accept Contract (+{data:reward} credits)",
      "commands": [
        "simchat data add contracts_done 1",
        "give @s emerald 10"
      ],
      "reply": "I'll take the job.",
      "nextState": "mypack:contractor/contract_details",
      "condition": "data:has_clearance"
    },
    {
      "label": "Decline",
      "reply": "Not interested.",
      "condition": "!data:forced_contract"
    }
  ]
}

对话字段

字段 类型 描述
entityId string 唯一实体标识符(用于头像查找和会话分组)
entityName string 聊天中显示的显示名称
entitySubtitle string 可选副标题(公司、头衔)
text string 消息内容(支持模板)
actions array 回复按钮(可选)

操作字段

字段 类型 描述
label string 按钮文本(支持模板)
commands array 点击时执行的命令
reply string 聊天中显示的玩家回复(支持模板)
nextState string 此操作后触发的对话 ID
condition string 显示按钮所需满足的条件
itemsVisual array 按钮上显示的物品
itemsInput array 需要玩家提供的物品(启用前检查)
itemsOutput array 给予玩家的物品

物品格式

{
  "item": "minecraft:diamond",
  "count": 5
}

模板

模板可用于 entityName、entitySubtitle、text、label、reply 和 commands。

以 {compile:...}(默认)为前缀,在消息创建时于服务端解析;以 {runtime:...} 为前缀,在消息显示时于客户端解析。运行时模板在客户端存储和解析;服务端只能看到编译后的文本。运行时值在聊天打开、新消息到达或点击刷新按钮时刷新。

在文本、标签和回复中使用 {resolver:name} 语法:

模板 描述 示例
{player:name} 玩家用户名 "Steve"
{player:uuid} 玩家 UUID "069a79f4..."
{team:id} 队伍 ID "a1b2c3d"
{team:title} 队伍名称 "The Builders"
{team:memberCount} 队伍成员数量 "3"
{team:color} 队伍颜色名称 "dark_blue"
{data:keyname} 队伍数据值 "42"
{world:day} 当前世界天数 "15"
{world:time} 一天中的时间(0-24000) "6000"
{world:dimension} 维度 ID "minecraft:overworld"
{world:weather} 天气状态 "clear"、"rain"、"thunder"
{kjs:callbackName} KubeJS 回调结果 (任意值)

示例:

{
  "text": "Day {world:day}: Hello {player:name}! You have {data:points} points."
}

条件

使用条件来显示/隐藏操作按钮。以 ! 为前缀表示取反。

条件 描述
data:keyname 若队伍数据为真值(存在、非零、非空)则为真
kjs:callbackName 若 KubeJS 回调返回真值则为真
score:objectiveName 若玩家的计分板分数 > 0 则为真
permission:level 若玩家拥有该权限等级则为真

示例:

{
  "actions": [
    {
      "label": "VIP Option",
      "condition": "data:is_vip"
    },
    {
      "label": "Regular Option",
      "condition": "!data:is_vip"
    },
    {
      "label": "Admin Only",
      "condition": "permission:2"
    }
  ]
}

KubeJS 集成

在 kubejs/server_scripts/simchat.js 中注册回调:

// Clear old callbacks on reload
SimChat.clearCallbacks()

// Register a condition callback
SimChat.registerCallback('hasEnoughGold', ctx => {
    return ctx.player.persistentData.getInt('gold') >= 100
})

// Register a template callback
SimChat.registerCallback('goldAmount', ctx => {
    return ctx.player.persistentData.getInt('gold')
})

// Register using team data
SimChat.registerCallback('isVeteran', ctx => {
    return ctx.team && ctx.team.data.missions_completed >= 10
})

// Time-based callback
SimChat.registerCallback('greeting', ctx => {
    let time = ctx.player.level.dayTime % 24000
    if (time < 6000) return 'Good morning'
    if (time < 12000) return 'Good afternoon'
    return 'Good evening'
})

SimChat.logStatus() // Log callback count

回调上下文

回调中可通过 ctx 使用:

// Player (KubeJS wrapped - full access)
ctx.player
ctx.player.persistentData
ctx.player.level.dayTime
ctx.player.inventory

// Team (null if no team)
ctx.team.id
ctx.team.title
ctx.team.memberCount
ctx.team.data           // Map of all team data
ctx.team.data.keyname   // Access specific key
ctx.team.hasData('key') // Boolean check

// Entity (null if no entity context)
ctx.entity.id
ctx.entity.displayName
ctx.entity.messageCount
ctx.entity.lastMessage
ctx.entity.isTyping

在对话中使用

{
  "text": "{kjs:greeting}, {player:name}! You have {kjs:goldAmount} gold.",
  "actions": [
    {
      "label": "Buy Item (100 gold)",
      "condition": "kjs:hasEnoughGold",
      "commands": ["simchat data add purchases 1"]
    }
  ]
}

实体文件

将实体配置和头像放在:config/simchat/entities/

每个实体可以包含:

  • <entityId>.json - 包含名称、副标题、头像设置的配置
  • <entityId>.png - 头像图片(任意尺寸,显示为 36x36)

示例:config/simchat/entities/merchant.json

{
  "name": "Merchant Bob",
  "subtitle": "Ironwood Trading Co.",
  "avatar": "merchant"
}
字段 描述
name 默认显示名称
subtitle 默认副标题
avatar 头像 ID(默认为 entityId)

默认值

创建 default.json 和/或 default.png 作为没有特定文件的实体的回退。

所有实体文件在修改后热重载。

配置

客户端配置(simchat-client.toml)

选项 默认值 描述
notificationSound minecraft:block.note_block.bell 新消息提示音
notificationVolume 0.5 音量(0.0-1.0)
showToasts true 显示 Toast 弹窗
toastDuration 5.0 Toast 显示时间(秒)
sidebarWidth 240 会话列表宽度
sidebarSortMode 0 排序:0=最近,1=字母顺序
chatBackgroundColor 0xDD12121F 聊天面板背景(ARGB 十六进制)
lazyLoadBatchSize 30 向上滚动时请求的消息数
lazyLoadThreshold 100 加载更早消息前距顶部的像素数
closedCacheSize 400 聊天关闭时每个会话保留缓存的消息数

通用配置(simchat-common.toml)

选项 默认值 描述
minDelay 0.3 最小输入延迟(秒)
maxDelay 3.0 最大输入延迟(秒)
charsPerSecond 100.0 模拟输入速度
permissions.* 4 各命令的权限等级(0-4)
permissions.openmessage 0 允许打开消息链接
teamJoin.joinBehavior join_largest join_largest、join_smallest、join_random、create_new
teamJoin.joinSizeCap -1 自动加入上限(-1 禁用,若无符合条件则创建新队伍)
initialMessageCount 30 初次同步时每个会话的消息数
maxLazyLoadBatchSize 100 服务端懒加载请求上限

颜色覆盖(simchat-client.toml)

颜色设置位于 [colors] 部分下,接受 ARGB 十六进制字符串(例如 0xFF88AAFF)。示例:

[ui]
chatBackgroundColor = "0x8047BAFF"

[colors]
sidebarBackgroundColor = "0xFF1B2230"
headerTextColor = "0xFFBBD7FF"
messageTextColor = "0xFFE8F1FF"
contextMenuBgColor = "0xFF202030"
toastBackgroundColor = "0xFF243048"

可用的颜色键(全部可选):

  • sidebarBackgroundColor
  • dividerColor
  • dividerHoverColor
  • headerTextColor
  • headerSubtitleColor
  • emptyStateTextColor
  • headerSeparatorColor
  • refreshButtonColor
  • refreshButtonHoverColor
  • refreshTextColor
  • sortButtonColor
  • sortButtonHoverColor
  • sortTextColor
  • compactHintColor
  • scrollbarColor
  • inputBgColor
  • outputBgColor
  • disabledBgColor
  • playerNameColor
  • entityNameColor
  • subtitleColor
  • dayTextColor
  • messageTextColor
  • disabledTextColor
  • whiteTextColor
  • systemTextColor
  • buttonDefaultColor
  • buttonHoverColor
  • borderDisabledColor
  • borderHoverColor
  • borderDefaultColor
  • focusBorderColor
  • contextMenuBgColor
  • contextMenuBorderColor
  • contextMenuTextColor
  • contextMenuHighlightColor
  • inputValidColor
  • inputInvalidColor
  • inputFieldBgColor
  • inputFieldBorderColor
  • inputFieldBorderFocusedColor
  • inputCursorColor
  • inputSendEnabledColor
  • inputSendDisabledColor
  • toastSenderColor
  • toastPreviewColor
  • toastBackgroundColor
  • toastBorderColor
  • toastHintColor

按键绑定

按键 操作
;(分号) 打开聊天界面

JSON Schema

使用 JSON schema 验证你的对话:schemas/dialogue.schema.json。

VS Code 设置:

{
  "$schema": "https://raw.githubusercontent.com/YardenZamir/sim-chat/main/schemas/dialogue.schema.json",
  "entityId": "...",
  ...
}

许可证

MIT