Other versions: Deutsch

Introduction

Welcome to the english Liquip-wiki. This book will teach you how to use the Liquip-plugin, which features it has and how to extend it with your own plugins.

Source Code

The source code from which this book is generated can be found on GitHub.

Getting started

To get started with Liquip, you first need to understand some crucial parts of the plugin. In this chapter, we will discuss:

• Installing the plugin
• Understanding the config

Installation

To install the plugin you need to download the latest version of it from the GitHub releases tab and put the inside of your servers plugin directory. In the following guide you will be taught to do so step by step.

Prerequisites

To use the plugin you need the following:

• Java 17 or higher
• Paper 1.19 server (other versions are not tested)

Installing Java

To install Java you can go to Adoptium. They provide prebuilt Java-binaries and even installers for Java.

Installing Paper

To install Paper please follow this guide.

Installing the plugin

The last step to installing Liquip is downloading the plugin from the releases tab on our GitHub.

On that page search for a file called somewhat similar to paper-standalone-3.x.x-all.jar.

This is the plugin archive you can then download and put into the plugins directory inside the directory you installed your paper server to.

After that restart your server, and you should be good to go.

The Config Format

Liquip uses a modified version of JSON for all of its config files.

If you don't know JSON yet, you easily learn it with the Wikipedia article.

This position is especially important.

Differences

Liquip allows the following things:

• unquoted field names
• comments
• single quotes

So you might do something like this:

{
  // some comment
  name: 'value',
  'otherName': "otherValue"
}

Custom items

In this chapter you will learn how to create custom items with Liquip.

Registration

The files for the items must be placed in a specific location and must be registered in the main config.

File structure

The file structure in the directory plugins/liquip should currently look something like this:

.
└── config.json

To now add items you want to create a new directory to store your item files.

Best is to name it something like items.

In this directory you can put your item files directly or make subdirectories for each namespace.

Here you can see an example:

.
├── config.json
└── items
    └── mynewitems
        ├── bedrock_pickaxe.json
        └── bedrock_sword.json

For each new item you add, you will create a new file there.

Registration

To register your items you have to add a new entry to the items list in the config.json file in the directory plugins/liquip with the path to the item file.

For the example shown above it would look something like this:

{
  "items": [
    "items/mynewitems/bedrock_pickaxe.json",
    "items/mynewitems/bedrock_sword.json"
  ]
}

Minimal item config

The minimal config that you put inside your item files looks like this:

{
  "key": "test:test_item",
  "material": "minecraft:paper",
  "displayName": "<blue>Test Item"
}

In the next chapters you will learn about more features of the item configuration but for now this is all you will need.

The key field is the key your item will be identified with. It consists of a first part, the namespace, and a second part the key. The namespace should be the name of the group of items you want to create or for plugin developers the name of their plugin. The both parts should be all lowercase and may separate words with underscores. The second part may contain slashes to further group items.¹

The material field is a simple minecraft item identifier used in command. You can find these on the unofficial Minecraft Wiki's page of the item. For paper for example you can find the key here. The namespace will always be minecraft.

The displayName field is a MiniMessage component. This allows you to format the name of your item with modern formatting features like RGB colors.

This will add a new item with the identifier test:test_item made out of paper to Liquip. If you give it to yourself with /liquip give test:test_item it will have the name Test Item colored in blue.

¹ For further information read this.

Adding a lore

In Liquip you can add a lore (the lines below the item's name) to your items.

For this you need to create a new list with the name lore like so:

{
  // ...
  "lore": []
}

You can put strings each representing a new line into this list.

Each individual line - as the item's display name - supports MiniMessages.

The default color of each line is purple.

Here's an example of this:

{
  // ...
  "lore": [
    "<blue>This is the first line",
    "This line is purple",
    "<italic>This line is italic"
  ]
}

Adding enchantments

Adding enchantments to items will apply the given enchantments to this item by default.

For example, you could add efficiency 10 to an item like this:

{
  // ...
  "enchantments": [
    {
      "id": "minecraft:efficiency",
      "level": 10
    }
  ]
}

Each entry in this list is a new enchantment applied to the item.

Adding unbreaking 4 to it would look like this:

{
  // ...
  "enchantments": [
    {
      "id": "minecraft:efficiency",
      "level": 10
    },
    {
      "id": "minecraft:unbreaking",
      "level": 4
    }
  ]
}

Features

A feature is a concept introduced by Liquip. It provides support for modifying items in other ways than just enchantments.

Features may or may not be tagged.

Untagged features have a value of null or true.

Tagged features have a value of anything but null.

Features are stored in an object called features like this one:

{
  // ...
  "features": {}
}

For example, to make your item unbreakable you'd have to write this:

{
  // ...
  "features": {
    "minecraft:unbreakable": true
  }
}

You could also use null inplace of true as the minecraft:unbreakable feature is untagged.

An example of a tagged feature would be this:

{
  // ...
  "features": {
    "minecraft:dye_leather": "#00FFC0"
  }
}

This would make your item - if it was made of leather - colored this specific color.

Attribute modifiers

Minecraft has a concept called attribute modifiers. It allows you to modify things like movement speed of players.

In the context of item creation they allow you to modify these things for the player holding or wearing your item.

An item may have none to several attribute modifiers.

Single attribute modifier

A single attribute modifier looks like this:

{
  // ...
  "features": {
    "minecraft:attribute_modifier": {
      "name": "myAttributeModifier",
      "attribute": "generic_movement_speed",
      "amount": 0.25,
      "operation": "*",
      "slot": "feet"
    }
  }
}

This will give every player wearing the item on their feet a 25% speed boost.

The name field is just a string to indicate from where the attribute modifier came.

The field called attribute specifies what attribute should be changed. Possible values can be found here.

The amount the attribute should be changed by is indicated by amount.

The amount can either be just added by setting operation to + or added in percent of the original by setting operation to *. Last will, for example, for a base damage amount of 10 and an attribute amount of 0.4 add 40% (or 4 damage) to the total damage. After appliance the damage will be 14.

The slot represents what slot a player need to wear the item in to get the attribute modifiers applied to themselves. Possible values are can be found here.

Several attribute modifiers

To add more attribute modifiers to one item you put them in a list like so:

{
  // ...
  "features": {
    "minecraft:attribute_modifier": [
      {
        "name": "myAttributeModifier",
        "attribute": "generic_movement_speed",
        "amount": 0.25,
        "operation": "*",
        "slot": "feet"
      },
      {
        "name": "myOtherAttributeModifier",
        "attribute": "generic_attack_damage",
        "amount": 5,
        "operation": "+",
        "slot": "feet"
      }
    ]
  }
}

Reference

This chapter provides information over all currently available features of Liquip:

• Default features

Types

Attribute modifier

An attribute modifier may be an object or a list of objects.

Each object has the following fields:

• attribute: Attribute
• name: String
• amount: Float
• operation: "+"/"*"

If operation is "+", amount will be added to the attribute.

If operation is "*", attribute's value will be multiplied by amount + 1. This means it will show up as e.g. +50%.

Example

{
  "attribute": "generic_attack_damage",
  "name": "myAttackDamageModifier",
  "amount": 0.5,
  "operation": "*"
}

Attribute

An attribute is one of the following strings representing an attribute of an entity:

Slot

Slots represent an equipment slot of a player like his hand. They may be one of the following values represented as a string:

Default features

This table shows all the features currently available in paper-standalone by default:

Planned / in progress