-------------------------------------------chinese

SunPlayer

假人玩家插件 · 支持 Paper / Folia 1.21.11

在你的服务器里凭空召唤一个“玩家”。他会挂机、会保持区块加载、能被推动、能被打、能掉落物品——就像一个真正的玩家一样。也可以把他摆成一个 NPC，玩家点一下就执行你设定的命令。

一个 jar 包，Paper 和 Folia 都能直接跑。无前置插件。

---

特性

• 真玩家体验 — 假人拥有真实的玩家行为：会被水冲走、被活塞推、会触发事件、能进计分板、能被 /ban
• 挂机不掉线 — 假人所在区块始终加载，种田、炼药、刷怪机不会停
• 完整动作 — 左键、右键、挥手、丢弃、跳跃、移动、转向、潜行、疾跑、换手、骑乘
• 点击式 NPC — 摆一个假人，玩家点他即可触发你指定的命令
• 正版皮肤 — 自动使用该名字对应的正版皮肤，取不到就用 Steve
• 不抢号 — 假人使用独立的服务端名字，与同名真人完全隔离
• 挂机限时 — 可限制每个假人的最长在线时间，到期自动删除
• 持久化 — 重启后自动复原，不用重新召唤

---

安装

1. 服务器需要 Paper 或 Folia 1.21.11 与 Java 21
2. 把 SunPlayer.jar 放进 plugins/ 文件夹
3. 重启服务器

---

快速开始

在游戏里执行：

/sunplayer Steve

一个叫 Steve 的假人就会出现在你脚下，使用你当前的游戏模式。

---

命令

命令	说明
/sunplayer <名字>	在你站的位置生成假人
/sunplayer <名字> <动作>	指挥假人做事
/sunplayer <名字> remove	让假人下线（重启后自动回来）
/sunplayer <名字> kill	彻底删除假人（含存档）
/sunplayer <名字> renew	重置挂机计时
/sunplayer list	查看所有在线假人与 NPC
/sunplayer reload	重载配置文件
/sunplayer revive	恢复未成功上线的假人

命令里只写名字本身即可，不用管前缀。

---

动作

动作	写法
右键 / 使用	use [once|continuous|interval <秒>]
左键 / 攻击	attack [once|continuous|interval <秒>]
挥手	swing [once|continuous|interval <秒>]
丢弃物品	drop [once|continuous|interval <秒>] [mainhand|offhand|<0-40>]
丢整组	dropstack
跳跃	jump
移动	move <forward|backward|left|right>
视角	look <yaw> <pitch>
转身	turn <left|right|back>
潜行 / 站起	sneak / unsneak
疾跑 / 停止疾跑	sprint / unsprint
停止所有动作	stop
切换快捷栏	hotbar <0-8>
交换主副手	swaphands
骑乘 / 下坐骑	mount / dismount

示例：

/sunplayer Steve
/sunplayer Steve attack continuous
/sunplayer Steve move forward
/sunplayer Steve stop

---

NPC 模式

把假人摆成 NPC，玩家点击时执行命令：

/sunplayer <名字> --npcmode --command <命令> [参数...]

参数	说明	默认
--npcmode	开启 NPC 模式（必需）	—
--command <命令,命令>	点击时执行的命令，逗号分隔	无
--left / --right / --both	哪种点击触发	--both
--look	始终面向最近的玩家	关
--look-range <格>	面向距离	8
--cooldown <tick>	同一玩家的点击冷却	10
--as-console	用控制台权限执行命令	关

示例：

/sunplayer Merchant --npcmode --command tell @s 欢迎光临,title @s title {"text":"商店"} --look
/sunplayer Guard --npcmode --left --command effect give @s minecraft:slowness 5 1

命令里的 @s 指向点击者本人，坐标与朝向也是他的。

NPC 不会移动、不会受伤、不占玩家位，参数创建后不可修改，要改请先 kill 再重建。

---

挂机限时

在 config.yml 中限制假人的最长挂机时间：

auto-remove:
  minutes: 120        # 最多挂 2 小时，0 = 关闭
  warn-minutes: 1     # 删除前 1 分钟提醒主人

• 每个假人独立计时，重启后继续计时
• 快到期时会私聊创建者，并附带可点击的 renew 续时链接
• 到期后假人会被彻底删除，重启也不会复活
• NPC 不受此限制

---

权限

权限	默认	作用
sunplayer.use	所有人	生成假人、发送动作、remove、kill、renew、list
sunplayer.npc	仅 OP	使用 NPC 模式及全部 NPC 参数
sunplayer.admin	仅 OP	以上全部，并可给别人的假人续时、重载配置

---

配置

max-fake-players: 20   # 全服假人上限
view-distance: 2       # 假人视距（区块）

naming:
  fake-prefix: "Bot_"  # 假人服务端名字前缀

auto-remove:
  minutes: 0           # 假人最多挂几分钟，0 = 关闭
  warn-minutes: 1      # 删除前几分钟提醒主人

compat:
  prevent-plugin-kicks: true   # 防止其他插件误踢假人
  authme-force-login: true     # 安装 AuthMe 时自动免登录
  remove-on-death: true        # 假人被打死后自动删除

改完配置执行 /sunplayer reload 即可生效，在线假人不受影响。

---

实用小贴士

• 假人占玩家位，NPC 不占。max-fake-players 建议按「服务器总人数 − 预期真人数」来设置
• view-distance 建议设为 2，可显著降低内存占用
• 关闭正版验证（online-mode=false）的服务器也能正常使用
• 假人不加载玩家背包与成就数据，每次生成都是干净的新玩家

---

常见问题

重启后假人没回来？ 执行 /sunplayer list，底部会列出未恢复的假人名字，再执行 /sunplayer revive 重试即可。

