Grasscutter 命令实践手册：7 个高频场景与 3 步自定义扩展

Grasscutter 命令实践手册：7 个高频场景与 3 步自定义扩展

【免费下载链接】GrasscutterA server software reimplementation for a certain anime game.项目地址: https://gitcode.com/GitHub_Trending/gr/Grasscutter

Grasscutter 命令是私服管理员每天打交道最多的东西：给角色发满命、把玩家扔到指定坐标、封掉捣乱的号，甚至给服务器加一条只属于自己的指令。读完这篇，你会知道每条命令要填什么参数、谁有资格用哪条命令、报错时去哪儿查，最后还能自己动手写一个新命令。

第一步：用 /help 确认你能用哪些命令

在开始之前先搞清楚一件事：Grasscutter 的命令分两个入口——游戏内聊天框和服务器控制台（就是你运行服务器的那个终端）。控制台输入的命令不受任何权限限制，而游戏内输入的命令会先过一道权限检查。

打开权限清单最简单的方式就是：

/help

这个命令只会列出你当前账号有权使用的命令，每条都带上用法示例、别名和所需的权限节点。想看某一条的细节：

/help give

权限的本质是一串字符串（叫权限节点），保存在账号数据里，规则很简单：

• 节点为空 = 谁都能用（比如/help、/kick对自己操作的部分）
• *= 通配一切（通过控制台account create建出来的账号会自动带上）
• 支持通配匹配，比如player.*覆盖所有player.开头的节点
• -xxx前缀表示显式拒绝，优先级高于通配
• 普通账号还有一组内置的默认节点，所以不是所有命令都对玩家关闭

几个高频命令对应的权限节点如下（第一个列是"对自己用"，第二个列是"对别人用"）：

🎯 注意这些前缀只是命令作者的命名习惯，不是内置"角色"。服务器里不存在叫admin的等级，有的只是你账号里那串节点列表。

如何一步给玩家开权限

/permission命令本身要求你拥有permission节点，操作对象必须是一个玩家。它的子命令只有四个：add、remove、clear、list。

先锁定目标，再开权限：

/target @123456 /permission add player.give

之后这条会话里所有命令都默认作用于 123456。也可以一条搞定：/permission @123456 add player.give。想看他现在有什么，用/permission list；收回就remove，清空就clear。

💡 小技巧：@后面填 UID 或账号名都行，目标解析时两者都会查。

一行命令发角色、武器和圣遗物

/give（别名g、item、giveitem）是出场率最高的命令，参数顺序不固定，靠前缀区分：lv等级、r精炼、x数量、c命座、sl天赋等级。

发一个 90 级满命、天赋 10 级的旅行者（角色 ID 也可以用 4 位短号，如 10002 代替 10000002）：

/give 10000002 lv90 c6 sl10

发一把 90 级 5 精炼武器：

/give 11502 lv90 r5 x1

圣遗物多一段参数：等级后跟主属性 ID，再跟若干"副属性 ID,次数"。这条会给你一套 20 级、主属性 1004、副属性 1012 洗 3 次、1022 洗 2 次的圣遗物：

/give 15001 lv20 1004 1012,3 1022,2

懒得一个个发？有四个关键词直接打包：

/give avatars lv90 c6 # 全部角色，默认满命 /give weapons lv90 r5 # 全部武器（每种最多 5 把） /give mats x999 # 全部材料，各 999 个 /give all lv90 # 上面三样全都要

给别人发东西时，记得检查自己有没有player.give.others这个节点，否则会收到权限提示。

如何用 tp 命令把玩家传送到指定坐标

传送语法是x y z加一个可选的场景 ID：

/tp 1148 1236 1905 10001

前三个数是坐标，最后一个是场景 ID，不写就留在当前场景。成功执行后你会收到包含昵称、坐标和场景 ID 的确认消息。

想把别人传走（而不是自己）？在参数里加一个@UID即可，它会顶掉默认目标：

