Skip to content

08 commands ​

0.26.0 变更

本章按 0.24.0 的 API 整理。0.26.0 中 api.client.command.HelpCommand 已移出 API(改为客户端内部实现),详见变更历史。

一句话定位:把 1.13+ 才有的 Brigadier 命令框架整套搬到 1.12.2 —— 事件里注册命令树、47 种参数类型、命令树网络同步与补全。

项值
模块 idcommands
Mavennet.ornithemc.osl-gen2:commands:0.1.0+mc14w28a-mc1.12.2
端双端(api.client 下的类型仅客户端存在)
版本0.1.0(1.12.2 构件为 0.1.0+mc14w28a-mc1.12.2)
依赖ploceus.dependOslModule('commands', '0.1.0')
传递依赖core, entrypoints, lifecycle-events, blockstates, blocks, items, entities, networking, text-components

1.12.2 的原版命令系统是 CommandRegistry + AbstractCommand(用 String[] args 手工解析),没有 ArgumentType、没有补全树、没有 CommandSourceStack。本模块把 Brigadier(com.mojang.brigadier)完整移植过来:用 CommandDispatcher 组命令树,用参数类型自动解析与补全,并把整棵命令树按玩家权限裁剪后同步给客户端。

模块本身分成三层:注册入口(ServerCommandEvents / ClientCommandEvents)、执行上下文(CommandSourceStack / ClientCommandSource)与 参数类型库(api.command.argument 下 47 个类型,覆盖 1.13 的全部原版参数)。原版那一套命令仍然可用,两者可以并存。

1.12.2 上的运行方式 ​

理解下面四点,后面的 API 就不会用错:

  1. 注册时机(服务端):服务端 CommandManager 构造完成(即原版命令全部注册完之后)时创建 dispatcher,并立刻触发 ServerCommandEvents.REGISTER_COMMANDS 与 REGISTER_LEGACY_COMMANDS。也就是说事件是在"服务器/世界启动"阶段触发的,监听器必须在 mod 初始化(entrypoint)时就注册好。
  2. 注册时机(客户端):客户端收到 handleLogin(连上服务器、进入世界)后创建客户端 dispatcher 并触发 ClientCommandEvents.REGISTER_COMMANDS;若你注册了至少一条客户端命令,框架会自动补上 /help。
  3. 执行优先级:服务端 CommandRegistry.run(CommandSource, String) 会先拿 Brigadier dispatcher 试一次;只有命令源是 CommandSourceBuilder(任何实体都实现了)且 dispatcher 认识该命令时才拦截,否则原样回落到原版命令。因此 /give、/tp 之类原版命令不在 Brigadier 树里,只有你自己注册的命令在。 客户端同理:以 / 开头的聊天会先由客户端 dispatcher 执行,认识就吃掉,不认识才发给服务端。
  4. 同步与补全:服务端在 PlayerManager.updatePermissions 之后把"该玩家看得见的命令树"序列化成自定义包发给客户端;原版补全包的结果会与 Brigadier 补全合并;需要服务端算的补全(SuggestionProviders.ASK_SERVER)走单独的自定义通道往返。

命令注册(服务端) ​

ServerCommands ​

Reference: net.ornithemc.osl.commands.api.server.ServerCommands

作用:服务端命令注册的工具类。真正的注册动作在 REGISTER_COMMANDS 监听器里做,这里只提供拿 dispatcher 与造节点 builder 的静态方法。

成员作用需要(参数 / 前置条件)返回
dispatcher()取当前服务端命令调度器在 REGISTER_COMMANDS 监听器内调用;服务端尚未启动(CommandManager 未构造)时内部字段还是 nullCommandDispatcher<CommandSourceStack>,未初始化时为 null
literal(String name)造一个字面量节点 builder(命令名 / 子命令名本身)name 不能含空格;返回的 builder 还要 .executes(...) 或 .then(...) 才算完整LiteralArgumentBuilder<CommandSourceStack>
argument(String name, ArgumentType<T> type)造一个必选参数节点 buildername 是参数名(后面 ctx.getArgument(name, …) 要用同名);type 用本模块参数类型或 Brigadier 自带的RequiredArgumentBuilder<CommandSourceStack, T>
ServerCommands.Selection(枚举)告诉监听器当前跑在什么服务端环境—见下
ServerCommands.BuildContext(接口)预留的构建上下文,目前是空接口—事件回调里传给你的实例永远非 null,但没有可调用成员

Selection 的取值与含义:

常量includesIntegrated()includesDedicated()说明
ALLtruetrue表示"两种环境都算"。框架自身不会传这个值,只在你自己的判断逻辑里用得到
INTEGRATEDtruefalse单人游戏的内置服务器;框架在 server.isDedicated() == false 时传入
DEDICATEDfalsetrue专用服务器;框架在 server.isDedicated() == true 时传入

典型用法(在 mod 的 init entrypoint 里挂监听器):

java
ServerCommandEvents.REGISTER_COMMANDS.register((commands, selection, context) -> {
    commands.register(ServerCommands.literal("example")
        .executes(ctx -> {
            ctx.getSource().sendSuccess(TextComponents.literal("ok"), false);
            return 1;
        }));
});

ServerCommandEvents ​

Reference: net.ornithemc.osl.commands.api.server.ServerCommandEvents

作用:服务端命令生命周期的唯一入口。两个事件分别在"原版命令注册完成之后"触发,是注册自定义命令的正确位置。

成员作用需要(参数 / 前置条件)返回
REGISTER_COMMANDSBrigadier 命令注册事件,类型 Event<RegisterCommandsListener>在 mod 初始化阶段调用 .register(listener);触发时 dispatcher 是新建的空树(原版命令不在里面)无(事件对象,注册后由框架调用)
REGISTER_LEGACY_COMMANDS原版 AbstractCommand 注册事件,类型 Event<RegisterLegacyCommandsListener>同上;回调拿到的 Consumer<Command> 就是原版 CommandRegistry::register无
ServerCommandEvents.RegisterCommandsListener(接口)前者要实现的回调实现 registerCommands(CommandDispatcher<CommandSourceStack> commands, ServerCommands.Selection selection, ServerCommands.BuildContext context)无(void)
ServerCommandEvents.RegisterLegacyCommandsListener(接口)后者要实现的回调实现 registerLegacyCommands(Consumer<Command> commands, ServerCommands.Selection selection, ServerCommands.BuildContext context)无(void)

命令注册(客户端,仅客户端) ​

ClientCommands ​

Reference: net.ornithemc.osl.commands.api.client.ClientCommands

作用:客户端命令注册的工具类。客户端命令只在客户端执行,框架在 LocalClientPlayerEntity.sendChat 里拦截以 / 开头的消息,客户端 dispatcher 认识就以客户端结果为准、不发给服务端。

成员作用需要(参数 / 前置条件)返回
dispatcher()取客户端命令调度器在 REGISTER_COMMANDS 监听器内或之后调用;未进入世界时为 nullCommandDispatcher<ClientCommandSource>,未初始化时为 null
literal(String name)造字面量节点 builder同服务端LiteralArgumentBuilder<ClientCommandSource>
argument(String name, ArgumentType<T> type)造必选参数节点 builder同服务端RequiredArgumentBuilder<ClientCommandSource, T>
ClientCommands.Selection(枚举)当前客户端处于什么环境—见下
ClientCommands.BuildContext(接口)预留的构建上下文,空接口—事件回调里传入,非 null

Selection 的取值:

常量includesSingleplayer()includesMultiplayer()说明
ALLtruetrue两者都算。框架自身不会传这个值
SINGLEPLAYERtruefalse内置服务器在跑(单人)时传入
MULTIPLAYERfalsetrue连的是远程服务器时传入

注意:客户端 dispatch 的返回值语义与 Brigadier 一致(1 表示成功执行);框架用"dispatcher 是否认识这条命令"来决定是否把消息继续发给服务端,所以你没法用"返回 0"来放弃执行、让服务端处理。

ClientCommandEvents ​

Reference: net.ornithemc.osl.commands.api.client.ClientCommandEvents

作用:客户端命令注册事件。触发时机是客户端完成登录(handleLogin 末尾),每次进入一个世界都会重新触发一次。

成员作用需要(参数 / 前置条件)返回
REGISTER_COMMANDS客户端命令注册事件,类型 Event<RegisterCommandsListener>在 ClientModInitializer 里 .register(listener)无
ClientCommandEvents.RegisterCommandsListener(接口)回调接口实现 registerCommands(CommandDispatcher<ClientCommandSource> commands, ClientCommands.Selection selection, ClientCommands.BuildContext context)无(void)

HelpCommand ​

Reference: net.ornithemc.osl.commands.api.client.command.HelpCommand

作用:/help [<命令>] 命令的实现。框架在客户端注册了至少一条命令后会自动调用 register,一般不需要你手动调用;这里公开出来是为了让你能在自己的 dispatcher 上复用它。

成员作用需要(参数 / 前置条件)返回
register(CommandDispatcher<ClientCommandSource> dispatcher)往给定 dispatcher 注册 help 字面量命令dispatcher 非 null;重复注册同名命令会抛 Brigadier 的 IllegalArgumentException无(void)

行为:不带参数时列出根节点的可用命令(调用 dispatcher.getSmartUsage);带 <命令> 时先解析该命令,取最后一个节点再列它的用法;解析不出任何节点时抛 SimpleCommandExceptionType(语言键 commands.help.failed)。每条结果通过 ClientCommandSource.sendSuccess 以 /<用法> 形式输出,返回值是输出的条数。

命令源与执行上下文 ​

CommandSourceStack ​

Reference: net.ornithemc.osl.commands.api.server.command.CommandSourceStack

作用:服务端的"命令执行上下文",对应 1.13 的 ServerCommandSource:把命令源、服务器、维度、实体、位置、朝向、锚点、权限等级、静默标志、结果回调打包在一起。所有 with… 方法都是不可变的,返回新实例(值没变时返回 this)。

成员作用需要(参数 / 前置条件)返回
new CommandSourceStack(CommandSource source, MinecraftServer server, ServerWorld world, Entity entity, Vec3d pos, Vec2f rotation, String name, Text displayName, int permissions)公开构造:displayName 传原版 Text 版本各参数非 null(entity 可以为 null,表示"非实体源"如命令方块/控制台);displayName 会被 TextComponents.resolve 转成 TextComponent新实例,锚点默认 Anchor.FEET、非静默、回调为空
new CommandSourceStack(…, TextComponent displayName, int permissions)同上,但 displayName 直接给 TextComponent同上同上
withEntity(Entity entity)换成另一个实体,同时把 name/displayName 换成该实体的名字与显示名entity 非 null新 CommandSourceStack(相同则返回 this)
withPos(Vec3d pos) / withRotation(Vec2f rotation)改位置 / 改朝向非 null新实例
withAnchor(Anchor anchor)改锚点(脚 / 眼)非 null新实例
withWorld(ServerWorld world)换维度非 null新实例
withPermissions(int permissions)直接设置权限等级0~4 有意义(见 hasPermissions)新实例
withMaxPermissions(int maxPermissions)只升不降:新值 ≤ 当前值时返回 this—新实例或 this
silent()标记为静默:后续 sendSuccess/sendFailure 不再真正发消息—新实例或 this
withCallback(ResultConsumer<CommandSourceStack> callback)设置命令执行结果回调非 null新实例
withCallback(ResultConsumer<CommandSourceStack> callback, BinaryOperator<ResultConsumer<CommandSourceStack>> chooser)用 chooser 把新回调和旧回调合并两者非 null新实例
withFacing(Entity entity, Anchor anchor)让上下文朝向"从当前锚点看向该实体锚点"entity 非 null新实例;计算不合法时抛 CommandSyntaxException
withFacing(Vec3d rotation)让上下文朝向"从当前锚点看向该坐标"非 null新实例;同上可能抛异常
getServer() / getWorld() / getEntity() / getPos() / getRotation() / getAnchor() / getName() / getDisplayName()读取对应字段—MinecraftServer / ServerWorld / Entity(可能 null)/ Vec3d / Vec2f / Anchor / String / TextComponent
getEntityOrThrow()取实体,没有就报错上下文中必须有实体Entity;否则抛 NOT_ENTITY_EXCEPTION(permissions.requires.entity)
getPlayerOrThrow()取玩家,不是玩家就报错上下文实体必须是 ServerPlayerEntityServerPlayerEntity;否则抛 NOT_PLAYER_EXCEPTION(permissions.requires.player)
hasPermissions(int permissions)权限判定:this.permissions >= permissionspermissions 为 0~4boolean
sendSuccess(TextComponent message, boolean broadcastToOps)给命令源回成功消息;broadcastToOps 为真且命令源允许时还会广播给 OP 并写管理员日志message 非 null;静默上下文不发送任何东西无(void)
sendFailure(TextComponent message)给命令源回失败消息(自动染红)同上无(void)
onCommandComplete(CommandContext<CommandSourceStack> ctx, boolean success, int result)转发给回调;框架把它挂在 dispatcher 的 consumer 上,所以每条命令执行完都会调用一般不手动调用无(void)
getPlayerNames() / getTeams()补全用:在线玩家名 / 记分板队伍名—Collection<String>
requestSuggestions(CommandContext<SharedSuggestionProvider> ctx, SuggestionsBuilder builder)请求服务端计算补全—源码直接返回 null,因此服务端源上的 ASK_SERVER 拿不到可用 future(源码未说明原因);参数类型若走这条路要自己返回建议
getRelevantCoordinates(boolean absolute)补全用:可作为坐标建议的候选—常量集合,仅含 TextCoordinates.DEFAULT_GLOBAL("~ ~ ~")
NOT_PLAYER_EXCEPTION / NOT_ENTITY_EXCEPTION两个预置异常类型—SimpleCommandExceptionType

