Skip to content

Designs

Jump to bottom
Björn Teichmann edited this page Dec 19, 2013 · 2 revisions

Overview

Gate designs describe how gates are built (using the trp design build and trp design create commands) and recognized when created (by placing a sign). Each design is stored in a separate YAML file in the <plugins>/Transporter/designs directory. A design's file name is not important, it's the content that matters.

On a running server, the trp design list command can be used to list the loaded designs. The trp reload designs command can be used to reload all the designs found in the designs directory. If a design can't be loaded because of an error, information about the problem will be displayed. Use the information to correct the error and reload the designs again.

There are three main areas of interest in a design file: general options, block keys, and blocks. Each is described below.

It is important to note that when a gate is created in a world, the entire design is copied into the gate file. This means that once a gate is created, it has no dependency on the design, so changes to a design don't have any effect on existing gates.

General Options

A design's general options are all those settings in the design file that aren't about block keys or blocks. When a gate is created based on a design, all the design's general options are copied to the gate's file unless specified otherwise. For a complete reference to all the options available in a design, see the Gates page. Only the options that aren't copied directly to a gate are documented below.

Option Type Default Description
attribution string none An attribution to the design's author(s), if any. This option is not copied to the gate file when the design is built.
name string none The name of the design. Design names are required and must be unique, no more than 15 characters long and cannot contain periods (.) or asterisks (*). When a gate is created based on this design, this value is copied into the gate's "designName" value.
buildable boolean true Can a player use the *trp design build* command to build this design?
buildFromInventory boolean false When a player uses the trp design build command, should the blocks that make up the gate be taken from the player's inventory?
buildWorlds string/list .* A single or list of regular expressions that must match a player's current world name in order to allow the player to either build or create gates based on this design. This option is not available for already created gates.
buildCost float 0 Economy The cost to build the gate (using trp design build).
creatable boolean true Can players create gates based on this design by placing a sign?
createCost float 0 Economy The cost to create the gate.
enabled boolean true Should the design be loaded by the plugin?

Items

The "bannedItems", "allowedItems", and "replaceItems" options specify inventory items using a simple string. The string can be an item number or name from the numbers and names in the materials.txt file, optionally followed by a colon and a number, which represents the item's "durability" or color. For example:

    WOOL:1          # block of orange wool
    STONE           # block of stone
    41              # block of gold
    WOOD_SWORD:30   # wooden sword at half damage

The special item "*" can be used to indicate "any item".

Block Key

The "blockKey" part of the design file is a mapping between the block characters used in the slices of the "blocks" section and the options common to those blocks.

A block character is a single alphanumeric character. The character cannot be any of the standard YAML special characters such as dash (-) or colon (:).

The value side of the mapping is either a simple string, which can be an item name or number, or a mapping, which can contain any of the following keys:

Key Type Default Description
build block none The specified block will be placed in this location when the gate is built, or must exist in this location when a gate is created. See below for more information about specifying blocks.
open block none The specified block will be placed in this location when the gate is open. See below for more information about specifying blocks.
screen boolean false Is this location a screen (sign) used to display the gate's name and destination?
portal boolean false Will this location cause an entity to teleport when they enter it? A design must have at least one portal.
trigger boolean false Will interaction with this location cause the gate to open and close?
switch boolean false Will interaction with this location case the gate's destination to change if the gate has multiple links?
insert boolean false Is this location the insert location? A design must have exactly one insertion location. When a gate is built using the trp design build and trp design create commands, this is the location the player is standing when the gate is built.
spawn string none If set, entities traveling to this gate can be spawned here. A design must have at least one spawn location. If multiple spawn locations are specified, one will be chosen randomly when an entity arrives. See below for more information about the allowed values.

When a block is specified as a simple string or number, it's the same as specifying a mapping with the "build" key set to the specified item name or number and all the other keys at their defaults.

Specifying Blocks

