史诗核心API

EpicCoreAPI

此模组基于 CoreMod（ITransformationService）、Java Agent 和 VarHandle 技术提供实体操作 API 和命令。请注意，虽然方法名可能类似原版逻辑，但底层实现完全不同。例如，生命值设置 API 可以使用自定义生命值修改实体（包括但不限于实体数据、数字字段和哈希表）；移除 API 执行底层 Minecraft 容器清理；无敌设置 API 提供了比原版创造模式无敌更强大的实现。此外，此模组默认将原版属性限制解锁至 Double.MAX_VALUE。您可以在配置文件中通过“Unlock Attribute Limits”选项禁用此功能。

此模组的初衷是为开发者提供简化的实体操作 API，同时在确保性能和兼容性的前提下达到一定的强度。因此，请不要将此模组用于模组强度比较或无尽代码军备竞赛。此外，在整合包生存环境中，最好确保“Attack and Defence Radical Logic”配置选项已禁用。

此模组还提供了一个 MCreator 插件，方便 MCreator 用户使用此模组中的 API。

玩家使用指南

玩家可以使用以下 /eca 命令（需要权限等级 ≥ 2）：

• /eca setHealth <目标> <生命值> - 设置实体生命值
• /eca setMaxHealth <目标> <最大生命值> - 设置实体最大生命值（反向计算属性基础值）
• /eca setInvulnerable <目标> <true|false> - 设置实体无敌状态
  • /eca lockHealth <目标> true <数值> - 将实体生命值锁定在特定数值
  • /eca lockHealth <目标> false - 解锁实体生命值
  • /eca lockMaxHealth <目标> true <数值> - 将实体最大生命值锁定在特定数值
  • /eca lockMaxHealth <目标> false - 解锁实体最大生命值
  • /eca banHealing <目标> true [数值] - 禁止实体治疗（数值可选，默认为当前生命值）
  • /eca banHealing <目标> false - 解除实体治疗禁止
  • /eca kill <目标> - 杀死实体
• /eca remove <目标> [原因] - 从世界中移除实体
• /eca memoryRemove <目标> - 危险！需要“Attack Radical Logic”配置。通过 LWJGL 内部通道移除实体
• /eca teleport <目标> <x> <y> <z> - 传送实体
• /eca lockLocation <目标> <true|false> [x y z] - 锁定/解锁实体位置
• /eca cleanBossBar <目标> - 清理 Boss 血条
• /eca allReturn <目标> <true|false> - 危险！需要“Attack Radical Logic”配置。对目标实体所属模组的所有布尔和空方法启用/禁用返回转换
• /eca allReturn global <true|false> - 危险！对所有非白名单模组启用/禁用全局 AllReturn
• /eca banSpawn <目标> <秒数> - 禁止指定实体类型在指定时长内生成
• /eca banSpawn clear - 解除当前维度所有生成禁令
• /eca setForceLoading <目标> <true|false> - 启用/禁用实体强制加载区块
• /eca setInvulnerable show_all - 显示所有无敌实体
• /eca entityExtension get_registry - 显示实体扩展注册表
• /eca entityExtension get_active - 显示当前维度活跃的实体扩展类型
• /eca entityExtension get_current - 显示当前生效的实体扩展
• /eca entityExtension clear - 清除当前维度的活跃实体扩展表和所有全局效果
• /eca entityExtension set_skybox <预设> - 设置全局天空盒着色器预设
• /eca setFilter <目标> true <类型> - 对玩家应用屏幕滤镜（类型：sketch、spotlight、matrix、rain、desert、snow、toxic、cosmos）
• /eca setFilter <目标> false - 移除玩家所有活跃滤镜
• /eca bossShow edit - 打开游戏内电影编辑器（切换至旁观模式）
• /eca bossShow exit - 退出编辑器并恢复之前的游戏模式
• /eca bossShow list - 列出所有已加载的过场动画
• /eca bossShow play <观看者> <目标> <id> - 强制播放过场动画
• /eca bossShow stop <观看者> - 停止观看者当前的过场动画
• /eca bossShow reload - 从磁盘重新加载所有过场动画 JSON 定义
• /eca bossShow clearHistory <玩家> - 清除玩家的“已观看”记录
• /eca resurrection start - 启动复活守护线程
• /eca resurrection stop - 停止复活守护线程
• /eca resurrection status - 显示守护线程状态和复活/检查计数
• /eca resurrection add <目标> - 将实体添加到复活跟踪（死亡时每个轮询周期自动复活）
• /eca resurrection remove <目标> - 将实体从复活跟踪中移除
• /eca resurrection list - 列出所有被跟踪实体及其容器完整性状态
• /eca resurrection check <目标> - 对实体执行一次性容器完整性检查
• /eca resurrection revive <目标> - 立即手动强制复活被跟踪实体
• /eca resurrection interval <毫秒> - 设置轮询间隔（100–10000；默认 25）

