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:

Battle Chain Demo

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

Easy NPC Demo

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).

Radical Cobblemon Trainers

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

Cobblemon
Radical Cobblemon Trainers API
Forge Config API Port (only on fabric)