ShiroCore

插件

· 作者 tantaihaha4487

ShiroVerse 项目的库

0 本站下载 0 关注 更新于 11 个月前

最新 1.21.10-2.0.1 · 1.21.11 · Paper

一键开服(送7天)

构建状态 jitpack 徽章

ShiroCore

ShiroCore 是一款功能强大的 Minecraft(Spigot/Paper)库插件,旨在简化复杂、交互式玩家能力的创建。它提供了一个稳健的框架来支持按住 Shift 键触发的技能,包含进度条、事件处理和简洁的 API,让开发者能够专注于构建独特的游戏机制。


?️ 理解组件:引擎与 API

ShiroVerse 项目由两个协同工作的关键模块组成:ShiroCore(引擎)和 shiro-api(开发套件)。理解它们各自的角色对于有效使用该框架至关重要。

ShiroCore — 引擎

  • 是什么: 这是你安装在 Minecraft 服务器上的实际 Spigot/Paper 插件。它是整个系统的核心。
  • 做什么: 它包含了所有核心逻辑,用于检测玩家操作(如快速切换潜行)、管理能力状态、处理冷却时间以及显示动作栏进度条等视觉反馈。
  • 适用对象:
    • 服务器所有者: 你只需将此单个插件放入服务器的 plugins 文件夹中。它是使所有依赖插件运行的动力源。
    • 开发者: 你的插件需要服务器上存在 ShiroCore 才能正常运行。它是你创作作品的运行时环境。

shiro-api — 开发套件

  • 是什么: 一个轻量级的 Java 库(.jar),供开发者用来编写与 ShiroCore 集成的自定义插件。
  • 做什么: 它提供了一套简洁明了的 API,用于注册自定义能力、监听事件并控制激活系统,而无需访问引擎复杂的内部代码。关键组件包括:
    • AbilityManager:用于注册和管理自定义能力。
    • ShiftAbility:一个抽象类,通过继承它可以快速创建自己的 Shift 触发技能。
    • ActionbarMessage:用于创建美观进度条和警报的工具类。
    • DependencyLogger:用于专业且一致地记录依赖错误信息的工具类。
  • 适用对象:
    • 开发者: 你将 shiro-api 作为依赖项添加到插件的 pom.xml(或其他构建系统)中。它是你在 ShiroCore 引擎之上构建新游戏功能的工具箱。

? 核心功能

1. Shift 激活系统

创建通过快速连续按下 Shift 键(可配置阈值)来激活的能力。

  • ? 可配置进度 - 设置自定义的 Shift 按键次数要求
  • ? 进度事件 - 实时跟踪激活进度
  • ? 动作栏集成 - 带有迷你字体支持的精美进度条
  • ⚡ 基于材质的注册 - 为特定材质注册激活条件

2. 能力管理器 API

简化的 API,用于创建和管理 Shift 触发的能力。

  • ? 插件友好 - 轻松集成到任何 Spigot/Paper 插件中
  • ? 自动状态管理 - 自动处理激活/停用状态
  • ? 事件驱动 - 内置能力事件处理
  • ?️ 线程安全 - 并发安全的追踪能力

3. 动作栏工具

使用多种设计选项创建时尚的动作栏消息。

  • ? 多种样式 - 默认、渐变和极简主义加载条
  • ? 迷你字体支持 - 小巧清晰的文本渲染
  • ? 自定义颜色 - 完全的颜色定制
  • ⚡ 警报消息 - 预格式化的警报系统

4. 依赖日志记录器

为你的插件提供专业、一致的依赖错误消息。

  • ? 标准化消息 - 美观的带边框错误框
  • ? 版本检查 - 内置的版本不匹配警告
  • ? 有用链接 - 自动提供 ShiroCore 下载链接
  • ♻️ 可复用 - 可在所有依赖 ShiroCore 的插件中使用

? 安装

作为服务器插件

  1. 从 Releases 下载最新的 JAR 文件
  2. 将其放入服务器的 plugins 文件夹
  3. 重启服务器

作为依赖项

添加到你的 pom.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>