新增命令选择器，通过 ECA 自身的实体查找解析：

• @eca_e[...] - 所有实体
• @eca_p[...] - 最近的玩家
• @eca_a[...] - 所有玩家
• @eca_r[...] - 随机玩家
• @eca_s[...] - 命令源实体（自身）

开发者使用指南

添加 ECA 作为依赖

步骤 1：添加 Modrinth Maven 仓库（build.gradle）

repositories {
    maven { url = "https://api.modrinth.com/maven"; content { includeGroup "maven.modrinth" } }
}

步骤 2：添加 ECA 依赖（build.gradle）

dependencies {
    implementation fg.deobf("maven.modrinth:epic-core-api:VERSION")
}

将 VERSION 替换为您需要的版本（例如 1.1.5-fix-fix）。前往 ECA Modrinth 页面 查找可用版本。

步骤 3：声明依赖（mods.toml）

[[dependencies.your_mod_id]]
modId="eca"
mandatory=true
versionRange="[1.1.5,)"
ordering="NONE"
side="BOTH"

API 参考

• lockHealth(entity, value) - 将实体生命值锁定在特定数值（用于无敌、治疗否定等）
• unlockHealth(entity) - 移除生命值锁定
• getLockedHealth(entity) - 获取当前生命值锁定值（未锁定则为 null）
• isHealthLocked(entity) - 检查实体生命值是否被锁定
• banHealing(entity, value) - 在指定数值下禁止实体治疗（实体无法治疗但可受伤）
• unbanHealing(entity) - 解除实体治疗禁止
• getHealBanValue(entity) - 获取当前治疗禁止值（未禁止则为 null）
• isHealingBanned(entity) - 检查实体是否被禁止治疗
• getHealth(entity) - 通过 VarHandle 获取原版生命值
• setHealth(entity, health) - 分阶段的生命值修改，仅在验证步骤失败时升级：原版（直接写入原版 DATA_HEALTH_ID）→ 符号（对 getHealth() 进行 ASM 字节码数据流分析以定位并反转真实存储，在定位到的存储上提供数字回退）→ 探针（对候选数字设置器进行行为探测，与名称无关）→ 动态（运行时字节码插桩，需要“Attack Radical Logic”配置）。玩家仅运行原版阶段。每个阶段都会在 max(1.0, abs(target) * 2%) 范围内针对 getHealth() 进行验证；第一个通过的阶段会按实体类缓存。
• setMaxHealth(entity, maxHealth) - 通过从当前修饰符反向计算属性基础值来设置最大生命值
• lockMaxHealth(entity, value) - 将实体最大生命值锁定在特定数值（每 tick 强制）
• unlockMaxHealth(entity) - 解锁实体最大生命值
• getLockedMaxHealth(entity) - 获取当前最大生命值锁定值（未锁定则为 null）
• isMaxHealthLocked(entity) - 检查实体最大生命值是否被锁定
• addHealthWhitelistKeyword(keyword) - 添加关键字到生命值修改白名单
• removeHealthWhitelistKeyword(keyword) - 从生命值修改白名单中移除关键字
• getHealthWhitelistKeywords() - 获取所有生命值白名单关键字
• addHealthBlacklistKeyword(keyword) - 添加关键字到生命值修改黑名单
• removeHealthBlacklistKeyword(keyword) - 从生命值修改黑名单中移除关键字
• getHealthBlacklistKeywords() - 获取所有生命值黑名单关键字
• kill(entity, damageSource) - 杀死实体（掉落物 + 进度 + 移除）
• revive(entity) - 清除死亡状态并恢复生命值
• revive(level, uuid) - 通过 UUID 在指定世界中清除死亡状态并恢复生命值
• reviveAllContainers(entity) - 复活所有关键实体容器（tickList、lookup、sections、tracker）
• reviveAllContainers(level, uuid) - 通过 UUID 在指定世界中复活所有关键实体容器
• teleport(entity, x, y, z) - 通过 VarHandle 传送并与客户端同步
• lockLocation(entity) - 将实体位置锁定在当前位置
• lockLocation(entity, position) - 将实体位置锁定在指定位置
• unlockLocation(entity) - 解锁实体位置
• isLocationLocked(entity) - 检查实体位置是否被锁定
• getLockedLocation(entity) - 获取锁定位置（未锁定则为 null）
• remove(entity, reason) - 完全移除（AI、Boss 血条、容器、乘客）
• memoryRemove(entity, reason) - 危险！需要“Attack Radical Logic”配置。通过 LWJGL 内部通道移除实体
• cleanupBossBar(entity) - 在不移除实体的情况下移除 Boss 血条
• isInvulnerable(entity) - 检查实体是否无敌（ECA 内部无敌逻辑）
• setInvulnerable(entity, invulnerable) - 设置无敌状态（启用：复活 + 锁定生命值 + 阻止伤害 + 每 tick 移除有害效果 + 防止生物目标选择 + 保护玩家物品栏；禁用：清除所有保护）
• enableAllReturn(entity) - 危险！需要“Attack Radical Logic”配置。对目标实体所属模组的所有布尔和空方法执行返回转换
• setGlobalAllReturn(enable) - 危险！需要“Attack Radical Logic”配置。对所有非白名单模组启用/禁用全局 AllReturn
• disableAllReturn() - 禁用 AllReturn 并清除目标
• isAllReturnEnabled() - 检查 AllReturn 是否已启用
• addAllReturnWhitelist(prefix) - 添加包前缀到 AllReturn 白名单（跳过 AllReturn，防御性钩子仍然生效）
• removeAllReturnWhitelist(prefix) - 从 AllReturn 白名单中移除包前缀（内置条目无法移除）
• addTransformWhitelist(prefix) - 添加包前缀到转换白名单（跳过所有 ECA 转换，包括防御性钩子）
• removeTransformWhitelist(prefix) - 从转换白名单中移除包前缀（内置条目无法移除）
• isAllReturnWhitelisted(className) - 检查类是否受 AllReturn 保护
• isTransformWhitelisted(className) - 检查类是否受所有 ECA 转换保护
• getAllWhitelistedPackages() - 获取所有白名单前缀（两个级别，内置 + 自定义）
• getEntityExtensionRegistry() - 获取所有已注册的实体扩展（Map<EntityType, EntityExtension>）
• getActiveEntityExtensionTypes(level) - 获取当前维度的活跃实体扩展类型（Map<EntityType, Integer>）
• getActiveEntityExtension(level) - 获取当前生效的实体扩展（最高优先级）
• clearActiveEntityExtensionTable(level) - 清除当前维度的活跃实体扩展表
• setGlobalFog(level, fogData) - 为维度设置全局雾效覆盖（不改变效果优先级）
• clearGlobalFog(level) - 清除全局雾效覆盖
• setGlobalSkybox(level, skyboxData) - 为维度设置全局天空盒覆盖（不改变效果优先级）
• clearGlobalSkybox(level) - 清除全局天空盒覆盖
• setGlobalMusic(level, musicData) - 为维度设置全局战斗音乐覆盖（不改变效果优先级）
• clearGlobalMusic(level) - 清除全局战斗音乐覆盖
• clearAllGlobalEffects(level) - 清除维度的所有全局效果覆盖（雾、天空盒、音乐）
• enableFilter(player, filterType) - 对玩家应用屏幕滤镜（FilterType：SKETCH、SPOTLIGHT、MATRIX、RAIN、DESERT、SNOW、TOXIC、COSMOS）
• disableFilter(player, filterType) - 移除玩家的屏幕滤镜
• isFilterEnabled(player, filterType) - 检查玩家是否激活了滤镜
• getActiveFilters(player) - 获取玩家的活跃滤镜（不可修改的 Set<FilterType>）
• playBossShow(viewer, target, cutsceneId) - 强制为观看者播放 BossShow 过场动画（忽略观看历史）
• playBossShowIfNew(viewer, target, cutsceneId) - 仅当观看者之前未看过时播放 BossShow 过场动画
• stopBossShow(viewer) - 停止观看者当前的 BossShow 过场动画
• isBossShowPlaying(viewer) - 检查观看者当前是否处于 BossShow 过场动画中
• launchBossShowEvent(eventName, viewer, target) - 触发所有匹配事件名称的 Custom 触发 BossShow（返回触发数量）
• banSpawn(level, entityType, seconds) - 禁止指定实体类型在指定时长内生成
• isSpawnBanned(level, entityType) - 检查实体类型是否被禁止生成
• getSpawnBanTime(level, entityType) - 获取剩余生成禁令时间（秒）
• unbanSpawn(level, entityType) - 解除实体类型的生成禁令，允许再次生成
• getAllSpawnBans(level) - 获取世界中的所有生成禁令（Map<EntityType, Integer>）
• unbanAllSpawns(level) - 解除世界中所有实体类型的生成禁令
• setForceLoading(entity, level, forceLoad) - 启用/禁用实体强制加载区块
• isForceLoaded(entity) - 检查实体是否被强制加载（通过 EntityExtension 或 API）
• getEntity(level, entityId) - 通过运行时 ID 在指定世界中解析实体（ECA 选择器路径）
• getEntity(level, uuid) - 通过 UUID 在指定世界中解析实体（ECA 选择器路径）
• getEntity(level, entityId, entityClass) - 通过 ID 解析类型化实体
• getEntity(level, uuid, entityClass) - 通过 UUID 解析类型化实体
• getEntity(server, entityId) - 跨所有世界通过 ID 解析实体
• getEntity(server, uuid) - 跨所有世界通过 UUID 解析实体
• getEntities(level) - 获取世界中的所有实体
• getEntities(level, area) - 获取 AABB 区域中的实体
• getEntities(level, filter) - 使用自定义谓词获取实体
• getEntities(level, area, filter) - 使用自定义谓词获取区域中的实体
• getEntities(level, entityClass) - 获取世界中指定类型的所有实体
• getEntities(level, area, entityClass) - 获取区域中指定类型的实体
• getEntities(server) - 获取所有服务器世界中的所有实体
• getEntities(server, filter) - 使用自定义谓词跨所有世界获取实体
• startResurrection() - 启动复活守护线程（幂等）
• stopResurrection() - 停止复活守护线程
• isResurrectionRunning() - 检查守护线程是否正在运行
• addResurrectionTarget(entity) - 将实体添加到复活跟踪集合
• removeResurrectionTarget(entity) - 将实体从复活跟踪集合中移除
• isResurrectionTracked(entity) - 检查实体是否被跟踪复活
• getResurrectionTrackedCount() - 获取当前被跟踪的实体数量
• clearAllResurrectionTargets() - 从跟踪集合中移除所有实体
• setResurrectionPollInterval(ms) - 设置守护线程轮询间隔（毫秒，限制为 1–10000，默认 25）
• getResurrectionPollInterval() - 获取当前轮询间隔（毫秒）
• getResurrectionTotalRevived() - 获取自启动以来复活的实体总数
• getResurrectionTotalChecks() - 获取自启动以来执行的实体检查总数
• checkResurrectionTarget(level, entity) - 执行一次性容器完整性检查
• reviveResurrectionTarget(level, entity) - 立即手动强制复活被跟踪实体