ClientCommandSource ​

Reference: net.ornithemc.osl.commands.api.client.command.ClientCommandSource

作用:客户端命令的执行上下文。框架的实现是 ClientSuggestionProvider(impl 包),客户端命令回调里的 ctx.getSource() 就是它。

成员作用需要(参数 / 前置条件)返回
getMinecraft()取 Minecraft 实例—Minecraft
getWorld()取当前客户端世界已在世界中ClientWorld(可能 null)
getPlayer()取本地玩家已在世界中LocalClientPlayerEntity(可能 null)
getPosition()玩家坐标玩家非 nullVec3d
getRotation()玩家朝向(x=pitch,y=yaw)玩家非 nullVec2f
sendSuccess(TextComponent message)往聊天栏输出成功消息非 null无(void)
sendFailure(TextComponent message)(继承 CommandFailureConsumer)往聊天栏输出失败消息(实现里会先染红)非 null无(void)

该接口同时继承 SharedSuggestionProvider,所以也有 getPlayerNames()、getTeams()、hasPermissions(int)、requestSuggestions(…)、getRelevantCoordinates(boolean) 这几个成员——由实现类提供,requestSuggestions 会真的向服务端发请求并等待回包。

CommandSourceBuilder ​

Reference: net.ornithemc.osl.commands.api.server.command.CommandSourceBuilder

作用:能把自己转成 CommandSourceStack 的类型。框架用 Entity 混入实现了它,这也是"原版命令执行路径会先问一遍 Brigadier"的判据(见"运行方式"第 3 点)。

成员作用需要(参数 / 前置条件)返回
createCommandSourceStack()按当前实体状态(世界、位置、朝向、名字、权限)构造上下文实体必须在 ServerWorld 里(实现会对 world 做强转)新的 CommandSourceStack

CommandFailureConsumer ​

Reference: net.ornithemc.osl.commands.api.command.CommandFailureConsumer

作用:只要能收失败消息就算命令源。服务端 CommandSourceStack 与客户端 ClientCommandSource 都实现它,框架执行命令时用它把 CommandSyntaxException 转成聊天提示。

成员作用需要(参数 / 前置条件)返回
sendFailure(TextComponent message)把失败原因发给玩家message 非 null;由实现决定是否染色/静默无(void)

SharedSuggestionProvider ​

Reference: net.ornithemc.osl.commands.api.command.SharedSuggestionProvider

作用:服务端与客户端命令源共用的"补全数据源"接口,并附一大堆静态补全工具方法。参数类型的 listSuggestions 基本都靠这些静态方法拼结果。

成员作用需要(参数 / 前置条件)返回
getPlayerNames()在线玩家名,用于实体/玩家名补全—Collection<String>
getSelectedEntities()准星指着的实体(默认空集合,客户端实现会返回该实体的 UUID 字符串)—Collection<String>
getTeams()记分板队伍名—Collection<String>
requestSuggestions(CommandContext<SharedSuggestionProvider> ctx, SuggestionsBuilder builder)让命令源去算补全(客户端实现会请求服务端)ctx / builder 非 nullCompletableFuture<Suggestions>;服务端 CommandSourceStack 的实现返回 null
getRelevantCoordinates(boolean absolute)可作为坐标建议的候选坐标—Collection<TextCoordinates>
hasPermissions(int permissions)权限判定—boolean
filterResources(Iterable<T> values, String target, Function<T, ? extends NamespacedIdentifier> converter, Consumer<T> consumer)按输入前缀过滤"带命名空间的 ID":target 含 : 时全串前缀匹配,否则命名空间或路径任一前缀匹配都能命中—无(void,命中项交给 consumer)
filterResources(Iterable<T> values, String target, String prefix, Function<T, ? extends NamespacedIdentifier> converter, Consumer<T> consumer)同上,但额外提供一个 prefix(如 "#")参与公共前缀裁剪;target 为空时全部命中—无(void)
suggestResource(Iterable<? extends NamespacedIdentifier> keys, SuggestionsBuilder builder)直接把 ID 列表作为建议(小写前缀匹配)—CompletableFuture<Suggestions>(已完成)
suggestResource(Iterable<? extends NamespacedIdentifier> keys, SuggestionsBuilder builder, String prefix)同上,但建议文本前面加 prefix—同上
suggestResource(Iterable<T> values, SuggestionsBuilder builder, Function<T, ? extends NamespacedIdentifier> key, Function<T, Message> tooltip)同上,且每项带悬浮提示—同上
suggestResource(Stream<NamespacedIdentifier> keys, SuggestionsBuilder builder) / suggestResource(Stream<T> values, SuggestionsBuilder builder, Function<T, ? extends NamespacedIdentifier> key, Function<T, Message> tooltip)Stream 重载—同上
suggestCoordinates(String s, Collection<TextCoordinates> coordinates, SuggestionsBuilder builder, Predicate<String> validator)三维坐标补全:按已输入的空格数补 x / x y / x y z,每一项都要过 validator(通常传 Commands.validator(arg::parse))coordinates 非空CompletableFuture<Suggestions>
suggestHorizontalCoordinates(String s, Collection<TextCoordinates> coordinates, SuggestionsBuilder builder, Predicate<String> validator)二维(水平)坐标补全:补 x / x z同上同上
suggestMatching(Iterable<String> suggestions, SuggestionsBuilder builder) / suggestMatching(Stream<String> …) / suggestMatching(String[] …)按 builder.getRemaining() 的小写前缀过滤字符串列表并建议—CompletableFuture<Suggestions>
SharedSuggestionProvider.TextCoordinates(嵌套类)"可建议的坐标"三元组,public final String x, y, z构造 TextCoordinates(String x, String y, String z)实例;常量 DEFAULT_LOCAL("^ ^ ^")、DEFAULT_GLOBAL("~ ~ ~")

MinecraftServerExtension ​

Reference: net.ornithemc.osl.commands.api.server.MinecraftServerExtension

作用:给 MinecraftServer 加"按 GameProfile 查权限等级"的能力(mixin 实现,直接 (MinecraftServerExtension) server 强转即可用)。

成员作用需要(参数 / 前置条件)返回
getPermissions(GameProfile profile)计算该玩家的权限等级profile 非 nullint(0~4)。逻辑:OP 列表里有条目就用条目里的等级;单人下是自己或开了作弊就是 4;专用服务器下是 op-permission-level;非 OP 为 0

PlayerManagerExtension ​

Reference: net.ornithemc.osl.commands.api.server.PlayerManagerExtension

作用:给 PlayerManager 加"是否允许作弊"与"刷新玩家权限(并把新命令树重新同步给该玩家)"的能力。

成员作用需要(参数 / 前置条件)返回
allowCommands()该存档/服务器是否开启了作弊(allow-commands)—boolean
updatePermissions(ServerPlayerEntity player)重算权限并触发命令树重新下发player 非 null无(void)。1.12.2 走 >=15w31a 分支:命令树是在 updatePermissions(player, permissions) 的尾部发出的,所以这个方法等价于"刷新 + 重发";只有 15w31a 之前的版本才走手工计算权限的那套实现

EntityExtension ​

Reference: net.ornithemc.osl.commands.api.entity.EntityExtension

作用:给 Entity 加权限查询,并让它能当命令源用。任何实体都能 (EntityExtension) entity。

成员作用需要(参数 / 前置条件)返回
createCommandSourceStack()(继承 CommandSourceBuilder)用该实体构造上下文实体在 ServerWorld 中CommandSourceStack
getPermissions()该实体的权限等级—int。普通实体恒为 0;ServerPlayerEntity 覆写为 server.getPermissions(gameProfile)
hasPermissions(int permissions)权限判定permissions 为 0~4boolean,实现为「permissions == 0 或 getPermissions() >= permissions」

ClientPlayNetworkHandlerExtension ​

Reference: net.ornithemc.osl.commands.api.client.network.handler.ClientPlayNetworkHandlerExtension

作用:客户端网络处理器上的命令状态:服务端下发来的命令树、补全用的命令源,以及两个收包入口。mod 一般只读 getCommands() / getSuggestionProvider()(例如给自己的 UI 做补全)。

成员作用需要(参数 / 前置条件)返回
getCommands()当前"服务端命令树 + 客户端命令"合并后的 dispatcher(未收到包时是空树)已登录CommandDispatcher<SharedSuggestionProvider>
getSuggestionProvider()补全用命令源已登录ClientSuggestionProvider(impl 类型);实际当 ClientCommandSource / SharedSuggestionProvider 用即可
handleCommands(CommandsPayload payload)处理"命令树同步"包;会用它替换 getCommands() 的根节点并把客户端命令合并进去由框架在收到包时调用无(void)
handleCommandSuggestions(CommandSuggestionsPayload payload)处理"补全结果"包,按请求 id 完成对应的 future由框架调用无(void)

参数类型总览 ​

api.command.argument 下的参数类型都是 Brigadier 的 ArgumentType 实现,用法统一:ServerCommands.argument("名字", XxxArgument.xxx())。每张表里的"命令里的样子"取自源码的 getExamples(),也就是玩家实际会敲的文本。

