Skip to content

About

A server-side utility mod for survival servers.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

diakoUtils

A server-side utility mod for survival servers.

diakoUtils provides a small module system for server-side utility features. Modules are disabled by default, can be configured from a TOML file, and can be enabled or disabled at runtime with the /diako command.

Repository: https://github.com/Our-Island/diakoUtils

Features

  • Runtime module and property management through /diako
  • Annotation-driven, validated TOML configuration in the Minecraft config/ directory
  • Optional LuckPerms permission support
  • Vanilla permission fallback when LuckPerms is not installed
  • Server-side module architecture for adding more utilities later

Included modules

Message Hider

Module ID: message_hider

Controls message visibility on the server.

Current options:

  • Hide public player chat broadcasts
  • Optionally hide player join and leave messages

Entities Monitor

Module ID: entities_monitor

Monitors the total entity count across loaded server levels and broadcasts a warning when the count exceeds the configured threshold.

Current options:

  • Entity count threshold
  • Check interval in ticks
  • Warning cooldown in ticks
  • Overlay/actionbar output toggle
  • Custom warning message template

Item Cleaner

Module ID: item_cleaner

Counts matching dropped-item stack contents across all loaded server levels. When the configured item count exceeds the threshold, the module warns players, shows an actionbar countdown, performs a final scan, and removes the currently matching dropped-item entities.

Current options:

  • WHITELIST, BLACKLIST, and ALL filter modes
  • Item selectors using item IDs and #item_tag entries
  • Item-count threshold based on actual stack sizes
  • Configurable warning duration and scan interval
  • Automatic countdown cancellation when the count returns to the threshold or below

The default mode is WHITELIST. Its default selectors cover common stone-like items, stone, cobblestone, netherrack, and end stone. The module only affects ItemEntity drops; it does not modify inventories, containers, item frames, or block entities.

Optional integrations

LuckPerms

LuckPerms is optional. When LuckPerms is installed, diakoUtils checks LuckPerms permission nodes through the LuckPerms API. When LuckPerms is not installed or its API is unavailable, diakoUtils falls back to the vanilla gamemaster command permission level.

Commands

Base command:

/diako

Available subcommands:

/diako list
/diako status <module>
/diako enable <module>
/diako disable <module>
/diako config <module>
/diako config <module> list
/diako config <module> get <property>
/diako config <module> set <property> <value>
/diako config <module> reset <property>
/diako config <module> reset-all
/diako reload

The <module> argument suggests registered module IDs. Property commands also suggest property IDs and common values such as booleans, enum values, defaults, and configured numeric limits. String values use a greedy argument, so values containing spaces do not need quotes. List<String> properties use comma-separated command input and are persisted as native TOML arrays.

Permissions

When LuckPerms is installed, use these permission nodes:

Permission Description
diakoutils.command Grants access to all /diako command actions
diakoutils.command.list Grants /diako list
diakoutils.command.status Grants /diako status <module>
diakoutils.command.enable Grants /diako enable <module>
diakoutils.command.disable Grants /diako disable <module>
diakoutils.command.reload Grants /diako reload
diakoutils.command.config Grants all module property commands
diakoutils.command.config.get Grants property list and get commands
diakoutils.command.config.set Grants the property set command
diakoutils.command.config.reset Grants property reset and reset-all commands

Example LuckPerms commands:

/lp group admin permission set diakoutils.command true
/lp group moderator permission set diakoutils.command.list true
/lp group moderator permission set diakoutils.command.status true
/lp group moderator permission set diakoutils.command.config.get true

Configuration

Configuration file:

config/diakoutils.toml

All modules are disabled by default. The file is created automatically on first run. Module properties are declared with @ModuleProperty, loaded and validated atomically per module, and written to their existing TOML paths.

Example configuration:

[modules.message_hider]
enabled = false
hide_public_chat = true
hide_join_leave_messages = false