以下是一个简单示例：

import net.eca.api.EcaAPI;
import net.eca.network.EntityExtensionOverridePacket.FogData;
import net.eca.network.EntityExtensionOverridePacket.MusicData;
import net.eca.network.EntityExtensionOverridePacket.SkyboxData;
import net.eca.util.entity_extension.EntityExtension;
import net.minecraft.resources.ResourceLocation;
import net.minecraft.server.level.ServerLevel;
import net.minecraft.world.entity.Entity;
import net.minecraft.world.entity.EntityType;
import net.minecraft.world.entity.LivingEntity;
import net.minecraft.world.phys.AABB;
import net.minecraft.world.phys.Vec3;

import java.util.Map;
import java.util.Set;

// 生命值锁定
EcaAPI.lockHealth(entity, 20.0f);
Float locked = EcaAPI.getLockedHealth(entity);
EcaAPI.unlockHealth(entity);

// 治疗禁止
EcaAPI.banHealing(entity, entity.getHealth());  // 在当前生命值处禁止治疗
Float banValue = EcaAPI.getHealBanValue(entity);
EcaAPI.unbanHealing(entity);

// 基础生命值访问
float realHealth = EcaAPI.getHealth(entity);
EcaAPI.setHealth(entity, 50.0f);

// 最大生命值
EcaAPI.setMaxHealth(entity, 1024.0f);
EcaAPI.lockMaxHealth(entity, 1024.0f);
Float lockedMax = EcaAPI.getLockedMaxHealth(entity);
EcaAPI.unlockMaxHealth(entity);

