Companion Tuanzi · 伴行团子

弹幕落下的地方，团子替你把远方的陪伴轻轻带进方块世界。
Where danmaku falls, a little companion carries the warmth of distant company into the blocky world.

Minecraft 26.1.2 · NeoForge 26.1.2.103 · Version v1.0.0 · English / 中文

English Version

✦ What Is This Mod?

Companion Tuanzi turns viewers from your livestream into little "Tuanzi" companions inside your Minecraft world.

Each Tuanzi follows the streamer it's bound to, displays its viewer's nickname, level, and intimacy above its head, and grows gradually through danmaku check-ins, interactions, feeding, and watching the stream.

✦ Main Features

• Live danmaku support — connects to Bilibili and Douyin livestream danmaku. The connector only receives danmaku; it never sends anything to the platform.
• Streamer binding & room switching — bind a streamer, switch rooms, toggle danmaku on/off, and hot-reload with /tuanzi reload.
• Viewer check-in & hatching — viewers use !签到 (check-in) to receive a Tuanzi egg, which hatches after accumulating enough valid watch activity.
• Safe & friendly companions — Tuanzi follows the streamer by default, does not attack, does not break blocks, does not push players, and can follow across dimensions.
• Rich interactions — pick up, put down, hug, pet, high-five, play, pick up items, warn of monsters, find items, light up the area, and more.
• Sleep & revive — when a viewer leaves, their Tuanzi goes to sleep; when they speak again, it wakes up. If it dies, it can be revived by paying the configured intimacy cost.
• Server-side data — viewer profiles, streamer bindings, room ownership, and Tuanzi entity bindings are all saved in the server data directory.

✦ Configuration

Config file location:

config/companion_tuanzi.toml

It is auto-generated on first launch. After editing, run:

/tuanzi reload

Level Formula

Level thresholds are calculated with the following formula, where n = target level - 1:

required intimacy = base + linear × n + quadratic × n²

Corresponding config in [level]:

[level]
base = 1
linear = 6
quadratic = 3
max = 20
health_per_level = 1
feed_health = 2

• max — the maximum level allowed by config. Even if a new level has no exclusive ability yet, viewers can still keep leveling up.
• health_per_level — HP added per level; base max HP is 10.
• feed_health — HP restored when the streamer feeds the Tuanzi once.

✦ Commands

/tuanzi bind
/tuanzi status
/tuanzi enable
/tuanzi disable
/tuanzi reload
/tuanzi room bili <room ID>
/tuanzi room dy <room ID>
/tuanzi test !签到
/tuanzi watch <viewer nickname> <minutes>

For the full list of subcommands, check the in-game /tuanzi prompt.
After a streamer is bound, danmaku sent while unbound will not create profiles, spawn Tuanzi, or add intimacy.

✦ Danmaku Commands

Common danmaku commands include:

!签到
!抱抱
!摸摸
!击掌
!玩耍
!查询
!回来
!加油

Interactions need to be confirmed by the streamer in-game.
Per-viewer command cooldown can be adjusted in the config — for testing, set interact.command_cooldown_seconds to 0.

✦ Data Location

By default, the server creates the following under the world directory:

companion_tuanzi/companions.json
companion_tuanzi/events.jsonl

You can use data.shared_data_dir to point multiple server instances at a shared data directory.

✦ Credits

• DyDanmaku — reference for Douyin livestream danmaku connection and protocol handling.
• Bilibili livestream danmaku — reference implementation provided by the user.

中文版本

✦ 这是个什么模组？

伴行团子把直播间里的观众化作 Minecraft 世界中的小团子。
团子会跟随绑定的主播行动，头顶显示观众昵称、等级与亲密度，并通过弹幕签到、互动、喂食和观看活动逐步成长。

✦ 主要功能

• 直播弹幕接入：支持 B 站直播与抖音直播弹幕。连接器只接收弹幕，不向平台发送内容。
• 主播绑定与房间切换：支持主播绑定、直播间切换、弹幕总开关，以及 /tuanzi reload 热重载。
• 签到与孵化：观众使用 !签到 获得团子蛋，累计有效观看活动后孵化。
• 安全友好的团子：团子默认跟随主播，不攻击、不破坏方块、不推挤玩家，并支持跨维度跟随。
• 丰富互动：支持抱起、放下、抱抱、摸摸、击掌、玩耍、捡取物品、怪物预警、找物品和点灯等互动或辅助能力。
• 休眠与复活：观众离开后团子进入休眠，重新发言后唤醒；死亡后需要支付配置的亲密度代价复活。
• 服务端数据：观众档案、主播绑定、房间归属和团子实体绑定保存在服务端数据目录中。

✦ 配置

配置文件位于：

config/companion_tuanzi.toml

配置文件首次启动时自动生成。修改后执行：

/tuanzi reload

等级公式

等级阈值由以下公式计算，其中 n = 目标等级 - 1：

所需亲密度 = base + linear × n + quadratic × n²

对应配置位于 [level]：

[level]
base = 1
linear = 6
quadratic = 3
max = 20
health_per_level = 1
feed_health = 2

• max：配置允许的最高等级。即使某个新等级暂时没有专属能力，观众仍可继续升级。
• health_per_level：每级增加的生命上限，基础生命上限为 10 点。
• feed_health：主播喂食一次恢复的生命点数。

✦ 常用指令

/tuanzi bind
/tuanzi status
/tuanzi enable
/tuanzi disable
/tuanzi reload
/tuanzi room bili <房间号>
/tuanzi room dy <房间号>
/tuanzi test !签到
/tuanzi watch <观众昵称> <分钟>

具体可用子命令以游戏内 /tuanzi 的提示为准。
主播绑定后，未绑定状态下的弹幕不会创建档案、生成团子或增加亲密度。

✦ 弹幕指令

常用弹幕指令包括：

!签到
!抱抱
!摸摸
!击掌
!玩耍
!查询
!回来
!加油

互动需要主播在游戏中确认。
同一观众的指令冷却可在配置中调整，测试时可将 interact.command_cooldown_seconds 设为 0。

✦ 数据位置

默认情况下，服务端会在世界目录下创建：

companion_tuanzi/companions.json
companion_tuanzi/events.jsonl

可以通过 data.shared_data_dir 指定多个服务端实例共享的数据目录。

✦ 鸣谢与参考

• DyDanmaku：抖音直播弹幕连接与协议处理参考。
• B 站直播弹幕：用户提供的参考实现。

弹幕落下的地方，团子替你把远方的陪伴轻轻带进方块世界。
Where danmaku falls, a little companion carries the warmth of distant company into the blocky world.