Mebahel's API

Mebahel's API

Mebahel的API是一个核心依赖模组，提供共享系统、实用工具和游戏框架，供Mebahel模组生态系统中使用。

Mebahel 的 API — Mebahel 模组核心库

Mebahel 的 API 是一个核心依赖模组，为 Mebahel 模组生态提供共用的系统、工具和游戏框架。

它面向模组开发者设计，为复杂机制提供可直接用于生产的构建模块，无需在每个项目中重写相同的基础设施。

⚠️ 本模组是一个库。它本身不添加独立的游戏内容。

支持的版本

  • Minecraft 1.20.1 — Fabric
  • Minecraft 1.21.1 — Fabric

⭐ 面向玩家与整合包用户

本模组是其他 Mebahel 模组使用的技术依赖。

它在游戏中的作用

你通常不会直接与本模组交互。 它在后台运行，以确保其他模组正确高效地工作。

根据使用它的模组，它可能提供：

🌊 干燥结构生成

结构可以在生成时不被水淹没，即使位于水下或潮湿地形中。

📦 高级自定义箱子

部分 Mebahel 模组使用由本 API 驱动的特殊箱子：

  • 开合动画
  • 多人游戏安全的物品栏
  • 可选的每玩家奖励（每个玩家获得各自独立的战利品）
  • 自定义音效和 GUI

⚔️ 改进的怪物行为

某些生物可能使用高级移动方式，例如：

  • 战斗中侧移走位
  • 距离过近时战术撤退
  • 更自然的站位
  • 减少“卡住”行为

我需要这个模组吗？

✔ 如果其他模组将其列为依赖项，则必须安装 ✔ 单人游戏和多人游戏均安全 ✔ 客户端和服务器端都必须安装

❌ 移除它将导致依赖它的模组无法运行

⭐ 面向模组开发者

Mebahel 的 API 提供可复用的系统，旨在简化复杂 Fabric 模组的开发。

提供的主要系统

🌊 结构水移除系统

防止结构在海洋、河流或地下含水层中生成时被水淹没。

能力

  • 结构生成后移除含水块（waterlogged）状态
  • 清除结构边界内的周围水体方块
  • 兼容基于模板的结构
  • 分帧处理，安全无卡顿（不会造成 Lag Spike）
  • 配置后全自动运行

📦 高级动画箱子框架

为创建自定义容器提供完整的、多人游戏安全的基础。

包含内容

  • GeckoLib 动画的开/关/生成序列
  • 内置音效同步
  • 自定义 GUI 支持
  • 服务器权威行为
  • 多人游戏兼容性
个人战利品模式

使用战利品表时：

  • 每个玩家获得独立奖励
  • 战利品为每位玩家单独生成一次
  • 防止复制漏洞
  • 适用于地牢或 Boss 宝箱
共享物品栏模式

未使用战利品表时：

  • 作为普通容器运行
  • 物品栏在玩家之间共享

🖥️ 即用型 GUI 和屏幕处理器

加快容器方块的开发速度：

  • 预配置的 ScreenHandler
  • 玩家物品栏集成
  • 客户端 GUI 实现
  • 所需样板代码极少

⚔️ 实体移动工具

用于高级战斗 AI 和移动行为的工具方法。

支持：

  • 围绕目标侧移
  • 战术撤退移动
  • 面向目标的旋转
  • 跳跃辅助
  • 防卡住处理

适用于 Boss、远程攻击型生物、构造体或机械实体。

🧠 为什么使用 Mebahel 的 API？

✔ 减少多个模组间的重复代码 ✔ 针对服务器性能优化 ✔ 多人游戏安全系统 ✔ 可直接用于生产的实现 ✔ 已在真实发布的模组中活跃使用

🔧 安装（开发者）

在你的 Fabric 模组项目中添加 API 作为依赖。

Maven 仓库

repositories {
  maven {
    name = "GitLab-Mebahel"
    url = uri("https://gitlab.com/api/v4/projects/77311613/packages/maven")
  }
}

依赖

dependencies {
    modImplementation "net.mebahelsapi:mebahels-api:<version>"
}

fabric.mod.json

{
  "depends": {
    "mebahels-api": "*"
  }
}

⚙️ 必要依赖

  • Fabric Loader
  • Fabric API
  • GeckoLib（用于动画方块和实体）

请确保版本与你的 Minecraft 版本匹配。