// 关键字管理
EcaAPI.addHealthWhitelistKeyword("mana");
EcaAPI.addHealthBlacklistKeyword("timer");
Set<String> whitelist = EcaAPI.getHealthWhitelistKeywords();
Set<String> blacklist = EcaAPI.getHealthBlacklistKeywords();
EcaAPI.removeHealthWhitelistKeyword("mana");
EcaAPI.removeHealthBlacklistKeyword("timer");

// 实体控制
EcaAPI.kill(entity, damageSource);
EcaAPI.revive(entity);
EcaAPI.revive(serverLevel, uuid);  // 通过 UUID 复活
Map<String, Boolean> containerResults = EcaAPI.reviveAllContainers(entity);  // 复活所有容器
EcaAPI.reviveAllContainers(serverLevel, uuid);  // 通过 UUID 复活所有容器
EcaAPI.teleport(entity, x, y, z);
EcaAPI.lockLocation(entity);  // 锁定在当前位置
EcaAPI.lockLocation(entity, new Vec3(100, 64, 200));  // 锁定在指定位置
boolean locationLocked = EcaAPI.isLocationLocked(entity);
Vec3 lockedPos = EcaAPI.getLockedLocation(entity);
EcaAPI.unlockLocation(entity);
EcaAPI.remove(entity, Entity.RemovalReason.KILLED);
EcaAPI.memoryRemove(entity, Entity.RemovalReason.CHANGED_DIMENSION);  // 使用 LWJGL 内部 Unsafe 实例移除
EcaAPI.cleanupBossBar(entity);

