CraftPresence

通过 Discord 的 Rich Presence API 和 DiscordIPC API，完全自定义其他玩家看到你玩 Minecraft 的方式
作者 jagrosh！

常规说明

• 从 v2.5.0 开始，UniLib 现在是必需的前置依赖
• UniLib 是我创建的一个新前置库模组，用于抽象出常见 API 功能，以便更通用的用例以及未来的项目使用
• 该模组可在此处下载
• 如果未找到 UniLib 或使用了不兼容的版本，该模组将会崩溃
• 该模组被标识为仅客户端模组
• 这意味着它不会在服务端运行。
• Fabric 和 Quilt 模组加载器会直接忽略该模组，而其他模组加载器可能会崩溃。
• 适用于 Minecraft 1.14.x 及以上版本的部分模组版本需要 Fabric API 和 Fabric 模组加载器
• 适用于 Minecraft 1.13.x 的部分模组版本需要 Rift API 和 Rift 模组加载器
• 适用于 Minecraft 1.1.0 及以下版本的部分模组版本需要 Risugami’s ModLoader

功能

除了可以将你的 Discord 状态从“Playing Minecraft”更改为其他内容之外，
这个模组还提供了大量自定义选项，让你完全决定其他人如何看到你的游戏状态。
你可以显示当前所在的生物群系、所在的维度、当前所在的服务器等信息。
自定义选项几乎没有限制，唯一真正的限制就是你在设计显示内容时的创意。

启动器和整合包集成支持

CraftPresence 会检测你的启动目录中是否包含以下文件：

• ATLauncher 实例（instance.json）
• 有效的 Twitch/Overwolf/Curse/GDLauncher 清单（manifest.json、minecraftinstance.json）
• MCUpdater 实例（instance.json）
• Modrinth 实例（profile.json）
• MultiMC 实例（instance.cfg）
• Technic 的 installedPacks 文件（installedPacks）

如果你使用上述任一启动器，请注意以下事项：

• 在 v1.6.0 之前，整合包名称会显示在你的状态中，并且还会显示其图标（不在服务器中时）
• 从 v1.6.0 到 v2.0.0，整合包名称会被解析到 &PACK& 占位符中，你可以配置该占位符以便在 RPC 中使用
• 在 v2.0 中，整合包信息会被解析到 pack.name 和 pack.icon 占位符中，你可以配置这些占位符以便在 RPC 中使用

例如，模组会按照以下方式将整合包名称转换为 iconKey：

示例：All the Mods 7 会被解析为 allthemods7

注意：MultiMC 原生提供了 Icon Key 属性，模组会优先使用该属性，而不是根据整合包的显示名称进行转换

命令

CraftPresence 目前提供以下命令：

请注意以下事项：

• 命令必须以 /craftpresence 或 /cp 开头
• 在 v1.5.0 及更高版本中，这些命令只能通过配置界面中的命令 GUI 使用

• /cp compile "[expr]" – 通过 Starscript 测试占位符表达式的输出结果
• /cp search (type:typeName, [searchTerm], all) – 搜索可用于 Rich Presence 的有效占位符
• /cp reload – 重新加载模组数据
• /cp request – 查看加入请求信息
• /cp export – 查看模组数据的导出命令
• /cp view – 帮助命令，用于显示可查看和控制各种显示数据的命令
• /cp view placeholders – 显示所有可用于 RPC 的占位符
• /cp view currentData – 以文本形式显示当前的 RPC 数据
• /cp view assets (custom | all) – 显示所有可用的资源图标键
• /cp view dimensions – 显示所有可用的维度名称，需要启用 Show Current Dimension
• /cp view biomes – 显示所有可用的生物群系名称，需要启用 Show Current Biome
• /cp view servers – 显示所有可用的服务器地址，需要启用 Show Game State
• /cp view screens – 显示所有可用的 GUI 名称，需要启用 Per-Gui
• /cp view items – 显示所有可用的物品名称，需要启用 Per-Item
• /cp view entities – 显示所有可用的实体名称，需要启用 Per-Entity
• /cp reboot – 重启 RPC
• /cp shutdown – 关闭 RPC（可通过 /cp reboot 重新开启）
• /cp (help | ?) – 帮助命令，用于显示上述命令及其说明