📦 使用此模组的项目

所有 Mebahel 生态模组 均依赖此 API 作为共享核心库。

👨‍💻 开发者指南 — 集成

🌊 水移除处理器（结构）

在结构生成后自动移除水和含水状态。

使用场景

  • 海洋结构
  • 与流体相交的地下建筑
  • 必须保持干燥的遗迹或地牢

如何启用

将处理器添加到你的结构配置中：

"processors": "mebahelsapi:water_removal_processor"

清理会在放置后自动运行。 仅限服务器端。

📦 BaseChest 框架 — 自定义动画容器

提供可直接扩展的动画同步箱子系统。

创建自定义箱子

  1. 继承基础箱子方块
  2. 继承基础箱子方块实体
  3. 正常注册它们
  4. 配置标题、音效和多人游戏行为

示例 — ChestBlockEntity：

public class DwemerChestBlockEntity extends BaseChestBlockEntity {
    public DwemerChestBlockEntity(BlockPos pos, BlockState state) {
        super(ModBlockEntities.DWEMER_CHEST_ENTITY, pos, state, 36);
    }

    @Override
    protected Text getChestTitle() {
        return Text.translatable("block.mebahelcreaturesdwarven.dwemer_chest");
    }

    @Override
    protected String getLogPrefix() {
        return "[DwemerChest]";
    }

    @Override
    @Environment(EnvType.CLIENT)
    public void playOpenSound() {
        playChestSound(ModSounds.DWARVEN_CHEST_OPEN);
    }

    @Override
    @Environment(EnvType.CLIENT)
    public void playCloseSound() {
        playChestSound(ModSounds.DWARVEN_CHEST_CLOSE);
    }

    @Override
    protected boolean isMultiplayerEnabled() {
        return ModMultiplayerChest.turnOnMultiplayerDraugrChest;
    }
}

示例 — ChestBlock：

public class DwemerChestBlock extends BaseChestBlock {
    public DwemerChestBlock(AbstractBlock.Settings settings) {
        super(
                settings,
                () -> ModBlockEntities.DWEMER_CHEST_ENTITY,
                DwemerChestBlockEntity::new
        );
    }

    @Override
    protected boolean isMultiplayerEnabled() {
        return ModMultiplayerChest.turnOnMultiplayerDraugrChest;
    }
}

🏹 MovementUtil — 高级 AI 定位

MovementUtil 提供可复用的战斗移动辅助方法，特别适用于远程攻击型生物。

典型职责：

  • 使实体面向其目标
  • 防止寻路停滞
  • 保持最佳距离
  • 控制侧移和撤退行为

推荐的使用模式（在 Goal 内）：

  1. 验证目标
  2. 面向目标
  3. 运行防卡住逻辑
  4. 根据距离选择移动方式
  5. 单独处理攻击时机

示例 — 射击 Goal（Draugr 弓箭手）：

public class DraugrArcherShootingGoal extends Goal {
    private final DraugrArcherEntity actor;
    private final MovementUtil movementUtil;
    private final double STRAFE_DISTANCE = 8;

    public DraugrArcherShootingGoal(DraugrArcherEntity actor) {
        this.actor = actor;
        this.movementUtil = new MovementUtil(this.actor);
    }

    @Override
    public void tick() {
        if (actor.isUsingPotion() || actor.getHealTicks() > 0) {
            actor.setShooting(false);
            actor.getNavigation().stop();
            return;
        }

        LivingEntity target = this.actor.getTarget();
        if (target == null || !target.isAlive()) {
            this.stop();
            return;
        }

        double distanceToTarget = this.actor.distanceTo(target);

        movementUtil.lookAtTarget(target, actor);
        movementUtil.checkIfStuck(target, actor);

        if (distanceToTarget <= STRAFE_DISTANCE) {
            movementUtil.moveBackward(target, actor);
        } else {
            movementUtil.strafeAroundTarget(target, actor);
        }

        // 射击逻辑单独处理
    }
}

这种分离方式既能保持移动流畅，又能精确控制攻击时机和动画。

📜 备注

  • 本模组是多个 Mebahel 项目所需的核心库。
  • 移除它会导致依赖模组无法加载或功能异常。
  • 单人游戏和专用服务器环境均安全。
  • 它本身不添加独立的游戏内容。
  • 加入 Discord 社区：https://discord.com/invite/y8uC2NepkB