// ECA 实体选择器 API
Entity byId = EcaAPI.getEntity(level, 123);
Entity byUuid = EcaAPI.getEntity(level, uuid);
List<Entity> allInLevel = EcaAPI.getEntities(level);
List<Entity> inArea = EcaAPI.getEntities(level, new AABB(0, 0, 0, 16, 256, 16));
List<Entity> filtered = EcaAPI.getEntities(level, e -> e.getType() == EntityType.ZOMBIE);
List<LivingEntity> livingInArea = EcaAPI.getEntities(level, new AABB(0, 0, 0, 32, 256, 32), LivingEntity.class);
List<Entity> allServerEntities = EcaAPI.getEntities(server);

// 无敌
EcaAPI.setInvulnerable(entity, true);
boolean isInv = EcaAPI.isInvulnerable(entity);
EcaAPI.setInvulnerable(entity, false);

// AllReturn（危险！需要“Attack Radical Logic”配置）
EcaAPI.enableAllReturn(entity);  // 对实体所属模组启用
EcaAPI.setGlobalAllReturn(true);  // 对所有非白名单模组启用
boolean enabled = EcaAPI.isAllReturnEnabled();
EcaAPI.disableAllReturn();  // 禁用并清除所有 AllReturn

// 白名单 — AllReturn 级别（仅跳过 AllReturn，防御性钩子仍然生效）
EcaAPI.addAllReturnWhitelist("com.yourmod.");
boolean removed = EcaAPI.removeAllReturnWhitelist("com.yourmod.");
boolean isProtected = EcaAPI.isAllReturnWhitelisted("com.yourmod.YourClass");

// 白名单 — 转换级别（跳过所有 ECA 转换，包括防御性钩子）
EcaAPI.addTransformWhitelist("com.yourmod.");
boolean removedTransform = EcaAPI.removeTransformWhitelist("com.yourmod.");
boolean isFullyProtected = EcaAPI.isTransformWhitelisted("com.yourmod.YourClass");

Set<String> allWhitelisted = EcaAPI.getAllWhitelistedPackages();

// 生成禁令
EcaAPI.banSpawn(serverLevel, EntityType.ZOMBIE, 300);  // 禁止僵尸生成 5 分钟
boolean banned = EcaAPI.isSpawnBanned(serverLevel, EntityType.ZOMBIE);
int remaining = EcaAPI.getSpawnBanTime(serverLevel, EntityType.ZOMBIE);
EcaAPI.unbanSpawn(serverLevel, EntityType.ZOMBIE);
Map<EntityType<?>, Integer> allBans = EcaAPI.getAllSpawnBans(serverLevel);
EcaAPI.unbanAllSpawns(serverLevel);

// 强制加载
EcaAPI.setForceLoading(livingEntity, serverLevel, true);
boolean forceLoaded = EcaAPI.isForceLoaded(livingEntity);
EcaAPI.setForceLoading(livingEntity, serverLevel, false);

// 实体扩展
Map<EntityType<?>, EntityExtension> registry = EcaAPI.getEntityExtensionRegistry();
Map<EntityType<?>, Integer> activeTypes = EcaAPI.getActiveEntityExtensionTypes(serverLevel);
EntityExtension active = EcaAPI.getActiveEntityExtension(serverLevel);
EcaAPI.clearActiveEntityExtensionTable(serverLevel);

// 全局效果覆盖（直接覆盖雾/天空盒/音乐而无需实体扩展，不改变效果优先级）
EcaAPI.setGlobalFog(serverLevel, new FogData(true, 8.0f, 0.0f, 0.0f, 0.0f, 0.02f, 0.25f, 0.0f, 1.0f, 0));
EcaAPI.clearGlobalFog(serverLevel);
EcaAPI.setGlobalSkybox(serverLevel, new SkyboxData(false, null, true, new ResourceLocation("eca", "the_last_end"), 1.0f, 100.0f, 1.0f, 1.0f, 1.0f, 1.0f));
EcaAPI.clearGlobalSkybox(serverLevel);
EcaAPI.setGlobalMusic(serverLevel, new MusicData(new ResourceLocation("your_mod", "music.boss"), 0, 1.0f, 1.0f, true, true));
EcaAPI.clearGlobalMusic(serverLevel);
EcaAPI.clearAllGlobalEffects(serverLevel);

// 复活
EcaAPI.startResurrection();
EcaAPI.addResurrectionTarget(entity);
boolean tracked = EcaAPI.isResurrectionTracked(entity);
EcaAPI.removeResurrectionTarget(entity);
EcaAPI.setResurrectionPollInterval(50);
EcaAPI.stopResurrection();

实体扩展

此模组还提供了可自定义的实体类型扩展功能，用于为您的实体添加特殊视觉效果。您需要创建一个继承 EntityExtension 的子类，并使用 @RegisterEntityExtension 注解来注册扩展。以下是一个快速入门示例：

@RegisterEntityExtension
public class MyBossExtension extends EntityExtension {

    static {
        EntityExtensionManager.register(new MyBossExtension());
    }

    public MyBossExtension() {
        super(EntityType.WITHER, 8);  // 实体类型 + 优先级（在一个维度中，某些全局扩展效果如雾、天空盒、战斗音乐仅应用于现有实体中优先级最高的实体扩展）
    }

    @Override
    public boolean enableForceLoading() {
        return true;  // 将此实体类型标记为强制加载，避免在大量生成的实体上使用以防止卡顿
    }

    @Override
    protected String getModId() {
        return "your_mod_id";  // 您的模组 ID，用于所有资源路径解析（纹理、声音等）
    }

    @Override
    public boolean enableBossBar() {
        return true;  // Boss 血条接管的总开关：是否让 ECA 清除实体的原生 Boss 血条并替换为 ECA 的。默认为 false — 未启用时，ECA 绝不接触实体自身的 Boss 血条。必须为 true 才能让 bossBarExtension() / shouldShowBossBar() / 自定义生命值覆盖生效
    }