按键绑定

CraftPresence 目前包含以下按键绑定：

注意事项：

• 在 v1.5.5 至 v1.8.0 中，按键绑定现在在配置界面的辅助功能设置中自定义，而不是在常规控制菜单中
• 在 v1.8.0 及以上版本中，按键绑定现在可以在配置界面的专用菜单或适用版本中的常规控制菜单中自定义

• Open Config Gui – 用于打开 CraftPresence 配置界面的按键绑定（默认：GRAVE/TILDE 键）

关于占位符和函数

在某些配置区域中，CraftPresence 提供了一些占位符和函数以简化操作：

请记住以下几点：

• 在 v2.0.0 中，占位符已被重写以兼容 Starscript
• 本节旧版列表可在此处查看
• 所有占位符、函数和代码表达式都必须用花括号包围（示例：{foo.bar}）
• 如果你需要在函数参数中将占位符与其他数据组合，请使用 getResult 函数
• 更多函数和标准变量可在 StandardLib 中找到

占位符列表

以下占位符可在 CraftPresence 中的任何位置使用：

• 通用占位符：
• general.brand – Minecraft 品牌标签
• general.icon – 默认显示图标
• general.mods – 当前模组文件夹中的模组数量
• general.title – Minecraft 标题标签
• general.version – Minecraft 版本标签
• general.protocol – Minecraft 版本协议标签
• 菜单事件占位符（加载和主菜单）：
• menu.message – 主菜单的显示数据（适用时）
• menu.icon – 主菜单的显示图标（适用时）
• 整合包占位符：
• pack.name – 当前检测到的整合包名称
• pack.icon – 当前检测到的整合包图标
• pack.type – 当前检测到的整合包类型
• 玩家占位符：
• player.name – 你的用户名
• player.uuid.short – 你的 UUID（精简格式）
• player.uuid.full – 你的 UUID（完整格式，如果 UUID 有效）
• player.icon – 你的玩家头像图标（适用时）
• player.position.x – 你当前的游戏内 X 坐标
• player.position.y – 你当前的游戏内 Y 坐标
• player.position.z – 你当前的游戏内 Z 坐标
• player.health.current – 你当前的游戏内生命值
• player.health.max – 你当前的游戏内最大生命值
• player.mode – 你当前的游戏模式
• 界面占位符：
• screen.message – 当前 GUI 界面的显示数据（适用时）
• screen.name – 当前 GUI 界面名称
• screen.icon – 当前 GUI 界面图标
• screen.default.icon – 默认 GUI 界面图标
• 生物群系占位符：
• biome.message – 当前生物群系的显示数据（在游戏中时）
• biome.name – 当前生物群系名称
• biome.identifier – 当前生物群系标识符
• biome.icon – 当前生物群系图标
• biome.default.icon – 默认生物群系图标
• 维度占位符：
• dimension.message – 游戏内当前维度的显示数据
• dimension.name – 当前维度名称
• dimension.identifier – 当前维度标识符
• dimension.icon – 当前维度图标
• dimension.default.icon – 默认维度图标
• 实体占位符：
• entity.default.icon – 默认实体图标
• entity.target.message – 当前目标实体的显示数据（如适用）
• entity.target.name – 当前目标实体的名称
• entity.target.icon – 当前目标实体的图标
• entity.riding.message – 当前骑乘实体的显示数据（如适用）
• entity.riding.name – 当前骑乘实体的名称
• entity.riding.icon – 当前骑乘实体的图标
• 世界占位符：
• world.difficulty – 当前世界的难度
• world.weather.name – 当前世界的天气名称
• world.name – 当前世界的名称
• world.type – 当前世界类型
• world.time.format_24 – 当前世界的游戏内时间（24 小时制）
• world.time.format_12 – 当前世界的游戏内时间（12 小时制）
• world.time.day – 当前世界的游戏内天数
• 服务器占位符：
• server.message – 游戏内当前服务器的显示数据
• server.icon – 当前服务器图标
• server.default.icon – 默认服务器图标
• server.players.current – 当前服务器玩家数量
• server.players.max – 当前服务器最大玩家数量
• server.address.full – （MP）当前服务器的原始地址
• server.address.short – （MP）格式化后的当前服务器地址
• server.name – （MP）当前服务器名称
• server.motd.raw – （MP）当前服务器的原始 MOTD
• server.minigame – （Realm）当前 Realm 小游戏名称
• server.type – （Realm）当前 Realm 世界类型
• 物品占位符：
• item.message.default – 默认物品显示数据（如适用）
• item.message.holding – 手持物品的显示数据（如适用）
• item.message.equipped – 已装备物品的显示数据（如适用）
• item.[slotId].name – 当前 slotId 物品名称
• item.[slotId].message – 当前 slotId 物品信息
• 集成 – Replay Mod：
• replaymod.time.current – 在视频渲染器中，获取 renderTimeTaken 字段
• replaymod.time.remaining – 在视频渲染器中，获取 renderTimeLeft 字段
• 额外占位符（高级用法）：
• _general.instance – Minecraft 实例
• _general.player – Minecraft 玩家实例
• _general.world – Minecraft 世界实例
• _config.instance – 模组配置实例
• _[moduleName].instance – CraftPresence 所拥有的某个模块实例
• 模块顺序：biome, dimension, entity, item, screen, server, <...>
• data.biome.instance – 玩家当前生物群系的实例
• data.biome.class – 玩家当前生物群系的类对象
• data.dimension.instance – 玩家当前所在维度的实例
• data.dimension.class – 玩家当前所在维度的类对象
• data.entity.target.instance – 当前目标实体的实例
• data.entity.target.class – 当前目标实体的类对象
• data.entity.riding.instance – 当前骑乘实体的实例
• data.entity.riding.class – 当前骑乘实体的类对象
• data.item.[slotId].instance – 当前slotId的实例
• data.item.[slotId].class – 当前slotId的类对象
• data.screen.instance – 当前GUI界面的实例
• data.server.motd.line_[number] – 获取server.motd.raw的指定行
• data.[moduleName].time – 模块更改其主要状态时的时间戳
• 使用data.general.time获取当前RPC起始时间戳

