ACF Tab补全与自动帮助系统实战教程用Annotation Command Framework让插件命令体验脱胎换骨【免费下载链接】commandsJava Command Dispatch Framework - (Bukkit, Spigot, Paper, Sponge, Bungee, JDA, Velocity supported, generically usable anywhere)项目地址: https://gitcode.com/gh_mirrors/comm/commandsACFAnnotation Command Framework注解命令框架是一款支持 Bukkit、Spigot、Paper、Sponge、BungeeCord、JDA、Velocity 的 Java 命令框架。本教程聚焦它的两大体验杀手锏Tab 补全与自动帮助系统。你只需要在方法上加几行注解玩家就能享受按 Tab 自动提示参数、输入 /help 秒查命令手册的现代化命令体验彻底告别手写的 if-else 补全逻辑和手动拼的帮助文本。为什么你的插件命令需要 Tab 补全和自动帮助想象一下服务器里一个拥有 20 子命令的管理插件玩家想执行某个命令却要靠猜参数、背语法。没有补全和帮助的命令用户体验约等于盲打。ACF 的解法是把这两件事都抽象成了注解Tab 补全用CommandCompletion声明静态候选项或用前缀注册动态补全处理器自动帮助用HelpCommandDescription自动生成带语法提示的命令手册下面一步步实战。第一步把 ACF 加进你的插件克隆源码仓库或直接在项目中引用对应平台的构件Bukkit 用acf-bukkitPaper 用acf-paperBungee 用acf-bungeegit clone https://gitcode.com/gh_mirrors/comm/commands多平台插件可以同时引入多个平台模块。引入后核心只需两行代码注册命令管理器具体初始化方式因平台而异Paper 版还有渐进增强。Tab 补全实战一个注解搞定三种补全1. 静态补全候选值直接用|分隔最简单的方式是给参数写上固定的候选列表CommandCompletion(foo1|foo2|foo3)表示该参数按 Tab 时只提示这三个值。完整示例可以直接参考官方示例模块中的 SomeCommand.javaSubcommand(completions) CommandCompletion(* * test foo1|foo2|foo3) public void onTestCompletion(CommandSender sender, OnlinePlayer player, World world, String test, String foo1, TestEnum e) { ... }这一行注解的信息量非常大逐段拆解补全声明含义*通配默认补全第一个*按玩家类型自动匹配在线玩家test自定义动态补全处理器插件里手动注册返回 foobarfoo1\|foo2\|foo3静态候选列表未声明的枚举参数TestEnum框架自动收集枚举值FOOTEST1、BARTEST2作为补全2. 动态补全前缀调用补全处理器平台模块已内置了一批开箱即用的补全器。以 Bukkit 为例BukkitCommandCompletions.java 里注册了players—— 按输入前缀模糊匹配在线玩家且自动隐藏对发送者不可见的玩家worlds—— 当前世界列表核心模块还内置了range数字区间、timeunits时间单位等见 CommandCompletions.java3. 自定义补全处理器registerCompletion一行注册你的业务需要比如列出服务器里所有商店也能轻松接入。在插件启动时调用completions.registerCompletion(shops, c - shopManager.getShopNames());之后任何参数上写CommandCompletion(shops)即可。补全逻辑可以访问玩家的输入前缀c.getInput()、权限甚至配置还支持registerAsyncCompletion异步执行避免大列表卡顿主线程。 小技巧setDefaultCompletion(players, OnlinePlayer.class)可以把某类参数默认绑定补全器——以后所有OnlinePlayer类型参数哪怕不写任何注解也自动获得玩家名补全。Bukkit 模块已经为World、OnlinePlayer做好了这个绑定。自动帮助系统实战/help不再是干巴巴的列表ACF 的命令帮助是从你的注解里自动生成的Description成为命令描述Subcommand拼出语法树参数名变成占位符提示。你不需要手写一行帮助文本。用HelpCommand一键注册帮助子命令给任意方法加上 HelpCommand 注解它就同时成为默认入口、兜底处理器和一组子命令默认help|?|-help|-h|-?HelpCommand public void onHelp(CommandSender sender, CommandHelp help) { sender.sendMessage(help.getFullMessage()); }效果输入/mycmd或/mycmd help→ 显示该命令下所有子命令及描述输入/mycmd badsub子命令打错→ 自动回退显示帮助而不是报未知命令帮助内容自动只列出玩家有权限执行的命令让帮助说人话给每个命令补上DescriptionSubcommand(admin) CommandPermission(some.perm) Description(Test Admin Commands) public void onAdminCommand(Player player) { ... }Description的值会原样出现在帮助列表里配合CommandAlias还能给子命令起别名帮助页会自动把别名一并展示。多语言场景下帮助文本可走语言文件参考 languages/core/acf-core_en.properties中英环境各得其所。进阶让补全更智能的细节枚举零配置参数是 enum 时框架自动把所有枚举值作为补全候选甚至能省略注解见 SomeCommand.java 中的TestEnum参数嵌套子命令补全链Subcommand(testsub test1)这种多级子命令补全会逐级跟随玩家输入到哪一层就提示哪一层的选项可选参数补全Optional参数不填也能执行补全时也不会卡住帮助语法里会标注为可选平台自适应同一套注解在 Velocity、JDADiscord上一样能生成补全Discord 端表现为 slash command 风格的选择器总结体验升级清单 ✅能力你要写的代码玩家得到的体验静态补全一行CommandCompletion(a\|b)按 Tab 出固定候选动态补全registerCompletionxxx按 Tab 出实时数据玩家/世界/商店枚举补全零代码枚举值自动提示命令帮助HelpCommandDescription/help自动出带描述、带权限过滤的手册ACF 的核心思想就是把样板代码藏进注解。掌握 Tab 补全与自动帮助这两板斧后你的插件命令体验会像官方原版命令一样顺手。更多注解CommandPermission、Dependency、Values等可继续深入 core/src/main/java/co/aikar/commands/annotation/ 目录下的各注解源码或阅读 README.md 中的平台构件说明。【免费下载链接】commandsJava Command Dispatch Framework - (Bukkit, Spigot, Paper, Sponge, Bungee, JDA, Velocity supported, generically usable anywhere)项目地址: https://gitcode.com/gh_mirrors/comm/commands创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考