    @Override
    public boolean shouldShowBossBar(LivingEntity entity) {
        return entity != null && entity.isAlive();  // Boss 血条显示条件（仅在 enableBossBar() 为 true 时生效）
    }

    @Override
    public boolean enableCustomHealthOverride() {
        return true;  // 如果为 true，ECA 自定义 Boss 血条当前生命值将从 getCustomHealthValue() 读取，而非原版 getHealth()
    }

    @Override
    public Number getCustomHealthValue(LivingEntity entity) {
        return entity.getEntityData().get(YOUR_CUSTOM_HEALTH_DATA);  // 用作当前生命值的实际值（例如实体数据、自定义字段），null = 回退到原版
    }

    @Override
    public boolean enableCustomMaxHealthOverride() {
        return true;  // 如果为 true，ECA 自定义 Boss 血条最大生命值将从 getCustomMaxHealthValue() 读取，而非原版 getMaxHealth()
    }

    @Override
    public Number getCustomMaxHealthValue(LivingEntity entity) {
        return entity.getEntityData().get(YOUR_CUSTOM_MAX_HEALTH_DATA);  // 用作最大生命值的实际值（例如实体数据、自定义字段），null = 回退到原版
    }

    // 自定义 Boss 生命条（需要 enableBossBar() = true）
    @Override
    public BossBarExtension bossBarExtension() {
        return new BossBarExtension() {
            @Override public boolean enabled() { return true; }  // 启用 Boss 血条
            @Override public ResourceLocation getFrameTexture() { return texture("boss/frame.png"); }  // 边框纹理（null 跳过）。如果同时设置了纹理和 RenderType，着色器将按纹理 alpha 遮罩渲染
            @Override public ResourceLocation getFillTexture() { return texture("boss/fill.png"); }  // 填充纹理（null 跳过）
            @Override public RenderType getFrameRenderType() { return CustomRenderTypes.BOSS_BAR; }  // 边框着色器/渲染类型（null 跳过）
            @Override public RenderType getFillRenderType() { return CustomRenderTypes.BOSS_BAR; }  // 填充着色器/渲染类型（null 跳过），可使用不同预设
            @Override public int getFrameWidth() { return 420; }  // 边框像素宽度（仅 RenderType 模式需要，纹理模式自动检测）
            @Override public int getFrameHeight() { return 40; }  // 边框像素高度
            @Override public int getFillWidth() { return 400; }  // 填充像素宽度（仅 RenderType 模式需要，纹理模式自动检测）
            @Override public int getFillHeight() { return 30; }  // 填充像素高度
            @Override public int getFrameOffsetX() { return 0; }  // 边框 X 偏移
            @Override public int getFrameOffsetY() { return -10; }  // 边框 Y 偏移
            @Override public int getFillOffsetX() { return 0; }  // 填充 X 偏移
            @Override public int getFillOffsetY() { return 0; }  // 填充 Y 偏移
            @Override public float getAlpha() { return 1.0f; }  // 整个 Boss 血条不透明度，0.0~1.0（默认 1.0）
        };
    }

    // 实体额外渲染层
    @Override
    public EntityLayerExtension entityLayerExtension() {
        return new EntityLayerExtension() {
            @Override public boolean enabled() { return true; }  // 启用渲染层
            @Override public RenderType getRenderType() { return CustomRenderTypes.BOSS_LAYER; }  // 渲染层着色器/渲染类型
            @Override public boolean isGlow() { return true; }  // 额外渲染层发光
            @Override public boolean isHurtOverlay() { return true; }  // 在该层上显示受伤覆盖效果
            @Override public float getAlpha() { return 0.8f; }  // 渲染层透明度（0.0 ~ 1.0）
        };
    }