添加到你的 plugin.yml:

depend: [ShiroCore]

? 快速开始

示例 1:创建一个 Shift 触发的能力

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

public class MyPlugin extends JavaPlugin {
    
    @Override
    public void onEnable() {
        // 获取 AbilityManager
        AbilityManager manager = AbilityManager.getOrThrow();
        
        // 注册你的自定义能力
        manager.registerAbility(new SuperJumpAbility());
    }
}

```java
// 自定义能力类
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());
    }
}

就是这样! 该能力将:

  • ✅ 自动监听 shift 连点事件
  • ✅ 在操作栏显示进度条
  • ✅ 达到阈值时激活
  • ✅ 切换物品时停用

示例 2:操作栏消息

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

// 简单的加载条
Component loadingBar = ActionbarMessage.getLoadingBar(currentProgress, maxProgress);
player.sendActionBar(loadingBar);

// 风格化的渐变条
Component gradientBar = ActionbarMessage.getStylizedLoadingBar(
    current, 
    max, 
    NamedTextColor.AQUA,  // 填充颜色
    NamedTextColor.GRAY    // 空余颜色
);

// 极简圆点条
Component dotBar = ActionbarMessage.getDotLoadingBar(current, max);

// 警报消息
Component alert = ActionbarMessage.getAlert("Warning!", NamedTextColor.RED);

输出示例:

╞═══▰════╡ 40%          (默认)
【█▓▒░░░░░░░】 40%        (渐变)
●●●●○○○○○○ 40%          (圆点)
(i) Warning!            (警报)

示例 3:依赖检查

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()) {
            // 插件将继续运行,但缺少 ShiroCore 功能
            return;
        }
        
        // 初始化 ShiroCore 功能
        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 + "+");
        }
    }
}

优势:

  • ✅ 专业且一致的错误消息
  • ✅ 为服务器管理员提供清晰的说明
  • ✅ 若 DependencyLogger 不可用时优雅降级
  • ✅ 可在所有插件中复用

? API 文档

AbilityManager

// 获取管理器
AbilityManager manager = AbilityManager.getOrThrow();

// 注册一个能力
manager.registerAbility(ShiftAbility ability);

// 注销一个能力
manager.unregisterAbility(String abilityId);

// 获取玩家当前激活的能力
Optional<ShiftAbility> active = manager.getActiveAbility(Player player);

// 检查玩家是否有任何能力处于激活状态
boolean hasAbility = manager.hasActiveAbility(Player player);

// 停用玩家的所有能力
manager.deactivateAll(Player player);

ShiftActivation(低级 API)

// 获取服务
ShiftActivation shift = ShiftActivation.getOrThrow();

// 设置所需的 shift 次数
shift.setMaxProgress(10);

// 注册用于 shift 激活的物品材质
shift.register(handler, Material.NETHERITE_PICKAXE, Material.DIAMOND_SWORD);

// 检查材质是否已注册
boolean registered = shift.isRegistered(Material.NETHERITE_PICKAXE);

事件

// 监听 shift 进度
@EventHandler
public void onShiftProgress(ShiftProgressEvent event) {
    Player player = event.getPlayer();
    int progress = event.getPercentage();
    Component message = event.getActionBarMessage();
    
    // 取消以阻止默认行为
    event.setCancelled(true);
}

// 监听 shift 激活
@EventHandler
public void onShiftActivation(ShiftActivationEvent event) {
    Player player = event.getPlayer();
    ItemStack item = event.getItem();
    
    // 你的自定义逻辑
}

DependencyLogger

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

// 记录未找到 ShiroCore 的情况
DependencyLogger.logShiroCoreNotFound(
    getLogger(),
    "YourPlugin",      // 你的插件名称
    "2.0.0"            // 所需的 ShiroCore 版本
);

// 当 ShiroCore 版本不兼容时记录日志 DependencyLogger.logIncompatibleVersion( getLogger(), "1.0.0", // 已找到的版本 "2.0.0" // 所需版本 );

// 记录自定义依赖错误 DependencyLogger.logDependencyError( getLogger(), "DEPENDENCY ERROR!", "ShiroCore API is required.", "Please install ShiroCore v2.0.0+" );

// 获取 ShiroCore 下载链接 String url = DependencyLogger.getShiroCoreUrl();


**输出示例:**

╔════════════════════════════════════════════════════════════╗ ║ ShiroCore NOT FOUND! ║ ║ YourPlugin requires ShiroCore v2.0.0+ ║ ║ for abilities to work. ║ ║ ║ ║ The plugin will continue without ability features. ║ ║ ║ ║ Download ShiroCore from: ║ ║ → ║ ╚════════════════════════════════════════════════════════════╝


**最佳实践 - 配合 try-catch 使用:**
```java
private void checkDependencies() {
    try {
        DependencyLogger.logShiroCoreNotFound(
            getLogger(), "MyPlugin", "2.0.0"
        );
    } catch (NoClassDefFoundError e) {
        // 如果 DependencyLogger 不可用时的回退方案
        getLogger().warning("ShiroCore required!");
    }
}