/tp @123456 1148 1236 1905 10001

顺带把场景里最常用的两个小功能也说了：/weather可以接受天气数字 ID 和气候类型词（比如降雨类关键词），不带参数时查询当前天气；/heal和/killall这类保命、清怪命令对玩家自己开放，具体用法/help里都有。

管理员三件套：踢人、封号、建账号

这三条命令都是控制台友好型，前两条也支持游戏内使用（需要server.kick/server.ban节点）。

踢人最干净的一条：

/kick @123456

封禁接受两个可选参数：结束时间（Unix 时间戳）和原因。不传时间默认封到 2051190000（大约 2035 年，即永久）：

/ban @123456 2051190000 挂机刷资源

被封的账号会立刻掉线。解封是对称操作，用/unban。

/account是纯控制台命令，游戏里输入会被拒。建号一行：

account create testplayer 123456

新建账号会自动带上*节点，等于出厂就是全权限管理员。配套子命令还有delete（删账号）、list（列出所有账号，账号多时会跑一会儿）、resetpass（重置密码，需要在配置里先打开EXPERIMENTAL_RealPassword）。

一条命令是怎么执行到生效的

看懂下面这 6 步，前面所有"为什么提示权限不足""为什么要求目标在线"的报错你就都明白了：

1. 消息按空格切开，第一个词小写后当作标签，去命令表里查处理器（查不到会再试一遍别名表）
2. 扫描参数里的@UID：谁出现，命令作用对象就换成谁；@单独出现表示"不要目标"
3. 没有@时依次回退：你在聊天里@的人 →/target设过的目标 → 你自己（控制台则无默认目标）
4. 权限检查：先比对命令的permission节点；如果操作对象不是你，还要再过一道permissionTargeted节点
5. 校验目标约束：有的命令要求目标必须在线（如/give、/ban），有的要求必须离线
6. 调用处理器的execute执行，标注了threading = true的命令（如/give）会开线程跑，不卡主循环

调试时你还会在日志里看到命令被谁执行、带了什么参数——前提是配置里SERVER下的logCommands打开了，控制台和游戏内输入都会落日志。

三步写出一条自定义命令

整个系统就是"注解 + 接口 + 注册表"，扩一条命令不需要动框架：

1. 写命令类：实现CommandHandler接口，写一个execute方法。类上挂@Command注解，声明label（命令名）、aliases（别名）、usage（/help展示的用法）、permission/permissionTargeted（两个权限节点）、threading（是否异步跑）
2. 注册：把类放进项目里会被启动扫描自动注册；走插件的话，在你的Plugin子类onEnable()里调CommandMap.getInstance().registerCommand("mycommand", new MyCommand())手动登记
3. 发提示：execute里用CommandHandler.sendMessage/sendTranslatedMessage回话，参数解析失败时调sendUsageMessage把用法甩给玩家

权限、目标解析、@UID、在线检查这些全都白送，你只写业务逻辑。参考实现直接翻 src/main/java/emu/grasscutter/command/commands/ 里任何一个文件；插件侧的结构见 src/main/java/emu/grasscutter/plugin/，仓库根目录的plugin-schema.json是插件元数据的格式说明。

常见报错往哪儿查

再就是翻日志：确认logCommands已开启，找到那行Command used by ...，参数原样都在。版本与命令的对应关系以源码为准，最新状态看 src/main/java/emu/grasscutter/command/ 目录，更多上手内容在 docs/README_zh-CN.md，想给社区加功能可以读一下 CONTRIBUTING.md。

把/help、/give、/tp这三条练熟，日常私服管理基本就够用了；剩下的命令都遵循同一套"目标 + 权限节点"的规矩，照着/help的输出抄参数就行。

【免费下载链接】GrasscutterA server software reimplementation for a certain anime game.项目地址: https://gitcode.com/GitHub_Trending/gr/Grasscutter