[modules.entities_monitor]
enabled = false
threshold = 800
check_interval_ticks = 100
cooldown_ticks = 200
overlay = false
message_template = "Entity count {count} exceeded the threshold of {threshold}."

[modules.item_cleaner]
enabled = false
mode = "whitelist"
items = [
    "#diakoutils:item_cleaner/stone_like",
    "minecraft:stone",
    "minecraft:cobblestone",
    "minecraft:netherrack",
    "minecraft:end_stone"
]
threshold = 1000
warning_duration_seconds = 10
check_interval_ticks = 20

Property changes made through /diako config are applied immediately and persisted. If saving fails, the in-memory value is rolled back. /diako reload validates a complete candidate property set before applying it, so a module is never left partially updated.

Message template placeholders

The entities_monitor.message_template option supports these placeholders:

Placeholder Description
{count} Current total entity count
{threshold} Configured entity threshold

The template must contain {count}. The shared diakoUtils › Entities Monitor › prefix and colors are applied by the module and cannot be replaced by the template.

Item cleaner selectors

item_cleaner.items accepts item IDs and item tags. Tags start with #:

minecraft:stone
#diakoutils:item_cleaner/stone_like

Command input is comma-separated:

/diako config item_cleaner set items minecraft:stone,minecraft:cobblestone,#diakoutils:item_cleaner/stone_like

WHITELIST removes only listed items, BLACKLIST preserves listed items and removes other drops, and ALL ignores the list. Empty lists are rejected in whitelist and blacklist modes. Enabling ALL mode writes a warning to the server log.

Development

This project targets Minecraft 26.3, which uses unobfuscated classes and does not use Yarn mappings.

Build the project with:

./gradlew build

Run a development client with:

./gradlew runClient

Run a development server with:

./gradlew runServer

The built mod jar is produced by the normal jar task under:

build/libs/

Project layout

src/main/java/top/ourisland/diakoutils/
├── DiakoUtils.java
├── IModule.java
├── ModuleManager.java
├── TickingModule.java
├── annotation/
├── command/
├── config/
├── discovery/
├── property/
├── modules/
│   ├── entitiesmonitor/
│   ├── itemcleaner/
│   └── messagehider/
├── text/
└── permissions/

Adding a new module

  1. Create a public, non-abstract class implementing IModule, or extend AbstractModule.
  2. Add @DiakoModule to the class and place it under top.ourisland.diakoutils.modules or one of its subpackages.
  3. Add configurable, non-static, non-final fields and annotate them with @ModuleProperty.
  4. Implement TickingModule if the module needs server tick callbacks.
  5. Override validateProperties(...) for rules involving multiple properties.
  6. Override onPropertiesChanged(...) only when runtime caches or counters must be refreshed.
  7. Add any required mixins to diakoutils.mixins.json.

Example:

@DiakoModule(
        id = "example_module",
        displayName = "Example Module",
        description = "An automatically discovered module."
)
public final class ExampleModule extends AbstractModule {

    @ModuleProperty(
            id = "threshold",
            displayName = "Threshold",
            description = "Example numeric threshold.",
            min = "0",
            max = "1000"
    )
    private final int threshold = 100;

}

The framework automatically discovers the module and property, captures the field initializer as its default value, adds command completion, validates command and TOML input, and persists the property at modules.example_module.threshold.

Feedback

Please use GitHub Issues for bug reports and feature requests. When reporting a bug, include the mod version, the Minecraft version, the Fabric version, the Fabric API version, your configuration files, and the relevant console logs so the issue can be reproduced.

Contributing

Contributions are welcome. Fork the repository, create a feature branch, and keep changes focused and easy to review.
When opening a Pull Request, explain what changed, why it changed, and how to test it.

You also need to follow certain commit and Pull Request rules. We use the Conventional Commits for commits and Pull Requests naming.

License

This project is licensed under the MIT License. See LICENSE.txt for details.

About

A server-side utility mod for survival servers.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages