ShiroCore

ShiroCore

ShiroCore is a powerful library plugin for Minecraft (Spigot/Paper) designed to simplify the creation of complex, interactive player abilities. It provides a robust framework for shift-activated skills, complete with progress bars, event handling, and a clean API, allowing developers to focus on building unique gameplay mechanics.

---

🛠️ Understanding the Components: Engine vs. API

The ShiroVerse project is composed of two key modules that work together: `ShiroCore` (the engine) and `shiro-api` (the developer kit). Understanding their distinct roles is crucial for using the framework effectively.

`ShiroCore` — The Engine

- Developers: The actual Spigot/Paper plugin that you install on your Minecraft server. It's the heart of the system. - Developers: It contains all the core logic for detecting player actions (like shift-spamming), managing ability states, handling cooldowns, and displaying visual feedback like action bar progress bars. - Developers: - Developers: You install this single plugin in your `plugins` folder. It's the powerhouse that makes all dependent plugins work. - Developers: Your plugins require `ShiroCore` to be present on the server to function. It's the runtime environment for your creations.

`shiro-api` — The Developer Kit

- Developers: A lightweight Java library (`.jar`) that developers use to write their own plugins that integrate with `ShiroCore`. - Developers: It provides a clean and simple API to register custom abilities, listen to events, and control the activation system without needing to access the complex internal code of the engine. Key components include: - `AbilityManager`: For registering and managing your custom abilities. - `ShiftAbility`: An abstract class you extend to create your own shift-activated skills quickly. - `ActionbarMessage`: A utility for creating stylish progress bars and alerts. - `DependencyLogger`: A utility for professional, consistent dependency error logging. - Developers: - Developers: You include `shiro-api` as a dependency in your plugin's `pom.xml` (or other build system). It is your toolbox for building new gameplay features on top of the ShiroCore engine.

---

🌟 Core Features

1. Shift Activation System

Create abilities that activate through rapid shift-key spamming (configurable threshold).

- 🎯 Material-Based Registration - Set custom shift count requirements - 📊 Material-Based Registration - Track activation progress in real-time - 🎨 Material-Based Registration - Beautiful progress bars with mini-font support - ⚡ Material-Based Registration - Register specific materials for activation

2. Ability Manager API

Simplified API for creating and managing shift-activated abilities.

- 🔌 Thread-Safe - Easy integration with any Spigot/Paper plugin - 🔄 Thread-Safe - Handles activation/deactivation automatically - 🎮 Thread-Safe - Built-in event handling for abilities - 🛡️ Thread-Safe - Concurrent-safe ability tracking

3. Action Bar Utilities

Create stylish action bar messages with multiple design options.

- 🎨 Alert Messages - Default, gradient, and minimalist loading bars - 🔤 Alert Messages - Small, clean text rendering - 🌈 Alert Messages - Full color customization - ⚡ Alert Messages - Pre-formatted alert system

4. Dependency Logger

Professional, consistent dependency error messaging for your plugins.

- 📦 Reusable - Beautiful bordered error boxes - 🎯 Reusable - Built-in version mismatch warnings - 🔗 Reusable - Automatic ShiroCore download links - ♻️ Reusable - Use across all your ShiroCore-dependent plugins

---

📦 Installation

As a Server Plugin

1. Download the latest JAR from Releases 2. Place in your server's `plugins` folder 3. Restart the server

As a Dependency

Add to your `pom.xml`:

```xml <repositories> <repository> <id>jitpack.io</id> <url>https://jitpack.io</url> </repository> </repositories>

<dependencies> <dependency> <groupId>com.github.tantaihaha4487.ShiroVerse</groupId> <artifactId>shiro-api</artifactId> <version>v1.21.10-2.0.0</version> <scope>provided</scope> </dependency> </dependencies> ```

Add to your `plugin.yml`: ```yaml depend: [ShiroCore] ```

---

🚀 Quick Start

Example 1: Create a Shift-Activated Ability

```java import net.thanachot.ShiroCore.api.ability.AbilityManager; import net.thanachot.ShiroCore.api.ability.ShiftAbility;

public class MyPlugin extends JavaPlugin {

@Override public void onEnable() { // Get the AbilityManager AbilityManager manager = AbilityManager.getOrThrow();

// Register your custom ability manager.registerAbility(new SuperJumpAbility()); } }

// Custom ability class public class SuperJumpAbility extends ShiftAbility { private final Set<UUID> activePlayers = new HashSet<>();

public SuperJumpAbility() { super("superjump", item -> item != null && item.getType() == Material.FEATHER ); }

@Override public void onActivate(Player player, ItemStack item) { activePlayers.add(player.getUniqueId()); player.sendActionBar(Component.text("Super Jump Activated!") .color(NamedTextColor.GREEN)); player.addPotionEffect(new PotionEffect( PotionEffectType.JUMP, Integer.MAX_VALUE, 2 )); }

@Override public void onDeactivate(Player player) { activePlayers.remove(player.getUniqueId()); player.removePotionEffect(PotionEffectType.JUMP); }

@Override public boolean isActive(Player player) { return activePlayers.contains(player.getUniqueId()); } } ```

That's it! The ability will: - ✅ Automatically listen for shift-spam events - ✅ Show progress bar on action bar - ✅ Activate when threshold is reached - ✅ Deactivate when item is swapped

---

Example 2: Action Bar Messages

```java import net.thanachot.ShiroCore.api.text.ActionbarMessage;

// Simple loading bar Component loadingBar = ActionbarMessage.getLoadingBar(currentProgress, maxProgress); player.sendActionBar(loadingBar);

// Stylized gradient bar Component gradientBar = ActionbarMessage.getStylizedLoadingBar( current, max, NamedTextColor.AQUA, // filled color NamedTextColor.GRAY // empty color );

// Minimalist dot bar Component dotBar = ActionbarMessage.getDotLoadingBar(current, max);

// Alert message Component alert = ActionbarMessage.getAlert("Warning!", NamedTextColor.RED); ```

Output Examples: ``` ╞═══▰════╡ 40% (Default) 【█▓▒░░░░░░░】 40% (Gradient) ●●●●○○○○○○ 40% (Dots) (i) Warning! (Alert) ```

---

Example 3: Dependency Checking

```java import net.thanachot.shiroverse.api.util.DependencyLogger; import org.bukkit.plugin.Plugin;

public class MyPlugin extends JavaPlugin {

private static final String REQUIRED_SHIROCORE_VERSION = "2.0.0";

@Override public void onEnable() { if (!checkShiroCore()) { // Plugin will continue but without ShiroCore features return; }

// Initialize ShiroCore features initializeAbilities(); }

private boolean checkShiroCore() { Plugin shiroCore = getServer().getPluginManager().getPlugin("ShiroCore");

if (shiroCore == null) { logShiroCoreNotFound(); return false; }

String version = shiroCore.getPluginMeta().getVersion(); if (!version.contains(REQUIRED_SHIROCORE_VERSION)) { logIncompatibleVersion(version); return false; }

return true; }

private void logShiroCoreNotFound() { try { DependencyLogger.logShiroCoreNotFound( getLogger(), "MyPlugin", REQUIRED_SHIROCORE_VERSION ); } catch (NoClassDefFoundError e) { getLogger().warning("ShiroCore NOT FOUND! MyPlugin requires ShiroCore v" + REQUIRED_SHIROCORE_VERSION + "+"); } }

private void logIncompatibleVersion(String foundVersion) { try { DependencyLogger.logIncompatibleVersion( getLogger(), foundVersion, REQUIRED_SHIROCORE_VERSION ); } catch (NoClassDefFoundError e) { getLogger().warning("INCOMPATIBLE ShiroCore VERSION! Found: " + foundVersion + ", Required: v" + REQUIRED_SHIROCORE_VERSION + "+"); } } } ```

Benefits: - ✅ Professional, consistent error messages - ✅ Clear instructions for server admins - ✅ Graceful degradation if DependencyLogger unavailable - ✅ Reusable across all your plugins

---

📚 API Documentation

AbilityManager

```java // Get the manager AbilityManager manager = AbilityManager.getOrThrow();

// Register an ability manager.registerAbility(ShiftAbility ability);

// Unregister an ability manager.unregisterAbility(String abilityId);

// Get a player's active ability Optional<ShiftAbility> active = manager.getActiveAbility(Player player);

// Check if player has any ability active boolean hasAbility = manager.hasActiveAbility(Player player);

// Deactivate all abilities for a player manager.deactivateAll(Player player); ```

ShiftActivation (Low-Level API)

```java // Get the service ShiftActivation shift = ShiftActivation.getOrThrow();

// Set shift count required shift.setMaxProgress(10);

// Register materials for shift activation shift.register(handler, Material.NETHERITE_PICKAXE, Material.DIAMOND_SWORD);

// Check if material is registered boolean registered = shift.isRegistered(Material.NETHERITE_PICKAXE); ```

Events

```java // Listen to shift progress @EventHandler public void onShiftProgress(ShiftProgressEvent event) { Player player = event.getPlayer(); int progress = event.getPercentage(); Component message = event.getActionBarMessage();

// Cancel to prevent default behavior event.setCancelled(true); }

// Listen to shift activation @EventHandler public void onShiftActivation(ShiftActivationEvent event) { Player player = event.getPlayer(); ItemStack item = event.getItem();

// Your custom logic } ```

DependencyLogger

```java import net.thanachot.shiroverse.api.util.DependencyLogger;

// Log when ShiroCore is not found DependencyLogger.logShiroCoreNotFound( getLogger(), "YourPlugin", // Your plugin name "2.0.0" // Required ShiroCore version );

// Log when ShiroCore version is incompatible DependencyLogger.logIncompatibleVersion( getLogger(), "1.0.0", // Found version "2.0.0" // Required version );

// Log custom dependency errors DependencyLogger.logDependencyError( getLogger(), "DEPENDENCY ERROR!", "ShiroCore API is required.", "Please install ShiroCore v2.0.0+" );

// Get ShiroCore download URL String url = DependencyLogger.getShiroCoreUrl(); ```

Output Example: ``` ╔════════════════════════════════════════════════════════════╗ ║ ShiroCore NOT FOUND! ║ ║ YourPlugin requires ShiroCore v2.0.0+ ║ ║ for abilities to work. ║ ║ ║ ║ The plugin will continue without ability features. ║ ║ ║ ║ Download ShiroCore from: ║ ║ → https://modrinth.com/plugin/shirocore ║ ╚════════════════════════════════════════════════════════════╝ ```

Best Practice - Use with try-catch: ```java private void checkDependencies() { try { DependencyLogger.logShiroCoreNotFound( getLogger(), "MyPlugin", "2.0.0" ); } catch (NoClassDefFoundError e) { // Fallback if DependencyLogger isn't available getLogger().warning("ShiroCore required!"); } }

---

🎨 Action Bar Styles

ShiroCore provides three beautiful loading bar styles:

1. Default Style

```java ActionbarMessage.getLoadingBar(current, max) ``` `╞═══▰════╡ 40%`

Features: - Smooth transition character (▰) - Green filled, black empty - Clean, modern look

2. Gradient Style

```java ActionbarMessage.getStylizedLoadingBar(current, max, filledColor, emptyColor) ``` `【█▓▒░░░░░░░】 40%`

Features: - Multi-level gradient effect (█ ▓ ▒ ░) - Custom color support - Asian-style brackets

3. Minimalist Dots

```java ActionbarMessage.getDotLoadingBar(current, max) ``` `●●●●○○○○○○ 40%`

Features: - Clean, simple design - Filled/empty dot indicators - Minimal visual noise

---

🏗️ Architecture

``` ShiroCore ├── api/ │ ├── ability/ │ │ ├── ShiftAbility.java (Abstract base class) │ │ └── AbilityManager.java (Service API) │ ├── event/ │ │ ├── ShiftProgressEvent.java │ │ ├── ShiftActivationEvent.java │ │ └── ShiftEvent.java │ ├── text/ │ │ └── ActionbarMessage.java │ ├── util/ │ │ └── DependencyLogger.java (Dependency logging) │ └── ShiftActivation.java └── internal/ ├── ability/ │ ├── AbilityManagerImpl.java (Implementation) │ └── AbilityListener.java (Event handling) ├── handler/ │ └── ShiftActivationHandler.java └── system/ └── ShiftActivationService.java ```

---

💡 Use Cases

What You Can Build

- 🔨 Custom Mechanics - Pickaxes with 3x3 mining, shovels with area digging - ⚔️ Custom Mechanics - Swords with special attacks, bows with enhanced arrows - 🏃 Custom Mechanics - Speed boots, jump abilities, teleportation - 🛡️ Custom Mechanics - Shields with absorption, armor with resistance - 🎯 Custom Mechanics - Anything that activates via shift-spam!

Real World Example: SuperPickaxe

Check out the SuperPickaxe-Prototype plugin that uses ShiroCore:

- 🔨 3x3 block breaking - 🎨 Beautiful activation effects - ⚡ Only ~80 lines of code (thanks to ShiroCore!)

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the project 2. Create your feature branch (`git checkout -b feature/AmazingFeature`) 3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) 4. Push to the branch (`git push origin feature/AmazingFeature`) 5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🔗 Links

- Issues: Issues - Issues: %%MD1%% - Issues: %%MD2%%

---

✨ Credits

Created by tantaihaha4487 for the ShiroVerse project.

Special thanks to all contributors and the Minecraft development community!

---

<sub>Built with ❤️ for the Minecraft community</sub>