Stellar Protect

Welcome

StellarProtect is an advanced data logging system for Minecraft servers, designed to help you monitor and review every action that occurs in your world. From block breaking, chest access, to PvP and much more. StellarProtect logs everything with a focus on performance and efficiency.

Key Features

✅ Detailed logging of player actions.
⚙️ Multithreaded architecture that avoids affecting the server’s main thread.
🧪 Proven stability on servers with over 200 players online.
🧩 Compatible with versions from Minecraft 1.8 to 1.21.7.
💬 Active community with ongoing support through Discord.
⚡ Folia support is built-in.

Configuration

StellarProtect allows highly adjustable configuration to adapt to server performance, database types, and logging needs. Below are the main sections of the config.yml file.

Debug Options

These options control whether the plugin generates extra messages during operation. Useful for development or troubleshooting.

debugs:
  log: false          # Enables internal log output
  save: false         # Shows detailed save information
  extras: false       # Debugs additional system functions

Performance Optimization

Controls how many resources are used and how data is managed in the background.

optimizations:
  maxCores: 4                    # Max cores used for multithreading
  save-period: 15                # Seconds between autosaves
  batch-size: 200                # Actions before forced save
  max-logs-per-location: 10      # Max logs per block
  time-for-cache-clear: 15       # Minutes before clearing internal cache
  days-to-keep-logs: 15          # Days to retain logs
  delete-old-period: 15          # How often to delete old logs (in minutes)
  clean-placed-cache-period: 30  # How often to clean placed block cache (seconds)
  item-save-period: 30           # How often to save indexed items

Increasing values may improve performance but can affect time accuracy.

Database Configuration

You can choose between h2, mysql, or mongodb. The default is h2, ideal for small or local servers.

databases:
  type: "h2"  # Options: h2, mysql, mongodb

  h2:
    database: StellarProtect

  mysql:
    host: localhost
    port: 3306
    database: StellarProtect
    user: admin
    password: 123456

  mongodb:
    host: localhost
    port: 27017
    database: StellarProtect
    user: admin
    password: 123456

Recommendation: if using MySQL or MongoDB in production, set users with limited access.

Advanced Tracking

Enables tracking of liquids like water or lava, useful to detect environmental griefing.

advanced:
  liquid-tracking: true  # Enables tracking of placed liquids

Log Types

You can enable or disable logging of specific actions by world, and even limit certain block or command types.

logs:
  block_break:
    enabled: true
    worlds:
      - all
    disable_types:
      - none
  command:
    enabled: true
    worlds:
      - all
    disable_types:
      - /login
      - /register
  etc:
    enabled: true
    worlds:
      - all
    disable_types:
      - none

✅ Use worlds: all to apply to all worlds. ❌ Use disable_types: type1, type2 to ignore specific blocks or commands.

Commands

The base command /sp groups multiple administrative, inspection, and maintenance tools.

Subcommand	Description
`/sp lookup`	Searches past actions recorded in the system.
`/sp inspect`	Activates block inspection mode.
`/sp purge`	Deletes old data from the logs.
`/sp debug`	Toggles debug info from the plugin.
`/sp memory`	Displays plugin memory usage stats.
`/sp version`	Displays the currently installed plugin version.
`/sp restore`	Restores actions in a radius or time window.

`/sp lookup`

Searches actions performed by players, such as placing/breaking blocks or chest interactions.

/sp lookup [filters...]

Filter	Example	Description
`action:`	`a:block_place`	Filter by actions
`page:`	`p:1-10`	Show another page or change logs per page
`time:`	`t:1h`	Show logs less than 1 hour old
`radius:`	`r:10`	Show logs within 10 blocks from you
`user:`	`u:user1,user2,=natural`	Shows logs caused by users or natural events.