函数列表

以下函数可在CraftPresence中的任何位置使用：

• asIcon(input, whitespaceIndex ?: '') – 将字符串转换为有效且可接受的图标格式
• asIdentifier(target, formatToId ?: false, avoid ?: false) – 将标识符转换为格式正确且可解释的名称
• asProperWord(input, avoid ?: false, skipSymbolReplacement ?: false, caseCheckTimes ?: -1) – 将输入转换为正确可读的字符串
• capitalizeWords(input, timesToCheck ?: -1) – 将指定字符串中的单词首字母大写
• clampDouble(num, min, max) – 将指定数字限制在最小值和最大值之间
• clampFloat(num, min, max) – 将指定数字限制在最小值和最大值之间
• clampInt(num, min, max) – 将指定数字限制在最小值和最大值之间
• clampLong(num, min, max) – 将指定数字限制在最小值和最大值之间
• convertTime(input, originalPattern, newPattern) – 如有可能，将指定字符串转换为指定的日期格式
• convertTimeFormat(dateString, fromFormat, toFormat) – 将日期字符串从一种格式转换为另一种格式
• convertTimeZone(dateString, fromFormat, fromTimeZone, toTimeZone) – 将日期字符串从一个时区转换为另一个时区
• dateToEpochMilli(dateString, format, timeZone ?: null) – 将日期字符串转换为以毫秒为单位的纪元时间戳
• dateToEpochSecond(dateString, format, timeZone ?: null) – 将日期字符串转换为以秒为单位的纪元时间戳
• epochMilliToDate(epochMilli, format, timeZone ?: null) – 将纪元时间戳转换为给定格式和时区的日期字符串
• epochSecondToDate(epochSecond, format, timeZone ?: null) – 将纪元时间戳转换为给定格式和时区的日期字符串
• executeMethod(classToAccess=Object|String|Class, instance=Object, methodName=String, <parameterType, parameter>...) – 通过反射调用目标类中的指定方法
• format(input=String, args=Object...) – 使用指定的格式字符串和参数返回格式化字符串
• formatAddress(input, returnPort ?: false) – 根据输入格式化IP地址
• getArrayElement(content=Array, index) – 从指定内容中获取数组元素，若无法获取则返回null
• getAsset(input) – 从图标键中获取指定的DiscordAsset数据（如果存在）
• getAssetId(input) – 从指定的键中检索解析后的图标 ID（如果存在）
• getAssetKey(input) – 从指定的键中检索解析后的图标键（如果存在）
• getAssetType(input) – 从指定的键中检索解析后的图像类型（如果存在）
• getAssetUrl(input) – 从指定的键中检索解析后的图像 URL（如果存在）
• getClass(reference=Object|String) – 尝试通过字符串路径或对象引用检索类对象
• getComponent(data=DataComponentHolder, path=String) – （MC 1.20.5+）尝试检索指定路径的组件数据
• getCurrentTime() – 以 Instant 形式检索当前时间
• getElapsedMillis() – 以毫秒为单位检索经过的时间
• getElapsedNanos() – 以纳秒为单位检索经过的时间
• getElapsedSeconds() – 以秒为单位检索经过的时间
• getField(classToAccess=Object|String|Class, instance=Object, fieldName=String...) – 通过反射检索指定的字段
• getFields(classObj=Object|String|Class) – 检索类对象可用的字段名称
• getFirst(args) – 从指定参数中检索第一个非空字符串，否则返回 null
• getJsonElement(url|jsonString, path=Object...) – 从指定内容中检索 JSON 元素，无法检索时返回 null
• getMethods(classObj=Object|String|Class) – 检索类对象可用的方法名称
• getNamespace(input) – 检索标识符风格对象的命名空间部分
• getNbt(data=Entity|ItemStack, path=String...) – 尝试检索指定路径的 NBT 标签
• getOrDefault(target, alternative ?: '') – 如果主值非空则检索主值；否则使用备用值
• getPath(input) – 检索标识符风格对象的路径部分
• getResult(input) – 对指定输入执行递归转换
• hasField(classObj=Object|String|Class, fieldName) – 检索指定类是否包含指定的字段名称
• isColor(input) – 判断输入的字符串是否属于有效的颜色代码
• isCustomAsset(input) – 判断指定的图标键是否存在于自定义资源列表中
• isUuid(input) – 通过正则表达式检查指定字符串是否属于有效的 UUID
• isValidAsset(input) – 判断指定的图标键是否存在于当前客户端 ID 下
• isValidId(input) – 判断指定的客户端 ID 是否有效
• isWithinValue(value, min, max, contains_min ?: false, contains_max ?: false, check_sanity ?: true) – 判断指定值是否在指定范围内
• length(input) – 返回指定字符串的长度
• lerpDouble(num, min, max) – 在指定值之间进行线性插值
• lerpFloat(num, min, max) – 在指定值之间进行线性插值
• mcTranslate(input=String, args=Object...) – 根据当前语言检索到的游戏翻译，翻译未本地化的字符串
• minify(input, length) – 将字符串长度缩减至指定长度
• nullOrEmpty(input, allowWhitespace ?: false) – 判断字符串是否属于 NULL 或 EMPTY
• randomAsset() – 尝试从可用资源中检索一个随机图标键
• randomString(args) – 从指定参数中随机获取一个元素，并以字符串形式返回
• removeRepeatWords(input) – 移除输入字符串中的重复单词
• roundDouble(num, places ?: 0) – 尽可能将 Double 四舍五入到指定的小数位数
• snapToStep(num, valueStep) – 使用步长值，将指定值四舍五入到最接近的值
• split(input, regex, limit ?: 0) – 根据给定正则表达式的匹配结果拆分此字符串
• stripAllFormatting(input) – 移除输入字符串中的颜色和格式代码
• stripColors(input) – 移除输入字符串中的颜色代码
• stripFormatting(input) – 移除输入字符串中的格式代码
• timeFromEpochMilli(epochMilli) – 根据指定的纪元时间获取时间瞬间
• timeFromEpochSecond(epochSecond) – 根据指定的纪元时间获取时间瞬间
• timeFromString(dateString, fromFormat, fromTimeZone ?: null) – 将指定时区和格式的日期字符串转换为有效的时间瞬间实例
• timeToEpochMilli(data) – 根据指定参数获取自 Java 纪元以来的毫秒数
• timeToEpochSecond(data) – 根据指定参数获取自 Java 纪元以来的秒数
• timeToString(date, toFormat, toTimeZone ?: null) – 使用指定的时区和格式格式化日期字符串。
• toCamelCase(input) – 将字符串转换为有效且符合要求的驼峰命名格式
• translate(input=String, args=Object...) – 根据当前语言所获取的模组翻译，翻译未本地化的字符串