类型工厂方法命令里的样子parse 的返回
Vec3dArgumentvec3d() / vec3d(boolean centered)0 0 0、~ ~ ~、^ ^ ^、^1 ^ ^-5Coordinates(全局或局部)
Vec2fArgumentvec2f()0 0、~ ~、0.1 -0.5Coordinates(只有 x/z)
BlockPosArgumentblockPos()0 0 0、~0.5 ~1 ~-5、^ ^ ^Coordinates(方块坐标)
ColumnPosArgumentcolumnPos()0 0、~1 ~-2、^-1 ^0Coordinates(列坐标 x/z)
RotationArgumentrotation()0 0、~-5 ~5Coordinates(pitch yaw)
AnchorArgumentanchor()eyes、feetAnchor
AxesArgumentaxes()xyz、xEnumSet<Axis>
BlockStateArgumentblock()stone、minecraft:stone、stone[foo=bar]、foo{bar=baz}BlockInput
BlockPredicateArgumentblockPredicate()stone、stone[foo=bar]Result(工厂,产出 Predicate<BlockPointer>)
LegacyBlockStateArgumentblock()stone、stone foo=bar、stone 0BlockInput
LegacyBlockPredicateArgumentblockPredicate()stone、stone 0Result
ItemArgumentitem()stick、minecraft:stick、stick{foo=bar}ItemInput
ItemPredicateArgumentitemPredicate()stick、minecraft:stickResult
EntityArgumententity() / entities() / player() / players()Player、@e、@e[type=foo]、dd12be42-…EntitySelector
GameProfileArgumentgameProfiles()Player、0123、@e、UUIDResult
TextArgumenttext()"hello world"、JSON 文本TextComponent
MessageArgumentmessage()Hello world!、Hello @p :)MessageArgument.Message
NbtCompoundArgumentnbtCompound(){}、{foo=bar}NbtCompound
ObjectiveArgumentobjective()foo、*String
ScoreHolderArgumentscoreHolder() / scoreHolders()Player、*、@eResult
ScoreboardCriterionArgumentcriterion()foo、minecraft:fooScoreboardCriterion
ScoreboardDisplaySlotArgumentdisplaySlot()sidebarInteger
OperationArgumentoperation()=、+=、><Operation
TeamArgumentteam()foo、123String
IdentifierArgumentidentifier()foo、foo:barNamespacedIdentifier
ColorArgumentcolor()red、greenFormatting
EnchantmentArgumentenchantment()unbreaking、silk_touchEnchantment
StatusEffectArgumenteffect()spooky、effectStatusEffect
SlotArgumentslot()container.5、weaponInteger
RangeArgument.IntsRangeArgument.intRange()0..5、0、-100..NumberRange.Ints
RangeArgument.FloatsRangeArgument.floatRange()0..5.2、-100.76..NumberRange.Floats

1.12.2 上所有 #标签 语法都不可用:BlockStateParser 与 ItemParser 在构造时把 allowTag 强制改成了 false(源码里留着 // TODO),所以 #minecraft:logs 这类输入会直接抛"不允许标签"的异常。

参数类型:坐标与朝向 ​

Vec3dArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.Vec3dArgument

作用:三维坐标参数,世界坐标(1 2 3)、相对坐标(~1 ~ ~-2)、局部坐标(^1 ^ ^-5)三种写法都支持,是 1.13 的 vec3 参数。

成员作用需要(参数 / 前置条件)返回
vec3d()工厂:整数写法会自动补 .5(居中修正开启)—Vec3dArgument
vec3d(boolean centered)工厂:自己决定是否做居中修正—Vec3dArgument
parse(StringReader reader)解析:首字符是 ^ 走局部坐标,否则走全局坐标reader 当前位置必须是坐标开头Coordinates(LocalCoordinates 或 GlobalCoordinates);缺分量抛 INCOMPLETE_EXCEPTION(argument.pos3d.incomplete),混写抛 MIXED_TYPE_EXCEPTION(argument.pos.mixed)
getVec3d(CommandContext<CommandSourceStack> ctx, String arg)取值:解析成绝对坐标arg 与注册时的参数名一致Vec3d;解析结果报错时抛 CommandSyntaxException
getCoordinates(CommandContext<CommandSourceStack> ctx, String arg)取值:保留 Coordinates 对象(可再判相对/绝对)同上Coordinates
listSuggestions(CommandContext<S> ctx, SuggestionsBuilder builder)补全:用 SharedSuggestionProvider.suggestHorizontalCoordinates + getRelevantCoordinates 给候选命令源需实现 SharedSuggestionProvider,否则返回 Suggestions.empty()CompletableFuture<Suggestions>
getExamples()示例(也用于错误提示)—Collection<String>

Vec2fArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.Vec2fArgument

作用:水平二维坐标(x/z)参数,对应 1.13 的 vec2。

成员作用需要(参数 / 前置条件)返回
vec2f()工厂(居中修正开启)—Vec2fArgument
new Vec2fArgument(boolean centerCorrect)直接构造,指定居中修正—实例
parse(StringReader reader)解析两个分量(x、z),中间必须有一个空格—Coordinates(内部是 GlobalCoordinates,y 恒为相对 0);分量不足抛 INCOMPLETE_EXCEPTION(argument.pos2d.incomplete)
getVec2f(CommandContext<CommandSourceStack> ctx, String arg)取 (x, z) 为 Vec2f命令源非 nullVec2f
listSuggestions(…)补全:水平坐标建议需 SharedSuggestionProviderCompletableFuture<Suggestions>
getExamples()示例—Collection<String>

BlockPosArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.BlockPosArgument

作用:方块坐标参数(block_pos),支持全局/相对/局部三种写法,并提供"取已加载方块坐标"的便利方法。

成员作用需要(参数 / 前置条件)返回
blockPos()工厂—BlockPosArgument
parse(StringReader reader)^ 开头走局部坐标,否则按整数全局坐标解析—Coordinates
getBlockPos(CommandContext<CommandSourceStack> ctx, String arg)解析成方块坐标—BlockPos
getLoadedBlockPos(CommandContext<CommandSourceStack> ctx, String arg)解析并检查区块已加载、坐标在世界内命令源必须有世界BlockPos;区块未加载抛 UNLOADED_EXCEPTION(argument.pos.unloaded),出界抛 OUT_OF_WORLD_EXCEPTION(argument.pos.outofworld)
listSuggestions(…)补全:局部前缀(^)只给 ^ ^ ^,否则用命令源的坐标候选需 SharedSuggestionProviderCompletableFuture<Suggestions>
getExamples()示例—Collection<String>

ColumnPosArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.ColumnPosArgument

作用:列坐标参数(只有 x/z,无 y),对应 1.13 的 column_pos,适合"按区块列操作"的命令。

成员作用需要(参数 / 前置条件)返回
columnPos()工厂—ColumnPosArgument
parse(StringReader reader)解析两个整数分量(^ 也接受,但只取数值)—Coordinates(y 固定相对 0);格式不完整抛 INCOMPLETE_EXCEPTION(argument.pos2d.incomplete)
getColumnPos(CommandContext<CommandSourceStack> ctx, String arg)取列坐标—ColumnPosArgument.ColumnPos
listSuggestions(…)补全:水平坐标建议需 SharedSuggestionProviderCompletableFuture<Suggestions>
getExamples()示例—Collection<String>
ColumnPosArgument.ColumnPos(嵌套类)结果类型,public final int x, z,toString() 形如 [x, z]构造 ColumnPos(int x, int z)实例

RotationArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.RotationArgument

作用:朝向参数(pitch / yaw 两个浮点),对应 1.13 的 rotation。

成员作用需要(参数 / 前置条件)返回
rotation()工厂—RotationArgument
parse(StringReader reader)解析两个分量:<pitch> <yaw>两个分量都要有,缺一个抛 INCOMPLETE_EXCEPTION(argument.rotation.incomplete)Coordinates,内部是 GlobalCoordinates(yaw, pitch, ~0),用 Coordinates#getRotation(source) 取出 Vec2f(x=pitch, y=yaw)
getRotation(CommandContext<?> ctx, String arg)取值—Coordinates
getExamples()示例—Collection<String>

注意:该类型没有实现 listSuggestions(走 Brigadier 默认的空建议)。

AnchorArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.AnchorArgument

作用:锚点参数(feet / eyes),决定"实体坐标取脚底还是眼睛",配合 CommandSourceStack.withAnchor 使用。

成员作用需要(参数 / 前置条件)返回
anchor()工厂—AnchorArgument
parse(StringReader reader)读一个非引号字符串并查表—Anchor;未知名字抛 DynamicCommandExceptionType(argument.anchor.invalid),并把游标回退
getAnchor(CommandContext<?> ctx, String arg)取值—Anchor
listSuggestions(…)补全:feet / eyes—CompletableFuture<Suggestions>
getExamples()示例—Collection<String>
AnchorArgument.Anchor(枚举)锚点:FEET(原坐标)、EYES(y 加 entity.getEyeHeight())—见下
Anchor.byName(String name)按名字查("feet" / "eyes")—Anchor,查不到返回 null
Anchor.apply(Entity entity)把锚点应用到实体的绝对坐标entity 非 nullVec3d
Anchor.apply(CommandSourceStack source)把锚点应用到命令源:有实体就按实体变换,没实体直接用 source.getPos()source 非 nullVec3d

AxesArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.AxesArgument

作用:坐标轴集合参数(xyz、xz 之类),对应 1.13 的 swizzle,用于 /clone、/fill 那种"哪些轴参与"的语义。

成员作用需要(参数 / 前置条件)返回
axes()工厂—AxesArgument
parse(StringReader reader)逐字符读到空格为止,x/y/z 各算一个轴字符必须是 x/y/z;重复或非法字符抛 INVALID_EXCEPTION(arguments.swizzle.invalid)EnumSet<Axis>
getAxes(CommandContext<CommandSourceStack> ctx, String arg)取值—EnumSet<Axis>(Direction.Axis)
getExamples()示例—Collection<String>(无自定义补全)

Coordinate ​

Reference: net.ornithemc.osl.commands.api.command.argument.Coordinate

作用:单个坐标分量的模型:一个 double 值 + "是否相对"。三个坐标参数最终都靠它解析。

成员作用需要(参数 / 前置条件)返回
new Coordinate(boolean relative, double coordinate)直接构造—实例
isRelative()是否为 ~ 相对值—boolean
get(double offset)求绝对值:相对则 coordinate + offset,绝对则原样offset 通常是命令源对应轴的坐标double
parseDouble(StringReader reader, boolean centered)解析一个浮点分量;centered 为真且写法是整数时自动 +0.5不能以 ^ 开头(否则抛 MIXED_TYPE_EXCEPTION);无输入抛 NOT_DOUBLE_EXCEPTION(argument.pos.missing.double)Coordinate
parseInt(StringReader reader)解析一个整数分量(相对写法允许小数)同上,无输入抛 NOT_INT_EXCEPTION(argument.pos.missing.int)Coordinate
equals(Object) / hashCode()值比较—boolean / int

Coordinates ​

Reference: net.ornithemc.osl.commands.api.command.argument.Coordinates

作用:坐标参数的公共接口,两种实现:GlobalCoordinates(世界/相对坐标)与 LocalCoordinates(^ 局部坐标)。它就是你从坐标参数里拿到的东西。

成员作用需要(参数 / 前置条件)返回
getPosition(CommandSourceStack source)解析成绝对坐标source 提供基准位置与朝向Vec3d
getRotation(CommandSourceStack source)解析成朝向(供 RotationArgument / Vec2fArgument 使用)同上Vec2f
getBlockPos(CommandSourceStack source)默认实现:new BlockPos(getPosition(source))同上BlockPos
isXRelative() / isYRelative() / isZRelative()各轴是否相对—boolean(LocalCoordinates 恒为 true)

GlobalCoordinates ​

Reference: net.ornithemc.osl.commands.api.command.argument.GlobalCoordinates

作用:世界坐标 / ~ 相对坐标的实现。

成员作用需要(参数 / 前置条件)返回
new GlobalCoordinates(Coordinate x, Coordinate y, Coordinate z)直接构造三个分量非 null实例
getPosition(CommandSourceStack source)用命令源坐标作为相对基准同上Vec3d
getRotation(CommandSourceStack source)用命令源朝向作为相对基准,x/y 两个分量转成 Vec2f同上Vec2f
isXRelative() / isYRelative() / isZRelative()转调对应分量—boolean
parseInt(StringReader reader)解析三个整数分量缺分量会回退游标并抛 Vec3dArgument.INCOMPLETE_EXCEPTIONGlobalCoordinates
parseDouble(StringReader reader, boolean centered)解析三个浮点分量(第一、三分量参与居中修正,中间分量不修正)同上GlobalCoordinates
self()造一个 ~ ~ ~(相对 0)—GlobalCoordinates
equals(Object) / hashCode()值比较—boolean / int

LocalCoordinates ​

Reference: net.ornithemc.osl.commands.api.command.argument.LocalCoordinates

作用:^ 局部坐标的实现(左 / 上 / 前三个分量,相对命令源朝向)。