Special User	Description
`=natural`	Actions caused by nature.
`=fire`	Caused by fire (such as natural wildfires).
`=water`	Related to water (such as flow or placement).
`=lava`	Related to lava.
`=ice_melt`	From melting ice.
`=snow_fall`	From falling snow.
`=lightning`	Caused by lightning strikes.
`=dripstone`	Related to stalactites/stalagmites.
`=piston`	Caused by pistons.
`=explosion`	Caused by explosions.
`=redstone`	Triggered by redstone mechanisms.
`=gravity`	Caused by blocks falling due to gravity.
`=dispenser`	Related to dispensers.
`=observer`	Activated by observers.
`=decay`	Due to natural decay (such as leaf decay).
`=portal`	Related to portals.
`=entity_id`	You can also filter by entity type. EntityType

/sp lookup t:1h r:20 p:3, u:InsiderAnh,User333 a:chat...

`/sp inspect`

Activates inspection mode which shows logs for a specific block when right-clicked, including the player who performed the action.

`/sp purge`

If you have many old logs, use this command to delete them. Be careful, this action is irreversible.

/sp purge t:30d r:20, u:InsiderAnh,User333 a:block_use,block_place

`/sp restore`

/sp restore [filters...]

Filter	Example	Description
`time:`	`t:1h`	Restores actions by time window
`radius:`	`r:10`	Restores actions within a radius

/sp restore t:1h r:20

Permissions

StellarProtect uses a granular permission system to control command access.

Permission List

Permission	Description
`stellarprotect.default`	Basic access for regular players (if applicable).
`stellarprotect.admin`	Full access to all commands and functions.
`stellarprotect.lookup`	Allows use of `/sp lookup` to search actions.
`stellarprotect.inspect`	Allows use of `/sp inspect` on blocks and containers.
`stellarprotect.purge`	Allows use of `/sp purge` to delete records.
`stellarprotect.memory`	Allows use of `/sp memory` to view memory usage.
`stellarprotect.rollback`	Allows use of `/sp restore` and rollback features.

DeveloperAPI

StellarProtect provides an extremely simple and direct public API for plugin developers. Its goal in this BETA version is to offer an immediate way to log common actions like blocks placed, broken, chat messages, and commands, without complex setup.

API Goals

Log custom actions with a single line of code.
Lightweight and direct, no external dependencies.
Respects optimizations and filters in config.yml (by block type or command).
Ideal for testing or basic integration with other plugins (e.g., minigames, region protection, etc.).

Main Class

public class StellarProtectAPI

All functions are static and can be used directly without creating instances.

Available Methods

`logPlace(Player player, Block block, boolean ignoreSkip)`

Logs that a player placed a block.

StellarProtectAPI.logPlace(player, block, false);

ignoreSkip = true ignores the exclusion logic in config.yml (disable_types).
Will not log if the player is not authenticated by StellarProtect.

`logBreak(Player player, Block block, boolean ignoreSkip)`

Logs that a block was broken.

StellarProtectAPI.logBreak(player, block, false);

`logChat(Player player, String message, boolean ignoreSkip)`

Logs a chat message.

StellarProtectAPI.logChat(player, "Hello world!", false);

`logCommand(Player player, String command, boolean ignoreSkip)`

Logs a command used by the player.

StellarProtectAPI.logCommand(player, "/spawn", false);

Why so simple?

StellarProtect is designed with a modular approach, allowing developers to easily access the logging layer without worrying about internal structure or storage. Despite being version 0.0.1 BETA, the API is already stable for its purpose, and:

Internally validates PlayerProtect to avoid errors.
Automatically filters entries based on server config.
Saves actions to cache to be processed asynchronously, improving performance.

Planned Future Improvements

Asynchronous events (ActionLoggedEvent, RollbackCompletedEvent, etc.).
Support for logging other entities and locations without needing a Player.
Custom results or callbacks after logging.

Full Usage Example

@EventHandler
public void onBlockPlace(BlockPlaceEvent event) {
    StellarProtectAPI.logPlace(event.getPlayer(), event.getBlockPlaced(), false);
}

Note: This API is in beta and may change in future versions. It’s recommended to check the changelog before updating.

Community & Feedback

This is a growing project. We welcome your suggestions, comments, and support, whether by leaving a review or joining our Discord.

Together we can keep improving it!