免责声明与其他信息

Minecraft 问题与其他构建信息

尽管已经尽力，但由于 Minecraft 代码库的现状，仍可能出现问题。

这些问题可能会影响后端的某些部分，并导致模组的部分功能无法正常工作。

基于此，请注意以下事项：

• Minecraft 1.16 及以上版本
• 随着游戏的更多部分转为数据驱动，某些模组数据在未进入世界之前将无法自动获取。
• 目前，生物群系模块和维度模块会受到此变化的影响，仅显示默认数据，额外数据需要先进行发现。
• Minecraft 1.15 及以下版本
• MC-112292：使用 v2 物品渲染器中的 RenderUtils#drawItemStack 方法时，使用特定渲染器的方块可能无法正常显示。
• 此外，仅在 1.15.x 版本中，使用此方法的界面可能会出现 z 轴层级问题
• Minecraft a1.1.2_01 及以下版本
• 在这些版本中，由于这些方法的逻辑缺失（最初在 Alpha 1.2.6 中实现），生物群系模块和维度模块使用默认数据作为占位。
• 其他问题
• 由于较早版本 Minecraft 存在混淆问题，使用模组的某些部分时可能会显示错误数据。
• 在这种情况下，生物群系模块和维度模块可能无法自动检测某些必要信息
• 作为备用方案，模组还设计了在首次发现相关生物群系或维度时添加可选模块数据的功能。
• 某些模块列表中的“添加新内容”选项也可以用来规避此问题。

