Skip to content

Changes

Page history
Updated wiki authored by Nanit's avatar Nanit
Show whitespace changes
Inline Side-by-side
Generated-menus.md
View page @ 675f0306
#### Page content # Documentation was moved
1. [Auto Generation Basics](#general)
1. [Switch pages](#pages)
1. [Placeholders](#placeholders)
1. [Catalogs](#catalogs)
* [Players](#catalog-players)
* [Worlds](#catalog-worlds)
* [Entities](#catalog-entities)
* [BungeeCord servers](#catalog-servers)
* [Iterator](#catalog-iterator)
## <a name="general"> Auto Generation Basics </a> **New documentation here**: https://abstractmenus.github.io/docs/
\ No newline at end of file
Since version 1.8 the plugin supports auto-generation of menus.
The menu is generated like this:
1) You specify the catalog of objects. It can contain additional parameters for filtering objects, etc.
2) You create a matrix of cells, into which items from the catalog will be placed according to the template. The matrix should have as many rows as the menu itself.
3) You specify item templates. It is in these items that the necessary placeholders from the catalog are indicated.
4) The generated menu might have several pages. Special actions are used to navigate the pages.
The catalogs are listed below. Here we will show you how to create a simple generated menu. We will use the `PLAYERS` catalog, which generates a list of all the players that are on the server.
```hocon
title: "Generated Menu"
size: 4
# Catalog of objects data to generate
catalog {
# Name of the registered catalog
type: PLAYERS
}
# A matrix of cells that will be used to generating
matrix {
# Templates for matrix
templates {
"x" {
skullOwner: "%ctg_player_name%"
name: "&7Player &e%ctg_player_name%"
}
}
# This is a matrix of cells
cells: [
"_________",
"_xxxxxxx_",
"_xxxxxxx_",
"_________",
]
}
```
Here we have created a menu with 4 lines. Once we have specified the `catalog` parameter, the plugin will assume that our menu is auto-generated and will behave appropriately.
`templates` - This is a list of menu templates. There can be many such templates. Each matrix template must have its own tag. A tag is any Latin character from `a` to `z`, or a special character. After we have created the tag, we can describe any menu item inside, as if we were doing it in the `items` block for the menu buttons. Note that we are not specifying a slot. This is because the slot is automatically detected when the menu is generated.
`cells` - This is a matrix of cells. It is essentially a list of strings. Each row of the matrix is ​​a menu row. Each symbol represents an inventory slot. The `_` character (or any other character that is not in the `templates` templates) denotes an empty slot, that is, no item will be added to that inventory slot. The `x` character is the template tag that we defined earlier. This means that only the item of the template `x` and no other item can be added to this inventory slot.
As a result, with enough online, we will get such a menu.
![image](uploads/e4d0c498092d1c622a83eb39a75c4709/image.png)
## <a name="pages"> Switching pages </a>
The catalog can contain many objects, so the menu is paginated when generated. To scroll through these pages, we have created two new actions for the buttons: `pageNext` and `pagePrev`, which scroll the next and previous page respectively.
To add buttons for scrolling, you need to define a list of static buttons, as we do in a simple menu.
```hocon
title: "Generated menu"
size: 4
# Catalog of objects data to generate
catalog {
# Name of the registered catalog
type: PLAYERS
}
# A matrix of cells that will be used to generating
matrix {
# Templates for matrix
templates {
"x" {
skullOwner: "%ctg_player_name%"
name: "&7Player &e%ctg_player_name%"
}
}
# This is a matrix of cells
cells: [
"_________",
"_xxxxxxx_",
"_xxxxxxx_",
"_________",
]
}
# Regular buttons, not generated
items: [
{
slot: 27
material: ARROW
name: "&e&l<<"
click {
// This action turns the previous page
pagePrev: 1
}
},
{
slot: 35
material: ARROW
name: "&e&l>>"
click {
// This action turns the next page
pageNext: 1
}
}
]
```
Here we have specified the static buttons with actions for turning the pages of the generated menu. These buttons will be displayed on all pages of the menu (unless we specify some rule for their display). Thus, we can specify any non-generated items in which placeholders from the catalog will also work.
## <a name="placeholders"> Placeholders </a>
An important part of the auto-generated menu is special placeholders. During menu generation, placeholders are generated for each catalog object that can be used almost anywhere in the menu.
Catalog placeholders look like this:
```hocon
%ctg_<placeholder>%
```
Here `ctg` is a prefix, short for `catalog`. `<placeholder>` is a specific placeholder, which is usually written as `%<placeholder>%`, between the characters `%`.
Each catalog has its own placeholders, you can find them under the description of each one. However, there are also common placeholders that exist outside some catalog. They are described below.
| Placeholder | Type | Description |
| ----------- | ---- | ----------- |
| `page` | Number | Current menu page |
| `pages` | Number | Number of menu pages |
| `page_next` | Number | Next menu page |
| `page_prev` | Number | Previous Menu Page |
| `elements` | Number | Total number of menu items |
For example, to use the `page` placeholder from this list, you can write `%ctg_page%`.
## <a name="catalogs"> Catalogs </a>
A catalog is a collection of objects of the same type. Each catalog has its own type (unique name), which is specified in the menu file.
The catalog can also have additional parameters that you can specify in the same `catalog` block.
Each catalog has its own placeholders. They can be used almost anywhere in the menu, including templates for generation. Below are the standard catalogs available from AbstractMenus.
> **Tip**: You can create your own catalogs using the API.
#### <a name="catalog-players"> Players </a>
Type: `PLAYERS`
Returns all online players on the server. Unlike other catalogs, it has no placeholders. Instead, you can use any placeholders, but in the format of catalog placeholders, that is, with the `ctg_` prefix. During the generation of the menu, the placeholder will be replaced according to the player's object from the catalog, not the player who opened the menu. See the example below.
```hocon
catalog {
type: PLAYERS
}
matrix {
templates {
"x" {
skullOwner: "%ctg_player_name%"
name: "Player level is %ctg_player_level%"
}
}
cells: [
"_________",
"_xxxxxxx_",
"_xxxxxxx_",
"_________",
]
}
```
That is, after the `ctg_` prefix, we can write any placeholder (without the `%` chars), and it will be replaced in the context of the player from the catalog.
#### <a name="catalog-worlds"> Worlds </a>
Type: `WORLDS`
Returns all worlds on the server. Has the following placeholders:
| Placeholder | Type | Description |
| ------------------- | --------- | --------------------------- |
| `world_name` | String | The name of the world |
| `world_type` | String | World type (default, flat, etc.) |
| `world_time` | Number | Time in the world |
| `world_difficulty` | String | Difficulty of the World |
| `world_players` | Number | Number of players in the world |
| `world_entities` | Number | Number of entities in the world |
#### <a name="catalog-entities"> Entities </a>
Type: `ENTITIES`
Returns all entities in the world the player is in. Has an additional parameter to search for entities of a certain type only.
`allowedTypes` - List of strings. If this parameter is specified, only entities of the specified types are returned. See the entity types here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/EntityType.html
| Placeholder | Type | Description |
| ------------------- | --------- | --------------------------- |
| `entity_name` | String | Entity name |
| `entity_custom_name` | String | Entity custom name |
| `entity_location` | String | Entity location |
| `entity_uuid` | String | Unique identifier of the entity |
| `entity_world` | String | The name of the world in which the entity is located |
| `entity_type` | String | Entity type |
#### <a name="catalog-servers"> BungeeCord servers </a>
Type: `BUNGEE_SERVERS`
Returns all BungeeCord servers. Works only if `bungeecord: true` is set in the plugin config
| Placeholder | Type | Description |
| ------------------- | --------- | --------------------------- |
| `server_name` | String | Server name |
| `server_online` | Number | Number of players on the server |
#### <a name="catalog-iterator"> Iterator </a>
Type: `ITERATOR`
Returns a generated list of numbers from A to B. Useful for generating an exact number of items from a template.
Has three parameters:
`start` - Number. Start value (inclusive)
`end` - Number. The final value (inclusive)
`desc` - Optional parameter true/false. If true, numbers will be generated in reverse order. That is if `start` is 1, and` end` is 10, then it will generate `10, 9, 8, ..., 1`
Standard placeholders (not directory placeholders) can be used in these parameters. This means that you can use, for example, the value of a variable.
| Placeholder | Type | Description |
| ----------- | ---- | ----------- |
| `index` | Number | Current number |
So far, these are all available directories. In general, the catalog system is designed for independent expansion by the user to suit his needs. Despite, we will modify and add new catalogs over time.
\ No newline at end of file