# RestrictIO

Banning blocks and items with ease

# RestrictIO

##### Links

- Curse
- [Source](https://git.unitedworldminers.com/io/RestrictIO)
- [Issues](https://git.unitedworldminers.com/io/RestrictIO/issues)
- [Development builds](https://git.unitedworldminers.com/io/RestrictIO/pipelines?scope=branches)

# Ban Entry Structure

Every ban entry has a structure consisting of Criterias, Actions and Triggers

# Criterias

A ban entry may have multiple criterias that will be matched against when checking a block or item. Every criteria has to match for a ban entry to fit.

<table id="bkmrk-name-parameters-desc"><tbody><tr><td>**Name**</td><td>**Parameters**</td><td>**Description**</td></tr><tr><td>ID</td><td>String itemID</td><td>Match the item id (e.g. `minecraft:stone`).

Blocks without a corresponding item can't be matched

</td></tr><tr><td>Meta</td><td>int meta</td><td>Match the item meta or damage. </td></tr><tr><td>Dimension</td><td>String dimName</td><td>the world name where the entry should apply.

The id is also allowed

</td></tr><tr><td>Nbt</td><td>String nbtJson</td><td>Matches the item's NBT tag. For blocks it matches to the tile entity's NBT.

For blocks without tile entity this criteria will be ignored.

</td></tr><tr><td>Player</td><td>String name</td><td>The playername of the player for which the the entry should be valid

</td></tr><tr><td>Mod</td><td>String modid</td><td>The modID the item will be matched against. The modID is the first part of the item's resource location (e.g. `minecraft` for `minecraft:stone`)

</td></tr><tr><td> </td><td> </td><td> </td></tr><tr><td>Not</td><td>Criteria crit</td><td>Negates a given criteria (e.g. `Not(Dimension(0))` will be any dimension exept 0)

</td></tr><tr><td>And</td><td>Criteria c1, Criteria c2</td><td>Combines two criterias with a logical AND. This is not very useful in the ban entry itself because the criterias in the ban entry are already linked to each other with AND

</td></tr><tr><td>Or</td><td>Criteria c1, Criteria c2</td><td>Combines two criterias with a logical OR

</td></tr></tbody></table>

# Actions

A ban entry may have multiple actions that will be executed when an item or block matches its criterias.

<table id="bkmrk-name-parameters-desc"><tbody><tr><td>**Name**</td><td>**Parameters**</td><td>**Description**</td></tr><tr><td>Remove</td><td>-</td><td>Removes the item or block from the world.

By default the player can keep the block or item that is banned (this is useful when an item is only banned in some dimensions).

</td></tr><tr><td>Message</td><td>String message</td><td>Prints a message to the player.</td></tr><tr><td>Log</td><td>-</td><td>Logs the incident to the console</td></tr><tr><td>Kick</td><td>String kickMessage</td><td>Kicks the player from the server with the given message</td></tr><tr><td>Ban</td><td>String kickMessage, String banMessage</td><td>Bans a player from the server</td></tr><tr><td>ServerCommand</td><td>String command</td><td>Executes a command in a console point of view</td></tr><tr><td>PlayerCommand</td><td>String command</td><td>Executes a command in a player point of view</td></tr></tbody></table>

The command of ServerCommand and PlayerCommand has some patterns for the execution environment:

<table id="bkmrk-%25p-the-player-name-%25"><tbody><tr><td>%p</td><td>The player name</td></tr><tr><td>%uuid</td><td>The player's UUID with hypens

</td></tr><tr><td>%id</td><td>The item id</td></tr><tr><td>%meta</td><td>The item meta / damage</td></tr><tr><td>%size</td><td>The item stack size</td></tr><tr><td>%dim</td><td>The dimension id of the incident</td></tr></tbody></table>

# Triggers

There are different incidents where RestrictIO checks whether the item or block is banned. You can specify for every Ban entry in which case it should be checked.

<table id="bkmrk-name-description-per"><tbody><tr><td>**Name**</td><td>**Description**</td><td>**Checked Items**</td><td>**Performance Cost**</td></tr><tr><td>BlockBreak</td><td>When a block gets broken</td><td>The block being broken</td><td>low</td></tr><tr><td>BlockPlace</td><td>When a block gets placed</td><td>The block being placed</td><td>low</td></tr><tr><td>InvScan</td><td>Periodic (all 30s) scan of all player inventories</td><td>All stacks in the player's inventory</td><td>low</td></tr><tr><td>ItemDrop</td><td>When a player drops an item or when he dies</td><td>The item(s) being dropped</td><td>low</td></tr><tr><td>ItemPickup</td><td>When a player tries to pickup an item</td><td>The items will be picked up</td><td>high</td></tr><tr><td>ItemInteract</td><td>When a player interacts (item rightclick, block left or rightclick)</td><td>The (optional) block the player interacts with and/or (optional) the item in hand</td><td>very high</td></tr><tr><td>ReciepeRegistration</td><td>When the reciepes get registered. <span style="text-decoration: underline;">The reciepe will be disabled globally</span>!</td><td>All standard shape(less) crafting outputs</td><td>on startup</td></tr></tbody></table>

<p class="callout danger">For performance reasons you should use as few triggers as possible for your needs.</p>

<p class="callout warning">Don't use BlockBreak/BlockPlace in conjunction with ItemInteract!   
ItemInteract covers the them.</p>

#####   
Examples:

- Blocking a machine that is not placed  
    
    - BlockPlace
    - ReciepeRegistration (when not allowed anywhere)
- Blocking a machine that may have already been placed 
    - ItemInteract
    - ReciepeRegistration (when not allowed anywhere).
- Completely blocking an item or block that is already in inventories and in the world 
    - ItemDrop
    - ItemPickup
    - ItemInteract
    - ReciepeRegistration
    - InvScan

# Manage Bans

After you got to read what a ban consists of we have to talk about adding and removing bans.

# Ingame GUI

RestrictIO has an ingame GUI that can be opened with `/rio gui`.

# RestrictIO command

You can manage the bans over the console with the `/rio` commands.

<p class="callout info">Unfortunately you can't edit a ban over console - you have to remove the old and recreate it.  
Alternatively you can edit a ban with the ingame GUI or by editing the file.</p>

##### Adding a ban

`/rio ban <criterias> <actions> <triggers>`

- Criterias:  
    `none` or a comma-separated list of criterias (see [criteria list](https://wiki.ender.io/books/restrictio/page/criterias "Criterias"))
- Actions:  
    `none` or a comma-separated list of actions (see[ action list](https://wiki.ender.io/books/restrictio/page/actions "Actions"))
- Triggers:  
    `none` or `all` or a comma-separated list of triggers (see [trigger list](https://wiki.ender.io/books/restrictio/page/triggers "Triggers"))

<p class="callout info">If you want to use spaces in strings like in the Message action, use underscores instead of spaces!  
If you explicitly want to use underscores, escape them with a backslashes.</p>

**Examples:**

`rio ban ID(minecraft:wool),meta(12) remove(),Message(This_is_banned!!!) all`   
 removes brown wool and gives a message at all incidents.

`rio ban mod(minecraft) none blockbreak,blockplace`  
 blocks any block break or place without any other action

##### Removing a ban

`rio unban <index>` removes a ban entry of the ban list at the specified index. You can obtain the index with `/rio list`. <span style="text-decoration: underline;">Note that if you want to delete several entries, the index may be moved.</span>

# File editing

RestrictIO uses the JSON format for storing the ban entries. The file is located at `./config/RestrictIO/restrictedItems.json`.

It is only useful to edit current values as it is fairly simple (i.e. if you don't have enough space for your text in the GUI or console). Adding new criterias/actions/etc. needs you to know the field names (the JSON is a serialization of the data structure in the core). For that you have to look into the [source code](https://git.unitedworldminers.com/io/RestrictIO).

If you have edited your file you can reload it with `rio reload`.

# Commands / Admin OptOut

#### Commands

##### /restrictio &lt;subcommand&gt;

This is the main command of RestrictIO. It can also be accessed by `/rio`.

<table id="bkmrk-subcommand-additiona"><tbody><tr><td>**Subcommand**</td><td>**Additional Parameters**</td><td>**Description**</td></tr><tr><td>gui</td><td>-</td><td>Opens a GUI if the console is too ugly for you</td></tr><tr><td>reload</td><td>-</td><td>Reloads the config, overrides current config if it succeeds to load the new config</td></tr><tr><td>list</td><td>-</td><td>Lists all current ban entries</td></tr><tr><td>ignore</td><td>optional playername</td><td>executes /ignoreitembans</td></tr><tr><td>show</td><td>entry index</td><td>Shows a single ban entry</td></tr><tr><td>ban</td><td>criterias, actions, triggers</td><td>Creates and adds a new ban entry (see [managing bans](https://wiki.ender.io/books/restrictio/page/restrictio-command "RestrictIO command")). Saves the config afterwards</td></tr><tr><td>unban</td><td>entry index</td><td>Removes a ban entry. Saves the config afterwards</td></tr></tbody></table>

##### /ignoreitembans

As an admin you might want to ignore the restrictions given for the users. In the individual entries you can of course exclude yourself with a player criteria, but this might be easier with `/ignoreitembans` or `/rio ignore`. This command toggles a optOut for you or the player you specified in the arguments. You can also toggle this in the mod's GUI.