成员作用需要(参数 / 前置条件)返回
new LocalCoordinates(double left, double upwards, double forwards)直接构造—实例
getPosition(CommandSourceStack source)用命令源的锚点、朝向换算出绝对坐标source 的 rotation 非 nullVec3d
getRotation(CommandSourceStack source)局部坐标没有朝向语义—恒为 Vec2f.ZERO
isXRelative() / isYRelative() / isZRelative()局部坐标永远相对—恒为 true
parse(StringReader reader)解析三个必须带 ^ 前缀的分量缺 ^ 抛 Vec3dArgument.MIXED_TYPE_EXCEPTION,缺分量抛 Vec3dArgument.INCOMPLETE_EXCEPTIONLocalCoordinates
equals(Object) / hashCode()值比较—boolean / int

Vec2f ​

Reference: net.ornithemc.osl.commands.api.command.argument.Vec2f

作用:OSL 自己的二维浮点向量(1.12.2 没有 net.minecraft.util.math.Vec2f),用来表示朝向 (pitch, yaw)。CommandSourceStack#getRotation 和 ClientCommandSource#getRotation 都返回它。

成员作用需要(参数 / 前置条件)返回
new Vec2f(float x, float y)构造—实例
x / y(public final float)两个分量——
equals(Vec2f other)值比较。注意这是重载,不是 equals(Object),不要指望放进 HashMap 里能按值命中other 非 nullboolean
ZERO / ONE / POS_X / NEG_X / POS_Y / NEG_Y / MAX / MIN预置常量—Vec2f

参数类型:方块 ​

BlockStateArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.BlockStateArgument

作用:方块状态参数(block_state),1.13 的 stone[foo=bar]{nbt} 写法的移植:给方块 ID,可选方括号里的属性表,可选大括号里的方块实体 NBT。

