### Dependency Injection Example

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Demonstrates UltiTools-API's dependency injection capabilities, similar to Spring. The `@Autowired` annotation can be used to inject dependencies, reducing the need for static singletons.

```java
@Autowired
```

--------------------------------

### Command Mapping Example

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Illustrates how UltiTools-API simplifies command registration using annotations. Instead of traditional switch-case statements, developers can use `@CmdMapping` to define command formats and associate them with methods.

```java
@CmdMapping(format = "pay <player> <amount>")
```

--------------------------------

### Event Listener Registration Example

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Shows the UltiTools-API approach to handling Bukkit events. The `@EventListener` annotation allows for automatic discovery and registration of event listeners, eliminating manual registration in `onEnable()`.

```java
@EventListener
```

--------------------------------

### Configuration Entry Example

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Illustrates how UltiTools-API handles configuration using typed fields and annotations. The `@ConfigEntry` annotation allows for defining configuration values with built-in validation, simplifying access to plugin settings.

```java
@ConfigEntry
```

--------------------------------

### Fluent Query DSL Examples in Java

Source: https://context7.com/ultikits/ultitools-reborn/llms.txt

Demonstrates how to use the Fluent Query DSL for various data retrieval and manipulation tasks. This DSL allows for chainable operations like filtering, ordering, pagination, and aggregation. It requires the UltiToolsPlugin and DataOperator interfaces.

```java
import com.ultikits.ultitools.abstracts.UltiToolsPlugin;
import com.ultikits.ultitools.interfaces.DataOperator;
import java.util.List;

public class HomeService {

    private final UltiToolsPlugin plugin;

    public HomeService(UltiToolsPlugin plugin) {
        this.plugin = plugin;
    }

    public HomeEntity findHome(String playerId, String homeName) {
        return plugin.getDataOperator(HomeEntity.class)
            .query()
            .where("playerId").eq(playerId)
            .and("homeName").eq(homeName)
            .first();
    }

    public List<HomeEntity> getPlayerHomes(String playerId) {
        return plugin.getDataOperator(HomeEntity.class)
            .query()
            .where("playerId").eq(playerId)
            .orderBy("homeName")
            .list();
    }

    public List<HomeEntity> searchHomes(String pattern) {
        return plugin.getDataOperator(HomeEntity.class)
            .query()
            .where("homeName").like("%" + pattern + "%")
            .limit(10)
            .list();
    }

    public boolean homeExists(String playerId, String homeName) {
        return plugin.getDataOperator(HomeEntity.class)
            .query()
            .where("playerId").eq(playerId)
            .and("homeName").eq(homeName)
            .exists();
    }

    public long countPlayerHomes(String playerId) {
        return plugin.getDataOperator(HomeEntity.class)
            .query()
            .where("playerId").eq(playerId)
            .count();
    }

    public int deletePlayerHomes(String playerId) {
        return plugin.getDataOperator(HomeEntity.class)
            .query()
            .where("playerId").eq(playerId)
            .delete();
    }
}
```

--------------------------------

### Manual UltiTools Module Setup: plugin.yml

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Manually configure a plugin.yml file for an UltiTools module. This file specifies the plugin's name, version, main class, API version, and authors, serving as the core descriptor for the module.

```yaml
name: MyPlugin
version: '${project.version}'
main: com.example.myplugin.MyPlugin
api-version: 620
authors: [ YourName ]
```

--------------------------------

### Scaffold UltiTools Module with CLI

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Use the UltiKits CLI to quickly scaffold a new UltiTools module project. This command installs the CLI, prompts for project details, and generates a complete, compilable project structure including build files and essential configuration.

```bash
npm install -g @ultikits/cli
ultikits create
# Answer the prompts, then:
cd MyModule && mvn compile
```

--------------------------------

### Scheduled Task Example

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Shows how to schedule tasks using UltiTools-API's annotation-driven approach. The `@Scheduled` annotation can be applied to any method to define a periodic execution, replacing the boilerplate of `BukkitRunnable`.

```java
@Scheduled(period = 6000)
```

--------------------------------

### Inter-Module Event Handling Example

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Shows how UltiTools-API facilitates communication between different modules or plugins using an event bus. The `@ModuleEventHandler` annotation enables a publish-subscribe pattern for events, avoiding static coupling.

```java
@ModuleEventHandler
```

--------------------------------

### Query Data with Fluent DSL

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Showcases the fluent Query DSL for constructing database queries. Supports chaining conditions (`where`, `and`), ordering (`orderBy`, `orderByDesc`), and pagination (`limit`), with examples for retrieving lists and checking existence across different storage types.

```java
List<AccountEntity> richPlayers = plugin.getDataOperator(AccountEntity.class)
    .query()
    .where("balance").gte(10000)
    .orderByDesc("balance")
    .limit(10)
    .list();

boolean exists = plugin.getDataOperator(AccountEntity.class)
    .query()
    .where("owner").eq(uuid)
    .and("name").eq("savings")
    .exists();
```

--------------------------------

### Conditional Feature Toggling Example

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Demonstrates UltiTools-API's feature toggling based on configuration. The `@ConditionalOnConfig` annotation allows entire components or features to be conditionally enabled or disabled based on configuration values, simplifying feature management.

```java
@ConditionalOnConfig
```

--------------------------------

### Map Command Parameters Automatically

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Demonstrates automatic parameter parsing and type conversion for command methods. The `@CmdParam` annotation specifies the parameter name, and the framework handles the conversion to the target type, such as `double` in this example.

```java
@CmdMapping(format = "pay <player> <amount>")
public void pay(@CmdSender Player sender, @CmdParam("player") String target, @CmdParam("amount") double amount) {
    // 'amount' is already a double — no manual parsing
}
```

--------------------------------

