从入门到精通：Grasscutter命令系统完全指南

Grasscutter命令系统是服务器管理的核心工具，提供了从基础运维到高级玩家管理的全方位功能。本文将系统介绍命令架构、权限控制、常用指令及实战案例，帮助管理员和玩家快速掌握这一强大工具集。

命令系统架构解析

Grasscutter的命令系统采用注解驱动设计，通过模块化结构实现命令注册、权限验证和执行逻辑的分离。核心组件位于src/main/java/emu/grasscutter/command目录，主要包含：

• 命令接口层：Command.java定义命令元数据注解，包括标签、用法、权限要求等属性
• 执行处理层：CommandHandler.java提供消息发送、翻译和用法生成等基础功能
• 权限控制层：DefaultPermissionHandler.java实现基于角色的权限验证
• 命令注册表：CommandMap.java管理所有命令的注册与查找

命令生命周期

sequenceDiagram
    participant 玩家/控制台
    participant CommandMap
    participant PermissionHandler
    participant CommandHandler
    
    玩家/控制台->>CommandMap: 输入命令(如/give)
    CommandMap->>CommandMap: 解析命令标签
    CommandMap->>PermissionHandler: 验证权限
    PermissionHandler-->>CommandMap: 返回权限检查结果
    CommandMap->>CommandHandler: 调用对应命令处理器
    CommandHandler->>CommandHandler: 执行命令逻辑
    CommandHandler-->>玩家/控制台: 返回执行结果

权限控制体系

Grasscutter采用多级权限控制模型，确保命令使用安全。权限系统核心配置通过PermissionCommand.java实现，支持以下权限粒度：

权限等级划分

权限前缀	适用对象	典型命令
player.	普通玩家	/tp, /heal
admin.	管理员	/ban, /kick
server.	服务器维护	/stop, /reload

权限管理示例

授予玩家管理员权限：

/permission set <玩家UID> admin

查看当前权限配置：

/permission list <玩家UID>

核心命令实战指南

帮助命令系统

HelpCommand.java提供交互式命令查询功能，支持两种使用方式：

• 查看所有可用命令：

  /help
  

• 查看特定命令详情：

  /help give
  

命令输出包含：标签、描述、用法示例、别名和权限要求等完整信息，是学习命令的首要工具。

物品给予系统

GiveCommand.java是最常用的管理命令之一，支持物品、角色、武器和圣遗物的精确给予。其强大之处在于支持丰富的参数控制：

基础用法

给予角色（如旅行者）：

/give 10000002 lv90 c6 sl10

给予武器（如天空之刃）：

/give 11502 lv90 r5 x1

高级圣遗物定制

/give 15001 lv20 1004 1012,3 1022,2

• 15001：圣遗物ID
• lv20：等级20
• 1004：主属性ID（攻击百分比）
• 1012,3：副属性ID及强化次数（暴击率，强化3次）
• 1022,2：副属性ID及强化次数（攻击力，强化2次）

批量给予

一次性给予全部角色：

/give avatars lv90 c6

给予全部材料：

/give mats x999

场景管理命令

Grasscutter提供完整的场景控制命令集，包括：

传送系统

TeleportCommand.java支持多种传送方式：

• 坐标传送：/tp x y z
• 区域传送：/tp domain 1001（进入风本）
• 玩家传送：/tp @<UID>（传送到指定玩家位置）

天气控制

WeatherCommand.java可调整场景天气：

/weather rain 5

• rain：天气类型（rain/snow/fog等）
• 5：强度等级（1-10）

玩家管理命令

管理员可通过以下命令维护服务器秩序：

• 封禁玩家：BanCommand.java

  /ban <UID> 30d "作弊行为"
  

• 踢出玩家：KickCommand.java

  /kick <UID> "异常数据"
  

• 账号管理：AccountCommand.java

  /account create <用户名> <密码>
  

自定义命令开发

Grasscutter支持通过插件系统扩展命令功能。开发新命令需实现以下步骤：

1. 创建命令类

@Command(
    label = "mycommand",
    usage = {"[参数1] [参数2]"},
    permission = "player.mycommand",
    threading = true
)
public class MyCommand implements CommandHandler {
    @Override
    public void execute(Player sender, Player targetPlayer, List<String> args) {
        // 命令逻辑实现
        sendMessage(sender, "自定义命令执行成功");
    }
}

2. 注册命令

在插件初始化时注册命令：

CommandMap.getInstance().registerCommand("mycommand", new MyCommand());

3. 本地化支持

添加多语言支持，在语言文件中添加：

commands.mycommand.description=我的自定义命令
commands.mycommand.success=命令执行成功

常见问题解决

命令执行失败排查流程

1. 权限检查：确认执行者拥有足够权限，使用/permission check <命令>
2. 参数验证：通过/help <命令>核对参数格式
3. 日志分析：查看服务器日志文件，路径通常在logs/目录下
4. 版本兼容：确认使用的命令与服务器版本匹配，参考README.md中的版本说明

高级调试技巧

启用命令调试模式：

/debug command true

调试信息将输出到debug.log，包含命令解析过程和参数处理详情。

命令速查表

常用管理命令

命令	功能	权限要求
/list	列出在线玩家	admin.list
/reload	重载配置	server.reload
/announce	发送公告	admin.announce
/clear	清理玩家数据	admin.clear

玩家常用命令

命令	功能	示例
/heal	治疗角色	/heal
/killall	清除怪物	/killall
/coop	邀请联机	/coop
/weather	改变天气	/weather clear

总结与扩展

Grasscutter命令系统通过灵活的架构设计和丰富的功能实现，为服务器管理提供了强大支持。无论是日常运维还是特殊活动配置，命令系统都能满足各种场景需求。

官方文档：docs/README_zh-CN.md
命令源码目录：src/main/java/emu/grasscutter/command/commands
插件开发指南：CONTRIBUTING.md

掌握命令系统不仅能提高管理效率，还能通过自定义命令扩展服务器功能，创造独特的游戏体验。建议定期查看官方更新，及时了解新命令和功能改进。

提示：收藏本文档以便快速查阅，关注项目GitHub仓库获取最新更新。