成员作用需要(参数 / 前置条件)返回
block()工厂—BlockStateArgument
parse(StringReader reader)用 new BlockStateParser(reader, false, false).parse() 解析,包成 BlockInput—BlockInput;未知方块 ID 抛 BlockStateParser.INVALID_ID_EXCEPTION,属性错误抛对应异常(见 BlockStateParser)
getBlock(CommandContext<?> ctx, String arg)取值—BlockInput
listSuggestions(…)补全:把已输入部分重新交给 BlockStateParser 解析后取它的建议(方块 ID、属性名、属性值、[/{/]/,)—CompletableFuture<Suggestions>
getExamples()示例:stone、minecraft:stone、stone[foo=bar]、foo{bar=baz}—Collection<String>

BlockPredicateArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.BlockPredicateArgument

作用:方块谓词参数(block_predicate):解析出的不是某一块的具体状态,而是一个能对世界里任意方块做匹配的 Predicate<BlockPointer>,适合"匹配区域内所有符合条件的方块"这类命令。

成员作用需要(参数 / 前置条件)返回
blockPredicate()工厂—BlockPredicateArgument
parse(StringReader reader)new BlockStateParser(reader, false, true).parse(),把状态 + 属性 + NBT 包成谓词—BlockPredicateArgument.Result。注意:方块 ID 不存在时解析阶段不报错,返回的 Result 在 create() 时才抛 arguments.block.unknown
getBlockPredicate(CommandContext<CommandSourceStack> ctx, String arg)取值:直接拿到谓词—Predicate<BlockPointer>;方块不存在时抛 CommandSyntaxException
listSuggestions(…)同 BlockStateArgument—CompletableFuture<Suggestions>
getExamples()示例:stone、minecraft:stone、stone[foo=bar]—Collection<String>
BlockPredicateArgument.Result(函数式接口)延迟构造谓词create() 可能抛 CommandSyntaxExceptionPredicate<BlockPointer>

谓词语义:方块类型相同 → 指定的每个属性值相同 → 有 NBT 时要求方块实体存在且 NbtUtils.matches(expected, actual, true)。

LegacyBlockStateArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.LegacyBlockStateArgument

作用:旧写法的方块状态参数:属性表用空格分隔、支持元数据数字(1.8~1.12 的命令风格),例如 stone、stone foo=bar、stone 0。

成员作用需要(参数 / 前置条件)返回
block()工厂—LegacyBlockStateArgument
parse(StringReader reader)new BlockStateParser(reader, true, false).parse()(legacyFormat = true)—BlockInput
getBlock(CommandContext<?> ctx, String arg)取值—BlockInput
listSuggestions(…)补全—CompletableFuture<Suggestions>
getExamples()示例:stone、minecraft:stone、stone foo=bar、stone 0—Collection<String>

旧写法的两点差别(读自 BlockStateParser):元数据写法会校验 0..15(否则 INVALID_DATA_EXCEPTION);属性表里有"既不属于该方块、也不像任何待填属性前缀"的名字时,解析会**退化成"只匹配方块本身"**而不是报错(1.8 起方块 ID + 元数据的写法允许后面跟任意文本)。

LegacyBlockPredicateArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.LegacyBlockPredicateArgument

作用:旧写法的方块谓词参数(stone、stone 0、stone foo=bar),语义与 BlockPredicateArgument 相同但不解析 NBT。

成员作用需要(参数 / 前置条件)返回
blockPredicate()工厂—LegacyBlockPredicateArgument
parse(StringReader reader)new BlockStateParser(reader, true, true).parse(),只用状态 + 属性构造谓词—LegacyBlockPredicateArgument.Result;未知方块同样延迟到 create() 才抛
getBlockPredicate(CommandContext<CommandSourceStack> ctx, String arg)取值—Predicate<BlockPointer>
listSuggestions(…)补全—CompletableFuture<Suggestions>
getExamples()示例:stone、minecraft:stone、stone foo=bar、stone 0—Collection<String>
LegacyBlockPredicateArgument.Result(函数式接口)延迟构造谓词create() 可能抛 CommandSyntaxExceptionPredicate<BlockPointer>

BlockInput ​

Reference: net.ornithemc.osl.commands.api.command.argument.BlockInput

作用:BlockStateArgument / LegacyBlockStateArgument 的解析结果:方块状态 + 需要匹配的属性集合 + 可选方块实体 NBT。它自己也是 Predicate<BlockPointer>,并且能直接把方块放到世界里。

成员作用需要(参数 / 前置条件)返回
new BlockInput(BlockState state, Set<Property<?>> properties, NbtCompound nbt)构造state 非 null;nbt 可为 null实例
getState()取方块状态—BlockState
test(BlockPointer ptr)判断某处方块是否匹配:方块类型、属性值、NBT 都要对上ptr 非 nullboolean
set(World world, BlockPos pos, int flags)把方块写进世界;有 NBT 时还会写入方块实体(并补上 x/y/z)world / pos 非 null;flags 是原版 setBlockState 的标志位boolean:false 表示方块没被设置成功

BlockStateParser ​

Reference: net.ornithemc.osl.commands.api.command.argument.BlockStateParser

作用:方块状态字符串的底层解析器,BlockStateArgument 与两个方块谓词参数共用。你也可以直接用它在自己的命令里解析 stone[foo=bar]{…}。

成员作用需要(参数 / 前置条件)返回
new BlockStateParser(StringReader reader, boolean legacyFormat, boolean allowTag)构造allowTag 目前无意义:构造里被强制改成 false(源码 // TODO),所以 #标签 一律不支持实例
parse()完整解析(方块 ID → 属性 → NBT)reader 停在起点BlockStateParser(this,方便链式)
parseBlock()只解析方块 ID同上无(void),结果进 getId() / getState();未知 ID 抛 INVALID_ID_EXCEPTION(argument.block.id.invalid)
parseProperties()解析属性表:新写法 [a=b,c=d],旧写法 a=b 或元数据数字必须已经解析过方块无(void);错误见下表
parseVagueProperties()解析"模糊属性"(标签时代的产物,[a=b] 允许多种方块)仅新写法 + 标签场景用到;1.12.2 上标签不可用,实际走不到无(void)
parseTag()解析 #标签allowTag 为 true 才允许无(void);1.12.2 上必然抛 NO_TAGS_ALLOWED_EXCEPTION(argument.block.tag.disallowed)
parseNbt()解析 {…} 方块实体 NBT只在非旧写法下由 parse() 调用无(void)
getId() / getProperties() / getState() / getNbt() / getTag()读解析结果解析过才有值;getState() 在方块不存在时是 nullNamespacedIdentifier / Map<Property<?>, Comparable<?>> / BlockState / NbtCompound / NamespacedIdentifier
addSuggestions(SuggestionsBuilder builder)把当前解析状态对应的建议塞进 builder—CompletableFuture<Suggestions>
serializeProperties(BlockState state)反向序列化成命令字符串state 非 nullString,形如 minecraft:stone[a=b](无属性时只有 ID)

公开的异常常量(都是 Brigadier 的异常类型,可直接 throw X.createWithContext(reader, …)):

常量语言键触发条件
NO_TAGS_ALLOWED_EXCEPTIONargument.block.tag.disallowed用了 #标签 但 allowTag 为假
INVALID_ID_EXCEPTIONargument.block.id.invalid方块 ID 查不到
INVALID_DATA_EXCEPTIONargument.block.data.invalid旧写法元数据不在 0..15
UNKNOWN_PROPERTY_EXCEPTIONargument.block.property.unknown属性名不属于该方块
DUPLICATE_PROPERTY_EXCEPTIONargument.block.property.duplicate同一属性写了两遍
INVALID_PROPERTY_EXCEPTIONargument.block.property.invalid属性值不合法
NO_VALUE_EXCEPTIONargument.block.property.novalue属性后面没有 =值
UNCLOSED_PROPERTY_EXCEPTIONargument.block.property.unclosed属性表没有闭合的 ]

参数类型:物品 ​

ItemArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.ItemArgument

作用:物品参数(item_stack):物品 ID + 可选 NBT,例如 stick、minecraft:stick、stick{foo=bar}。

成员作用需要(参数 / 前置条件)返回
item()工厂—ItemArgument
parse(StringReader reader)用 new ItemParser(reader, false).parse() 解析—ItemInput;未知物品 ID 抛 ItemParser.INVALID_ID_EXCEPTION
getItem(CommandContext<S> ctx, String arg)取值—ItemInput
listSuggestions(…)补全:物品 ID 前缀匹配,解析完成后会给 { 建议—CompletableFuture<Suggestions>
getExamples()示例—Collection<String>

ItemPredicateArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.ItemPredicateArgument

作用:物品谓词参数(item_predicate):解析成 Predicate<ItemStack>,用于"背包里所有符合…的物品"。

成员作用需要(参数 / 前置条件)返回
itemPredicate()工厂—ItemPredicateArgument
parse(StringReader reader)new ItemParser(reader, true).parse()—ItemPredicateArgument.Result;物品 ID 不存在时不立刻报错,create(ctx) 时才抛 arguments.item.unknown
getItemPredicate(CommandContext<CommandSourceStack> ctx, String arg)取值—Predicate<ItemStack>
listSuggestions(…)补全—CompletableFuture<Suggestions>
getExamples()示例里含 #stick,但 1.12.2 上标签不可用,实际只能写物品 ID—Collection<String>
ItemPredicateArgument.Result(函数式接口)延迟构造谓词create(CommandContext<CommandSourceStack> ctx) 可能抛 CommandSyntaxExceptionPredicate<ItemStack>

ItemInput ​

Reference: net.ornithemc.osl.commands.api.command.argument.ItemInput

作用:ItemArgument 的解析结果:物品 + 可选 NBT。既是 Predicate<ItemStack>,也能造出真正的 ItemStack。

成员作用需要(参数 / 前置条件)返回
new ItemInput(Item item, NbtCompound nbt)构造item 非 null;nbt 可为 null实例
getItem()取物品—Item
test(ItemStack item)判断物品堆是否匹配(物品相同 + NBT 部分匹配)item 非 nullboolean
createItem(int size, boolean validateStackSize)造一个物品堆,并可选地校验堆叠上限size ≥ 0;validateStackSize 为真且超上限时抛 arguments.item.overstackedItemStack
serialize()反向序列化为命令字符串—String:物品ID + NBT 的 toString()

ItemParser ​

Reference: net.ornithemc.osl.commands.api.command.argument.ItemParser

作用:物品字符串的底层解析器(ItemArgument 与 ItemPredicateArgument 共用)。

成员作用需要(参数 / 前置条件)返回
new ItemParser(StringReader reader, boolean allowTag)构造allowTag 目前无意义:构造里被强制改成 false(源码 // TODO)实例
parse()完整解析(#标签 或物品 ID → 可选 {…} NBT)reader 停在起点ItemParser(this)
parseItem()只解析物品 ID—无(void),结果进 getId() / getItem();未知 ID 抛 INVALID_ID_EXCEPTION(argument.item.id.invalid)
parseTag()解析 #标签allowTag 为真无(void);1.12.2 上必然抛 NO_TAGS_ALLOWED_EXCEPTION(argument.item.tag.disallowed)
parseNbt()解析 {…}—无(void)
getId() / getItem() / getNbt() / getTag()读解析结果—NamespacedIdentifier / Item(可能 null)/ NbtCompound / NamespacedIdentifier
addSuggestions(SuggestionsBuilder builder)把建议塞进 builder—CompletableFuture<Suggestions>
NO_TAGS_ALLOWED_EXCEPTION / INVALID_ID_EXCEPTION公开异常常量—SimpleCommandExceptionType / DynamicCommandExceptionType

参数类型:实体与玩家 ​

EntityArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.EntityArgument

作用:实体/玩家参数(entity、entities、player、players 四种变体):既能写具体名字、UUID,也能写 @e / @e[type=foo] 这类选择器。四个工厂方法的区别只在于"允许多个"和"只允许玩家"。

成员作用需要(参数 / 前置条件)返回
entity()工厂:单个实体(@e 也接受,但只能选中 1 个)—EntityArgument(single = true, players = false)
entities()工厂:多个实体—EntityArgument(single = false, players = false)
player()工厂:单个玩家—EntityArgument(single = true, players = true)
players()工厂:多个玩家—EntityArgument(single = false, players = true)
parse(StringReader reader)交给 EntitySelectorParser 解析,再按变体校验数量与玩家限制—EntitySelector;选择器选中多个而参数是"单个"时抛 TOO_MANY_ENTITIES_EXCEPTION(argument.entity.toomany)或 TOO_MANY_PLAYERS_EXCEPTION(argument.player.toomany);只允许玩家却选了非玩家时抛 NOT_PLAYER_EXCEPTION(argument.player.entities)
getEntity(CommandContext<CommandSourceStack> ctx, String arg)取单个实体—Entity;找不到抛 ENTITY_NOT_FOUND_EXCEPTION(argument.entity.notfound.entity),多于一个抛 TOO_MANY_ENTITIES_EXCEPTION
getEntities(CommandContext<CommandSourceStack> ctx, String arg)取实体集合(至少 1 个)—Collection<? extends Entity>;空则抛 ENTITY_NOT_FOUND_EXCEPTION
getOptionalEntities(CommandContext<CommandSourceStack> ctx, String arg)取实体集合,允许为空—Collection<? extends Entity>
getPlayer(CommandContext<CommandSourceStack> ctx, String arg)取单个玩家—ServerPlayerEntity;不是恰好 1 个时抛 PLAYER_NOT_FOUND_EXCEPTION(argument.entity.notfound.player)
getPlayers(CommandContext<CommandSourceStack> ctx, String arg)取玩家集合(至少 1 个)—Collection<ServerPlayerEntity>;空则抛 PLAYER_NOT_FOUND_EXCEPTION
getOptionalPlayers(CommandContext<CommandSourceStack> ctx, String arg)取玩家集合,允许为空—Collection<ServerPlayerEntity>
listSuggestions(…)补全:先重解析一遍再给出选择器名(@p/@a/@r/@s/@e)、选项名、玩家名命令源不是 SharedSuggestionProvider 时返回 Suggestions.empty()CompletableFuture<Suggestions>
getExamples()示例:Player、0123、@e、@e[type=foo]、UUID—Collection<String>
TOO_MANY_ENTITIES_EXCEPTION / TOO_MANY_PLAYERS_EXCEPTION / NOT_PLAYER_EXCEPTION / ENTITY_NOT_FOUND_EXCEPTION / PLAYER_NOT_FOUND_EXCEPTION / SELECTOR_NOT_ALLOWED_EXCEPTION公开异常常量—各自的 Brigadier 异常类型
EntityArgument.Serializer(嵌套类)网络序列化:用 1 字节标志位(1=single,2=players)见"参数序列化"ArgumentSerializer<EntityArgument>

EntitySelector ​

Reference: net.ornithemc.osl.commands.api.command.argument.EntitySelector

作用:EntityArgument 的解析结果,也就是"怎么选实体"的完整描述:数量上限、是否允许非玩家、是否限制在本维度、谓词、距离区间、位置变换、包围盒、排序方式、限定名字/UUID/类型、是否是 @ 选择器。

成员作用需要(参数 / 前置条件)返回
new EntitySelector(int max, boolean allowNonPlayers, boolean restrictOtherWorlds, Predicate<Entity> predicate, NumberRange.Floats range, Function<Vec3d, Vec3d> position, Box bounds, BiConsumer<Vec3d, List<? extends Entity>> order, boolean allowSelf, String name, UUID uuid, Class<? extends Entity> type, boolean selector)全部字段的构造器(一般由 EntitySelectorParser 造)predicate/range/position/order 非 null;name/uuid 可空实例
getMax()最多选几个—int
hasNonPlayers()是否允许非玩家实体(@e/@s 为真,@a/@p/@r 为假)—boolean
hasSelf()是否是"自己"(@s)—boolean
isRestrictOtherWorlds()是否只在本维度找—boolean
findSingleEntity(CommandSourceStack source)找唯一实体命令源权限 ≥ 2(用了 @ 选择器时),否则抛 SELECTOR_NOT_ALLOWED_EXCEPTION(argument.entity.selector.not_allowed)Entity;空抛 ENTITY_NOT_FOUND_EXCEPTION,多个抛 TOO_MANY_ENTITIES_EXCEPTION
findEntities(CommandSourceStack source)找实体列表:有名字查 PlayerManager,有 UUID 遍历所有维度,否则按包围盒/距离/谓词在对应维度里收集,再排序并截断到 max同上权限要求List<? extends Entity>(可能为空)
findSinglePlayer(CommandSourceStack source)找唯一玩家同上ServerPlayerEntity;不是恰好 1 个时抛 PLAYER_NOT_FOUND_EXCEPTION
findPlayers(CommandSourceStack source)找玩家列表同上List<ServerPlayerEntity>
joinNames(List<? extends Entity> entities)(静态)把实体列表拼成"名字、名字、…"的文本(多于 1 个时用灰色逗号分隔)entities 非 nullTextComponent(空列表返回空文本)

EntitySelectorParser ​

Reference: net.ornithemc.osl.commands.api.command.argument.EntitySelectorParser

作用:@e[type=foo,sort=nearest] 这类选择器字符串的解析器。通常不用直接 new,但如果你想在自己的参数类型里复用选择器语法(MessageArgument、ScoreHolderArgument 就是这么做的),就把 reader 交给它。

成员作用需要(参数 / 前置条件)返回
new EntitySelectorParser(StringReader reader)构造(允许选择器)—实例
new EntitySelectorParser(StringReader reader, boolean allowSelectors)构造:allowSelectors 为假时遇到 @ 抛异常权限不足(< 2)时应传 false实例
parse()完整解析:@ 开头走选择器,否则按"名字或 UUID"解析reader 停在起点EntitySelector;缺选择器字符抛 SELECTOR_MISSING_EXCEPTION,未知选择器抛 UNKNOWN_SELECTOR_EXCEPTION,名字非法抛 INVALID_EXCEPTION
getSelector()把当前状态打包成 EntitySelector(parse() 内部会调用)已解析过EntitySelector
getReader()取内部的 StringReader—StringReader
addSuggestions(SuggestionsBuilder builder, Consumer<SuggestionsBuilder> names)按当前解析阶段给建议;names 用来补"名字"这一类候选names 非 nullCompletableFuture<Suggestions>
setSuggestions(BiFunction<SuggestionsBuilder, Consumer<SuggestionsBuilder>, CompletableFuture<Suggestions>> suggestions)替换建议策略(选项处理器里用)—无(void)
shouldInvertValue()读可选的 ! 取反前缀reader 已跳过空白boolean
addPredicate(Predicate<Entity> predicate)追加实体过滤条件(多个条件取"与")—无(void)
setRestrictOtherWorlds()标记"只在本维度找"—无(void)
getDistance() / setDistance(NumberRange.Floats)distance 选项—NumberRange.Floats
getXp() / setXp(NumberRange.Ints)level 选项—NumberRange.Ints
getPitch() / setPitch(WrappedNumberRange)x_rotation 选项—WrappedNumberRange
getYaw() / setYaw(WrappedNumberRange)y_rotation 选项—WrappedNumberRange
getX() / getY() / getZ() / setX(double) / setY(double) / setZ(double)基准坐标选项—Double / 无(void)
getDx() / getDy() / getDz() / setDx(double) / setDy(double) / setDz(double)体积(包围盒)选项—Double / 无(void)
setMax(int max) / setAllowNonPlayers(boolean) / setOrder(BiConsumer<Vec3d, List<? extends Entity>>)数量上限 / 是否允许非玩家 / 排序方式—无(void)
setType(Class<? extends Entity> type)限定实体类型—无(void)
hasSelf() / hasName() / hasNotName() / hasLimit() / hasOrder() / hasGameMode() / hasNotGameMode() / hasTeam() / hasNotTeam() / hasType() / hasNotType() / hasScores() / hasAdvancements()选项"是否已用过"的标记(用来阻止重复或互斥的选项)—boolean
setHasName(boolean) / setHasNotName(boolean) / setHasLimit(boolean) / setHasOrder(boolean) / setHasGameMode(boolean) / setHasNotGameMode(boolean) / setHasTeam(boolean) / setHasNotTeam(boolean) / setHasNotType() / setHasScores(boolean) / setHasAdvancements(boolean)设置上面的标记—无(void)
parseSelector() / parseNameOrUuid() / parseOptions()(protected)分段解析,供子类在自定义语法里复用由 parse() 调用无(void)
ORDER_NEAREST / ORDER_FURTHEST / ORDER_RANDOM / ORDER_ARBITRARY四种排序方式(sort= 的取值)—BiConsumer<Vec3d, List<? extends Entity>>
NO_SUGGESTIONS / SORT_ORDER_SUGGESTIONS预置建议策略—BiFunction<…>
INVALID_EXCEPTION / UNKNOWN_SELECTOR_EXCEPTION / SELECTOR_NOT_ALLOWED_EXCEPTION / SELECTOR_MISSING_EXCEPTION / UNTERMINATED_OPTIONS_EXCEPTION / OPTION_WITHOUT_VALUE_EXCEPTION公开异常常量—各自的 Brigadier 异常类型

各选择器的默认值(读自 parseSelector()):

选择器max允许非玩家排序类型限制附加
@p1否最近ServerPlayerEntity—
@aInteger.MAX_VALUE否无ServerPlayerEntity—
@r1否随机ServerPlayerEntity—
@s1是无不限allowSelf = true
@eInteger.MAX_VALUE是无不限谓词要求 Entity::isAlive

EntitySelectorOptions ​

Reference: net.ornithemc.osl.commands.api.command.argument.EntitySelectorOptions

作用:选择器方括号里那些选项(name、type、sort、scores …)的注册表与实现。解析由 EntitySelectorParser.parseOptions() 驱动,这里只提供"按名字取处理器"和"给建议"。

成员作用需要(参数 / 前置条件)返回
init()注册全部内置选项。幂等(表非空就直接返回)见下方警告无(void)
get(EntitySelectorParser parser, String name, int cursor)取某选项的处理器name 必须已注册,否则回退游标并抛 UNKNOWN_EXCEPTION(argument.entity.options.unknown)Modifier;该选项在当前状态下不适用时抛 NOT_APPLICABLE_EXCEPTION(argument.entity.options.inapplicable)
suggest(EntitySelectorParser parser, SuggestionsBuilder builder)建议当前可用的选项名(带 = 和说明文本)—无(void)
EntitySelectorOptions.Modifier(函数式接口)选项处理器实现 apply(EntitySelectorParser parser),可能抛 CommandSyntaxException无(void)
UNKNOWN_EXCEPTION / NOT_APPLICABLE_EXCEPTION / NEGATIVE_DISTANCE_EXCEPTION / NEGATIVE_XP_EXCEPTION / LIMIT_TOO_SMALL_EXCEPTION / UNKNOWN_ORDER_EXCEPTION / INVALID_GAME_MODE_EXCEPTION / INVALID_ENTITY_TYPE_EXCEPTION公开异常常量—各自的 Brigadier 异常类型

内置选项一览(方括号里的内容):

选项值写法作用
name名字,可加 ! 取反按实体名精确匹配
distance5、1..5、..10、3..与命令源的距离区间;负值报错;同时会把搜索限制在本维度
level同上的整数区间玩家经验等级;会把"允许非玩家"关掉
x / y / z浮点搜索基准坐标(覆盖命令源坐标),同时限制本维度
dx / dy / dz浮点以基准点为角的体积,负值自动纠正方向
x_rotation角度区间,如 -90..90pitch 区间,按 MathHelper.wrapDegrees 环绕
y_rotation同上yaw 区间
limit正整数最多选几个;@s 上不允许
sortnearest / furthest / random / arbitrary结果排序;@s 上不允许
gamemodesurvival / creative / …,可加 !玩家游戏模式;会把"允许非玩家"关掉
team队伍名,可加 !;空串表示"无队伍"队伍匹配(只对 LivingEntity 生效)
type实体类型 ID(minecraft:zombie),可加 !实体类型;写玩家类型会关掉"允许非玩家"
tag命令标签名,可加 !;空串表示"没有任何标签"匹配 Entity#getCommandTags()
nbtSNBT 复合标签,可加 !匹配实体 NBT(玩家还会带上 SelectedItem)
scores{objective=区间, …}记分板分数匹配;任一目标不存在/没分数即不匹配
advancements{id=true, id={criterion=false}}进度匹配(1.12 及以上才注册,1.12.2 可用);会把"允许非玩家"关掉

重要提醒:本子工程的 fabric.mod.json 入口只挂了 BrigadierCommandsImpl::init / initClient,在整个仓库里搜不到对 EntitySelectorOptions.init() 的调用。也就是说 1.12.2 上这张选项表默认是空的,@e[name=…] 之类会抛"未知选项"。需要选项时请在自己的 mod 初始化里先调用一次 EntitySelectorOptions.init()(幂等,重复调用无副作用)。

GameProfileArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.GameProfileArgument

作用:玩家档案参数(game_profile):名字、UUID 或玩家选择器,解析成 GameProfile 集合(用档案缓存,不需要实体在线)。

成员作用需要(参数 / 前置条件)返回
gameProfiles()工厂—GameProfileArgument
parse(StringReader reader)@ 开头按选择器解析(不允许非玩家),否则读到空格为止当名字—GameProfileArgument.Result;选择器含非玩家时抛 EntityArgument.NOT_PLAYER_EXCEPTION
getGameProfiles(CommandContext<CommandSourceStack> ctx, String arg)取值名字不在档案缓存里时抛 UNKNOWN_PLAYER_EXCEPTION(argument.player.unknown);选择器选不到玩家时抛 argument.entity.notfound.playerCollection<GameProfile>
listSuggestions(…)补全:选择器名 + 在线玩家名需 SharedSuggestionProviderCompletableFuture<Suggestions>
getExamples()示例:Player、0123、UUID、@e—Collection<String>
GameProfileArgument.SelectorResult(嵌套类)用 EntitySelector 实现的 Result构造时传选择器实例
GameProfileArgument.Result(函数式接口)延迟求值create(CommandSourceStack source) 可能抛 CommandSyntaxExceptionCollection<GameProfile>

参数类型:文本 ​

TextArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.TextArgument

作用:JSON 文本组件参数(component):"hello"、{"text":"hi","color":"red"} 这类写法,解析成 TextComponent。

成员作用需要(参数 / 前置条件)返回
text()工厂—TextArgument
parse(StringReader reader)取 reader.getRemaining() 整体当 JSON 解析;不推进游标,所以这个参数实际上只能放在命令末尾(贪婪)—TextComponent;JSON 非法或解析结果为空时抛 INVALID_TEXT_EXCEPTION(argument.component.invalid),并把 JSON 解析错误的 cause 消息塞进参数
getText(CommandContext<?> ctx, String arg)取值—TextComponent
getExamples()示例:"hello world"、""、转义双引号包着的 JSON、[""]—Collection<String>
INVALID_TEXT_EXCEPTION公开异常常量—DynamicCommandExceptionType

MessageArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.MessageArgument

作用:聊天消息参数(message):取剩下所有文本,但保留其中的 @p / @e 选择器,等到真正取文本时再按命令源的权限展开成玩家名字。/msg、/say 这类命令需要它。

成员作用需要(参数 / 前置条件)返回
message()工厂—MessageArgument
parse(StringReader reader)取剩下全部文本并扫描 @ 选择器(转调 Message.parseText)—MessageArgument.Message
getMessage(CommandContext<CommandSourceStack> ctx, String arg)取值并展开成文本组件命令源权限 ≥ 2 才展开选择器,否则整段当普通文本TextComponent;选择器解析失败时抛 CommandSyntaxException
getExamples()示例:Hello world!、foo、@e、Hello @p :)—Collection<String>
MessageArgument.Message(嵌套类)原始文本 + 选择器片段表构造 Message(String text, Part[] parts)实例
Message.toText(CommandSourceStack source, boolean op)展开成文本:op 为假或没有片段时直接返回整段字面量source 非 nullTextComponent
Message.parseText(StringReader reader, boolean op)(静态)扫描文本里的 @ 选择器;op 为假时不扫描、直接吃掉剩余输入—Message;选择器语法错误但不是"缺选择器/未知选择器"时原样外抛
MessageArgument.Part(嵌套类)一个选择器片段:getStart() / getEnd()(相对整段文本的偏移)与 getText(CommandSourceStack source)source 非 nullint / int / TextComponent

参数类型:NBT ​

NbtCompoundArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.NbtCompoundArgument

作用:SNBT 复合标签参数(nbt):{}、{foo:bar}、{a:[1,2],b:{c:"d"}},解析成 NbtCompound。

成员作用需要(参数 / 前置条件)返回
nbtCompound()工厂—NbtCompoundArgument
parse(StringReader reader)交给 new SnbtParser(reader).readCompound()reader 停在 { 上NbtCompound;语法错误抛 SnbtParser 的各类异常(见该类的表)
getNbtCompound(CommandContext<S> ctx, String arg)取值—NbtCompound
getExamples()示例:{}、{foo=bar}—Collection<String>
INVALID_NBT_EXCEPTION公开异常常量(argument.nbt.invalid);注意 parse 自己不抛它,实际抛的是 SnbtParser 的异常—DynamicCommandExceptionType

参数类型:记分板 ​

ObjectiveArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.ObjectiveArgument

作用:记分板目标名参数(objective),getObjective 会顺手帮你查表。

成员作用需要(参数 / 前置条件)返回
objective()工厂—ObjectiveArgument
parse(StringReader reader)读一个非引号字符串当目标名名字长度不得超过 16String;超长时回退游标并抛 NAME_TOO_LONG_EXCEPTION(commands.scoreboard.objectives.add.longName)
getObjective(CommandContext<CommandSourceStack> ctx, String arg)按名字查目标命令源必须有世界ScoreboardObjective;查不到抛 arguments.objective.notFound
getWritableObjective(CommandContext<CommandSourceStack> ctx, String arg)查目标并检查可写(只读判据不可写)同上ScoreboardObjective;只读时抛 arguments.objective.readonly
listSuggestions(…)补全:当前记分板里的目标名;命令源是 SharedSuggestionProvider 时改为向它请求(即客户端会问服务端)—CompletableFuture<Suggestions>
getExamples()示例:foo、*、012—Collection<String>
NAME_TOO_LONG_EXCEPTION公开异常常量—DynamicCommandExceptionType

ScoreHolderArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.ScoreHolderArgument

作用:记分项持有者参数(score_holder):玩家名、*(全部)、或实体选择器,解析成"名字列表"。

成员作用需要(参数 / 前置条件)返回
scoreHolder()工厂:单个持有者—ScoreHolderArgument(multiple = false)
scoreHolders()工厂:多个持有者—ScoreHolderArgument(multiple = true)
new ScoreHolderArgument(boolean multiple)直接构造—实例
parse(StringReader reader)@ 开头按选择器解析(单个模式下选择器上限 > 1 就报错),* 走"全部"分支,否则当名字—ScoreHolderArgument.Result;单个模式选了多个时抛 EntityArgument.TOO_MANY_ENTITIES_EXCEPTION
getScoreHolder(CommandContext<CommandSourceStack> ctx, String arg)取第一个名字—String;集合为空抛 argument.entity.notfound.entity
getScoreHolders(CommandContext<CommandSourceStack> ctx, String arg)取名字集合,* 视为空—Collection<String>;为空抛 argument.entity.notfound.entity
getScoreHoldersOrAll(CommandContext<CommandSourceStack> ctx, String arg)同上的 * 版本:回退成"记分板里所有有分数的人"—Collection<String>
getScoreHolders(CommandContext<CommandSourceStack> ctx, String arg, Supplier<Collection<String>> fallback)自己给 * 的回退集合fallback 非 null;回退结果为空抛 argument.scoreHolder.emptyCollection<String>;结果为空抛 argument.entity.notfound.entity
getExamples()示例:Player、0123、*、@e—Collection<String>
SCORE_HOLDER_SUGGESTIONS现成的补全器(按选择器语法解析后补在线玩家名)—SuggestionProvider<CommandSourceStack>
ScoreHolderArgument.Result(函数式接口)延迟求值create(CommandSourceStack source, Supplier<Collection<String>> fallback) 可能抛异常Collection<String>
ScoreHolderArgument.SelectorResult(嵌套类)用 EntitySelector 实现的 Result:玩家取名字,其他实体取 UUID 字符串构造时传选择器实例
ScoreHolderArgument.Serializer(嵌套类)网络序列化:1 字节标志位(1=multiple)见"参数序列化"ArgumentSerializer<ScoreHolderArgument>

ScoreboardCriterionArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.ScoreboardCriterionArgument

作用:记分板判据参数(objective_criteria),比如 dummy、health、minecraft:foo。

成员作用需要(参数 / 前置条件)返回
criterion()工厂—ScoreboardCriterionArgument
parse(StringReader reader)读到空格为止,再按名字查 ScoreboardCriterion.BY_NAME—ScoreboardCriterion;查不到回退游标并抛 INVALID_CRITERION_EXCEPTION(argument.criteria.invalid)
getCriterion(CommandContext<CommandSourceStack> ctx, String arg)取值—ScoreboardCriterion
listSuggestions(…)补全:所有判据名—CompletableFuture<Suggestions>
getExamples()示例:foo、foo.bar.baz、minecraft:foo—Collection<String>
INVALID_CRITERION_EXCEPTION公开异常常量—DynamicCommandExceptionType

ScoreboardDisplaySlotArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.ScoreboardDisplaySlotArgument

作用:记分板显示位置参数(scoreboard_slot),例如 sidebar、list、below_name,解析成原版的槽位数字。

成员作用需要(参数 / 前置条件)返回
displaySlot()工厂—ScoreboardDisplaySlotArgument
parse(StringReader reader)读一个非引号字符串,交给 Scoreboard.getDisplaySlot(name)—Integer;返回 -1(未知槽位)时回退游标并抛 INVALID_DISPLAY_SLOT_EXCEPTION(argument.scoreboardDisplaySlot.invalid)
getDisplaySlot(CommandContext<?> ctx, String arg)取值(返回原始 int)—int
listSuggestions(…)补全:Scoreboard.getDisplayLocations()—CompletableFuture<Suggestions>
getExamples()示例:sidebar、foo.bar—Collection<String>
INVALID_DISPLAY_SLOT_EXCEPTION公开异常常量—DynamicCommandExceptionType

OperationArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.OperationArgument

作用:记分板运算参数(operation):=、+=、-=、*=、/=、%=、<、>、><(交换)。

成员作用需要(参数 / 前置条件)返回
operation()工厂—OperationArgument
parse(StringReader reader)读到空格为止再查表输入为空抛 arguments.operation.invalid;符号不认识同样抛它OperationArgument.Operation
getOperation(CommandContext<?> ctx, String arg)取值—Operation
listSuggestions(…)补全:九个运算符号—CompletableFuture<Suggestions>
getExamples()示例:=、>、<—Collection<String>
OperationArgument.Operation(函数式接口)对两个 ScoreboardScore 执行运算(apply(score1, score2))/= 与 %= 在除数为 0 时抛 arguments.operation.div0无(void)

< 取较小值、> 取较大值、>< 交换两个分数;除法与取模用 MathHelper.floorDiv / floorMod(向下取整,与 Java 的 / 不同)。

TeamArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.TeamArgument

作用:队伍名参数(team)。

成员作用需要(参数 / 前置条件)返回
team()工厂—TeamArgument
parse(StringReader reader)读一个非引号字符串—String
getTeam(CommandContext<CommandSourceStack> ctx, String arg)按名字查队伍命令源必须有世界Team;查不到抛 team.notFound
listSuggestions(…)补全:命令源的 getTeams()需 SharedSuggestionProvider,否则空建议CompletableFuture<Suggestions>
getExamples()示例:foo、123—Collection<String>

参数类型:杂项 ​

IdentifierArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.IdentifierArgument

作用:命名空间 ID 参数(resource_location),例如 foo、minecraft:stone。

成员作用需要(参数 / 前置条件)返回
identifier()工厂—IdentifierArgument
parse(StringReader reader)交给 IdentifierParser.parse—NamespacedIdentifier(OSL 的 ID 类型);非法时抛 argument.id.invalid
getNamespacedIdentifier(CommandContext<?> ctx, String arg)取 OSL 的 ID—NamespacedIdentifier
getIdentifier(CommandContext<?> ctx, String arg)取原版 Identifier—Identifier(内部 new Identifier(id.toString()))
getExamples()示例:foo、foo:bar、012—Collection<String>
UNKNOWN_ID_EXCEPTION公开异常常量(argument.id.unknown);parse 不用它,供你自己在查表失败时使用—DynamicCommandExceptionType

IdentifierParser ​

Reference: net.ornithemc.osl.commands.api.command.argument.IdentifierParser

作用:OSL 命名空间 ID 的解析工具,IdentifierArgument、ItemParser、BlockStateParser、StatusEffectArgument 等都靠它读 ID。

成员作用需要(参数 / 前置条件)返回
parse(StringReader reader)读尽可能长的合法 ID 字符,再交给 NamespacedIdentifiers.parse—NamespacedIdentifier;不合法时回退游标并抛 argument.id.invalid
parseIdentifier(StringReader reader)同上的原版类型版本同上Identifier

ColorArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.ColorArgument

作用:颜色参数(color),取值是 Formatting(red、gold、reset …)。

成员作用需要(参数 / 前置条件)返回
color()工厂—ColorArgument
parse(StringReader reader)读一个非引号字符串,按 Formatting.byName 查—Formatting;查不到回退游标并抛 INVALID_COLOR_EXCEPTION(argument.color.invalid)
getColor(CommandContext<?> ctx, String arg)取值—Formatting
listSuggestions(…)补全:Formatting.getNames(true, false)(只要颜色名,不含 bold 之类格式)—CompletableFuture<Suggestions>
getExamples()示例:red、green—Collection<String>
INVALID_COLOR_EXCEPTION公开异常常量—DynamicCommandExceptionType

EnchantmentArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.EnchantmentArgument

作用:附魔参数(item_enchantment),例如 unbreaking、silk_touch。

成员作用需要(参数 / 前置条件)返回
enchantment()工厂—EnchantmentArgument
parse(StringReader reader)读 ID 后查 Enchantment.REGISTRY—Enchantment;查不到回退游标并抛 UNKNOWN_ENCHANTMENT_EXCEPTION(enchantment.unknown)
getEnchantment(CommandContext<?> ctx, String arg)取值—Enchantment
listSuggestions(…)补全:注册表里所有附魔 ID—CompletableFuture<Suggestions>
getExamples()示例:unbreaking、silk_touch—Collection<String>
UNKNOWN_ENCHANTMENT_EXCEPTION公开异常常量—DynamicCommandExceptionType

StatusEffectArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.StatusEffectArgument

作用:状态效果参数(mob_effect),例如 speed、minecraft:poison。

成员作用需要(参数 / 前置条件)返回
effect()工厂—StatusEffectArgument
parse(StringReader reader)读 ID 后查 StatusEffect.REGISTRY—StatusEffect;查不到回退游标并抛 UNKNOWN_STATUS_EFFECT_EXCEPTION(effect.effectNotFound)
getEffect(CommandContext<?> ctx, String arg)取值—StatusEffect
listSuggestions(…)补全:注册表里所有效果 ID—CompletableFuture<Suggestions>
getExamples()示例:spooky、effect—Collection<String>
UNKNOWN_STATUS_EFFECT_EXCEPTION公开异常常量—DynamicCommandExceptionType

SlotArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.SlotArgument

作用:物品槽位参数(item_slot):只能用具名槽位,解析成原版槽位号。

成员作用需要(参数 / 前置条件)返回
slot()工厂—SlotArgument
parse(StringReader reader)读一个非引号字符串查表只接受下表里的名字Integer;不认识时抛 slot.unknown(源码的 getExamples() 里有 "12",但表里没有纯数字键,写数字会报错)
getSlot(CommandContext<CommandSourceStack> context, String arg)取值—int
listSuggestions(…)补全:全部具名槽位—CompletableFuture<Suggestions>
getExamples()示例—Collection<String>

槽位名与编号(源码里的完整映射):

名字编号名字编号
container.0…container.530…53weapon / weapon.mainhand98
hotbar.0…hotbar.80…8weapon.offhand99
inventory.0…inventory.269…35armor.feet / armor.legs / armor.chest / armor.head100 / 101 / 102 / 103
enderchest.0…enderchest.26200…226horse.saddle / horse.armor / horse.chest400 / 401 / 499
villager.0…villager.7300…307——
horse.0…horse.14500…514——

参数类型:数值区间 ​

RangeArgument ​

Reference: net.ornithemc.osl.commands.api.command.argument.RangeArgument

作用:数值区间参数(int_range / float_range):5、1..5、..10、3.. 四种写法。既是接口又是工厂,两个实现是嵌套的 Ints / Floats。

成员作用需要(参数 / 前置条件)返回
intRange()(静态)工厂:整数区间—RangeArgument.Ints
floatRange()(静态)工厂:浮点区间—RangeArgument.Floats
getIntRange(CommandContext<CommandSourceStack> ctx, String arg)(静态)取整数区间—NumberRange.Ints
getFloatRange(CommandContext<CommandSourceStack> ctx, String arg)(静态)取浮点区间—NumberRange.Floats
RangeArgument.Ints.parse(StringReader reader)转调 NumberRange.Ints.fromString—NumberRange.Ints;语法错误抛 argument.range.empty / 内置的 readerInvalidInt
RangeArgument.Ints.getExamples()示例:0..5、0、-5、-100..、..100—Collection<String>
RangeArgument.Floats.parse(StringReader reader)转调 NumberRange.Floats.fromString—NumberRange.Floats
RangeArgument.Floats.getExamples()示例:0..5.2、0、-5.4、-100.76..、..100—Collection<String>
RangeArgument.Serializer(抽象类)+ Ints.Serializer / Floats.Serializer网络序列化:这两个类型没有额外状态,序列化写空、反序列化直接 new见"参数序列化"ArgumentSerializer

NumberRange ​

Reference: net.ornithemc.osl.commands.api.command.argument.NumberRange

作用:数值区间模型(抽象类,Floats / Ints 两个实现),支持区间匹配与"按平方值匹配"(比较距离时省一次开方)。RangeArgument 与 EntitySelector 的 distance / level 都用它。

成员作用需要(参数 / 前置条件)返回
getMin() / getMax()两端(可能为 null,表示无界)—T(Float / Integer)
isAny()两端都为空 = 不作限制—boolean
toJson()序列化成 JSON(无限制 → JsonNull;上下界相同 → 单值;否则 {min,max})—JsonElement
NumberRange.Floats.ANY / NumberRange.Ints.ANY无限制常量—对应实例
NumberRange.Floats.ofAtLeast(float min) / NumberRange.Ints.of(int v) / NumberRange.Ints.ofAtLeast(int min)便捷构造—对应实例
NumberRange.Floats.matches(float value) / matchesSquare(double value)判定 / 按平方值判定(用于距离比较)—boolean
NumberRange.Ints.matches(int value) / matchesSquare(long value)同上—boolean
fromString(StringReader reader) / fromString(StringReader reader, Function<T, T> processor)从命令文本解析区间;processor 可先对数值做变换(如把角度规范化)reader 非空,否则抛 EMPTY_EXCEPTION(argument.range.empty)对应实例;min > max 抛 DECIMAL_NOT_ALLOWED_EXCEPTION(argument.range.swapped)
fromJson(JsonElement json)从 JSON 解析—对应实例;json 为空时返回 ANY
NumberRange.Factory<T, R> / NumberRange.FactoryFromReader<T, R>(函数式接口)自定义子类时用—实例
EMPTY_EXCEPTION / DECIMAL_NOT_ALLOWED_EXCEPTION公开异常常量—SimpleCommandExceptionType

WrappedNumberRange ​

Reference: net.ornithemc.osl.commands.api.command.argument.WrappedNumberRange

作用:可以"环绕"(wrap)的浮点区间,用于 x_rotation / y_rotation 这种 -180..180 会绕圈的取值。

成员作用需要(参数 / 前置条件)返回
new WrappedNumberRange(Float min, Float max)构造(两端可空)—实例
getMin() / getMax()两端—Float(可能 null)
fromString(StringReader reader, boolean doublePrecision, Function<Float, Float> processor)(静态)解析区间;doublePrecision 决定是否允许小数点;processor 通常传 MathHelper::wrapDegreesreader 非空WrappedNumberRange;空输入抛 NumberRange.EMPTY_EXCEPTION;整数模式出现 . 抛 ERROR_INTS_ONLY(argument.range.ints);数值非法抛内置的 readerInvalidInt / readerInvalidDouble
ANY无限制常量—WrappedNumberRange
ERROR_INTS_ONLY公开异常常量—SimpleCommandExceptionType

注意:它不是 NumberRange 的子类,只是一个轻量的"可空上下界 + 环绕变换"容器;环形匹配的判断在 EntitySelectorParser 里做(min > max 时按"跨 0 点"处理)。

参数序列化(网络同步) ​

服务端会把自己的命令树同步给客户端,客户端才能给服务端命令做补全。树里每个参数节点都要能"序列化类型 + 反序列化类型",这套机制就是本节。

ArgumentSerializer ​

Reference: net.ornithemc.osl.commands.api.command.argument.serdes.ArgumentSerializer

作用:参数类型的序列化器接口。自定义参数类型想在客户端补全里出现,就必须为它提供一个实现并注册进 ArgumentTypes。

成员作用需要(参数 / 前置条件)返回
serialize(T arg, PacketBuffer buffer)把参数类型的状态写进包该类型已用 ArgumentTypes.register 注册无(void)
deserialize(PacketBuffer buffer)从包里还原参数类型客户端与服务端的注册必须完全一致(同样的 ID、同样的字段顺序)T

ArgumentTypes ​

Reference: net.ornithemc.osl.commands.api.command.argument.serdes.ArgumentTypes

作用:参数类型 ↔ 序列化器的双向注册表,同时提供包的读写入口。内置的 31 个原版风格参数(minecraft:entity、minecraft:block_pos …)和 5 个 Brigadier 参数(brigadier:integer …)都由它登记。

成员作用需要(参数 / 前置条件)返回
register(NamespacedIdentifier identifier, Class<T> type, ArgumentSerializer<T> serializer)注册一个参数类型type 与 identifier 都不能重复,否则抛 IllegalArgumentException无(void)
init()注册全部内置类型(内部先调 BrigadierArgumentSerializers.init())见下方警告无(void)
serialize(PacketBuffer buffer, T argument)写"类型 ID + 类型状态"类型未注册时打一条 error 日志并写入空 ID无(void)
deserialize(PacketBuffer buffer)读回参数类型ID 不认识时打 error 日志ArgumentType<?>;失败时返回 null(随后该节点整棵被丢弃)
ArgumentTypes.Entry<T>(嵌套类)一条注册记录:public final Class<T> type / NamespacedIdentifier identifier / ArgumentSerializer<T> serializer—实例

内置注册名(命名空间默认 minecraft):entity、game_profile、block_pos、column_pos、vec3、vec2、block_state、block_predicate、legacy_block_state、legacy_block_predicate、item_stack、item_predicate、color、component、message、nbt、objective、objective_criteria、operation、rotation、scoreboard_slot、score_holder、swizzle、team、item_slot、resource_location、mob_effect、entity_anchor、int_range、float_range、item_enchantment。

重要提醒:与 EntitySelectorOptions.init() 一样,本子工程里搜不到对 ArgumentTypes.init() 的调用(入口点只挂了 BrigadierCommandsImpl::init)。这意味着 1.12.2 上内置参数类型的序列化表默认是空的:服务端同步命令树时每个参数节点都会命中"未注册"分支(写空 ID),客户端读到后 deserialize 返回 null、该节点被丢弃。要让同步生效,请在自己的 mod 初始化里先调用一次 ArgumentTypes.init()。

BrigadierArgumentSerializers ​

Reference: net.ornithemc.osl.commands.api.command.argument.serdes.BrigadierArgumentSerializers

作用:把 Brigadier 自带的 5 个参数类型(bool、float、double、integer、string)注册进 ArgumentTypes,命名空间为 brigadier;另外提供 "min/max 标志位" 的打包工具。

成员作用需要(参数 / 前置条件)返回
init()注册上面 5 个类型(被 ArgumentTypes.init() 调用)重复调用会因重复注册抛 IllegalArgumentException无(void)
minMaxFlags(boolean min, boolean max)把"有下界/有上界"打包成 1 字节—byte(1=min,2=max)
hasMin(byte flags) / hasMax(byte flags)读标志位—boolean

EmptyArgumentSerializer ​

Reference: net.ornithemc.osl.commands.api.command.argument.serdes.EmptyArgumentSerializer

作用:适用于"没有状态"的参数类型:序列化不写任何东西,反序列化直接调用你给的构造方法。绝大多数内置参数类型(方块、物品、坐标、玩家…)都用它。

成员作用需要(参数 / 前置条件)返回
new EmptyArgumentSerializer(Supplier<T> constructor)构造constructor 非 null,且必须返回默认配置的实例实例
serialize(T arg, PacketBuffer buffer)什么都不写—无(void)
deserialize(PacketBuffer buffer)调 constructor.get()—T

FloatArgumentSerializer ​

Reference: net.ornithemc.osl.commands.api.command.argument.serdes.FloatArgumentSerializer

作用:FloatArgumentType 的序列化器:写 1 字节 min/max 标志位 + 存在的边界值。

成员作用需要(参数 / 前置条件)返回
serialize(FloatArgumentType arg, PacketBuffer buffer)写标志与 getMinimum() / getMaximum()(等于 ±Float.MAX_VALUE 视为"没有该界")—无(void)
deserialize(PacketBuffer buffer)按标志读回边界并 FloatArgumentType.floatArg(min, max)—FloatArgumentType

DoubleArgumentSerializer ​

Reference: net.ornithemc.osl.commands.api.command.argument.serdes.DoubleArgumentSerializer

作用:DoubleArgumentType 的序列化器,逻辑与浮点版相同(边界判定用 ±Double.MAX_VALUE)。

成员作用需要(参数 / 前置条件)返回
serialize(DoubleArgumentType arg, PacketBuffer buffer)写标志与边界—无(void)
deserialize(PacketBuffer buffer)读回并 DoubleArgumentType.doubleArg(min, max)—DoubleArgumentType

IntegerArgumentSerializer ​

Reference: net.ornithemc.osl.commands.api.command.argument.serdes.IntegerArgumentSerializer

作用:IntegerArgumentType 的序列化器(边界判定用 Integer.MIN_VALUE / MAX_VALUE)。

成员作用需要(参数 / 前置条件)返回
serialize(IntegerArgumentType arg, PacketBuffer buffer)写标志与边界—无(void)
deserialize(PacketBuffer buffer)读回并 IntegerArgumentType.integer(min, max)—IntegerArgumentType

StringArgumentSerializer ​

Reference: net.ornithemc.osl.commands.api.command.argument.serdes.StringArgumentSerializer

作用:StringArgumentType 的序列化器:只写一个枚举值(SINGLE_WORD / QUOTABLE_PHRASE / GREEDY_PHRASE)。

成员作用需要(参数 / 前置条件)返回
serialize(StringArgumentType arg, PacketBuffer buffer)写 arg.getType()—无(void)
deserialize(PacketBuffer buffer)按枚举还原成 word() / string() / greedyString()枚举值不认识时退化成 greedyString()StringArgumentType

建议补全 ​

SuggestionProviders ​

Reference: net.ornithemc.osl.commands.api.command.SuggestionProviders

作用:具名补全器注册表。Brigadier 的 SuggestionProvider 是匿名对象,没法过网络;这里的做法是给每个补全器一个 NamespacedIdentifier,同步时只发 ID,客户端查表拿到同一个实现。1.12.2 上"由服务端算补全"就是靠 ASK_SERVER 实现的。

成员作用需要(参数 / 前置条件)返回
register(NamespacedIdentifier identifier, SuggestionProvider<SharedSuggestionProvider> provider)注册一个具名补全器ID 不能重复,否则抛 IllegalArgumentException包装后的 SuggestionProvider<S>(IdentifiableSuggestionProvider)
get(NamespacedIdentifier identifier)按 ID 取补全器—SuggestionProvider<SharedSuggestionProvider>;查不到时回退为 ASK_SERVER
getIdentifier(SuggestionProvider<SharedSuggestionProvider> provider)取补全器的 ID—NamespacedIdentifier;未包装过的补全器一律返回 minecraft:ask_server
getIdentifiable(SuggestionProvider<SharedSuggestionProvider> provider)保证返回一个可同步的补全器—已包装的原样返回,否则返回 ASK_SERVER
ASK_SERVER预置补全器:转调 ctx.getSource().requestSuggestions(ctx, builder)(客户端会向服务端发请求)命令源必须实现 SharedSuggestionProviderSuggestionProvider<SharedSuggestionProvider>
SuggestionProviders.IdentifiableSuggestionProvider(嵌套类)带 ID 的包装器构造 IdentifiableSuggestionProvider(NamespacedIdentifier identifier, SuggestionProvider<SharedSuggestionProvider> provider)实例;getSuggestions(ctx, builder) 转发给内部实现

用法:ServerCommands.argument("目标", EntityArgument.players()).suggests(SuggestionProviders.ASK_SERVER)。若你要自定义补全且希望它在客户端也生效,必须通过 register 拿到包装后的实例再用。

辅助工具 ​

Commands ​

Reference: net.ornithemc.osl.commands.api.Commands

作用:两个小工具:把"解析器"变成 Brigadier 的字符串校验 Predicate(补全时用来剔除非法候选),以及"只吃 reader 不回值"的解析器接口。

成员作用需要(参数 / 前置条件)返回
validator(Commands.Parser parser)造一个 Predicate<String>:能完整解析就 true,抛 CommandSyntaxException 就 falseparser 非 nullPredicate<String>;典型用法 Commands.validator(this::parse)
Commands.Parser(函数式接口)解析一段文本但不返回结果实现 parse(StringReader reader),可能抛 CommandSyntaxException无(void)

SnbtParser ​

Reference: net.ornithemc.osl.commands.api.command.argument.SnbtParser

作用:SNBT({a:1b,b:[1,2],c:"x"})解析器,NbtCompoundArgument 与实体选择器的 nbt 选项都用它。

成员作用需要(参数 / 前置条件)返回
new SnbtParser(StringReader reader)构造reader 非 null实例
parse(String rawNbt)(静态)一次性解析整段 SNBT,且要求没有多余字符rawNbt 是完整复合标签NbtCompound;尾部还有内容抛 TRAILING_DATA_EXCEPTION(argument.nbt.trailing)
readCompound()从当前位置读一个 {…}reader 停在 { 上NbtCompound;键/值缺失抛 KEY_EXPECTED_EXCEPTION / VALUE_EXPECTED_EXCEPTION
readKey() / readElement() / readValue() / readListOrArray()(protected)子类可复用的分段读取—String / NbtElement
TRAILING_DATA_EXCEPTION / KEY_EXPECTED_EXCEPTION / VALUE_EXPECTED_EXCEPTION / MIXED_LIST_TYPE_EXCEPTION / MIXED_ARRAY_TYPE_EXCEPTION / INVALID_ARRAY_EXCEPTION公开异常常量—各自的 Brigadier 异常类型

支持的写法:双引号字符串或不带引号的裸串、整数 1、带后缀的 1b/1s/1l/1f/1d、浮点 1.5 / 1.5e3、true/false(存成 NbtByte)、[1,2] 列表(元素类型必须一致,否则 MIXED_LIST_TYPE_EXCEPTION)、[B;…]/[I;…]/[L;…] 数组(L 型数组从 1.12 起才注册,1.12.2 可用)。

键值分隔符只接受 :(源码是 expect(':')),所以 NbtCompoundArgument.getExamples() 里的 {foo=bar} 实际会解析失败,写 {foo:bar} 才对。

NbtUtils ​

Reference: net.ornithemc.osl.commands.api.command.argument.NbtUtils

作用:NBT 的"部分匹配"比较,方块谓词、物品谓词、实体选择器的 nbt 选项都靠它。

成员作用需要(参数 / 前置条件)返回
matches(NbtElement expected, NbtElement actual, boolean partialListMatches)判断 actual 是否包含 expected:复合标签只比较 expected 里出现的键;列表在 partialListMatches 为真时按"每个期望元素都能在实参列表里找到"匹配(不要求顺序、长度可多),为假时退化成 equals;类型必须一致;任一侧为 null 直接算匹配两个参数都可为 nullboolean

注意事项汇总 ​

写代码前值得先扫一眼这几条,它们都是"读源码才能发现"的行为:

  1. ArgumentTypes.init() 与 EntitySelectorOptions.init() 在本子工程里没有被框架调用,需要你自己在 mod 初始化阶段调一次(两者都幂等)。否则参数类型同步与 @e[选项] 都不工作。
  2. #标签 语法在 1.12.2 上不可用(allowTag 被硬编码为 false)。
  3. CommandSourceStack.requestSuggestions 返回 null,服务端命令源上不要指望 ASK_SERVER 能拿到补全 future。
  4. TextArgument 不推进 StringReader 游标,只能当最后一个参数用。
  5. Vec2f.equals(Vec2f) 是重载而非覆写;SlotArgument.getExamples() 里的 "12" 实际解析不了。
  6. 原版命令(/give 等)不在 Brigadier 树里;给自定义命令起同名不会覆盖原版,执行顺序是"先 Brigadier,未命中再原版"。
  7. 客户端命令每次进入世界都会重新触发 REGISTER_COMMANDS,监听器里不要做"只能做一次"的事。

基于 Ornithe Standard Libraries 0.24.0(MC 1.12.2)源码整理