Cobblemon Trainer Battle Commands (TBCS)
提供用于管理训练家并启动战斗的命令,可作为其他模组(如 Easy NPC)的接口。
此模组主要面向地图制作者和整合包开发者。
支持方
命令
tbcs
attach <trainerId> <entity>:将指定的训练家附加到实体上(一个训练家只能附加到一个实体)。附加关系不会在服务端重启后保留。
battle <battleFormat> <participants1>... vs <participants2>... [rules <battleRules>] [onwin <winCommands>]:在指定的参与者之间开始一场战斗,使用指定的战斗格式、规则和胜利命令(后两者为可选参数)。
reload <trainerId>:允许从任何配置的 训练家路径 重新加载单个训练家(使用原版的 /reload 命令可重新加载所有训练家)。
重要提示:自版本 0.14.0-beta 起,attach 命令仍然可用,但通常建议使用 as <trainerId> 参数(详见 参与者)。
所有命令都需要权限等级 2。
参与者
battle 命令支持多种参数类型来指定战斗参与者。这些包括 单一实体选择器(如 @s、@e[...,limit=1] 或 @p)、实体 UUID 和 训练家 ID。
此外,可选参数 as <trainerId> 可用于在战斗开始时立即将训练家附加到选定的实体上:
- 该参数可以跟随任何实体选择器之后,用于指定应在战斗开始时附加到该实体的训练家 ID
- 使用此参数等同于对目标实体调用
attach,并且使得显式调用 attach 变得多余(虽然 attach + battle 配合 battle ... <entity> as <trainerId> 仍可使用,但通常建议使用前者)
- 当与玩家选择器一起使用时(例如
@s as <trainerId>),玩家将以该训练家队伍的临时副本进入战斗(适合设置谜题)
- 当与其他训练家 ID 一起使用时(例如
<trainerId_1> as <trainerId_2>),则 trainerId_2 将被附加到 trainerId_1 当前附加的同一实体上(如果可能)
参数 as <traineId> 自版本 0.14.0-beta 起可用。
战斗规则
战斗规则由具有以下属性的 JSON 对象描述:
maxItemUses:指定每个参与者在战斗中可以使用物品的次数。
是的,目前只有这一个属性。
胜利命令
胜利命令也由 JSON 对象描述,但具有更动态的结构。一个胜利命令对象可以为每个 战斗阵营(即 1 或 2)定义一个属性,包含相应阵营获胜时要执行的命令数组(见下面的示例)。
此外,任何胜利命令都可以访问特殊的 选择器(类似于 @s 或 @e),允许在命令中选择任何战斗参与者。这些选择器的结构如下:@<n>,其中 <n> 指定相对于执行胜利命令一方的战斗参与者的 位置。
在讨论命令时,需要问一些重要的问题:谁在执行命令?在哪里执行?
胜利命令通常由服务器在所有战斗参与者的中心执行。虽然可以让战斗的任何参与者成为命令的 执行者,在这种情况下,该命令也将在该参与者的位置执行。
现在,正式描述已经结束,让我们来看...
示例
重要提示: 以下命令中使用的训练家(例如 tbcs:mytrainer1)仅作为示例。你必须提供自己的训练家或安装提供训练家的其他模组(见下方的 训练家 部分)。
tbcs attach tbcs:mytrainer1 @e[type=minecraft:villager,limit=1,sort=nearest]
将 tbcs:mytrainer1 附加到最近的村民。
tbcs battle GEN_9_SINGLES @s vs tbcs:mytrainer1
开始执行命令的玩家与 tbcs:mytrainer1(必须已附加到某个实体)之间的战斗。
tbcs battle GEN_9_SINGLES @s vs tbcs:mytrainer1 rules {maxItemUses: 1}
与上述相同,但限制每方的物品使用次数为 1。
tbcs battle GEN_9_SINGLES @s vs tbcs:mytrainer1 rules {maxItemUses: 1} onwin {1: ['give @1 minecraft:diamond']}
另一个例子,这次玩家在获胜时会获得一颗钻石(第一阵营的第一位参与者)。
tbcs battle GEN_9_SINGLES @s vs tbcs:mytrainer1 onwin {1: ['loot spawn ~ ~ ~ loot minecraft:chests/simple_dungeon']}
使用 give 的替代方案(通常会有更多奖励,但这取决于战利品表)。胜利命令将由服务器在所有战斗参与者的中心执行。要以玩家的身份执行命令(即在玩家头顶直接生成战利品),可以在 loot 命令前加上 @1(另见下面的示例)。
tbcs battle GEN_9_MULTI @s tbcs:mytrainer1 vs tbcs:mytrainer2 tbcs:mytrainer3 onwin {1: ['give @1 minecraft:diamond', '@2 say We got them!']}
位置选择器的示例。当第一阵营获胜(即玩家阵营)时,玩家将收到一颗钻石,而 tbcs:mytrainer1 会说“We got them!”。这也展示了命令可以从不同于服务器的不同来源执行(第二个命令将由 tbcs:mytrainer1 附加到的实体执行)。
tbcs battle GEN_9_MULTI @s tbcs:mytrainer1 vs tbcs:mytrainer2 tbcs:mytrainer3 onwin {1: ['give @1 minecraft:diamond', '@2 say We got them!'], 2: ['@3 tp ~ ~10 ~']}
我们可以通过为另一方添加 win 命令来扩展前面的示例,即当玩家所在方失败时执行这些命令。作为提醒,位置参数是相对于 win 命令的方的,并且从左到右排列。因此,从第二方执行的命令中,选择器的映射如下:
@1 -> tbcs:mytrainer2
@2 -> tbcs:mytrainer3
@3 -> @s
@4 -> tbcs:mytrainer1
作为参考,从第一方执行的命令会将选择器映射为:
@1 -> @s
@2 -> tbcs:mytrainer1
@3 -> tbcs:mytrainer2
@4 -> tbcs:mytrainer3
因此,第二方的 win 命令将在其所在方失败(即第二方获胜)时“惩罚”玩家,将玩家从其当前位置向上传送 10 个方块(该命令由玩家执行)。
tbcs battle GEN_9_SINGLES @s vs tbcs:mytrainer1 onwin {1: ['@2 say Not bad, but are you ready for this?!', 'tbcs attach tbcs:mytrainer2 @2', 'tbcs battle GEN_9_SINGLES @1 vs tbcs:mytrainer2 onwin {1: [\'give @1 minecraft:diamond\']}']}
这将一个战斗链接到另一个之后。让我们分解一下(所有这些都在玩家获胜时执行):
- 第一个命令将使
tbcs::mytrainer1 的训练家实体说:“不错,但你准备好迎接这个了吗?!”
- 第二个命令将另一个训练家
tbcs:mytrainer2 附加到与 tbcs:mytrainer1 相同的实体上
- 第三个命令随后立即启动玩家与
tbcs:mytrainer2 之间的另一场战斗。这场战斗也带有自己的 win 命令定义,奖励玩家一颗钻石。
查看命令的实际效果:

这可以无限重复。注意,win 命令嵌套得越深,就需要更多的反斜杠 (\) 来转义包围命令的单引号 (')。
tbcs battle GEN_9_SINGLES @s vs tbcs:mytrainer1 onwin {2: ['@1 say You need to practice more @2!'], 1: ['@2 say You got me. Take this @1', 'loot spawn ~ ~ ~ loot minecraft:chests/end_city_treasure']}
这里没有什么新内容。这是来自我测试的一个命令。
Easy NPC Example

注意:视频来自旧版本,训练家 ID 现在的结构略有不同(参见游戏内命令的建议),但功能相同。你可以在仓库中找到完整视频。
Trainers
Structure
训练家可以使用 json 定义,训练家模式由 RCTApi 提供,因此结构与我的另一个模组 Radical Cobblemon Trainers 基本相同(唯一的例外是 identity,此模组中也不存在,以及 battleFormat 和 battleRules,它们都是命令参数)。你可以在相应的文档中找到更多信息和示例。
Location
每当世界加载时,都会在所有的 trainerPaths 中搜索训练家文件,这是一个相对于世界目录的路径列表。所有训练家都将使用由其文件名派生的 id 进行注册。例如,假设我们的 Minecraft 安装如下(已缩短):
mods
config
trainers
bug_catcher.json
saves
My Cool World
Strong Trainers
Ash Ketchum.json
Boring World
...
其中 trainerPaths 定义为:["Strong Trainers", "../../trainers"]。
- 加载
My Cool World: 这将注册训练家 tbcs:bug_catcher 和 tbcs:ash_ketchum。
- 加载
Boring World: 这将仅注册训练家 tbcs:bug_catcher。
如果具有相同 id 的训练家(即不同文件夹但相同文件名)被多次注册,任何后续训练家的 id 后面都会附加一个计数器 (_n)。
Compat
此模组与其他依赖 RCTApi 的模组兼容。副本来自这些模组的训练家在安装这些模组时将自动注册到 tbcs(参见配置)。
Configuration
配置文件位于 config/tbcs-server.toml:
[Trainers]
#━━━━━━━━━━
#List of paths, relative to the world directory, to search for trainer
#json files when (re)loading a world.
#
#Default: ["trainers", "../trainers", "../../trainers"]
trainerPaths = ["trainers", "../trainers", "../../trainers"]
#━━━━━━━━━━
#List of mod ids from mods that also rely on RCTApi to define trainers.
#Copies of trainers from the listed mods will also be registered to TBCS.
#
#Default: ["rctmod"]
trainerMods = ["rctmod"]
[Commands]
#━━━━━━━━━━
#Elevated permission level for win commands.
#
#Default: 2
#Range: 1 ~ 4
winCommandsPermission = 2
Server Side Only API
从版本 0.14.0-beta 开始,API 版本将与常规模组一起分发(文件名中包含 api 后缀,例如 tbcs-api):
- 所有 API 功能仅限服务器端,可以使用任何
tbcs-api 版本安装(即客户端不需要安装 TBCS)
- 如果在服务器上安装了常规 TBCS 模组,则不应同时安装
tbcs-api,因为 TBCS 已经包含 API(这将要求客户端也安装 TBCS)
- 模组的 API 版本不提供任何命令,它本身不做任何事情(它仅为可能依赖 TBCS 的其他模组提供功能)
Dependencies
License
版权所有 (c) 2026 HDainester。详见 LICENSE.txt。
Cobblemon Trainer Battle Commands (TBCS)
Provides commands to manage trainers and start battles that can act as interface for other mods (e.g. Easy NPC).
This mod is mostly intended for map makers and modpack developers.
Supported By
Commands
tbcs
attach <trainerId> <entity>: Attaches the given trainer to the specified entity (a trainer will only ever be attached to one entity). The attachament does not persist on server restart.
battle <battleFormat> <participants1>... vs <participants2>... [rules <battleRules>] [onwin <winCommands>]: Starts a battle between the given participants with the specified battle format, rules and win commands (the latter two are optional).
reload <trainerId>: Allows to reload a single trainer from any of the configured trainer paths (use the vanilla /reload command to reload all trainers).
Important: Since version 0.14.0-beta, the attach command remains functional, but using the as <trainerId> argument is generally advised (see Participants for details).
All commands require a permission level of 2.
Participants
The battle command supports multiple argument types to specify battle participants. These include single entity selectors (like @s, @e[...,limit=1] or @p), entity UUIDs and trainer ids.
In addition the optional argument as <trainerId> can be used to immediately attach a trainer to a selected entity on battle start:
- This argument can follow any entity selector and allows to specify the id of a trainer that should be attached to the entity at the start of the battle
- Using this argument is equivalent to invoking
attach for the targeted entity, and makes an explicit invocation of attach obsolete (while attach + battle still works using battle ... <entity> as <trainerId> is generally adviced)
- When used with a player selector (e.g.
@s as <trainerId>) the player will enter the battle with a temporary copy of that trainers team (enjoy setting up puzzles)
- When used with another trainer id (e.g.
<trainerId_1> as <trainerId_2>) then trainerId_2 will be attached to the same entity trainerId_1 is currently attached to (if possible)
The argument as <traineId> is available since version 0.14.0-beta.
Battle Rules
Battle rules are described by a json object with following properties:
maxItemUses: Specifies how many items each participant may use in a battle.
Yes, it is currently only this one property.
Win Commands
Win commands are also described by a json object but with a little bit more dynamic structure. A win command object may define a property for each battle side (i.e. 1 or 2), containing an array of commands to execute if the respective side wins (see examples below).
In addition any win command has access to special selectors (similar to @s or @e) that allow to select any battle participant within the command. These selectors are structured as follows: @<n> with <n> specifying a position of the battle participants, relative to the side the win command is executed for.
When talking about commands some important questions to ask are: Who is executing the command? And where is it executed?
Win commands are usually executed by the server in the center of all participants from a battle. Although it is possible to have any participant of a battle become the executor of a command, in which case that command is also executed at the position of that participant.
Now, with the formal description out of the way lets get to...
Examples
Important: The trainers used in the following commands (e.g. tbcs:mytrainer1) are just an example. You have to provide your own trainers or install another mod that provides any (see Trainers section below).
tbcs attach tbcs:mytrainer1 @e[type=minecraft:villager,limit=1,sort=nearest]
Attaches tbcs:mytrainer1 to the closest villager.
tbcs battle GEN_9_SINGLES @s vs tbcs:mytrainer1
Starts a battle between the player executing the command and tbcs:mytrainer1 (must be attached to an entity).
tbcs battle GEN_9_SINGLES @s vs tbcs:mytrainer1 rules {maxItemUses: 1}
Like above but limits the item usage of each side to 1.
tbcs battle GEN_9_SINGLES @s vs tbcs:mytrainer1 rules {maxItemUses: 1} onwin {1: ['give @1 minecraft:diamond']}
Another one of these but this time the player is granted a diamond on win (first participant of the first side).
tbcs battle GEN_9_SINGLES @s vs tbcs:mytrainer1 onwin {1: ['loot spawn ~ ~ ~ loot minecraft:chests/simple_dungeon']}
An alternative to using give (often with quite a few more rewards but it depends on the loot table). The win command will be executed by the server in the center of all battle participants. To execute the command as the player (i.e. to spawn the loot directly on top of them) one could precede the loot command with @1 (see also example below).
tbcs battle GEN_9_MULTI @s tbcs:mytrainer1 vs tbcs:mytrainer2 tbcs:mytrainer3 onwin {1: ['give @1 minecraft:diamond', '@2 say We got them!']}
An example for positional selectors. The player will receive a diamond and tbcs:mytrainer1 will say "We got them!" when the first side wins (i.e. player side). This also shows how a command can be executed from a different source other than the server (the second command will be executed by the entity that tbcs:mytrainer1 is attached to).
tbcs battle GEN_9_MULTI @s tbcs:mytrainer1 vs tbcs:mytrainer2 tbcs:mytrainer3 onwin {1: ['give @1 minecraft:diamond', '@2 say We got them!'], 2: ['@3 tp ~ ~10 ~']}
We can extend the previous example by adding win commands for the other side, i.e. these are executed if the player side loses. As a reminder, the positional arguments are relative to the side of the win command and go from left to right. So for commands executed from the second side the selectors are mapped as the following:
@1 -> tbcs:mytrainer2
@2 -> tbcs:mytrainer3
@3 -> @s
@4 -> tbcs:mytrainer1
For reference commands executed from the first side will map the selectors like this:
@1 -> @s
@2 -> tbcs:mytrainer1
@3 -> tbcs:mytrainer2
@4 -> tbcs:mytrainer3
So the win command of the second side will punish the player when their side loses (i.e. the second side wins) by teleporting the player 10 blocks up relative from their position (the command is executed by the player).
tbcs battle GEN_9_SINGLES @s vs tbcs:mytrainer1 onwin {1: ['@2 say Not bad, but are you ready for this?!', 'tbcs attach tbcs:mytrainer2 @2', 'tbcs battle GEN_9_SINGLES @1 vs tbcs:mytrainer2 onwin {1: [\'give @1 minecraft:diamond\']}']}
This one chains one battle after another. Lets break it down (all of these are executed when the player wins):
- the first command will cause the trainer entity of
tbcs::mytrainer1 to say "Not bad, but are you ready for this?!"
- the second command attaches another trainer,
tbcs:mytrainer2, to the same entity that tbcs:mytrainer1 is attached to
- the third command starts another battle between the player and
tbcs:mytrainer2 immediately afterwards. This battle also comes with its own definition for win commands rewarding the player with a diamond on win.
See the command in action:

This could be repeated indefinetely. Note that the further nested a win command is the more backslashes (\) are required to escape the apostrophes (') surrounding the command.
tbcs battle GEN_9_SINGLES @s vs tbcs:mytrainer1 onwin {2: ['@1 say You need to practice more @2!'], 1: ['@2 say You got me. Take this @1', 'loot spawn ~ ~ ~ loot minecraft:chests/end_city_treasure']}
There is nothing new here. It's a command from one of my tests.
Easy NPC Example

Note: The video is from an older version, trainer ids are now structured a little bit different (see suggestions of the commands ingame) but the functionality is the same. You can find the full video on the repository.
Trainers
Structure
Trainers can be defined using json, the trainer schema is provided by RCTApi hence the structure is mostly the same as from my other mod Radical Cobblemon Trainers (the only exceptions are identity, which does not exist in this mod as well as battleFormat and battleRules, which are both command arguments). You can find more information and an example in the corresponding documentation.
Location
Whenever a world is loaded trainer files will be searched in all trainerPaths, a list of paths relative to the world directory. All trainers will be registered with an id that will be derived from their file name. For example, lets assmume we have a minecraft installation like this (shortened):
mods
config
trainers
bug_catcher.json
saves
My Cool World
Strong Trainers
Ash Ketchum.json
Boring World
...
With trainerPaths being defined as: ["Strong Trainers", "../../trainers"].
- Loading
My Cool World: This will register the trainers tbcs:bug_catcher and tbcs:ash_ketchum.
- Loading
Boring World: This will only register the trainer tbcs:bug_catcher.
If a trainer with the same id (i.e. different folders but same file name) will be registered multiple times any subsequent trainers will have a counter (_n) appended to their id.
Compat
The mod is compatible with other mods that also rely on RCTApi. Copies of trainers from these mods will automatically be registered to tbcs when these mods are also installed (see config).
Configuration
The config file is located at config/tbcs-server.toml:
[Trainers]
#━━━━━━━━━━
#List of paths, relative to the world directory, to search for trainer
#json files when (re)loading a world.
#
#Default: ["trainers", "../trainers", "../../trainers"]
trainerPaths = ["trainers", "../trainers", "../../trainers"]
#━━━━━━━━━━
#List of mod ids from mods that also rely on RCTApi to define trainers.
#Copies of trainers from the listed mods will also be registered to TBCS.
#
#Default: ["rctmod"]
trainerMods = ["rctmod"]
[Commands]
#━━━━━━━━━━
#Elevated permission level for win commands.
#
#Default: 2
#Range: 1 ~ 4
winCommandsPermission = 2
Server Side Only API
As of version 0.14.0-beta an API version will be distributed along the regular mod (with the api suffix in the filename, e.g. tbcs-api):
- All API features are server side only and can be installed with any of the
tbcs-api releases (i.e. clients do not need to have TBCS installed)
- If the regular TBCS mod is installed on a server then
tbcs-api should not be installed alongside, since TBCS already contains the api (this will require clients to also have TBCS installed)
- The API version of the mod does not provide any commands, it does nothing by itself (it only offers functionalities for other mods that may depend on TBCS)
Dependencies
License
Copyright (c) 2026 HDainester. See LICENSE.txt for details.
评论 0
登录后参与评分
还没有评论,来抢沙发吧