CoreProtect — Minecraft Java Edition 1.16 - 1.21.11+

Multiplayer Minecraft servers require a detailed audit of player actions in order to prevent unauthorized changes to the map and the theft of in-game valuables. The server's vanilla core does not record the history of terrain edits or the movement of items in containers, so administrators are left with no way to identify offenders or undo destruction without fully restoring the map files from backups. The CoreProtect server plugin logs all events that change the world, builds detailed indexes of user actions, and performs pinpoint rollbacks of an area based on complex parametric queries. The tool operates in asynchronous mode, writing transactions to a queue in order to protect the server's main thread from delays.

1. Databases and asynchronous logging architecture

The CoreProtect plugin intercepts server events using the event handlers of the Bukkit/Paper API. To prevent the server's main thread (Server Thread) from being blocked while processing thousands of records per second, the plugin uses an asynchronous logging model. Events (the destruction of a block, a change in a chest's inventory, the use of a command) are first placed into an internal dynamic buffer, DataQueue. A background consumer thread (Consumer Thread) reads the transactions from the buffer and writes them to the database in batch transactions (Batch processing), which reduces the load on the storage drive.

The plugin supports working with two database management systems (DBMS):

1. SQLite (local by default): All information is written to the database.db file in the plugin's directory. SQLite does not require the installation of third-party services, which makes it convenient for small local servers with a low transaction level.

2. MySQL / MariaDB (external server): Uses a network connection to a separate database server. This solution is the industry standard for large servers and server networks with a high player count (from 50 players). MySQL ensures a high execution speed for index queries and eliminates fragmentation of the local storage.

Database table schema

CoreProtect creates a set of relational tables in order to optimize data storage. Instead of storing full text strings for each record, the plugin uses dictionary tables for unique player names, worlds, block types, and entities.

All coordinates x, y, z are indexed together with the world identifier wid to ensure instant searching of transactions within a given radius.

2. Command syntax and filtering parameters

Interaction with the CoreProtect database is carried out using text commands. The main operations are: inspecting, looking up, rolling back, and undoing a rollback.

Inspector mode /co inspect or /co i)

The command switches the client into local audit mode. After activation, the player can interact with the world to retrieve logs:

·        A left-click on an existing block displays in chat the nickname of whoever placed it, along with the date, time, and coordinates.

·        A right-click on an empty surface (or block) displays the history of blocks that previously occupied this space or were removed.

·        A right-click on a container (chest, furnace, barrel, shulker) shows the log of item movement.

Query filtering parameters /co rollback, /co restore, /co lookup)

To select data, the plugin uses combined parameters in the format parameter:value. Parameters are separated by spaces:

1. User u:<name>): Specifies the player to check. You can specify several names separated by a comma (for example, u:Stevie,Alex). To roll back natural events, technical identifiers are used:

·        u:#fire – the spread of fire.

·        u:#lava – the flow of lava.

·        u:#water – the flow of water.

·        u:#creeper – a CREEPER explosion.

·        u:#tnt – a TNT explosion.

·        u:#enderman – the movement of blocks by an ENDERMAN.

2. Time t:<value>): The time interval for analysis. Supports units of measurement: s (seconds), m (minutes), h (hours), d (days), w (weeks), y (years). Combining units is allowed, for example: t:2w4d6h (2 weeks, 4 days, and 6 hours).

3. Radius r:<number>): The radius of the search zone in blocks around the command executor. Also supports special values:

·        r:#global – a search across the entire database (within all loaded chunks).

·        r:#world – a search within the current game world.

·        r:#chunk – a search within the player's current chunk.

·        r:#selection (or r:#we) – limits the search to the bounds of the current WorldEdit selection.

4. Action a:<type>): Filters records by operation type:

·        a:block – the placement and destruction of blocks.

·        a:+block – only the placement of blocks.

·        a:-block – only the destruction of blocks.

·        a:container – inventory transactions.

·        a:+container – adding items to a container.

·        a:-container – removing items from a container.

·        a:kill – the death of animals and monsters.

·        a:spawn – the spawning of entities.

·        a:chat – chat messages.

·        a:command – entered commands.

·        a:session – player logins.

5. Blocks b:<material>): Limits the search to the specified materials (for example, b:stone,oak_planks).

6. Exclusion e:<material>): Excludes materials from processing (for example, e:tnt).

Rollback preview and undoing operations

To minimize errors during large-scale rollbacks, CoreProtect supports a visual simulation system:

1. Running the rollback command with the #preview flag (for example, /co rollback u:Griefer t:2h r:20 #preview) does not change the map files. Instead, the client receives block-change packets in the current rendering session. The administrator sees the world in its "post-rollback" state, while for other players the blocks remain unchanged.

#preview

/co apply

2. To apply the result, the command /co apply is used.

3. To cancel the preview, the command /co cancel is used.

4. To undo an already executed physical rollback, the command /co undo is used, which returns the coordinates to the state prior to running /co rollback.

3. Full description of the configuration file config.yml

The configuration file manages limits, logging parameters, and connections to databases.

General settings block (General Settings)

·        verbose: true – outputs a detailed report to the console about each modified coordinate during the execution of rollbacks. If set to false, only the total number of changed blocks is output.

·        check-updates: true – checks at startup whether there are new versions of the plugin on the developer's servers.

