# Home

TetrisFriends (TF) is a Minecraft plugin inspired by the popular TetrisFriends once found on Facebook.

| Page                                                        | Description                                         |
| ----------------------------------------------------------- | --------------------------------------------------- |
| [Installation](/installation)                               | Guide on how to install TetrisFriends               |
| [Dependencies](/dependencies)                               | Overview of TetrisFriend's dependencies             |
| [Configuration Files](/configurations)                      | View the content of the default configuration files |
| [Game Configuration Files](/game-configuration-files)       | View info on game configuration files               |
| [Game Modes](/game-modes)                                   | Description of the current game modes               |
| [Commands and Permission](/commands-and-permissions)        | Overview of all commands and permissions            |
| [Controls](/controls)                                       | How to play and control types                       |
| [Challenges](/challenges)                                   | Info on the types of challenges there are           |
| [Scoring](/scoring)                                         | Overview of how score is awarded.                   |
| [Highscores](/highscores)                                   | Overview of what highscores there are               |
| [Creating your own schematic](/creating-your-own-schematic) | Extensive guide on how to create a custom schematic |
| [World Mechanics](/world-mechanics)                         | How does the plugin work and note on performance    |


# Installation

This page provides information on how to install and setup TetrisFriends.

### Required steps

1\. Download the plugin and drop it into your plugins folder.

{% hint style="danger" %}
Please make sure that you have installed all the required [dependencies](/dependencies)!
{% endhint %}

2\. Start or restart your server.

{% hint style="warning" %}
Reloading may have unexpected results. Please do a full stop/start cycle.
{% endhint %}

3\. TetrisFriends is now installed and ready for use.

{% hint style="info" %}
It is recommended that you review the optional steps.
{% endhint %}

###

### Optional Steps

{% tabs %}
{% tab title="Configuration" %}
Customize the plugin to make it fit your server. You can customize anything from messages, scoreboards, schematics, GUIs, and much more. [Learn more here.](/configurations)
{% endtab %}

{% tab title="SQLite vs. MySQL" %}
The plugin will use a local database i.e. SQLite by default. If you would like to synchronize data across servers you can do so by configuring MySQL in the config.yml file.
{% endtab %}