A block is specified by either a string indicating it's item name or number as seen in the materials.txt file, or a mapping of keys and values. In addition, the special string "NONE" can be used to indicate no item.

When using a mapping to specify a block, the following keys are available:

Key Type Default Description
type string or integer none This key is required and must specify an item name or number as seen in the materials.txt file. The special type "NONE" can also be used, in which case no other keys will be considered.
physics boolean false Should physics be applied when this block is placed? This is useful is you want water or lava to flow, for example.
data integer none The data value for the item. How this is interpreted depends on the block type as defined in Bukkit. It's usually more convenient to use the more specific keys below.
facing string none The facing direction for signs, ladders, torches, stairs, etc. If the block type can't handle a facing (e.g., stone), this key is ignored. Valid values are any value of the BlockFace enumeration.
color string none The color of the block. This currently only applies to wool blocks.
open boolean none The open state for doors, gates, etc. If the block type isn't "openable", this key is ignored.
lines string none The lines of text for a sign. Use "\n" in the string where you'd like the line breaks to appear.
triggerOpenMode string HIGH The relative redstone level to open the gate. This only applies to trigger blocks. The following values are valid: NONE: the gate cannot be opened via redstone, HIGH: the gate will open when the redstone level goes above zero, LOW: the gate will open when the redstone level drops to zero.
triggerCloseMode string LOW The relative redstone level to close the gate. This only applies to trigger blocks. The following values are valid: NONE: the gate cannot be closed via redstone, HIGH: the gate will close when the redstone level goes above zero, LOW: the gate will close when the redstone level drops to zero.
switchMode string HIGH The relative redstone level to cause the gate to switch its next link. This only applies to switch blocks. The following values are valid: NONE: the gate will not switch links via redstone, HIGH: the gate will switch when the redstone level goes above zero, LOW: the gate will switch when the redstone level drops to zero.
sendLightningMode string NONE Specifies if lightning should strike this block when an entity teleports from the gate. If multiple blocks specify this option, one will be chosen at random. The following values are valid: NONE: the block will not be struck by lightning, NORMAL: the block will be struck with normal lightning which can cause damage and start fires, SAFE: the block will be stuck with "safe" lightning that doesn't cause damage or start fires.
receiveLightningMode string NONE Specifies if lightning should strike this block when an entity teleports to the gate. See "sendLightningMode" above for more details.

Spawn Direction

When players arrive at a gate, they are "spawned" at one of the gate's spawn locations. The direction the player is facing when they are spawned is controlled by the value of the "spawn" location. The eight cardinal directions are represented, as well as some special "directions". In the case of the cardinal directions, the actual direction the player will end up facing is relative to the direction the player who built the gate was facing when the gate was built (the gate direction). A gate design always uses the convention that north is the direction being faced when looking at a block slice (see below).

The valid values of the "spawn" option are:

Value Description
NORTH Spawn the player so they're pointing north, relative to the gate direction.
SOUTH Spawn the player so they're pointing south, relative to the gate direction.
EAST Spawn the player so they're pointing east, relative to the gate direction.
WEST Spawn the player so they're pointing west, relative to the gate direction.
NORTH_EAST Spawn the player so they're pointing north east, relative to the gate direction.
NORTH_WEST Spawn the player so they're pointing north west, relative to the gate direction.
SOUTH_EAST Spawn the player so they're pointing south east, relative to the gate direction.
SOUTH_WEST Spawn the player so they're pointing south west, relative to the gate direction.
RANDOM Spawn the player facing a random direction.
PLAYER Spawn the player so they're facing exactly the same direction they were pointing when they entered the originating gate.
FORWARD Spawn the player so they're pointing in the same direction they were, relative to the originating gate.
REVERSE Spawn the player so they're pointing in the opposite direction they were, relative to the originating gate.

Some examples might help explain how this works.

Originating Gate Direction Player Direction Destination Gate Direction Spawn Value New Player Direction
don't care don't care NORTH NORTH NORTH
don't care don't care NORTH EAST EAST
don't care don't care EAST NORTH EAST
don't care don't care EAST EAST SOUTH
don't care don't care don't care RANDOM random
don't care NORTH don't care PLAYER NORTH
don't care EAST don't care PLAYER EAST
NORTH NORTH NORTH FORWARD NORTH
EAST NORTH NORTH FORWARD WEST
EAST EAST NORTH FORWARD NORTH
EAST NORTH NORTH FORWARD WEST

Note that the actual player direction is represented internally as a floating point number of degrees. The player's direction will be quantized to a cardinal direction when necessary.

Blocks

The "blocks" structure is a "drawing" of the gate, one vertical slice at a time. Each slice is a collection of strings where each character is represented in the "blockKey" section of the design. The slices are arranged in order. If you imagine yourself facing north, the slices are listed north to south. If you imagine all the slices stacked like slices of bread in a loaf, you get the idea.

A design must specify at least one slice. Every slice must have the same number of strings, and each string must be the same length. Every unique character in all the slices must be represented in the block key.

Example: nether.yml

    name: Nether              # must be unique on the server
    duration: -1              # millis until gate closes, -1 means always on
    buildable: true           # can a user build the gate automatically?
    buildFromInventory: false # when building the gate, take the blocks from the user's inventory?
    buildWorlds: .*           # list of world name patterns where this gate can be built and created
    linkLocal: true           # can be linked to another gate in same world?
    linkWorld: true           # can be linked to another gate in a world on the same server?
    linkServer: true          # can be linked to another gate on a different server?
    multiLink: true           # can be linked to multiple gates?
    restoreOnClose: false     # restore open blocks when closing the gate?
    requirePin: false         # does the gate require a valid player pin for use?
    requireValidPin: true     # will the gate allow reception of an invalid pin?
    invalidPinDamage: 10      # how much damage does reception of an invalid pin do?
    requireAllowedItems: true # don't allow reception of banned items

    blockKey:
      X: NONE
      O: OBSIDIAN
      P: { build: AIR, open: STATIONARY_WATER, portal: true  }
      p: { build: AIR, open: STATIONARY_WATER, portal: true, spawn: FORWARD }
      I: { build: AIR, open: STATIONARY_WATER, portal: true, spawn: FORWARD, insert: true }
      S: { build: { type: WALL_SIGN, facing: SOUTH }, screen: true, trigger: true, switch: true }

    blocks:
      -
        - "OOOO"
        - "OPPO"
        - "OPPO"
        - "OIpO"
        - "OOOO"
      -
        - "XXXX"
        - "XXXX"
        - "SXXX"
        - "XXXX"
        - "XXXX"

Example: stargate.yml

name: Stargate
duration: 10000
buildable: true
buildFromInventory: false
buildWorlds: .*
linkLocal: true
linkWorld: true
linkServer: true
multiLink: true
restoreOnClose: false

blockKey:
  X: NONE
  O: OBSIDIAN
  G: { build: OBSIDIAN, open: GLOWSTONE }
  o: STEP
  P: { build: AIR, open: STATIONARY_WATER, portal: true  }
  p: { build: AIR, open: STATIONARY_WATER, portal: true, spawn: SOUTH }
  I: { insert: true }
  S: { build: { type: WALL_SIGN, facing: SOUTH }, screen: true, trigger: true, switch: true }

blocks:
  -
    - "XXOGOXX"
    - "XGPPPGX"
    - "OPPPPPO"
    - "GPPPPPG"
    - "OPPPPPO"
    - "XGpppGX"
    - "XXOGOXX"
  -
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXoooXX"
  -
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXIXXX"
  -
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXXXOX"
    - "XXXXXOX"
  -
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXXXXX"
    - "XXXXXSX"
    - "XXXXXXX"
Clone this wiki locally