Difference between revisions of "TrainCarts/Commands/Selectors"

From BergerHealer Wiki
Jump to navigation Jump to search
Line 8: Line 8:
 
To quickly view what options are available ingame, use a Traincarts command like <code>/train info --train @ptrain[</code> which will then auto-complete and show suggestions of supported options.
 
To quickly view what options are available ingame, use a Traincarts command like <code>/train info --train @ptrain[</code> which will then auto-complete and show suggestions of supported options.
  
Quick command examples:
+
=== Quick Command Examples ===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 28: Line 28:
 
| /train launch 0.5 --options 2 --train @train[tag=express]
 
| /train launch 0.5 --options 2 --train @train[tag=express]
 
| Launches the train with tag 'express' to a speed of 0.5 over 2 blocks distance
 
| Launches the train with tag 'express' to a speed of 0.5 over 2 blocks distance
 +
|}
 +
 +
== Options ==
 +
Multiple options can be specified, which are all AND-ed together. All number-based options support Minecraft range syntax: <code>a..b</code>. For example, <code>-5..5</code> (-5 to 5), <code>..6</code> (6 or less) and <code>12..</code> (12 or more). Prefixing the option value with <code>!</code> will make it evaluate as 'not'.
 +
 +
In all examples below, <code>@train</code> can be substituted for <code>@ptrain</code>.
 +
 +
=== Position Cuboid ===
 +
The <code>x/y/z</code> options specify where on the world trains should be selected. This specifies a cuboid range. The <code>dx/dy/dz</code> can also be specified to grow this cuboid. If only dx/dy/dz are specified, then the x/y/z of the sender is used. The <code>world</code> option can optionally be specified to operate on other worlds, or to run from a server terminal where no world can be inferred.
 +
 +
{| class="wikitable"
 +
|-
 +
| @train[x=10..12,y=23..56,z=-100..-80]
 +
| All trains in cuboid (10, 23, -100) -> (12, 56, 80)
 +
|-
 +
| @train[x=10,y=23,z=-100, dx=2,dy=33,dz=20]
 +
| Same as above, but specified with dx/dy/dz to 'grow' the cuboid
 +
|-
 +
| @train[x=10,y=10,z=10,dx=-2..2,dy=-10..10,dz=-2..2]
 +
| Complex use: grows the cuboid from point (10, 10, 10) in both directions. This becomes cuboid (8, 0, 8) -> (12, 20, 12)
 +
|-
 +
| @train[dx=-10..10,dy=-5..5,dz=-10..10]
 +
| Selects a cuboid around the sender (command block / player) of the command
 +
|-
 +
| @train[world=world_the_end,x=10,y=89,z=-20,dx=-10..10,dy=-10..10,dz=-10..10]
 +
| The world name to target can be used to target trains on other worlds
 +
|}
 +
 +
=== Distance ===
 +
The <code>distance</code> option filters trains based on distance to the sender, or a cuboid specified. This is a spherical distance.
 +
 +
{| class="wikitable"
 +
|-
 +
| @train[distance=..10]
 +
| All trains 10 blocks or less away from the sender
 +
|-
 +
| @train[distance=1000..]
 +
| All trains 1000 blocks away or more from the sender
 +
|-
 +
| @train[x=100,y=50,z=-100,distance=..5]
 +
| All trains 5 blocks or less away from coordinate (100, 50, -100)
 +
|-
 +
| @train[x=10,y=10,z=10,dx=50,dz=50,distance=..10]
 +
| All trains 10 blocks or less away from cuboid (10, 10, 10) -> (60, 10, 60)
 +
|}
 +
 +
=== Sort and Limit ===
 +
The <code>sort</code> and <code>limit</code> options can be used to pick a single result from many based on distance, or to pick limited results at random. '''Sort''' supports options <code>nearest</code>, <code>furthest</code> and <code>random</code>. '''Limit''' must be a natural integer.
 +
 +
{| class="wikitable"
 +
|-
 +
| @train[distance=..100,sort=random,limit=1]
 +
| Picks a single random train 100 blocks away or less
 +
|-
 +
| @train[distance=..100,sort=nearest,limit=2]
 +
| Picks at most 2 nearest trains, 100 blocks away or less
 +
|-
 +
| @train[distance=1000..,sort=furthest,limit=10]
 +
| Picks at most 10 trains furthest away, 1000 blocks distance away or more
 +
|}
 +
 +
=== Train Name ===
 +
The <code>name</code> option can be used to select trains by name, or a name pattern. Supports the same wildcard pattern rules as the [[TrainCarts/Signs#Remote_Control|remote control]] syntax.
 +
 +
{| class="wikitable"
 +
|-
 +
| @train[name=train12]
 +
| Selects train with name 'train12'
 +
|-
 +
| @train[name=Intercity*Express]
 +
| Selects trains with name starting with "Intercity" and ending with "Express"
 +
|-
 +
| @train[name=*]
 +
| Selects all trains on the world
 +
|}
 +
 +
=== Train Tags ===
 +
The <code>tag</code> option, which can be specified multiple times, can be used to select the tags assigned to trains and filter on those. Like the ''name'' option, this supports a wildcard pattern. This only checks that a particular tag is or isn't present, not that it is the only tag present.
 +
 +
{| class="wikitable"
 +
|-
 +
| @train[tag=mytag]
 +
| Selects trains that have tag 'mytag'
 +
|-
 +
| @train[tag=*fast,tag=!express]
 +
| Selects trains that have a tag ending with 'fast', but do not have tag 'express'
 +
|}
 +
 +
=== Passenger Count ===
 +
The <code>passengers</code> and <code>playerpassengers</code> options select the trains that meet a certain number of (player) passengers. This supports the range command to check for 'at least' a number of passengers, such as <code>@train[passengers=5..]</code>
 +
 +
=== Derailed ===
 +
The <code>derailed</code> option selects trains that have derailed. For example: <code>@train[derailed=1]</code> or <code>@train[derailed=true]</code>
 +
 +
=== Speed ===
 +
The <code>speed</code> option (alias: <code>velocity</code>) selects trains that move at a certain speed. This is the actual movement speed, which is at most the speed limit set for the train. Example: <code>@train[speed=0]</code> for trains that are not moving.
 +
 +
=== Miscellaneous Properties ===
 +
More might be added in the future, but the additional properties can be used to filter the selection
 +
 +
{| class="wikitable"
 +
|-
 +
| destination
 +
| [[TrainCarts/PathFinding|Destination]] set for the train
 +
|-
 +
| friction
 +
| Friction modifier of the train (default: 1)
 +
|-
 +
| gravity
 +
| Gravity modifier of the train (default: 1)
 +
|-
 +
| keepchunksloaded
 +
| Whether the train keeps nearby chunks loaded
 +
|-
 +
| speedlimit
 +
| Speed limit set for the train
 +
|-
 +
| ticket
 +
| Same checks as for tags, but for [[TrainCarts/Tickets|ticket names]] instead
 +
|-
 
|}
 
|}

Revision as of 20:34, 20 August 2022

« Go back

Introduction

Traincarts adds command selectors that can be used to target trains, or passengers of trains, similar to how vanilla minecraft's @e selector works. Besides the usual position-based selector filters, other train properties can be used to select trains that match specific criteria. These selectors can be used with other plugins. If a selector targets more than one player/train, then the entire command is repeated for every player/train argument.

Two selectors exist: @train and @ptrain. Both accept identical selector options, which will be discussed on the rest of this page.

To quickly view what options are available ingame, use a Traincarts command like /train info --train @ptrain[ which will then auto-complete and show suggestions of supported options.

Quick Command Examples

Example Description
/say hello @ptrain[distance=..5] Message "hello" to the passengers of all trains 5 blocks away or less
/kick @ptrain[name=train23] Kicks players inside train with name 'train23'
/train destroy --train @train[destination=InterState5] Destroy the trains heading for InterState5
/train eject --train @train[dx=-2..2,dy=-3..3,dz=-2..2] Eject the trains within a cuboid range of the sender
/train launch 0.5 --options 2 --train @train[tag=express] Launches the train with tag 'express' to a speed of 0.5 over 2 blocks distance

Options

Multiple options can be specified, which are all AND-ed together. All number-based options support Minecraft range syntax: a..b. For example, -5..5 (-5 to 5), ..6 (6 or less) and 12.. (12 or more). Prefixing the option value with ! will make it evaluate as 'not'.

In all examples below, @train can be substituted for @ptrain.

Position Cuboid

The x/y/z options specify where on the world trains should be selected. This specifies a cuboid range. The dx/dy/dz can also be specified to grow this cuboid. If only dx/dy/dz are specified, then the x/y/z of the sender is used. The world option can optionally be specified to operate on other worlds, or to run from a server terminal where no world can be inferred.

@train[x=10..12,y=23..56,z=-100..-80] All trains in cuboid (10, 23, -100) -> (12, 56, 80)
@train[x=10,y=23,z=-100, dx=2,dy=33,dz=20] Same as above, but specified with dx/dy/dz to 'grow' the cuboid
@train[x=10,y=10,z=10,dx=-2..2,dy=-10..10,dz=-2..2] Complex use: grows the cuboid from point (10, 10, 10) in both directions. This becomes cuboid (8, 0, 8) -> (12, 20, 12)
@train[dx=-10..10,dy=-5..5,dz=-10..10] Selects a cuboid around the sender (command block / player) of the command
@train[world=world_the_end,x=10,y=89,z=-20,dx=-10..10,dy=-10..10,dz=-10..10] The world name to target can be used to target trains on other worlds

Distance

The distance option filters trains based on distance to the sender, or a cuboid specified. This is a spherical distance.

@train[distance=..10] All trains 10 blocks or less away from the sender
@train[distance=1000..] All trains 1000 blocks away or more from the sender
@train[x=100,y=50,z=-100,distance=..5] All trains 5 blocks or less away from coordinate (100, 50, -100)
@train[x=10,y=10,z=10,dx=50,dz=50,distance=..10] All trains 10 blocks or less away from cuboid (10, 10, 10) -> (60, 10, 60)

Sort and Limit

The sort and limit options can be used to pick a single result from many based on distance, or to pick limited results at random. Sort supports options nearest, furthest and random. Limit must be a natural integer.

@train[distance=..100,sort=random,limit=1] Picks a single random train 100 blocks away or less
@train[distance=..100,sort=nearest,limit=2] Picks at most 2 nearest trains, 100 blocks away or less
@train[distance=1000..,sort=furthest,limit=10] Picks at most 10 trains furthest away, 1000 blocks distance away or more

Train Name

The name option can be used to select trains by name, or a name pattern. Supports the same wildcard pattern rules as the remote control syntax.

@train[name=train12] Selects train with name 'train12'
@train[name=Intercity*Express] Selects trains with name starting with "Intercity" and ending with "Express"
@train[name=*] Selects all trains on the world

Train Tags

The tag option, which can be specified multiple times, can be used to select the tags assigned to trains and filter on those. Like the name option, this supports a wildcard pattern. This only checks that a particular tag is or isn't present, not that it is the only tag present.

@train[tag=mytag] Selects trains that have tag 'mytag'
@train[tag=*fast,tag=!express] Selects trains that have a tag ending with 'fast', but do not have tag 'express'

Passenger Count

The passengers and playerpassengers options select the trains that meet a certain number of (player) passengers. This supports the range command to check for 'at least' a number of passengers, such as @train[passengers=5..]

Derailed

The derailed option selects trains that have derailed. For example: @train[derailed=1] or @train[derailed=true]

Speed

The speed option (alias: velocity) selects trains that move at a certain speed. This is the actual movement speed, which is at most the speed limit set for the train. Example: @train[speed=0] for trains that are not moving.

Miscellaneous Properties

More might be added in the future, but the additional properties can be used to filter the selection

destination Destination set for the train
friction Friction modifier of the train (default: 1)
gravity Gravity modifier of the train (default: 1)
keepchunksloaded Whether the train keeps nearby chunks loaded
speedlimit Speed limit set for the train
ticket Same checks as for tags, but for ticket names instead