    // 全局雾
    @Override
    public GlobalFogExtension globalFogExtension() {
        return new GlobalFogExtension() {
            @Override public boolean enabled() { return true; }  // 启用雾
            @Override public boolean globalMode() { return true; }  // 全局模式（忽略半径，始终在维度中激活）
            @Override public float radius() { return 8.0f; }  // 实体周围雾激活半径
            @Override public int fogColor() { return 0x000000; }  // 雾颜色为打包的 RGB 整数（例如 0xFF0000 = 红色，0x800080 = 紫色，0x000000 = 黑色）。改为覆盖 fogRed/Green/Blue() 以混合自定义颜色。
            @Override public float terrainFogStart(float renderDistance) { return renderDistance * 0.02f; }  // 地形雾开始距离
            @Override public float terrainFogEnd(float renderDistance) { return renderDistance * 0.25f; }  // 地形雾结束距离
            @Override public float skyFogStart(float renderDistance) { return 0.0f; }  // 天空雾开始距离
            @Override public float skyFogEnd(float renderDistance) { return renderDistance; }  // 天空雾结束距离
            @Override public FogShape fogShape() { return FogShape.SPHERE; }  // 雾形状（SPHERE 或 CYLINDER）
        };
    }

    // 全局自定义天空盒
    @Override
    public GlobalSkyboxExtension globalSkyboxExtension() {
        return new GlobalSkyboxExtension() {
            @Override public boolean enabled() { return true; }  // 启用天空盒
            @Override public boolean enableTexture() { return true; }  // 启用基于纹理的天空盒渲染
            @Override public ResourceLocation texture() { return texture("sky/skybox.png"); }  // 天空盒纹理资源位置
            @Override public boolean enableShader() { return true; }  // 启用基于着色器的天空盒渲染
            @Override public RenderType shaderRenderType() { return CustomRenderTypes.SKYBOX; }  // 天空盒着色器/渲染类型
            @Override public float alpha() { return 0.9f; }  // 天空盒透明度（0.0 ~ 1.0）
            @Override public float size() { return 100.0f; }  // 天空盒四边形大小
            @Override public float textureUvScale() { return 16.0f; }  // 纹理 UV 缩放
            @Override public float textureRed() { return 1.0f; }  // 纹理颜色红色（0.0 ~ 1.0）
            @Override public float textureGreen() { return 1.0f; }  // 纹理颜色绿色（0.0 ~ 1.0）
            @Override public float textureBlue() { return 1.0f; }  // 纹理颜色蓝色（0.0 ~ 1.0）
        };
    }

    // 全局战斗音乐
    @Override
    public CombatMusicExtension combatMusicExtension() {
        return new CombatMusicExtension() {
            @Override public boolean enabled() { return true; }  // 启用战斗音乐
            @Override public ResourceLocation soundEventId() { return sound("music.boss_battle"); }  // 声音事件 ID（必须在 sounds.json 中注册）
            @Override public SoundSource soundSource() { return SoundSource.MUSIC; }  // 声音类别
            @Override public float volume() { return 1.0f; }  // 播放音量（0.0 ~ 1.0）
            @Override public float pitch() { return 1.0f; }  // 播放音调
            @Override public boolean loop() { return true; }  // 循环播放
            @Override public boolean strictMusicLock() { return true; }  // 激活时阻止所有其他 MUSIC 声音
        };
    }

    // 条件门控：雾/天空盒/音乐仅在匹配的 shouldEnableXxx 返回 true 时激活；约每秒钟针对维度的主要实体重新检查
    @Override
    public boolean shouldEnableFog(LivingEntity entity) {
        return entity.getHealth() < entity.getMaxHealth() * 0.5f;  // 示例：实体生命值低于 50% 时雾激活
    }

    @Override
    public boolean shouldEnableSkybox(LivingEntity entity) {
        return true;  // 每个实体实例的天空盒激活条件
    }

    @Override
    public boolean shouldEnableMusic(LivingEntity entity) {
        return true;  // 每个实体实例的战斗音乐激活条件
    }

    /*
     * 条件切换 — 覆盖感知实体的重载（在所有五个扩展方法上：bossBar / entityLayer / globalFog /
     * globalSkybox / combatMusic）以根据实体状态返回不同的扩展对象。ECA 仅在实体非空时调用感知实体的重载
     *（其他情况使用无参变体），并捕获其抛出的任何异常，回退到无参变体。
     * 全局效果约每秒钟针对维度的主要实体重新评估；实例效果（Boss 血条/渲染层）每帧重新评估。
     */