假人会和同名真人冲突吗？ 不会。假人在服务端有独立名字，与同名真人完全隔离。

---

-------------------------------------------english

SunPlayer

Fake player plugin · Works on Paper & Folia 1.21.11

Summon a real “player” on your server. They can idle, keep chunks loaded, be pushed around, take damage, drop items — just like an actual player. You can also place one as an NPC that runs commands when players click it.

One jar. Works on both Paper and Folia. No dependencies.

---

Features

• Real player behavior — fake players can be pushed by pistons, washed away by water, trigger events, appear on scoreboards, and even be /banned
• Chunk keeping — chunks around fake players stay loaded, so farms, brewing stands, and mob grinders keep running
• Full action set — left-click, right-click, swing, drop, jump, move, turn, sneak, sprint, swap hands, ride
• Clickable NPCs — place a fake player as an NPC and run your commands when players click it
• Official skins — automatically uses the Mojang skin for that name, or Steve if unavailable
• No account conflicts — fake players use isolated server-side names, so they never steal inventories or kick real players with the same name
• Idle time limit — optionally limit how long each fake player can stay online, then remove it automatically
• Persistence — fake players come back automatically after a restart

---

Installation

1. You need Paper or Folia 1.21.11 and Java 21
2. Put SunPlayer.jar into the plugins/ folder
3. Restart the server

---

Quick Start

Run this in game:

/sunplayer Steve

A fake player named Steve will appear at your feet, using your current game mode.

---

Commands

Command	Description
/sunplayer <name>	Spawn a fake player at your position
/sunplayer <name> <action>	Make the fake player do something
/sunplayer <name> remove	Take the fake player offline (returns after restart)
/sunplayer <name> kill	Permanently delete the fake player and its data
/sunplayer <name> renew	Reset the idle timer
/sunplayer list	List online fake players and NPCs
/sunplayer reload	Reload the config
/sunplayer revive	Restore fake players that failed to come online

Use the bare name in commands. No prefix needed.

---

Actions

Action	Syntax
Right-click / use	use [once|continuous|interval <n>]
Left-click / attack	attack [once|continuous|interval <n>]
Swing	swing [once|continuous|interval <n>]
Drop item	drop [once|continuous|interval <n>] [mainhand|offhand|<0-40>]
Drop stack	dropstack
Jump	jump
Move	move <forward|backward|left|right>
Look	look <yaw> <pitch>
Turn	turn <left|right|back>
Sneak / stand	sneak / unsneak
Sprint / stop sprinting	sprint / unsprint
Stop all actions	stop
Hotbar slot	hotbar <0-8>
Swap hands	swaphands
Mount / dismount	mount / dismount

Examples:

/sunplayer Steve
/sunplayer Steve attack continuous
/sunplayer Steve move forward
/sunplayer Steve stop

---

NPC Mode

Place a fake player as an NPC that runs commands when clicked:

/sunplayer <name> --npcmode --command <command> [options...]

Option	Description	Default
--npcmode	Enable NPC mode (required)	—
--command <cmd,cmd>	Commands to run on click, separated by commas	None
--left / --right / --both	Which click triggers the commands	--both
--look	Always face the nearest player	Off
--look-range <blocks>	Facing range	8
--cooldown <ticks>	Per-player click cooldown	10
--as-console	Run commands with console permission	Off

Examples:

/sunplayer Merchant --npcmode --command tell @s Welcome,title @s title {"text":"Shop"} --look
/sunplayer Guard --npcmode --left --command effect give @s minecraft:slowness 5 1

In commands, @s refers to the player who clicked. Coordinates and rotation also come from that player.

NPCs do not move, cannot be damaged, and do not take up player slots. NPC options cannot be changed after creation — use kill and recreate it if you need different settings.

---

Idle Time Limit

Limit how long fake players can stay online in config.yml:

auto-remove:
  minutes: 120        # Max idle time in minutes, 0 = disabled
  warn-minutes: 1     # Warn the owner this many minutes before removal

• Each fake player is timed independently; the timer continues across restarts
• The owner gets a private warning before removal, with a clickable renew command
• When time runs out, the fake player is permanently deleted and will not return after restart
• NPCs are decorative and are not affected

---

Permissions

Permission	Default	Description
sunplayer.use	Everyone	Spawn fake players, send actions, remove, kill, renew, list
sunplayer.npc	OP only	Use NPC mode and all NPC options
sunplayer.admin	OP only	Everything above, plus renewing other players’ fake players and reloading config

---

Configuration

max-fake-players: 20   # Global fake player limit
view-distance: 2       # Fake player view distance in chunks

naming:
  fake-prefix: "Bot_"  # Server-side name prefix for fake players

auto-remove:
  minutes: 0           # Max idle time in minutes, 0 = disabled
  warn-minutes: 1      # Warn the owner this many minutes before removal

compat:
  prevent-plugin-kicks: true   # Prevent other plugins from kicking fake players
  authme-force-login: true     # Auto-login when AuthMe is installed
  remove-on-death: true        # Remove fake players automatically when killed

After editing the config, run /sunplayer reload. Online fake players are not affected.

---

Tips

• Fake players take up player slots; NPCs do not. Set max-fake-players based on your total slots minus expected real players
• Set view-distance to 2 to save a lot of memory
• Works on servers with online-mode=false as well
• Fake players do not load player inventories or advancements; each spawn is a clean new player

---

FAQ

A fake player did not return after restart. What should I do? Run /sunplayer list. The bottom of the list shows fake players that have data but are not online. Then run /sunplayer revive to retry.

Will a fake player conflict with a real player using the same name? No. Fake players use isolated server-side names and are fully separated from real players.

---