·        api-enabled: true – allows third-party plugins to interact with CoreProtect's data.

·        default-radius: 10 – the default rollback radius if this parameter is not specified in the command.

·        max-radius: 250 – limits the maximum radius for a single command. The value 0 removes the limit.

Logging settings block (Logging Settings)

These parameters determine which events specifically are recorded in the database. Disabling unnecessary logs helps reduce the size of the database:

·        block-place: true / block-break: true – logging of the ordinary placement and destruction of blocks by players.

·        natural-break: true – logging of blocks falling as a result of shifts or the destruction of supporting blocks (for example, breaking the block on which a torch was held).

·        block-movement: true – logging of the gravitational falling of sand, gravel, or concrete.

·        pistons: true – logging of the movement of blocks using pistons.

·        block-burn: true – logging of the destruction of blocks by fire.

·        block-ignite: true – logging of players igniting blocks using flint and steel or fireballs.

·        explosions: true – logging of explosions from TNT, CREEPERS, beds in the Nether, or End crystals.

·        entity-kills: true – recording of the death of villagers, animals, monsters, and armor stands.

·        player-chat: true / player-command: true – logging of chat messages and console commands.

·        player-session: true – logging of the times players log in to and out of the server.

·        container-transactions: true – logging of operations involving the movement of items in chests, furnaces, hoppers, and shulkers.

Database block (Database Settings)

·        use-mysql: false – a switch for the database type. If set to true, the plugin connects to an external MySQL DBMS.

·        table-prefix: co_ – a prefix for the names of SQL tables.

·        mysql-host: localhost – the IP address or domain name of the MySQL database server.

·        mysql-port: 3306 – the network port for the connection.

·        mysql-database: minecraft – the name of the target database.

·        mysql-username: root – the database user name.

·        mysql-password: password – the user's password.

·        mysql-ssl: false – enables SSL encryption of the connection to the database server.

4. API for plugin developers

CoreProtect provides developers with access to its database through the CoreProtectAPI class. This allows other plugins (for example, WorldEdit or protection systems) to register their changes or perform an automatic history lookup.

API initialization

To connect to the API, the initialization method is used:

Main methods of the API interface

·        boolean logPlacement(String user, Location location, Material type, BlockData blockData) – registers the placement of a block in the database on behalf of the specified user.

·        boolean logRemoval(String user, Location location, Material type, BlockData blockData) – registers the destruction of a block.

·        boolean logContainerTransaction(String user, Location location, Material type, ItemStack itemStack, boolean isAdded) – records the operation of adding (true) or removing (false) items from a container.

·        List<String[]> performLookup(int time, List<String> restrictUsers, List<String> excludeUsers, List<Object> restrictBlocks, List<Object> excludeBlocks, List<Integer> restrictActions, int radius, Location location) – performs a lookup according to the specified filters and returns an array of results.

·        List<String[]> performRollback(int time, List<String> restrictUsers, List<String> excludeUsers, List<Object> restrictBlocks, List<Object> excludeBlocks, List<Integer> restrictActions, int radius, Location location) – initiates an asynchronous rollback of changes in the world.

·        List<String[]> performRestore(int time, List<String> restrictUsers, List<String> excludeUsers, List<Object> restrictBlocks, List<Object> excludeBlocks, List<Integer> restrictActions, int radius, Location location) – initiates an asynchronous restoration of changes.

·        boolean hasPlaced(String user, Block block, int time, int offset) – checks whether the specified player placed this block within a certain time.

·        boolean hasRemoved(String user, Block block, int time, int offset) – checks whether the specified player destroyed this block.

5. Performance, compatibility, and maintenance

When working with CoreProtect on servers with a high player count, administrators take into account the specifics of interacting with modern server architectures:

·        Folia support: The Folia server core uses regionized multithreading (Regionized multithreading), which requires strict thread safety from plugins when working with the world. CoreProtect is adapted to work in Folia: the execution of the /co rollback and /co restore operations occurs through the region scheduler (Region Scheduler), which prevents conflicts in chunk access and critical errors such as ConcurrentModificationException.

·        MultiPaper clustering: On MultiPaper-type servers, CoreProtect is configured to use a single external MySQL database. This helps synchronize the history of player actions across the different server nodes of the cluster.

·        Cleaning the database (Purge): The local SQLite database becomes fragmented over time and grows, slowing down the execution of commands. The command /co purge t:30d deletes records older than 30 days. After cleaning the database, the SQLite file database.db does not automatically decrease in size, because the SQLite DBMS keeps free pages for future records. To physically reduce the file on disk, it is necessary to run the VACUUM command via the database console, or to stop the server and perform compression using third-party utilities. Using MySQL eliminates this problem, since the MySQL DBMS releases unused disk space more efficiently.

Conclusion

CoreProtect is the standard for logging and recovery systems on Minecraft Java Edition servers. Unlike alternatives such as LogBlock (which supports only working with MySQL and is limited to logging blocks) or Prism (which has a more complex configuration structure), CoreProtect offers a fully standalone launch with SQLite, detailed tracking of container contents, and a unique rollback preview system, #preview. The plugin's only technical limitation is the significant load on the disk drive during the cleaning of large local SQLite databases, which is why large projects are recommended to use dedicated MySQL DBMS on fast NVMe drives. The plugin is suitable both for small private servers among friends and for large-scale projects with hundreds of active players.