Puppets

作者：azerbaiGH

一款适用于开发者、创作者和建筑师，且真正能用的假玩家模组。

模组 Fabric Forge NeoForge 实用服务器工具附属

介绍

介绍由机器翻译自 CurseForge 原页面，仅供参考。

木偶

由你操控的替身玩家，可在自己的世界里测试任何需要多名玩家的内容。

木偶会以真实玩家的身份加入你的世界或服务器。它会显示在玩家列表中、受到伤害、需要呼吸、会饿、能乘坐载具，并会被计入队伍、权限以及所有其他以玩家为对象的机制。你可以命令它行动、录下自己的操作并让它重播、为它编写脚本，也可以接管它并用自己的按键操控。

Puppets 支持：

Minecraft 版本	加载器
1.20.1	Fabric（需要 Fabric API）、Forge
1.21.1	Fabric（需要 Fabric API）、Forge、NeoForge
1.21.11	Fabric（需要 Fabric API）、Forge、NeoForge
26.3	Fabric（需要 Fabric API）、NeoForge

只需在服务器端（或你的单人游戏世界）安装。若要使用菜单和控制附身功能，你也需要在自己的游戏中安装。

入门指南

单人游戏中，使用允许作弊开启局域网。服务器中，你需要拥有管理员权限。
按O，或输入/puppet menu。如果你的游戏里没有安装 Puppets，请使用指令；/puppet help会列出基本指令，点击任意一行即可执行。
输入名称并按下生成。在列表中选择木偶，再使用按钮。将鼠标悬停在按钮上可查看其功能和对应发送的指令。

木偶能做什么

每个动作都是/puppet <name> <action>。/puppet all <action>会对所有木偶执行。/puppet group <prefix> <action>会对所有名称以该前缀开头的木偶执行。

动作	功能
`move forward\\|back\\|left\\|right\\|stop`	持续行走，直到收到停止指令
`jump\\|sneak\\|sprint on\\|off`	按住按键（`jumpevery <ticks>`则是点按）
`look <yaw> <pitch>`、`look north\\|south\\|east\\|west\\|up\\|down`、`lookat <x y z>`、`turn left\\|right\\|back`	转向
`leftclick once\\|hold\\|every <ticks>\\|stop`	鼠标左键。按住时，会以生存模式速度连续挖掘方块，或攻击面前的目标
`rightclick once\\|hold\\|every <ticks>\\|stop`	鼠标右键。依次使用面前的实体、方块，然后是物品
`use`、`useblock [x y z face]`、`useentity`、`attack`、`mine`、`release`	对一个目标点击一次。`release`会松开拉开的弓，或停止进食
`slot <1-9>`、`swap`、`drop [one\\|stack\\|offhand\\|everything] [every <ticks>]`	快捷栏和手持物品
`inventory`	为你打开它的物品栏，让你给予或取走物品。你也可以潜行并右键点击它
`copygear`	复制你携带和穿戴的所有物品
`click <slot> [button] [mode]`、`button <id>`、`trade <n>`、`close`、`sign x y z front <line1\\|line2>`	操作已打开的界面，例如箱子、机器或村民交易界面
`mount [entity]`、`dismount`	乘坐最近的船、马、矿车或载具
`follow [player\\|me]`、`goto <x y z>`、`wander [radius]`、`guard [radius]`、`stay`	自动寻路。它会直线行走、跳过台阶并游泳。`guard`会攻击所在位置附近的怪物，然后返回原位
`skin <player>\\|none`	穿上任意真实玩家的皮肤，并在重启后保留
`possess`	你来操控它：你的按键和鼠标会控制它的行动，并通过它的视角观察。O或`/puppet release`可解除控制。需要在你的游戏中安装 Puppets
`run <command>`	以它的身份执行指令（`run say hi`、`run give @s bread`）
`say <text>`、`respawn`、`kill`、`wake`、`remove`	说话、复活、死亡、起床、离开
`status`、`check health\\|air\\|food\\|x\\|y\\|z <op> <value>`	查看它正在做什么。`check`条件为真时返回 1，可用于脚本和命令方块
`play <script> [relative]`、`stop`	播放脚本。`stop`会松开所有按住的按键

生成木偶可按任意顺序接受选项：/puppet spawn Bob count 5 at 0 64 0 facing north in the_nether as survival skin jeb_。添加rejoin可让它在上次离开的位置回来。一次生成多个时，会依次命名为 Bob1 到 Bob5。

影身。 /puppet shadow会让你登出，并在你所在的位置生成一个使用你名字和皮肤、手持你所持物品的木偶。可用于挂机农场，或测试别人眼中的你。重新登录时，你会接替它。

重启。服务器停止时仍在场的 Puppets 木偶，会在服务器启动后于原地回来。

生物木偶

任何生物也能成为木偶：马、村民、僵尸、牛都可以。看着生物并运行/puppet mob take（或/puppet mob take @e[type=horse,limit=1,sort=nearest] as Star），也可以在菜单的收服我看到的生物按钮中操作，该按钮位于生物页面。成为木偶期间，生物会停止自主行动（闲逛、逃跑、工作、狩猎），转而听从指令：

动作	功能
`move forward\\|back\\|left\\|right\\|stop`、`jump [on\\|off]`、`look`、`turn`、`lookat x y z`	像玩家木偶一样行走和观察
`goto x y z`、`come`、`follow [me\\|player\\|mob]`、`wander [radius]`、`stay`	使用自己的寻路能力移动
`attack [nearest\\|player\\|mob]`	会战斗的生物会攻击（骷髅会射箭）
`mount`、`dismount`	乘坐最近的可乘坐目标
`possess`	用你自己的按键操控；右键点击会执行该生物种类对应的动作。O可解除控制
`play <script> [relative]`、`stop`	脚本和录制内容也可用于生物
`ai on\\|off`	让生物恢复自主行动，同时仍保留木偶身份
`letgo`	恢复为普通生物