### UltiTools Module Main Class

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Define the main class for an UltiTools module, extending UltiToolsPlugin and annotated with @UltiToolsModule. This setup enables automatic registration of commands, listeners, and services by the framework.

```java
@UltiToolsModule(scanBasePackages = {"com.example.myplugin"})
public class MyPlugin extends UltiToolsPlugin {
    @Override
    public boolean registerSelf() {
        return true;  // Commands, listeners, services are all auto-registered!
    }

    @Override
    public void unregisterSelf() { }
}
```

--------------------------------

### Implement Scheduled Command Service (Java)

Source: https://github.com/ultikits/ultitools-reborn/blob/main/docs/plans/2026-02-13-issue-36-features-design.md

Provides the Java implementation for the ScheduledCommandService in UltiEssentials. This service initializes, starts, and shuts down scheduled tasks that execute console commands at specified intervals.

```java
@Service
public class ScheduledCommandService {
    @Autowired private EssentialsConfig config;
    private Plugin bukkitPlugin;
    private final List<BukkitTask> tasks = new ArrayList<>();

    @PostConstruct
    public void init() {
        this.bukkitPlugin = Bukkit.getPluginManager().getPlugin("UltiTools");
        startTasks();
    }

    public void startTasks() {
        if (!config.isScheduledCommandsEnabled()) return;
        for (String entry : config.getScheduledCommands()) {
            int colonIndex = entry.indexOf(':');
            if (colonIndex <= 0) continue;
            int interval = Integer.parseInt(entry.substring(0, colonIndex));
            String command = entry.substring(colonIndex + 1);
            BukkitTask task = new BukkitRunnable() {
                @Override
                public void run() {
                    Bukkit.dispatchCommand(Bukkit.getConsoleSender(), command);
                }
            }.runTaskTimer(bukkitPlugin, interval * 20L, interval * 20L);
            tasks.add(task);
        }
    }

    public void shutdown() {
        tasks.forEach(BukkitTask::cancel);
        tasks.clear();
    }

    public void reload() {
        shutdown();
        startTasks();
    }
}
```

--------------------------------

### Transactional Annotation Example

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Illustrates UltiTools-API's support for database transactions using annotations. The `@Transactional` annotation enables Aspect-Oriented Programming (AOP) proxies to manage transaction boundaries automatically, simplifying error handling and rollback.

```java
@Transactional
```

--------------------------------

### ORM Data Storage Example

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Highlights UltiTools-API's Object-Relational Mapping (ORM) feature for data storage. It allows defining database tables and columns using annotations like `@Table` and `@Column`, supporting various databases like MySQL, SQLite, and JSON.

```java
@Table
@Column
```

--------------------------------

### DataOperator CRUD Operations in Java

Source: https://context7.com/ultikits/ultitools-reborn/llms.txt

Illustrates basic Create, Read, Update, and Delete (CRUD) operations using the DataOperator. This class handles automatic data persistence and requires UltiToolsPlugin for initialization. It supports operations like saving, retrieving by ID, getting all, updating, and deleting entities.

```java
import com.ultikits.ultitools.interfaces.DataOperator;
import com.ultikits.ultitools.entities.WhereCondition;
import com.ultikits.ultitools.entities.Comparison;

public class HomeRepository {

    private final DataOperator<HomeEntity> dataOperator;

    public HomeRepository(UltiToolsPlugin plugin) {
        this.dataOperator = plugin.getDataOperator(HomeEntity.class);
    }

    public void saveHome(HomeEntity home) {
        dataOperator.insert(home);
    }

    public HomeEntity getById(String id) {
        return dataOperator.getById(id);
    }

    public List<HomeEntity> getAllHomes() {
        return dataOperator.getAll();
    }

    public List<HomeEntity> getHomesByPlayer(String playerId) {
        return dataOperator.getAll(
            WhereCondition.builder()
                .column("playerId")
                .comparison(Comparison.EQUAL)
                .value(playerId)
                .build()
        );
    }

    public void updateHomeName(String id, String newName) {
        dataOperator.update("homeName", newName, id);
    }

    public void updateHome(HomeEntity home) throws IllegalAccessException {
        dataOperator.update(home);
    }

    public void deleteById(String id) {
        dataOperator.delById(id);
    }

    public List<HomeEntity> getHomesPage(int page, int size) {
        return dataOperator.page(page, size);
    }
}
```

--------------------------------

### Initialize UltiTools Module

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Sets up the main plugin class for UltiTools by applying a single annotation to enable auto-scanning of components within specified packages. This class extends UltiToolsPlugin and overrides essential registration methods.

```java
// Main class — just one annotation to enable auto-scanning
@UltiToolsModule(scanBasePackages = {"com.example.myplugin"})
public class MyPlugin extends UltiToolsPlugin {
    @Override
    public boolean registerSelf() { return true; }

    @Override
    public void unregisterSelf() { }
}
```

--------------------------------

### Develop Services with Dependency Injection and Scheduled Tasks

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Builds services leveraging dependency injection and a fluent query DSL for data operations. Includes a `@Scheduled` annotation for defining background tasks that are automatically managed by the framework.

```java
// Service with DI, query DSL, and scheduled tasks
@Service
public class HomeService {

    @Autowired
    private UltiToolsPlugin plugin;

    public void teleport(Player player, String name) {
        HomeEntity home = plugin.getDataOperator(HomeEntity.class)
            .query()
            .where("playerId").eq(player.getUniqueId().toString())
            .and("name").eq(name)
            .first();

        if (home != null) {
            Location loc = new Location(
                Bukkit.getWorld(home.getWorld()),
                home.getX(), home.getY(), home.getZ()
            );
            player.teleport(loc);
        }
    }

    public List<HomeEntity> getHomes(Player player) {
        return plugin.getDataOperator(HomeEntity.class)
            .query()
            .where("playerId").eq(player.getUniqueId().toString())
            .orderBy("name")
            .list();
    }

    @Scheduled(period = 72000, async = true) // Cleanup every hour
    public void cleanupExpiredHomes() {
        // Automatically called by the framework — no BukkitRunnable needed
    }
}
```

--------------------------------

### Implement Commands with Annotation Mappings

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Creates command executors using annotations for automatic registration and completion. Methods are mapped to specific command formats and parameters, with dependency injection for services.

```java
// Write commands like controllers — auto-registered, auto-completed
@CmdTarget(CmdTarget.CmdTargetType.PLAYER)
@CmdExecutor(alias = {"home"}, permission = "myplugin.home")
public class HomeCommand extends AbstractCommandExecutor {

    @Autowired
    private HomeService homeService;

    @CmdMapping(format = "tp <name>")
    public void teleport(@CmdSender Player player, @CmdParam("name") String name) {
        homeService.teleport(player, name);
    }

    @CmdMapping(format = "set <name>")
    public void setHome(@CmdSender Player player, @CmdParam("name") String name) {
        homeService.setHome(player, name, player.getLocation());
        player.sendMessage("Home set!");
    }

    @CmdMapping(format = "list")
    public void listHomes(@CmdSender Player player) {
        homeService.getHomes(player).forEach(h ->
            player.sendMessage(" - " + h.getName())
        );
    }
}
```

--------------------------------

### Access Configuration in Services (Java)

Source: https://context7.com/ultikits/ultitools-reborn/llms.txt

Shows how to access configuration values within a service using the ConfigManager. It demonstrates retrieving a specific configuration entity and reloading it, ensuring type safety and dynamic updates.

```java
import com.ultikits.ultitools.annotations.Autowired;
import com.ultikits.ultitools.annotations.Service;

@Service
public class HomeService {

    @Autowired
    private UltiToolsPlugin plugin;

    public boolean canCreateHome(Player player) {
        PluginConfig config = plugin.getConfig(PluginConfig.class);
        long currentHomes = plugin.getDataOperator(HomeEntity.class)
            .query()
            .where("playerId").eq(player.getUniqueId().toString())
            .count();
        return currentHomes < config.getMaxHomes();
    }

    public void reloadConfig() {
        try {
            plugin.getConfig(PluginConfig.class).reload();
        } catch (IOException e) {
            plugin.getLogger().error("Failed to reload config", e);
        }
    }
}
```

--------------------------------

### Conditionally Register Components Based on Config (Java)

Source: https://context7.com/ultikits/ultitools-reborn/llms.txt

Illustrates how to use the @ConditionalOnConfig annotation to control the registration of services and command executors. Components are only instantiated if the specified configuration path evaluates to true, or false if `negate` is set to true.

```java
import com.ultikits.ultitools.annotations.ConditionalOnConfig;
import com.ultikits.ultitools.annotations.Service;
import com.ultikits.ultitools.annotations.command.CmdExecutor;

// Service only created if features.teleport_enabled: true
@Service
@ConditionalOnConfig(value = "config/settings.yml", path = "features.teleport_enabled")
public class TeleportService {
    public void teleport(Player player, Location location) {
        player.teleport(location);
    }
}

// Command only registered if features.warp_enabled: true
@CmdExecutor(alias = {"warp"}, permission = "myplugin.warp")
@ConditionalOnConfig(value = "config/settings.yml", path = "features.warp_enabled")
public class WarpCommand extends BaseCommandExecutor {
    @Override
    protected void handleHelp(CommandSender sender) {
        sender.sendMessage("Warp commands help");
    }
}

// Register when feature is DISABLED (negate = true)
@Service
@ConditionalOnConfig(value = "config/settings.yml", path = "features.legacy_mode", negate = true)
public class ModernFeatureService {
    // Only active when legacy_mode is false
}
```

--------------------------------

### Create UltiTools Module with Auto-Scanning

Source: https://context7.com/ultikits/ultitools-reborn/llms.txt

Defines the main entry point for a plugin module using UltiTools-API. It enables auto-scanning for components like @Service, @CmdExecutor, and @EventListener, along with dependency injection and component registration.

```java
import com.ultikits.ultitools.abstracts.UltiToolsPlugin;
import com.ultikits.ultitools.annotations.UltiToolsModule;

@UltiToolsModule(scanBasePackages = {"com.example.myplugin"})
public class MyPlugin extends UltiToolsPlugin {

    @Override
    public boolean registerSelf() {
        // Framework auto-registers all @Service, @CmdExecutor, @EventListener classes
        getLogger().info("MyPlugin enabled!");
        return true;
    }

    @Override
    public void unregisterSelf() {
        getLogger().info("MyPlugin disabled!");
    }
}
```

--------------------------------

### Config Validation with Annotations (Java)

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Demonstrates how UltiTools Reborn validates configuration values using annotations like @ConfigEntity, @ConfigEntry, @Range, @NotEmpty, and @Size. Invalid values are automatically reset to defaults.

```java
@Getter @Setter
@ConfigEntity("config/config.yml")
public class EcoConfig extends AbstractConfigEntity {

    @ConfigEntry(path = "interestRate", comment = "Interest rate per cycle")
    @Range(min = 0.0, max = 1.0)
    private double interestRate = 0.0003;

    @ConfigEntry(path = "currency_name", comment = "Currency display name")
    @NotEmpty
    private String currencyName = "Gold Coin";

    @ConfigEntry(path = "motd", comment = "Server message of the day")
    @Size(min = 1, max = 256)
    private String motd = "Welcome!";
}
```

--------------------------------

### Integrate External Bukkit Plugin with UltiTools

Source: https://context7.com/ultikits/ultitools-reborn/llms.txt

Connects an existing Bukkit plugin to the UltiTools framework, enabling dependency injection and other framework features for standalone plugins. This is achieved by calling UltiToolsAPI.connect() in the plugin's onEnable method.

```java
import com.ultikits.ultitools.api.UltiToolsAPI;
import org.bukkit.plugin.java.JavaPlugin;

public class MyBukkitPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        // Connect to UltiTools - scans for @Service, @CmdExecutor, @EventListener
        UltiToolsAPI.connect(this);
        getLogger().info("Connected to UltiTools framework!");
    }

    @Override
    public void onDisable() {
        UltiToolsAPI.disconnect(this);
    }
}
```

--------------------------------

### Add UltiTools-API Dependency (Gradle)

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

This snippet demonstrates how to include the UltiTools-API in your Gradle project. It uses the 'implementation' configuration to add the specified version of the API to your project's dependencies.

```groovy
implementation 'com.ultikits:UltiTools-API:6.2.2'
```

--------------------------------

### Send Localized and Formatted Messages in Java

Source: https://context7.com/ultikits/ultitools-reborn/llms.txt

This Java code snippet demonstrates how to send localized and formatted messages to players using the UltiTools-API's internationalization (i18n) service. It relies on language files in the `lang/` directory and the `UltiToolsPlugin` service for message retrieval. The `sendLocalizedMessage` method fetches a message by key, while `sendFormattedMessage` allows for message templating with arguments.

```java
import com.ultikits.ultitools.abstracts.UltiToolsPlugin;
import com.ultikits.ultitools.annotations.Service;
import org.springframework.beans.factory.annotation.Autowired;
import org.bukkit.entity.Player;

@Service
public class MessageService {

    @Autowired
    private UltiToolsPlugin plugin;

    public void sendLocalizedMessage(Player player, String key) {
        // Looks up key in lang/{language_code}.json
        String message = plugin.i18n(key);
        player.sendMessage(message);
    }

    public void sendFormattedMessage(Player player, String key, Object... args) {
        String template = plugin.i18n(key);
        String message = String.format(template, args);
        player.sendMessage(message);
    }
}
```

--------------------------------

### Conditional Feature Toggling with @ConditionalOnConfig (Java)

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Shows how to conditionally enable or disable entire features (like services or commands) based on configuration values using the @ConditionalOnConfig annotation. This avoids scattered if-checks in the code.

```java
@Service
@ConditionalOnConfig(value = "config/config.yml", path = "enableInterest")
public class InterestService {
    // This bean is never created if enableInterest: false
}

@CmdExecutor(alias = {"warp"}, permission = "myplugin.warp")
@ConditionalOnConfig(value = "config/config.yml", path = "enableWarp")
public class WarpCommands extends AbstractCommandExecutor {
    // Command doesn't exist if enableWarp: false
}
```

--------------------------------

### AOP Proxies for @Transactional and @ExceptionCatch (Java)

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Illustrates the use of Aspect-Oriented Programming (AOP) proxies, specifically CGLIB, for declarative transaction management with @Transactional and exception handling with @ExceptionCatch. This reduces boilerplate code.

```java
@Service
public class BankService {
    @Transactional(propagation = Propagation.REQUIRED)
    public void transfer(UUID from, UUID to, double amount) {
        withdraw(from, amount);
        deposit(to, amount); // Rolls back both if this throws
    }

    @ExceptionCatch(value = IOException.class, silent = true)
    public String readExternalData() {
        // Returns null on IOException instead of crashing
    }
}
```

--------------------------------

### Integrate UltiTools-API into Bukkit Plugin

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Integrate UltiTools-API into an existing Bukkit plugin by adding a dependency to your plugin.yml and calling UltiToolsAPI.connect(this) in your onEnable method. This allows UltiTools to manage annotated classes within your plugin.

```java
public class MyBukkitPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        // One line — UltiTools scans your plugin for @Service, @CmdExecutor, @EventListener, etc.
        UltiToolsAPI.connect(this);
    }

    @Override
    public void onDisable() {
        UltiToolsAPI.disconnect(this);
    }
}
```

--------------------------------

### Apply World Difficulty Setting (Java)

Source: https://github.com/ultikits/ultitools-reborn/blob/main/docs/plans/2026-02-13-issue-36-features-design.md

Demonstrates how to apply the per-world difficulty setting within the WorldService in UltiWorlds. This code snippet shows the logic for setting the world's difficulty based on the stored configuration.

```java
// In getOrCreateSettings(), after loading settings:
if (settings.getDifficulty() != null) {
    World world = Bukkit.getWorld(worldName);
    if (world != null) {
        world.setDifficulty(Difficulty.valueOf(settings.getDifficulty()));
    }
}
```

--------------------------------

### Utilize IoC Container with @Autowired

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Illustrates dependency injection using the `@Autowired` annotation within a service. The framework manages the instantiation and injection of dependent services, like `TransactionLogger`, and supports transactional operations with automatic rollback.

```java
@Service
public class EconomyService {
    @Autowired
    private TransactionLogger logger;  // Auto-injected

    @Transactional
    public void transfer(UUID from, UUID to, double amount) {
        // Automatic rollback on exception
    }
}
```

--------------------------------

### Module EventBus for Decoupled Communication (Java)

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Demonstrates the Module EventBus for decoupled publish/subscribe communication between modules. It includes defining custom events, subscribing via annotations (@ModuleEventHandler), and publishing events.

```java
// Define a custom event
public class BalanceChangeEvent extends ModuleEvent {
    @Getter private final UUID player;
    @Getter private final double amount;
    public BalanceChangeEvent(UUID player, double amount) {
        this.player = player;
        this.amount = amount;
    }
}

// Subscribe via annotation — auto-discovered by the framework
@Service
public class AuditService {
    @ModuleEventHandler(priority = EventPriority.NORMAL)
    public void onBalanceChange(BalanceChangeEvent event) {
        log(event.getSourceModule(), event.getPlayer(), event.getAmount());
    }
}

// Publish from anywhere
eventBus.publish(new BalanceChangeEvent(player, 100.0));
```

--------------------------------

### Display Description After Teleport (Java)

Source: https://github.com/ultikits/ultitools-reborn/blob/main/docs/plans/2026-02-13-issue-36-features-design.md

This Java code snippet, located in WorldService.java, displays a world description to a player after a successful teleport. It checks configuration settings and parses the description string, translating color codes and replacing placeholders like {player} and {world}. Dependencies include Bukkit API for player messages and ChatColor for formatting.

```java
if (config.isShowDescriptionOnTeleport() && settings.getDescription() != null
        && !settings.getDescription().isEmpty()) {
    String[] lines = settings.getDescription().split("\\n");
    for (String line : lines) {
        String parsed = ChatColor.translateAlternateColorCodes('&',
            line.replace("{player}", player.getName())
                .replace("{world}", displayName));
        player.sendMessage(parsed);
    }
}
```

--------------------------------

### Define Type-Safe Configuration Entity with Validation (Java)

Source: https://context7.com/ultikits/ultitools-reborn/llms.txt

Demonstrates how to create a type-safe configuration entity using @ConfigEntity and @ConfigEntry annotations. It supports automatic validation for ranges, non-empty strings, size constraints, and regex patterns, with default values for invalid entries.

```java
import com.ultikits.ultitools.abstracts.AbstractConfigEntity;
import com.ultikits.ultitools.annotations.ConfigEntity;
import com.ultikits.ultitools.annotations.ConfigEntry;
import com.ultikits.ultitools.annotations.config.*;
import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
@ConfigEntity("config/settings.yml")
public class PluginConfig extends AbstractConfigEntity {

    @ConfigEntry(path = "max_homes", comment = "Maximum homes per player")
    @Range(min = 1, max = 100)
    private int maxHomes = 5;

    @ConfigEntry(path = "home_cooldown", comment = "Teleport cooldown in seconds")
    @Range(min = 0, max = 300)
    private int homeCooldown = 3;

    @ConfigEntry(path = "currency_name", comment = "Currency display name")
    @NotEmpty
    private String currencyName = "Gold";

    @ConfigEntry(path = "welcome_message", comment = "Welcome message for players")
    @Size(min = 1, max = 256)
    private String welcomeMessage = "Welcome to the server!";

    @ConfigEntry(path = "server_id", comment = "Server identifier pattern")
    @Pattern(regex = "[a-zA-Z0-9_-]+")
    private String serverId = "main-server";

    @ConfigEntry(path = "features.teleport_enabled", comment = "Enable teleport feature")
    private boolean teleportEnabled = true;

    public PluginConfig() {
        super("config/settings.yml");
    }
}
```

--------------------------------

### Define Data Entities with ORM Annotations in Java

Source: https://context7.com/ultikits/ultitools-reborn/llms.txt

Demonstrates how to create persistent data entities using UltiTools-API's ORM annotations like @Table and @Column. The framework handles data storage across different backends (MySQL, SQLite, JSON) based on server configuration.

```java
import com.ultikits.ultitools.abstracts.data.BaseDataEntity;
import com.ultikits.ultitools.annotations.Column;
import com.ultikits.ultitools.annotations.Table;
import lombok.*;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@EqualsAndHashCode(callSuper = true)
@Table("player_homes")
public class HomeEntity extends BaseDataEntity<String> {

    @Column("player_id")
    private String playerId;

    @Column("home_name")
    private String homeName;

    @Column("world")
    private String world;

    @Column(value = "x", type = "DOUBLE")
    private double x;

    @Column(value = "y", type = "DOUBLE")
    private double y;

    @Column(value = "z", type = "DOUBLE")
    private double z;

    @Override
    public void onCreate() {
        // Called before first insert
        if (getId() == null) {
            setId(java.util.UUID.randomUUID().toString());
        }
    }
}
```

--------------------------------

### Add UltiTools-API Dependency (Maven)

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

This snippet shows how to add the UltiTools-API as a dependency to your Maven project. It specifies the group ID, artifact ID, and version required to integrate the framework into your build.

```xml
<dependency>
    <groupId>com.ultikits</groupId>
    <artifactId>UltiTools-API</artifactId>
    <version>6.2.2</version>
</dependency>
```

--------------------------------

### Configure Teleport Description Display (Java)

Source: https://github.com/ultikits/ultitools-reborn/blob/main/docs/plans/2026-02-13-issue-36-features-design.md

Defines the Java configuration entry for controlling whether world descriptions are displayed upon teleportation in UltiWorlds. This allows administrators to toggle the visibility of these descriptions.

```java
@ConfigEntry(path = "tp_to_world.show_description", comment = "Show world description on teleport")
private boolean showDescriptionOnTeleport = true;
```

--------------------------------

### Execute Post-Teleport Commands (Java)

Source: https://github.com/ultikits/ultitools-reborn/blob/main/docs/plans/2026-02-13-issue-36-features-design.md

This Java code snippet from WorldService.java executes a list of newline-separated commands after a player teleports. It parses the command string, replaces placeholders like {player} and {world}, and dispatches them to the console sender. This functionality requires the Bukkit API for command dispatching.

```java
if (settings.getPostTeleportCommands() != null && !settings.getPostTeleportCommands().isEmpty()) {
    String[] commands = settings.getPostTeleportCommands().split("\\n");
    for (String cmd : commands) {
        String parsed = cmd.trim()
            .replace("{player}", player.getName())
            .replace("{world}", worldName);
        if (!parsed.isEmpty()) {
            Bukkit.dispatchCommand(Bukkit.getConsoleSender(), parsed);
        }
    }
}
```

--------------------------------

### Configure Scheduled Commands in UltiEssentials (Java)

Source: https://github.com/ultikits/ultitools-reborn/blob/main/docs/plans/2026-02-13-issue-36-features-design.md

Defines the Java configuration entries for enabling and configuring scheduled commands in UltiEssentials. It includes fields for enabling the feature and a list of commands with their execution intervals.

```java
@ConfigEntry(path = "features.scheduled-commands.enabled", comment = "Enable scheduled command execution")
private boolean scheduledCommandsEnabled = false;

@ConfigEntry(path = "features.scheduled-commands.commands",
    comment = "Scheduled commands (format: interval_seconds:command)")
private List<String> scheduledCommands = Arrays.asList(
    "300:say Server is online!",
    "600:broadcast &cReminder: follow server rules!"
);
```

--------------------------------

### AnnouncementService Java Class

Source: https://github.com/ultikits/ultitools-reborn/blob/main/docs/wiki/tutorials/EXAMPLES.md

The AnnouncementService class is responsible for managing in-game announcements. It loads, schedules, and broadcasts announcements based on their configuration. It uses a DataOperator for persistence and Bukkit's scheduler for timed execution. It also handles the creation, deletion, and toggling of announcements.

```java
package com.example.announce.services;

import com.example.announce.AnnouncePlugin;
import com.example.announce.entities.Announcement;
import com.ultikits.ultitools.UltiTools;
import com.ultikits.ultitools.annotations.PostConstruct;
import com.ultikits.ultitools.annotations.PreDestroy;
import com.ultikits.ultitools.annotations.Service;
import com.ultikits.ultitools.entities.WhereCondition;
import com.ultikits.ultitools.interfaces.DataOperator;
import org.bukkit.Bukkit;
import org.bukkit.ChatColor;
import org.bukkit.entity.Player;
import org.bukkit.scheduler.BukkitTask;

import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;

@Service
public class AnnouncementService {
    
    private final DataOperator<Announcement> announcementOperator;
    private final Map<String, BukkitTask> scheduledTasks = new HashMap<>();
    
    public AnnouncementService() {
        this.announcementOperator = AnnouncePlugin.getInstance().getDataOperator(Announcement.class);
    }
    
    @PostConstruct
    public void init() {
        // 启动时加载所有启用的公告
        loadEnabledAnnouncements();
    }
    
    @PreDestroy
    public void cleanup() {
        // 取消所有定时任务
        scheduledTasks.values().forEach(BukkitTask::cancel);
        scheduledTasks.clear();
    }
    
    /**
     * 加载所有启用的公告
     */
    public void loadEnabledAnnouncements() {
        List<Announcement> enabled = announcementOperator.getAll(
            WhereCondition.builder().column("enabled").value(true).build()
        );
        
        for (Announcement announcement : enabled) {
            scheduleAnnouncement(announcement);
        }
        
        Bukkit.getLogger().info("[Announce] 已加载 " + enabled.size() + " 条定时公告");
    }
    
    /**
     * 调度公告
     */
    private void scheduleAnnouncement(Announcement announcement) {
        if (scheduledTasks.containsKey(announcement.getName())) {
            scheduledTasks.get(announcement.getName()).cancel();
        }
        
        long intervalTicks = announcement.getIntervalSeconds() * 20L;
        
        BukkitTask task = Bukkit.getScheduler().runTaskTimer(
            UltiTools.getInstance(),
            () -> broadcastAnnouncement(announcement),
            intervalTicks,
            intervalTicks
        );
        
        scheduledTasks.put(announcement.getName(), task);
    }
    
    /**
     * 广播公告
     */
    public void broadcastAnnouncement(Announcement announcement) {
        String message = ChatColor.translateAlternateColorCodes('&', announcement.getMessage());
        String permission = announcement.getPermission();
        
        for (Player player : Bukkit.getOnlinePlayers()) {
            if (permission == null || permission.isEmpty() || player.hasPermission(permission)) {
                player.sendMessage(message);
            }
        }
    }
    
    /**
     * 创建公告
     */
    public void createAnnouncement(String name, String message, int intervalSeconds) {
        Announcement announcement = Announcement.builder()
            .name(name)
            .message(message)
            .intervalSeconds(intervalSeconds)
            .enabled(true)
            .createdAt(System.currentTimeMillis())
            .build();
        
        announcementOperator.insert(announcement);
        scheduleAnnouncement(announcement);
    }
    
    /**
     * 删除公告
     */
    public boolean deleteAnnouncement(String name) {
        Optional<Announcement> announcement = getAnnouncement(name);
        if (announcement.isPresent()) {
            // 取消定时任务
            if (scheduledTasks.containsKey(name)) {
                scheduledTasks.get(name).cancel();
                scheduledTasks.remove(name);
            }
            
            announcementOperator.delById(announcement.get().getId());
            return true;
        }
        return false;
    }
    
    /**
     * 启用/禁用公告
     */
    public boolean toggleAnnouncement(String name, boolean enabled) {
        Optional<Announcement> announcementOpt = getAnnouncement(name);
        if (announcementOpt.isPresent()) {
            Announcement announcement = announcementOpt.get();
            announcement.setEnabled(enabled);
            
            try {
                announcementOperator.update(announcement);
            } catch (IllegalAccessException e) {
                return false;
            }
            
            if (enabled) {
                scheduleAnnouncement(announcement);
            } else {
                if (scheduledTasks.containsKey(name)) {
                    scheduledTasks.get(name).cancel();
                    scheduledTasks.remove(name);
                }
            }
            
            return true;
        }
        return false;
    }
    
    /**
     * 获取所有公告
     */
    public List<Announcement> getAllAnnouncements() {
        return announcementOperator.getAll();
    }
    
    /**
     * 获取指定公告
     */
    private Optional<Announcement> getAnnouncement(String name) {
        return announcementOperator.getOne(
            WhereCondition.builder().column("name").value(name).build()
        );
    }
}
```

--------------------------------

### Annotation-Driven Command Executor in Java

Source: https://context7.com/ultikits/ultitools-reborn/llms.txt

Defines commands using `@CmdExecutor` and `@CmdMapping` annotations. It automatically handles parameter parsing, type conversion, permissions, sender restrictions, and asynchronous execution. Dependencies like `HomeService` are injected via `@Autowired`.

```java
import com.ultikits.ultitools.abstracts.command.BaseCommandExecutor;
import com.ultikits.ultitools.annotations.Autowired;
import com.ultikits.ultitools.annotations.command.*;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;

@CmdTarget(CmdTarget.CmdTargetType.PLAYER)
@CmdExecutor(alias = {"home", "h"}, permission = "myplugin.home", description = "Home management commands")
public class HomeCommand extends BaseCommandExecutor {

    @Autowired
    private HomeService homeService;

    @CmdMapping(format = "set <name>")
    public void setHome(@CmdSender Player player, @CmdParam("name") String name) {
        homeService.createHome(player, name, player.getLocation());
        player.sendMessage("Home '" + name + "' has been set!");
    }

    @CmdMapping(format = "tp <name>")
    public void teleportHome(@CmdSender Player player, @CmdParam("name") String name) {
        HomeEntity home = homeService.findHome(player.getUniqueId().toString(), name);
        if (home != null) {
            player.teleport(home.toLocation());
            player.sendMessage("Teleported to home '" + name + "'!");
        } else {
            player.sendMessage("Home not found!");
        }
    }

    @CmdMapping(format = "delete <name>")
    public void deleteHome(@CmdSender Player player, @CmdParam("name") String name) {
        homeService.deleteHome(player.getUniqueId().toString(), name);
        player.sendMessage("Home '" + name + "' deleted!");
    }

    @CmdMapping(format = "list")
    public void listHomes(@CmdSender Player player) {
        List<HomeEntity> homes = homeService.getPlayerHomes(player.getUniqueId().toString());
        player.sendMessage("Your homes:");
        homes.forEach(h -> player.sendMessage(" - " + h.getHomeName()));
    }

    @CmdMapping(format = "", permission = "myplugin.home.admin")
    @RunAsync
    public void adminList(@CmdSender Player player) {
        // Runs asynchronously
        player.sendMessage("Loading all homes...");
    }

    @Override
    protected void handleHelp(CommandSender sender) {
        sender.sendMessage("/home set <name> - Set a home");
        sender.sendMessage("/home tp <name> - Teleport to home");
        sender.sendMessage("/home delete <name> - Delete a home");
        sender.sendMessage("/home list - List all homes");
    }
}

```

--------------------------------

### Define Data Entities for Storage

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Defines data entities for automatic persistence across MySQL, SQLite, and JSON. Uses Lombok annotations for conciseness and UltiTools annotations for table and column mapping. Extends BaseDataEntity for generic type handling.

```java
// Define your data — works with MySQL, SQLite, and JSON automatically
@Data @Builder @NoArgsConstructor @AllArgsConstructor
@EqualsAndHashCode(callSuper = true)
@Table("homes")
public class HomeEntity extends BaseDataEntity<String> {
    @Column("player_id") private String playerId;
    @Column("name")      private String name;
    @Column("world")     private String world;
    @Column("x")         private double x;
    @Column("y")         private double y;
    @Column("z")         private double z;
}
```

--------------------------------

### Java Bukkit Event Listener with Auto-Registration

Source: https://context7.com/ultikits/ultitools-reborn/llms.txt

Create Bukkit event listeners that are automatically registered with the server using the @EventListener annotation. This simplifies the process of handling game events by eliminating the need for manual registration in your plugin's main class.

```java
import com.ultikits.ultitools.annotations.EventListener;
import com.ultikits.ultitools.annotations.Autowired;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.event.player.PlayerQuitEvent;

@EventListener
public class PlayerListener implements Listener {

    @Autowired
    private WelcomeService welcomeService;

    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent event) {
        welcomeService.sendWelcome(event.getPlayer());
    }

    @EventHandler
    public void onPlayerQuit(PlayerQuitEvent event) {
        welcomeService.handleQuit(event.getPlayer());
    }
}
```

--------------------------------

### Scheduled Commands Configuration (YAML)

Source: https://github.com/ultikits/ultitools-reborn/blob/main/docs/plans/2026-02-13-issue-36-features-design.md

Represents the YAML output for the scheduled commands configuration in UltiEssentials. It shows the structure for enabling the feature and defining commands with their intervals.

```yaml
features:
  scheduled-commands:
    enabled: false
    commands:
      - "300:say Server is online!"
      - "600:broadcast &cReminder: follow server rules!"
```

--------------------------------

### Java Module EventBus for Inter-Module Communication

Source: https://context7.com/ultikits/ultitools-reborn/llms.txt

Implement decoupled communication between modules using the Module EventBus. Publish and subscribe to custom events, with support for synchronous and asynchronous dispatch, as well as priority ordering. Events can be defined as cancellable, allowing subscribers to prevent default actions.