---

## ? Action Bar Styles

ShiroCore 提供了 **三种美观的加载栏样式**:

### **1. 默认样式**
```java
ActionbarMessage.getLoadingBar(current, max)

╞═══▰════╡ 40%

特性:

  • 平滑过渡字符 (▰)
  • 绿色填充,黑色空白
  • 简洁现代的外观

2. 渐变样式

ActionbarMessage.getStylizedLoadingBar(current, max, filledColor, emptyColor)

【█▓▒░░░░░░░】 40%

特性:

  • 多级渐变效果 (█ ▓ ▒ ░)
  • 支持自定义颜色
  • 亚洲风格括号

3. 极简圆点

ActionbarMessage.getDotLoadingBar(current, max)

●●●●○○○○○○ 40%

特性:

  • 干净简约的设计
  • 填充/空白的圆点指示器
  • 最小化的视觉干扰

?️ Architecture

ShiroCore
├── api/
│   ├── ability/
│   │   ├── ShiftAbility.java          (抽象基类)
│   │   └── AbilityManager.java        (服务 API)
│   ├── event/
│   │   ├── ShiftProgressEvent.java
│   │   ├── ShiftActivationEvent.java
│   │   └── ShiftEvent.java
│   ├── text/
│   │   └── ActionbarMessage.java
│   ├── util/
│   │   └── DependencyLogger.java      (依赖日志记录)
│   └── ShiftActivation.java
└── internal/
    ├── ability/
    │   ├── AbilityManagerImpl.java    (实现类)
    │   └── AbilityListener.java       (事件处理)
    ├── handler/
    │   └── ShiftActivationHandler.java
    └── system/
        └── ShiftActivationService.java

? Use Cases

你可以构建什么

  • ? 超级工具 - 具有 3x3 挖掘范围的镐子,具有区域挖掘功能的铲子
  • ⚔️ 战斗能力 - 具有特殊攻击的剑,具有增强箭矢的弓
  • ? 移动技能 - 加速靴子,跳跃能力,传送功能
  • ?️ 防御力量 - 具有吸收效果的盾牌,具有抗性加成的护甲
  • ? 自定义机制 - 任何可以通过连续点击 Shift 激活的功能!

实际案例:SuperPickaxe

查看使用 ShiroCore 的 SuperPickaxe-Prototype 插件:

  • ? 3x3 方块破坏
  • ? 精美的激活特效
  • ⚡ 仅需约 80 行代码(得益于 ShiroCore!)

? Contributing

欢迎贡献!请随时提交 Pull Request。

  1. Fork 该项目
  2. 创建你的功能分支 (git checkout -b feature/AmazingFeature)
  3. 提交你的更改 (git commit -m 'Add some AmazingFeature')
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 打开一个 Pull Request

? License

本项目遵循 MIT 许可证 - 详情请参阅 LICENSE 文件。


? Links


✨ Credits

由 tantaihaha4487 为 ShiroVerse 项目创建。

特别感谢所有贡献者以及 Minecraft 开发社区!


Built with ❤️ for the Minecraft community

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源