此外，某些设置或 API 调用在不同的 MC 版本下可能会有不同表现。

图标请求

没有找到喜欢的图标，或者你是否有想要在默认客户端 ID 上添加或修改的图标建议？

如果是这样，你可以在我的问题追踪器中提交请求，并满足以下要求：

• 如果要添加来自某个维度的图标，请注明该维度所属模组的链接
• 这是因为必须使用特定的图标 ID，你可以从该模组中找到这些 ID，或者在进入维度后查看日志/聊天，因为 CraftPresence 会告诉你所需的 ID
• 请提供一张尺寸介于 512x512 和 1024x1024 之间的图标（前者为最低尺寸，后者为获得最佳质量的推荐尺寸）
• 也可以使用介于这些尺寸之间的图标，但最终质量可能不太理想
• 如果请求修改或移除默认客户端 ID 中的图标，请说明原因
• 主要是为了记录修改原因，以便日后查阅

此外，你还可以按照这份指南创建自己的图标集合

支持

需要我的某个模组的帮助，或希望提供反馈？

你可以通过以下方式联系我：

• 电子邮件
• CurseForge
• Discord ::

此外，该模组的代码库文档可在这里查看，
并且Wiki中还提供了更多指南

许可

本模组同时采用 MIT 许可证和 Apache 2.0 许可证

该项目目前在内部使用了以下依赖项：

• Starscript，由 MeteorDevelopment 提供
• DiscordIPC API，由 jagrosh 提供
• UniLib，由 CDAGaming 提供

Discord 服务条款

与其他 RPC 模组一样，本模组会使用你在游戏中的数据，将显示信息发送至第三方服务（在本例中为 Discord）。

有关为图标创建 Discord ID 的服务条款，可在这里查看

有关使用 Discord 服务的条款，也可以在这里查看