```java
import com.ultikits.ultitools.events.ModuleEvent;
import com.ultikits.ultitools.events.Cancellable;
import com.ultikits.ultitools.events.EventBus;
import com.ultikits.ultitools.events.EventPriority;
import com.ultikits.ultitools.annotations.ModuleEventHandler;
import lombok.Getter;

// Define a custom event
public class HomeTeleportEvent extends ModuleEvent implements Cancellable {
    @Getter private final Player player;
    @Getter private final HomeEntity home;
    @Getter @Setter private boolean cancelled = false;

    public HomeTeleportEvent(Player player, HomeEntity home) {
        this.player = player;
        this.home = home;
    }
}

// Subscribe via annotation
@Service
public class TeleportAuditService {

    @ModuleEventHandler(priority = EventPriority.NORMAL, ignoreCancelled = true)
    public void onHomeTeleport(HomeTeleportEvent event) {
        // Log teleport events
        System.out.println(event.getPlayer().getName() + " teleported to " + event.getHome().getHomeName());
    }
}

// Publish events
@Service
public class HomeService {

    @Autowired
    private EventBus eventBus;

    public void teleportToHome(Player player, HomeEntity home) {
        HomeTeleportEvent event = new HomeTeleportEvent(player, home);
        eventBus.publish(event);  // Synchronous dispatch

        if (!event.isCancelled()) {
            player.teleport(home.toLocation());
        }
    }

    public void notifyHomeCreated(HomeEntity home) {
        HomeCreatedEvent event = new HomeCreatedEvent(home);
        eventBus.publishAsync(event);  // Async dispatch (non-cancellable events only)
    }
}

// Programmatic subscription with Subscription handle
@Service
public class DynamicSubscriber {

    @Autowired
    private EventBus eventBus;

    private Subscription subscription;

    public void enableFeature() {
        subscription = eventBus.subscribe(HomeTeleportEvent.class, event -> {
            event.getPlayer().sendMessage("Teleporting...");
        });
    }

    public void disableFeature() {
        if (subscription != null && subscription.isActive()) {
            subscription.unsubscribe();
        }
    }
}
```

--------------------------------

### Schedule Tasks with @Scheduled Annotation

Source: https://github.com/ultikits/ultitools-reborn/blob/main/README.md

Defines background tasks using the `@Scheduled` annotation. The framework handles the creation, registration, and cancellation of BukkitRunnables, simplifying the management of timed or delayed operations, including asynchronous execution.

```java
@Service
public class InterestService {
    @Scheduled(delay = 100, period = 36000, async = true) // 30min cycle, async
    public void distributeInterest() {
        // Called automatically. Cancelled when plugin unloads.
    }

    @Scheduled(delay = 20) // One-shot: runs once after 1 second
    public void onStartup() {
        // Initialization logic
    }
}
```

--------------------------------

### Dependency Injection with @Autowired in Java

Source: https://context7.com/ultikits/ultitools-reborn/llms.txt

Enables automatic dependency injection using the Spring-style `@Autowired` annotation. The Inversion of Control (IoC) container manages object instantiation and resolves circular dependencies. Dependencies can be marked as optional using `required = false`.

```java
import com.ultikits.ultitools.annotations.Autowired;
import com.ultikits.ultitools.annotations.Service;
import com.ultikits.ultitools.abstracts.UltiToolsPlugin;

@Service
public class HomeService {

    @Autowired
    private UltiToolsPlugin plugin;

    @Autowired
    private NotificationService notificationService;

    @Autowired(required = false)  // Optional dependency
    private AuditService auditService;

    public void createHome(Player player, String name, Location location) {
        HomeEntity home = HomeEntity.builder()
            .playerId(player.getUniqueId().toString())
            .homeName(name)
            .world(location.getWorld().getName())
            .x(location.getX())
            .y(location.getY())
            .z(location.getZ())
            .build();

        plugin.getDataOperator(HomeEntity.class).insert(home);
        notificationService.notify(player, "Home created!");

        if (auditService != null) {
            auditService.log("Home created: " + name);
        }
    }
}

```

--------------------------------

### World Settings Post-Teleport Commands Field (Java)

Source: https://github.com/ultikits/ultitools-reborn/blob/main/docs/plans/2026-02-13-issue-36-features-design.md

This Java code defines a new field `postTeleportCommands` in the WorldSettings entity. This field stores newline-separated commands to be executed after a teleport. It is annotated with `@Column` for database persistence. The `createDefault()` method initializes this field to null.

```java
@Column("post_teleport_commands")
private String postTeleportCommands;  // Newline-separated commands, or null
```

```java
.postTeleportCommands(null)
```

--------------------------------

### Java Transaction Management with @Transactional

Source: https://context7.com/ultikits/ultitools-reborn/llms.txt

Utilize the @Transactional annotation to wrap database operations in transactions. This ensures that all operations within a method either commit together or roll back together in case of exceptions. It supports configurable propagation and isolation levels, and can be set to rollback for specific exception types or be read-only for optimization.

```java
import com.ultikits.ultitools.annotations.Service;
import com.ultikits.ultitools.annotations.Transactional;
import com.ultikits.ultitools.annotations.Propagation;

@Service
public class BankService {

    @Autowired
    private UltiToolsPlugin plugin;

    @Transactional
    public void transfer(String fromPlayer, String toPlayer, double amount) {
        // Both operations commit together or rollback together
        withdraw(fromPlayer, amount);
        deposit(toPlayer, amount);
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void logTransaction(String message) {
        // Always runs in a new transaction
    }

    @Transactional(readOnly = true)
    public double getBalance(String playerId) {
        // Read-only transaction for optimization
        return plugin.getDataOperator(AccountEntity.class)
            .query()
            .where("playerId").eq(playerId)
            .first()
            .getBalance();
    }

    @Transactional(rollbackFor = {InsufficientFundsException.class})
    public void withdrawWithCheck(String playerId, double amount) throws InsufficientFundsException {
        // Rollback on specific exception types
        if (getBalance(playerId) < amount) {
            throw new InsufficientFundsException();
        }
        withdraw(playerId, amount);
    }
}
```

--------------------------------

### Add World Difficulty Field (Java)

Source: https://github.com/ultikits/ultitools-reborn/blob/main/docs/plans/2026-02-13-issue-36-features-design.md

Introduces a new 'difficulty' field to the WorldSettings entity in UltiWorlds. This field allows for per-world difficulty configuration, accepting values like PEACEFUL, EASY, NORMAL, or HARD.

```java
@Column("difficulty")
private String difficulty;  // PEACEFUL, EASY, NORMAL, HARD, or null (use Bukkit default)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.