{% tab title="Pregeneration" %}
Use the pregeneration command found [here](https://tetrisfriends.benzoft.com/commands-and-permissions#admin-commands-tetrisfriendsadmin). This will make sure the server won't lag at peak times. Found out why [here](/world-mechanics#note-on-performance).
{% endtab %}

{% tab title="Controls" %}
If you have [ProtocolLib ](/dependencies#optional-dependencies)installed it is recommended that you set Controls.Enhanced to true in the [config.yml](/configurations). This will greatly improve the gameplay experience!
{% endtab %}
{% endtabs %}


# Dependencies

This page provides information on the required and optional dependencies TetrisFriends has.

### Required dependencies

| Dependency    | Description                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **WorldEdit** | <p>WorldEdit is required in order for TetrisFriends to spawn in the schematic in which the game takes place. Said schematic can also be replaced by one that you make yourself. WorldEdit is required for that task as well.</p><p></p><p>You may use FastAsyncWorldEdit to benefit from the performance increase it provides.</p> |

### Optional dependencies

| Dependency                                                                 | Description                                                                                                                                                                                                                                                   |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**ProtocolLib**](https://www.spigotmc.org/resources/1997/)                | With ProtocolLib you'll be able to take advantage of packet-based controls. This is recommended and is by far the best option for controls in comparison to default event-based controls. [Enable this in the config.yml](/configurations).                   |
| [**NoteBlockAPI**](https://www.spigotmc.org/resources/noteblockapi.19287/) | The original Tetris soundtrack has been converted to a much similar noteblock version which is included in the TetrisFriends plugin. The soundtrack will play whenever you're in the TetrisFriends game world. NoteBlockAPI is required for playing the song. |


# Configuration Files

This page provides information on the configurability of TetrisFriends.

Below are the configuration files that TetrisFriends ships with. You can find [game-configurations here](/game-configuration-files).

{% tabs %}
{% tab title="config.yml" %}
{% hint style="warning" %}
Please make sure that **ReturnLocation.PlayerJoinLocation** is a valid location. Preferably make it match the location of your servers spawn point.
{% endhint %}

```yaml
#########################################################################
# +-------------------------------------------------------------------+ #
# |    _____      _         _      ___      _                _        | #
# |   |_   _|___ | |_  _ _ (_) ___| __|_ _ (_) ___  _ _   __| | ___   | #
# |     | | / -_)|  _|| '_|| |(_-<| _|| '_|| |/ -_)| ' \ / _` |(_-<   | #
# |     |_| \___| \__||_|  |_|/__/|_| |_|  |_|\___||_||_|\__,_|/__/   | #
# |                                                                   | #
# | By: Benz56                                                        | #
# +-------------------------------------------------------------------+ #
#########################################################################

# Customize various parameters of the TetrisFriends game world.
World:
  # Set to -1 to enable the daylight cycle.
  Time: 6000

  # Valid Environments: NORMAL, NETHER, THE_END.
  # If changed you have to delete the 'TetrisFriends' world and generate a new one.
  Environment: 'NORMAL'

  # Select the schematic you wish to use for the TetrisFriends game cells.
  #
  # If you wish to create your own please follow these instructions:
  # - Execute '/tfa schematic center' and '/tfa schematic helper'.
  # - Build your schematic.
  # - Once you're done execute '/tfa schematic save <name>'
  #
  # Please note that you do not have to use the built-in schematic creator, however,
  # this is by far the easiest way to create your own schematics. It'll highlight
  # areas to look out for, provide you with troubleshooting information as you
  # create your schematic and validate it for you before creating it. It'll
  # also make sure your schematic is perfectly centered when pasted.
  Schematic: 'standard.schematic'


# Set the NoteBlock song that should play while playing Tetris.
# The songs are located in the 'songs' folder. You can add your own .nbs files.
# This requires the plugin NoteBlockAPI. https://www.spigotmc.org/resources/19287/
Music:
  Song: 'theme.nbs'


# Determine where the player is teleported to once a game has finished.
ReturnLocation:
  # false: Players are teleported back to the location they were teleported from when the game started.
  # true: Players are teleported to the FixedLocation configured below when the game ends.
  UseFixedLocation: false

  # Set the fixed return-location in the following format:
  #   <world>, <x>, <y>, <z>, <yaw>, <pitch>
  # Pitch and yaw are optional.
  FixedLocation: 'world, 0, 60, 0, 0, 0'

  # If a player for some reason joins in the TetrisFriends world where should they get teleported?
  PlayerJoinLocation: 'world, 0, 60, 0, 0, 0'


# Set the number of seconds a challenge is valid.
Challenge:
  # A public challenge is a challenge all players accept.
  Public:
    ExpiryTime: 1800
  # A targeted challenge is a challenge created when a player challenges a specific player.
  Targeted:
    ExpiryTime: 120


# Select the type of Controls to use.
Controls:
  # Event-based controls. Will cause a little bit of movement while playing.
  Standard:
    # Determine the milliseconds between each input action when playing.
    # Lower input delay will allow moving the tetrominoes faster, however,
    # may result in accidental movements. Recommended are 120 - 160.
    InputDelay: 140
  # Packet-based controls. Requires ProtocolLib.
  # This option results in a far better gameplay experience.
  # This is the recommended option for controls.
  Enhanced:
    enabled: false


# By default Tetris Friends saves its data in a local SQLite database file.
# By configuring a MySQL database you can make multiple servers share the same data.
MySQL:
  Enabled: false
  Host: localhost
  Port: 3306
  DatabaseName: database
  Username: root
  Password: password
  MaximumPoolSize: 5


# Update Checker.
# Enable or disable the update checker.
UpdateCheckerEnabled: true

# false: All OPs are notified of a new update when they join.
# true: OPs are only notified if they have the tetrisfriends.update permission as well.
# N.B. any user with the tetrisfriends.update permission is notified; OP or not.
UpdateCheckerPermissionOnly: false
```

{% endtab %}

{% tab title="messages.yml" %}

```yaml
# This is the Message file for all TetrisFriends messages.
# 
# All messages are fully customizable and support color codes, formatting and ASCII symbols.
# Set the Prefix and use %prefix% to add the corresponding prefix to a message.
# Prepend any message with <ActionBar> to send it as an ActionBar message.
# Leave a message blank ('') to disable it.
# 
# You can also create messages with Hover and Click events. Syntax options: (Space between comma and quote is NOT allowed)
#  - ["Message","/Command"]
#  - ["Message","Hover"]
#  - ["Message","/Command","Hover"]
#  - ["Message","/Command","Suggest"]
#  - ["Message","/Command","Hover","Suggest"]
# You can add as many events to a message as you want. Example:
# '%prefix% &cInvalid arguments! ["&c&n&oHelp","/tetrisfriends help","&aClick to get help!"]'
# The "Suggest" tag is used if the click event should suggest the command. Default is Run.



Prefix: '&7[&cT&6e&et&ar&bi&ds&cF&6r&ei&ae&bn&dd&cs&7]'
Messages:
  General:
    InvalidPermission: '%prefix% &cYou do not have permission to do this!'
    NoCommands: 'Unknown command. Type "/help" for help.'
    PlayerOnly: '%prefix% &cCommand can only be used as a Player!'
    InvalidArguments: '%prefix% &cInvalid arguments! ["&c&n&oHelp","/tetrisfriends help","&aClick to get help!"]'
  Tetris:
    AlreadyPlaying: '%prefix% &cAlready playing!'
    AlreadyHaveAPublicChallenge: '%prefix% &cYou already have a public challenge!'
    PublicChallengeCreated: '%prefix% &aPublic challenge created!'
    ChallengeSent: '%prefix% &aChallenge sent to &e%player%'
    ChallengeReceived: '%prefix% &e%player% &ahas challenged you in Tetris! ["&b&nAccept","/tetrisfriends menu challenges","&aClick to open the challenges menu!"]'
    AlreadyChallenged: '%prefix% &cYou''ve already challenged that player!'
    ChallengeInvalid: '%prefix% &cThe challenge is no longer valid!'
    CommandsDisabled: '%prefix% &cYou can''t execute commands while playing!'
  Admin:
    ConfigurationsReloaded: '%prefix% &aConfiguration files successfully reloaded!'

```

{% endtab %}

{% tab title="menus.yml" %}
{% hint style="info" %}
Please note that the material names in this file are for 1.12.2. The plugin will automatically generate the correct material names for the version you're running.
{% endhint %}

```yaml
# This is the menu file for all TetrisFriends menus. Here you'll be able to customize all GUI menus used by TetrisFriends.
# 
# Each menu has a 'Required' section:
#  - You can customize the items in this section.
#  - You can not add or remove sections.
# Each menu has an 'Optional' section:
#  - You can add new items by creating a new section with a unique name e.g. instead of 'EdgeRed' you could add 'MyOwnItem'.
#  - You can remove items by deleting a section.
# 
# An item-section consists of:
#  - [Required] Material:  <Material>  If you're using 1.12 you can use <Material>:[Data]. If you're not using 1.12 use the full material name.
#  - [Required] Name:      <String>    You may use color codes in names.
#  - [Required] Slot(s):   <Integer>   Select where the item should be placed with 'Slot: <Integer>' or 'Slots: <Integer,Integer,Integer>'
#  - [Optional] Lore:      <List>      A lore is a list of strings. Please see an example below for the syntax.
#  - [Optional] Glow:      <Boolean>   Give an item enchant 'glow'. true/false.
#  - [Optional] Amount:    <Integer>   Set the amount in the itemstack. 1 to 64 both inclusive.
#  - [Optional] ItemFlags: <List>      Give an item various ItemFlags to e.g. hide attributes)


MainMenu:
  Title: '&c&lT&6&le&e&lt&a&lr&b&li&d&ls&c&lF&6&lr&e&li&a&le&b&ln&d&ld&c&ls'
  Required:
    ChallengesButton:
      Material: NETHER_STAR
      Name: '        &eChallenges!'
      Lore:
      - ' &f&m-------------------&7 '
      - ''
      - '  &aClick here to view all'
      - '  &aavailable challenges!'
      - ''
      - ' &7&m-------------------&7 '
      Slot: 39
    HighScoreSelectorButton:
      Material: BOOK
      Name: '        &eHigh Scores!'
      Lore:
      - ' &f&m--------------------&7 '
      - ''
      - '  &aClick here to view all'
      - '  &acurrent high-scores!'
      - ''
      - ' &7&m--------------------&7 '
      Slot: 41
  Optional:
    EdgeRed:
      Material: STAINED_GLASS_PANE:14
      Name: '&c&l█'
      Slots: 0,6,18,44,48
    EdgeOrange:
      Material: STAINED_GLASS_PANE:1
      Name: '&6&l█'
      Slots: 1,7,9,46,53
    EdgeYellow:
      Material: STAINED_GLASS_PANE:4
      Name: '&e&l█'
      Slots: 2,8,47,52
    EdgeGreen:
      Material: STAINED_GLASS_PANE:5
      Name: '&a&l█'
      Slots: 3,17,45,51
    EdgeBlue:
      Material: STAINED_GLASS_PANE:3
      Name: '&b&l█'
      Slots: 4,26,36,50
    EdgeMagenta:
      Material: STAINED_GLASS_PANE:2
      Name: '&d&l█'
      Slots: 5,27,35,49
OpponentSelector:
  Title: '&c&lT&6&le&e&lt&a&lr&b&li&d&ls&c&lF&6&lr&e&li&a&le&b&ln&d&ld&c&ls &7&l>
    &c&lC&6&lh&e&la&a&ll&b&ll&d&le&c&ln&6&lg&e&le'
  Required:
    Opponent:
      Head: '%player%'
      Name: '&eChallenge &a%player%'
      Slots: 10,11,12,13,14,15,16,19,20,21,22,23,24,25,28,29,30,31,32,33,34
    PublicChallenge:
      Material: DIAMOND_SWORD
      Name: '     &eCreate a Public Challenge'
      Lore:
      - ' &f&m---------------------------&7 '
      - ''
      - '  &aClick here to create a public'
      - '  &achallenge in the selected game'
      - '  &amode. The game starts once a'
      - '  &aplayer accepts the challenge!'
      - ''
      - ' &f&m---------------------------&7 '
      ItemFlags:
      - HIDE_ATTRIBUTES
      Slot: 38
    NextPage:
      Head: http://textures.minecraft.net/texture/e3fc52264d8ad9e654f415bef01a23947edbccccf649373289bea4d149541f70
      Name: '&eNext Page'
      Slot: 42
    PrevPage:
      Head: http://textures.minecraft.net/texture/5f133e91919db0acefdc272d67fd87b4be88dc44a958958824474e21e06d53e6
      Name: '&ePrevious Page'
      Slot: 40
    Back:
      Material: BARRIER
      Name: '&eMain Menu'
      Slot: 41
  Optional:
    EdgeRed:
      Material: STAINED_GLASS_PANE:14
      Name: '&c&l█'
      Slots: 0,6,18,44,48
    EdgeOrange:
      Material: STAINED_GLASS_PANE:1
      Name: '&6&l█'
      Slots: 1,7,9,46,53
    EdgeYellow:
      Material: STAINED_GLASS_PANE:4
      Name: '&e&l█'
      Slots: 2,8,47,52
    EdgeGreen:
      Material: STAINED_GLASS_PANE:5
      Name: '&a&l█'
      Slots: 3,17,45,51
    EdgeBlue:
      Material: STAINED_GLASS_PANE:3
      Name: '&b&l█'
      Slots: 4,26,36,50
    EdgeMagenta:
      Material: STAINED_GLASS_PANE:2
      Name: '&d&l█'
      Slots: 5,27,35,49
ChallengesMenu:
  Title: '&c&lT&6&le&e&lt&a&lr&b&li&d&ls&c&lF&6&lr&e&li&a&le&b&ln&d&ld&c&ls &7&l>
    &c&lC&6&lh&e&la&a&ll&b&ll&d&le&c&ln&6&lg&e&le&a&ls'
  Required:
    Challenger:
      Head: '%player%'
      Name: '   &eCreated by &a%player%'
      Lore:
      - ' &f&m-------------------&7 '
      - ''
      - '   &eGameMode: &a%gameMode%'
      - '   &ePublic:      &a%public%'
      - ''
      - ' &7&m-------------------&7 '
      - '    &eL-Click to accept.'
      - ' &7&m-------------------&7 '
      Slots: 10,11,12,13,14,15,16,19,20,21,22,23,24,25,28,29,30,31,32,33,34
    NextPage:
      Head: http://textures.minecraft.net/texture/e3fc52264d8ad9e654f415bef01a23947edbccccf649373289bea4d149541f70
      Name: '&eNext Page'
      Slot: 41
    PrevPage:
      Head: http://textures.minecraft.net/texture/5f133e91919db0acefdc272d67fd87b4be88dc44a958958824474e21e06d53e6
      Name: '&ePrevious Page'
      Slot: 39
    Back:
      Material: BARRIER
      Name: '&eMain Menu'
      Slot: 40
  Optional:
    EdgeRed:
      Material: STAINED_GLASS_PANE:14
      Name: '&c&l█'
      Slots: 0,6,18,44,48
    EdgeOrange:
      Material: STAINED_GLASS_PANE:1
      Name: '&6&l█'
      Slots: 1,7,9,46,53
    EdgeYellow:
      Material: STAINED_GLASS_PANE:4
      Name: '&e&l█'
      Slots: 2,8,47,52
    EdgeGreen:
      Material: STAINED_GLASS_PANE:5
      Name: '&a&l█'
      Slots: 3,17,45,51
    EdgeBlue:
      Material: STAINED_GLASS_PANE:3
      Name: '&b&l█'
      Slots: 4,26,36,50
    EdgeMagenta:
      Material: STAINED_GLASS_PANE:2
      Name: '&d&l█'
      Slots: 5,27,35,49
HighScoreSelector:
  Title: '&c&lT&6&le&e&lt&a&lr&b&li&d&ls&c&lF&6&lr&e&li&a&le&b&ln&d&ld&c&ls &7&l>
    &c&lH&6&li&e&lg&a&lh&b&lS&d&lc&c&lo&6&lr&e&le'
  Required:
    Back:
      Material: BARRIER
      Name: '&eMain Menu'
      Slot: 40
    MostGames:
      Head: http://textures.minecraft.net/texture/e34a592a79397a8df3997c43091694fc2fb76c883a76cce89f0227e5c9f1dfe
      Name: '&6&l&m--[-&f  &e&lMost Games Played&f  &6&l&m-]--'
      Lore:
      - ' &f&m----------------------------&7 '
      - ''
      - '  &aSee who plays the most:'
      - '    &a - Overall'
      - '    &a - Singleplayer'
      - '    &a - Multiplayer'
      - ''
      - '  &aSorted by most games played.'
      - ''
      - ' &f&m----------------------------&7 '
      Slot: 19
    MostLosses:
      Head: http://textures.minecraft.net/texture/e34a592a79397a8df3997c43091694fc2fb76c883a76cce89f0227e5c9f1dfe
      Name: '  &6&l&m--[-&f  &e&lMost Losses&f  &6&l&m-]--'
      Lore:
      - ' &f&m-------------------------&7 '
      - ''
      - '   &aSee who losses the most!'
      - ''
      - ' &f&m-------------------------&7 '
      Slot: 20
    MostWins:
      Head: http://textures.minecraft.net/texture/e34a592a79397a8df3997c43091694fc2fb76c883a76cce89f0227e5c9f1dfe
      Name: '  &6&l&m--[-&f  &e&lMost Wins&f  &6&l&m-]--'
      Lore:
      - ' &f&m----------------------&7 '
      - ''
      - '   &aSee who wins the most!'
      - ''
      - ' &f&m----------------------&7 '
      Slot: 21
    HighestTotalScore:
      Head: http://textures.minecraft.net/texture/e34a592a79397a8df3997c43091694fc2fb76c883a76cce89f0227e5c9f1dfe
      Name: '&6&l&m--[-&f  &e&lHighest Total Score&f  &6&l&m-]--'
      Lore:
      - ' &f&m------------------------------&7 '
      - ''
      - '  &aSee who has the highest score:'
      - '    &a - Overall'
      - '    &a - Singleplayer'
      - '    &a - Multiplayer'
      - ''
      - '  &aSorted by highest total score.'
      - ''
      - ' &f&m------------------------------&7 '
      Slot: 22
    MostLinesSent:
      Head: http://textures.minecraft.net/texture/e34a592a79397a8df3997c43091694fc2fb76c883a76cce89f0227e5c9f1dfe
      Name: '  &6&l&m--[-&f  &e&lMost Lines Sent&f  &6&l&m-]--'
      Lore:
      - ' &f&m----------------------------&7 '
      - ''
      - '  &aSee who sends the most lines:'
      - '    &a - Overall'
      - '    &a - Singleplayer'
      - '    &a - Multiplayer'
      - ''
      - '  &aSorted by total lines sent.'
      - ''
      - ' &f&m----------------------------&7 '
      Slot: 23
    MostKOs:
      Head: http://textures.minecraft.net/texture/e34a592a79397a8df3997c43091694fc2fb76c883a76cce89f0227e5c9f1dfe
      Name: '  &6&l&m--[-&f  &e&lMost KOs&f  &6&l&m-]--'
      Lore:
      - ' &f&m----------------------&7 '
      - ''
      - '   &aSee who KOs the most!'
      - ''
      - ' &f&m----------------------&7 '
      Slot: 24
    MostPlaytime:
      Head: http://textures.minecraft.net/texture/e34a592a79397a8df3997c43091694fc2fb76c883a76cce89f0227e5c9f1dfe
      Name: '  &6&l&m--[-&f  &e&lMost Playtime&f  &6&l&m-]--'
      Lore:
      - ' &f&m--------------------------&7 '
      - ''
      - '  &aSee who plays the most:'
      - '    &a - Overall'
      - '    &a - Singleplayer'
      - '    &a - Multiplayer'
      - ''
      - '  &aSorted by total playtime.'
      - ''
      - ' &f&m--------------------------&7 '
      Slot: 25
  Optional:
    EdgeRed:
      Material: STAINED_GLASS_PANE:14
      Name: '&c&l█'
      Slots: 0,6,18,44,48
    EdgeOrange:
      Material: STAINED_GLASS_PANE:1
      Name: '&6&l█'
      Slots: 1,7,9,46,53
    EdgeYellow:
      Material: STAINED_GLASS_PANE:4
      Name: '&e&l█'
      Slots: 2,8,47,52
    EdgeGreen:
      Material: STAINED_GLASS_PANE:5
      Name: '&a&l█'
      Slots: 3,17,45,51
    EdgeBlue:
      Material: STAINED_GLASS_PANE:3
      Name: '&b&l█'
      Slots: 4,26,36,50
    EdgeMagenta:
      Material: STAINED_GLASS_PANE:2
      Name: '&d&l█'
      Slots: 5,27,35,49
HighScore:
  Titles:
    MostGames: '&c&lH&6&li&e&lg&a&lh&b&lS&d&lc&c&lo&6&lr&e&le &7&l> &c&lG&6&la&e&lm&a&le&b&ls'
    MostLosses: '&c&lH&6&li&e&lg&a&lh&b&lS&d&lc&c&lo&6&lr&e&le &7&l> &c&lL&6&lo&e&ls&a&ls&b&le&d&ls'
    MostWins: '&c&lH&6&li&e&lg&a&lh&b&lS&d&lc&c&lo&6&lr&e&le &7&l> &c&lW&6&li&e&ln&a&ls'
    HighestTotalScore: '&c&lH&6&li&e&lg&a&lh&b&lS&d&lc&c&lo&6&lr&e&le &7&l> &c&lS&6&lc&e&lo&a&lr&b&le'
    MostLinesSent: '&c&lH&6&li&e&lg&a&lh&b&lS&d&lc&c&lo&6&lr&e&le &7&l> &c&lL&6&li&e&ln&a&le&b&ls'
    MostKOs: '&c&lH&6&li&e&lg&a&lh&b&lS&d&lc&c&lo&6&lr&e&le &7&l> &c&lK&6&lO&e&ls'
    MostPlaytime: '&c&lH&6&li&e&lg&a&lh&b&lS&d&lc&c&lo&6&lr&e&le &7&l> &c&lP&6&ll&e&la&a&ly&b&lt&d&li&c&lm&6&le'
  Required:
    MostGames:
      Head: '%player%'
      Name: '  &e&l%position%. &a%player%'
      Lore:
      - ' &f&m-------------------&7 '
      - ''
      - '  &eTotal Games:  &a%totalGames%'
      - '  &eSingleplayer: &a%singleplayerGames%'
      - '  &eMultiplayer:   &a%multiplayerGames%'
      - ''
      - ' &f&m-------------------&7 '
      Slots: 10,11,12,13,14,15,16,19,20,21,22,23,24,25,28,29,30,31,32,33,34
    MostLosses:
      Head: '%player%'
      Name: '  &e&l%position%. &a%player%'
      Lore:
      - ' &f&m-----------------&7 '
      - ''
      - '  &eLosses: &a%losses%'
      - ''
      - ' &f&m-----------------&7 '
      Slots: 10,11,12,13,14,15,16,19,20,21,22,23,24,25,28,29,30,31,32,33,34
    MostWins:
      Head: '%player%'
      Name: '  &e&l%position%. &a%player%'
      Lore:
      - ' &f&m-----------------&7 '
      - ''
      - '  &eWins: &a%wins%'
      - ''
      - ' &f&m-----------------&7 '
      Slots: 10,11,12,13,14,15,16,19,20,21,22,23,24,25,28,29,30,31,32,33,34
    HighestTotalScore:
      Head: '%player%'
      Name: '  &e&l%position%. &a%player%'
      Lore:
      - ' &f&m-------------------------&7 '
      - ''
      - '  &eTotal Score:  &a%totalScore%'
      - '  &eSingleplayer: &a%singleplayerScore%'
      - '  &eMultiplayer:   &a%multiplayerScore%'
      - ''
      - ' &f&m-------------------------&7 '
      Slots: 10,11,12,13,14,15,16,19,20,21,22,23,24,25,28,29,30,31,32,33,34
    MostLinesSent:
      Head: '%player%'
      Name: '  &e&l%position%. &a%player%'
      Lore:
      - ' &f&m--------------------&7 '
      - ''
      - '  &eTotal Lines:   &a%totalLines%'
      - '  &eSingleplayer: &a%singleplayerLines%'
      - '  &eMultiplayer:   &a%multiplayerLines%'
      - ''
      - ' &f&m--------------------&7 '
      Slots: 10,11,12,13,14,15,16,19,20,21,22,23,24,25,28,29,30,31,32,33,34
    MostKOs:
      Head: '%player%'
      Name: '  &e&l%position%. &a%player%'
      Lore:
      - ' &f&m-----------------&7 '
      - ''
      - '  &eKO''s: &a%kos%'
      - ''
      - ' &f&m-----------------&7 '
      Slots: 10,11,12,13,14,15,16,19,20,21,22,23,24,25,28,29,30,31,32,33,34
    MostPlaytime:
      Head: '%player%'
      Name: '  &e&l%position%. &a%player%'
      Lore:
      - ' &f&m------------------------&7 '
      - ''
      - '  &eTotal Playtime:  &a%totalPlaytime%'
      - '  &eSingleplayer:   &a%singleplayerPlaytime%'
      - '  &eMultiplayer:     &a%multiplayerPlaytime%'
      - ''
      - ' &f&m------------------------&7 '
      Slots: 10,11,12,13,14,15,16,19,20,21,22,23,24,25,28,29,30,31,32,33,34
    NextPage:
      Head: http://textures.minecraft.net/texture/e3fc52264d8ad9e654f415bef01a23947edbccccf649373289bea4d149541f70
      Name: '&eNext Page'
      Slot: 41
    PrevPage:
      Head: http://textures.minecraft.net/texture/5f133e91919db0acefdc272d67fd87b4be88dc44a958958824474e21e06d53e6
      Name: '&ePrevious Page'
      Slot: 39
    Back:
      Material: BARRIER
      Name: '&eMain Menu'
      Slot: 40
    Loading:
      Material: WATCH
      Name: '&e&lLoading...'
      Slot: 22
  Optional:
    EdgeRed:
      Material: STAINED_GLASS_PANE:14
      Name: '&c&l█'
      Slots: 0,6,18,44,48
    EdgeOrange:
      Material: STAINED_GLASS_PANE:1
      Name: '&6&l█'
      Slots: 1,7,9,46,53
    EdgeYellow:
      Material: STAINED_GLASS_PANE:4
      Name: '&e&l█'
      Slots: 2,8,47,52
    EdgeGreen:
      Material: STAINED_GLASS_PANE:5
      Name: '&a&l█'
      Slots: 3,17,45,51
    EdgeBlue:
      Material: STAINED_GLASS_PANE:3
      Name: '&b&l█'
      Slots: 4,26,36,50
    EdgeMagenta:
      Material: STAINED_GLASS_PANE:2
      Name: '&d&l█'
      Slots: 5,27,35,49

```

{% endtab %}

{% tab title="tetrominoes.yml" %}
{% hint style="info" %}
Please note that the material names in this file are for 1.12.2. The plugin will automatically generate the correct material names for the version you're running.
{% endhint %}

```yaml
# Select the material for the tetrominoes as well as ghost blocks and garbage blocks.
# 
# If you are using 1.12 you can use data values e.g. CONCRETE:3
# If you are using 1.13 or above please use full names e.g. LIGHT_BLUE_CONCRETE


Tetrominoes:
  I: CONCRETE:3
  J: CONCRETE:11
  L: CONCRETE:1
  O: CONCRETE:4
  S: CONCRETE:5
  T: CONCRETE:10
  Z: CONCRETE:14
Ghost: STAINED_GLASS:8
Garbage: STONE:6

```

{% endtab %}

{% tab title="schematics folder" %}
This folder by default contains **standard.schematic**. This is the structure in which the game takes place. You may create your own by using the /tfa schematic \<action> command [found here](/commands-and-permissions).
{% endtab %}

{% tab title="songs folder" %}
This folder by default contains **theme.nbs**. This is the standard music track played when players are playing Tetris. You can drop in your own .nbs tracks and configure the plugin to play that.
{% endtab %}
{% endtabs %}

*Please note that some configuration files might not be 100% up to date due to updates.*


# Game Configuration Files

This page provides information on how to configure each individual game mode.

### Default Options

These options are found in all files. Below are comments on each of the options and what they do.

```yaml
# Set whether the game is visible in the game menu and can be played.
Enabled: <Boolean>

# Set what item should represent the game mode in the main menu.
MenuItem:
  Material: <Material>
  Name: <String>
  Lore:
  - <StringList>
  Slot: <Integer>
  Page: <Integer> #WIP

# The scoreboard that is shown during the game.
Scoreboard:
  Enabled: <Boolean>
  # A scoreboard line can be a maximum of 32 characters including formatting.
  # Placeholders are translated before they're displayed e.g.
  #   " &eLines Sent On This Side: &a%LinesLeft%" is 41 characters, but only 31-32 once translated.
  #
  # Longer lines are cut off to avoid unexpected behavior/bugs.
  Title: <String>
  Lines:
  - <StringList>
  
# The title that is displayed once the game finishes.
GameOverTitle:
  FadeIn: <Integer>
  Stay: <Integer>
  FadeOut: <Integer>
  Title: <String>
  Subtitle: <String>

# There are two default game settings.
GameSettings:
  # This is the duration in seconds the game lasts. Set to -1 for infinite.
  GameDuration: <Integer>
  # This is the speed the tetrominoe moves. Fastest is 1 i.e. 1 move per tick.
  TetrominoeSpeed: <Integer>
```

### Placeholders

| Placeholder     | Description                                   | Usage                      |
| --------------- | --------------------------------------------- | -------------------------- |
| %PlayerLeft%    | Name of Player1                               | Scoreboard & GameOverTitle |
| %ScoreLeft%     | Player1's score                               | Scoreboard & GameOverTitle |
| %LinesLeft%     | The number of lines Player1 has sent          | Scoreboard & GameOverTitle |
| %KOsLeft%       | The number of times Player1 has KO'ed Player2 | Scoreboard & GameOverTitle |
| %PlayerRight%   | Name of Player2                               | Scoreboard & GameOverTitle |
| %ScoreRight%    | Player2's score                               | Scoreboard & GameOverTitle |
| %LinesRight%    | The number of lines Player2 has sent          | Scoreboard & GameOverTitle |
| %KOsRight%      | The number of times Player2 has KO'ed Player1 | Scoreboard & GameOverTitle |
| %Winner%        | The winner of the multiplayer game            | GameOverTitle              |
| %TimeRemaining% | Seconds until the game is over                | Scoreboard                 |
| %TimeElapsed%   | The number of elapsed seconds                 | Scoreboard                 |

### Custom Options

Some game modes have more game settings. These are specified below:

{% tabs %}
{% tab title="Marathon" %}

| Placeholder | Description                                                                                                                                           | Usage      |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| %level%     | Shows the level the player has reached during this game. The level reflects how fast the tetrominoes drop. The higher the level the faster they drop. | Scoreboard |

```yaml
GameSettings:
  # Every x lines sent the game will get harder.
  LinesPerLevel: <Integer>
```

{% endtab %}
{% endtabs %}


# Game Modes

This page provides information on the available game modes.

### Single player game modes

| Game mode    | Description                                                                                                                                           |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ultra**    | In this game mode the target is to send as many lines and score as many points as possible within 2 minutes.                                          |
| **Marathon** | In this game mode the target is to send as many lines and score as many points as possible with no time limit. The game will get increasingly harder. |

### Multiplayer game modes

| Game mode    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Battle2P** | <p>Battle another player and show them who's boss! The player with the most KOs at the 2 minute mark wins. If both players have the same number of KOs the player with the most lines sent win. </p><p></p><p><strong>Garbage</strong></p><p>You can send garbage to your opponent by clearing multiple lines at a time.</p><p>1 line sent   = 0 garbage lines</p><p>2 lines sent = 1 garbage lines</p><p>3 lines sent = 2 garbage lines</p><p>4 lines sent = 4 garbage lines</p> |


# Commands and Permissions

This page provides information on commands and permissions for TetrisFriends.

{% hint style="warning" %}
All commands require the permission **tetrisfriends.commands**
{% endhint %}

### User Commands (/tetrisfriends)

| Command          | Permission                  | Description                                                                                                            | Type           |
| ---------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------- |
| /tf help         | tetrisfriends.commands.help | Shows a help menu for all of the TetrisFriends commands. All entries have hover and click events.                      | Player/Console |
| /tf menu \[menu] | tetrisfriends.commands.menu | Opens the main menu. You can open specific menus with the menu parameter. Use the tab completer to see openable menus. | Player         |

### Admin commands (/tetrisfriendsadmin)

{% hint style="warning" %}
All admin commands require the permission **tetrisfriends.admin**
{% endhint %}

| Command                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Type           |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| /tfa help                                        | Shows a help menu for all of the TetrisFriends admin commands. All entries have hover and click events.                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Player/Console |
| /tfa startgame \<gamemode> \<player1> \[player2] | Start a game in a specific gamemode. \<player1> is required for singleplayer and multiplayer game modes. \[player2] is required for multiplayer game modes.                                                                                                                                                                                                                                                                                                                                                                                                       | Player/Console |
| /tfa schematic \<action>                         | This command is used to create your own TetrisFriends schematic. For an in-depth tutorial please review [this page](/creating-your-own-schematic).                                                                                                                                                                                                                                                                                                                                                                                                                | Player         |
| /tfa reload                                      | Reload all configuration files. This will end all games and close all open TetrisFriends menus.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Player/Console |
| /tfa pregenerate \<cells> \[interval]            | <p>This command allows you to pregenerate the schematics in the game cells. This will ensure that the server won't lag when "live".<br><br>Generate the amount of \<cells> you believe is the max concurrent players. E.g. you expect a max of 5 players playing Tetris at the same time; then generate 5 or a few more to be sure. </p><p></p><p>The \[interval] is in seconds. This will allow your server to keep up when generating a large number of schematics. E.g. generating 10 cells at the default rate of 2 seconds will take roughly 20 seconds.</p> | Player/Console |

{% hint style="info" %}
All commands have parameter suggestions - use tab-completion.
{% endhint %}

### Permissions

| Permission           | Description                                                        |
| -------------------- | ------------------------------------------------------------------ |
| tetrisfriends.play   | Players with this permission can play any TetrisFriends game mode. |
| tetrisfriends.update | Player with this permission will receive update notifications.     |


# Controls

This page provides information on how the controls work.

### Side to Side

Use **A** to move left and **D** to move right.

### Rotate

Use **W** to rotate the tetromino.

### Soft Drop

Press or hold **S** to perform a soft drop. This will move the tetromino down quicker.

### Hard Drop

Press **SPACE** to drop the drop tetromino i.e. place it where the ghost is.

### Hold

Press **SHIFT** to hold the tetromino. You can't hold again until you've placed the current tetromino.

{% hint style="info" %}
[Using ProtocolLib?](/dependencies#optional-dependencies) Set *Controls.Enhanced* to *true* in the [config.yml](/configurations) file to improve the controls.
{% endhint %}


# Challenges

This page provides information on challenge types.

### Public Challenge

You can create a public challenge by selecting a multiplayer game mode and clicking on the "Create a Public Challenge" button. This will allow any player to accept the game and play against you.

### Challenging a Friend

You can challenge a friend by selecting a multiplayer game mode and clicking on their head in the challenge menu. They'll receive a message that you've challenged them and they can then accept it.


# Scoring

This page provides information on how scoring works.

| Action                 | Score           |
| ---------------------- | --------------- |
| Clear 1 Line           | 100             |
| Clear 2 Lines          | 300             |
| Clear 3 Lines          | 500             |
| Clear 4 Lines (Tetris) | 800             |
| Soft Drop              | 1 \* distance   |
| Hard Drop              | 2 \* distance   |
| T-Spin                 | \*Coming Soon\* |


# Highscores

This page provides information on the tracked highscores

| Highscore           |
| ------------------- |
| Most Games Played   |
| Most Losses         |
| Most Wins           |
| Highest Total Score |
| Most Lines          |
| Most KOs            |
| Most Playtime       |


# Creating your own schematic

This page provides information on how to create your own schematic.

The plugin ships with the large arcade machine as the standard schematic. You can of course change this if you want to use your own custom schematic. To do so it is strongly advised that you make use of the built in schematic creator i.e. /tfa schematic \<action>. This allows you to create a schematic with ease and make sure that it fits the requirements for being used as a TetrisFriends schematic.

![The schematic helper in action highlighting points of interest with the use of particles.](https://3754903123-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LyYVALeKwHUzgU4rQQM%2F-Lya5OWIo3V2gHi_WVPD%2F-Lya6bD7QAPNsZ2fYy7S%2FSchematicHelper.png?alt=media\&token=7d093138-6875-4e86-9389-484920603a08)

### Step 1 - Setting the center

Set the center of the schematic with **/tfa schematic center**. The center is highlighted with a yellow box after the next step is completed. You can move the center later if it doesn't fit.

{% hint style="warning" %}
The center is always set at y=92 to match the internal positioning.
{% endhint %}

### Step 2 - Enabling the visualizer

Execute **/tfa schematic helper**. This will highlight points of interest relative to the specified center.

| Color         | Description                                                           |
| ------------- | --------------------------------------------------------------------- |
| Yellow Cube   | The center of the schematic.                                          |
| Green Cube    | Blocks that have to be placed i.e. the two platforms for the players. |
| Red Cube/Area | You can not place any blocks here.                                    |
| Blue Outline  | Your WorldGuard selection.                                            |

### Step 3 - Validating your schematic

Execute **/tfa schematic validate.** If everything is OK the following message will be sent.

```
Your schematic is valid. You can save it with '/tfa schematic save <name>'
```

If anything is incorrect an informative message with the issue and the solution to it is sent to the player.

### Step 4 - Saving your new schematic

Execute **/tfa schematic save \<name>** to save the schematic. The schematic is then saved to the schematics folder in the TetrisFriends folder. The suffix **.schematic** is appended if not specified.

{% hint style="warning" %}
You have to use a unique name for the schematic.
{% endhint %}

### Step 5 - Putting the schematic to use \*IMPORTANT\*

{% hint style="danger" %}
This step contains very important information. Please review it carefully.
{% endhint %}

To use your new schematic you have to do the following.

1. Stop the server.
2. Open your config.yml and set the World.Schematic to your new schematic.
3. **Delete the TetrisFriends world.**
4. Start your server.

You have to delete the TetrisFriends world to remove already pasted schematics. The plugin checks if there are two player platforms (the green cubes in the helper); if there are, no schematic is pasted. To make sure all cells have your new schematic you have to delete the world.

{% hint style="success" %}
Made it here? Your new schematic is ready to be put to use - congratulations!
{% endhint %}


# World Mechanics

This page provides information on how TetrisFriends actually work.

### Grid system

In order for multiple game instances to be running concurrently TetrisFriends makes use of a custom grid based system which spins up new instances on demand. Take a look at the image below:

![](https://3754903123-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LyYVALeKwHUzgU4rQQM%2F-Ly_uwRGBiPR2mZjbiIt%2F-Ly_xiih56BVPMdttbm-%2Fimage.png?alt=media\&token=edecd3ab-467f-49d7-9e4c-f257b12981c1)

It first tries to start a game in the cell in the upper right corner. If that is not possible it proceeds to the next cell and checks. It will continue to do so until it finds a free cell. If it reaches the end of the red arrow it will try in the 16 cells in the next ring and then the 24 cells in the third ring and so on.

### Note on performance

The plugin has a "warm-up" related to the cells. Each cell contains a copy of the selected schematic in the default case each cell has a large arcade machine. When a schematic is pasted it'll spike the server shortly, however, the schematic is only pasted once in each cell. Here's an example:

The plugin has been installed and one player is playing in the first cell where the schematic has been pasted. A second player starts a game which results in a schematic being pasted in the second cell spiking the server shortly. Now both players are done playing and two new players want to play. A schematic has been pasted in the first two cells so there is no need for a schematic to be pasted again thus no spike.

{% hint style="info" %}
You can skip the "warm-up" with the pregeneration command found [here](https://tetrisfriends.benzoft.com/commands-and-permissions#admin-commands-tetrisfriendsadmin).
{% endhint %}