部分种类可执行的专属动作，均符合其原本能力：马可以jump high和rear；农民村民可以harvest和plant（从其物品栏中取出种子）；驯服的宠物可以sit和stand；绵羊可以graze；苦力怕可以ignite；末影人可以pickup和place。

不受限制（/puppet mob Bessie unrestricted on）可以解除所有限制：任何生物都可以place <block>、break、fly on、say <text>、speed <n>、tp、攻击目标，还能在你曾到过的地方精确重播录制内容。只需一条指令，就能让牛学会盖房子。

录制与脚本

运行/puppet record start myroute（或按下录制我的操作），然后亲自完成操作。你可以行走、建造、打开箱子、操作机器、驾驶、射击。完成后运行/puppet record stop，任何木偶都能通过/puppet Bob play myroute重播录制内容。添加relative可让它从 Bob 所在的位置开始。

游戏发送给服务器的所有操作都会逐字节录入，包括模组自己的按键和按钮（载具按键、枪械扳机、机器按钮）。因此，Puppets 即使不认识某个模组，录制内容也能照样使用。仅用于获取显示信息的请求（Jade、Xaero、JEI）不会录入。

脚本是服务器上puppets/scripts/目录中的文本文件，每行一项操作。模组自带的example_脚本包括：

# Walks a square, then waits to be told
repeat 4
  move forward
  wait 1s
  move stop
  turn right
end
goto ~5 ~ ~          # ~ is where the puppet is
waituntil idle       # until it gets there
@Alice say Bob's back!
say Done

行内容	含义
任意动作	同上，但不需要`/puppet <name>`
`wait 20wait 3s`	暂停，单位为游戏刻（每秒 20 刻）或秒
`repeat 3` … `end`、`loop` … `end`	重复（`loop`会一直重复，直到脚本停止）
`waituntil idle`、`waituntil health < 10`	等待，直到它完成行走或挖掘，或某个条件成立
`@Alice <action>`	由另一个木偶执行，可用一个脚本指挥多个木偶
`log <text>`、`stop`、`# comment`

无法执行的行会被跳过，并记录为PUPPET_SCRIPT_LINE_FAILED。不会导致服务器崩溃。

模组

录制回放任何模组自身的网络包。少数模组还提供可手动编写的动作：

Superb Warfare： sbw forward\|back\|left\|right\|space\|shift\|ctrl\|flares\|fire\|none 持有载具按键
TACZ： tacz draw\|shoot\|reload\|aim\|unaim\|fireselect\|melee\|bolt
Trinkets（Fabric）和 Curios（Forge、NeoForge）：equip 将手持物品穿戴到第一个可用的空闲槽位
Rackcraft： 喷气背包和零重力推进跟随 jump 和 sneak

已使用 Rackcraft 机器、机械动力（扳手）、农夫乐事（砧板）、旅行者背包、Artifacts、TACZ、Superb Warfare 以及 300 模组的 Rackcraft Expanded 整合包进行测试。

面向服主

puppets/config.json 会在每项设置旁进行说明：

设置	默认值
`rejoinAfterRestart`	true	重启后，之前开启的傀儡会重新出现
`maxPuppets`	50	同时存在的最大数量（0：无限制）
`permissionLevel`	2	谁可以使用 `/puppet`（2：管理员）
`shadow`	true	玩家是否可以留下影子

傀儡使用基于其名称的离线模式 UUID，因此永远不会与真实账户冲突。皮肤来自 Mojang 的公开档案服务，并缓存在 puppets/skins.json 中。

面向开发者

ServerPlayerEntity bob = PuppetsApi.spawn(server, "Bob", world, new Vec3d(0, 64, 0));
PuppetsApi.act(server, "Bob", "move forward");        // any action, as its words
PuppetsApi.act(server, "Bob", "play example_square");
boolean isPuppet = PuppetsApi.isPuppet(player);
PuppetsApi.remove(server, "Bob");

示例使用的是 1.20.1 和 1.21.1 的名称。在 1.21.11 和 26.3 上，它们是 ServerPlayer 和 Vec3。

傀儡是普通的服务器玩家，因此任何对玩家有效的功能对它也有效。对于自动化测试，check 行（日志中的 PUPPET_CHECK ... true|false）可与命令运行器配对。Rackcraft DevTools 的 assert puppet Bob check air > 0 就是其中之一。脚本会记录 PUPPET_SCRIPT DONE、PUPPET_ARRIVED 和 PUPPET_LOG 行。

关于你自己的动作和行为，请参阅 addon-template/：一个可供复制的示例附加包，包含一个“wave”动作、一个“circle”行为和一个加入监听器。它通过 puppets Fabric 入口点注册，或在 Forge 和 NeoForge 上通过 META-INF/services 文件注册。

从各自的文件夹构建每个 Minecraft 版本：cd 1.20.1 && ./gradlew build（jar 位于 fabric/build/libs 和 forge/build/libs）、cd 1.21.1 && ./gradlew build 或 cd 1.21.11 && ./gradlew build（Fabric、Forge 和 NeoForge），或 cd 26.3 && ./gradlew build（Fabric 和 NeoForge）。使用 Java 25 构建。tools/ingame_basic.txt 是每次构建都会通过的的游戏内测试。