由于个人原因,本模组将在未来两个月内停止更新。在此期间,我将不会回复任何消息。
本模组基于 CoreMod(ITransformationService)、Java Agent 和 Mixin 技术提供实体操作 API 与命令,并附带一系列功能模块:BossShow、实体扩展、ECA Blender 模型、方块扩展、物品扩展、屏幕过滤器、ECA 光影生成器、自定义阵营以及自定义袭击。请注意,虽然其提供的实体操作方法可能与原版逻辑同名,但底层实现完全不同。例如,set health API 可以使用自定义生命值修改实体(包括但不限于实体数据、数值字段和哈希表);remove API 执行的是底层的 Minecraft 容器清理工作;set invulnerable API 提供了比原版创造模式无敌状态更强大的实现。此外,本模组默认将原版属性上限解锁至 Double.MAX_VALUE。你可以在配置文件中通过“Unlock Attribute Limits”选项禁用此功能。
本模组的初衷是为开发者提供简化的实体操作 API,同时在确保性能与兼容性的前提下实现一定的强度。因此,请勿将此模组用于模组强度对比或无休止的代码军备竞赛。另外,在整合包生存环境中,建议确保“Attack and Defence Radical Logic”配置项处于禁用状态。
本模组还为 MCreator 用户提供了一个 MCreator 插件,方便他们在 MCreator 中调用本模组的 API。
社区版(如果你想在更高版本的 Minecraft 上游玩):
玩家使用说明
玩家可使用以下 /eca 命令(需要权限等级 ≥ 2):
-
/eca setHealth <targets> <health> [report] - 设置实体生命值。添加 report 参数可为每个存活目标直接在 logs/ 目录下写入一个结构化的 <entity>_health_report_<timestamp>.txt 文件;报告包含健康模型判断、通道结果、延迟验证、完整的按源数据流反演追踪以及相关背景分析。
-
/eca setMaxHealth <targets> <maxHealth> - 设置实体最大生命值(反向计算属性基础值)
-
/eca setInvulnerable <targets> <true|false> - 设置实体无敌状态
-
/eca lockHealth <targets> true <value> - 将实体生命值锁定在特定值
-
/eca lockHealth <targets> false - 解锁实体生命值
-
/eca lockMaxHealth <targets> true <value> - 将实体最大生命值锁定在特定值
-
/eca lockMaxHealth <targets> false - 解锁实体最大生命值
-
/eca banHealing <targets> true [value] - 阻止受影响实体的生命值超过配置的治疗禁令值(可选;默认为当前生命值)。
-
/eca banHealing <targets> false - 解除对实体的治疗禁令
-
/eca hurt <targets> <amount> - 强制实体受到伤害(先执行原版受伤逻辑,当生命值损失未正常结算时强制写入;由活体实体执行时,击杀归属执行者)
-
/eca kill <targets> - 杀死实体
-
/eca remove <targets> [reason] - 从世界中移除实体
-
/eca memoryRemove <targets> - 危险!需要 Attack Radical Logic 配置。使用 LWJGL 内部的 Unsafe 实例移除实体
-
/eca teleport <targets> <x> <y> <z> - 将实体传送至其当前维度中的指定坐标。
-
/eca lockLocation <targets> <true|false> [x y z] - 锁定/解锁实体位置
-
/eca cleanBossBar <targets> - 清理 Boss 条
-
/eca allReturn <targets> <true|false> - 危险!需要 Attack Radical Logic。根据请求启用或禁用 AllReturn;玩家针对其四个护甲槽和两个手持槽中拥有物品的模组,其他实体则针对其自身的模组。白名单转换生效。
-
/eca allReturn global <true|false> - 危险!为所有非白名单模组启用/禁用全局 AllReturn
-
/eca banSpawn <targets> <seconds> - 禁止所选实体类型的生成,持续指定时长
-
/eca banSpawn clear - 解除当前维度内所有生成禁令
-
/eca setForceLoading <targets> <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 <preset> - 设置全局天空盒光影预设
-
/eca setFilter <targets> true <type> - 为玩家应用屏幕滤镜(类型:sketch, spotlight, matrix, rain, desert, snow, toxic, cosmos)
-
/eca setFilter <targets> false - 移除玩家的所有活动滤镜
-
/eca bossShow edit - 打开游戏内电影编辑器(切换至旁观者模式)
-
/eca bossShow exit - 退出编辑器并恢复之前的游戏模式
-
/eca bossShow list - 列出所有已加载的过场动画
-
/eca bossShow play <viewer> <target> <id> - 强制播放过场动画
-
/eca bossShow stop <viewer> - 停止观看者当前的过场动画
-
/eca bossShow reload - 从磁盘重新加载所有过场动画 JSON 定义
-
/eca bossShow clearHistory <player> - 清除玩家的“已观看”记录
-
/eca shaderGenerator - 打开游戏内光影预设生成器
-
/eca resurrection start - 启动复活守护线程
-
/eca resurrection stop - 停止复活守护线程
-
/eca resurrection status - 显示守护线程状态及复活/检查计数
-
/eca resurrection add <targets> - 将实体加入复活追踪(在每个轮询周期死亡时自动复活)
-
/eca resurrection remove <targets> - 将实体从复活追踪中移除
-
/eca resurrection list - 列出所有受追踪实体及其容器完整性状态
-
/eca resurrection check <target> - 对实体进行一次性容器完整性检查
-
/eca resurrection revive <target> - 手动立即强制复活受追踪实体
-
/eca resurrection interval <ms> - 设置轮询间隔(毫秒,100–10000;默认 25)
-
/eca faction create <id> <displayName> [color] - 创建阵营(颜色接受预设名称,如 red/gold/teal)
-
/eca faction remove <id> - 移除阵营定义,并丢弃指向该阵营的所有实体绑定
-
/eca faction join <factionId> [targets] - 将实体绑定到阵营(默认为命令来源实体)
-
/eca faction leave [targets] - 将实体从其当前阵营解绑
-
/eca faction list - 列出所有已注册的阵营
-
/eca faction info [factionId] - 显示阵营的颜色、成员及关系覆盖信息
-
/eca faction relation <factionA> <factionB> <relation> - 设置 A 对 B 的关系。hostile / neutral / friendly 存储关系覆盖;same_faction 则将 B 合并到 A 中(B 的成员被重新绑定到 A,关系被折叠,B 被删除)
-
/eca faction leader <factionId> - 显示阵营领袖及其是否当前已加载
-
/eca faction leader <factionId> set [target] - 设置领袖(默认为命令来源实体;自动加入阵营)
-
/eca faction leader <factionId> clear - 清除领袖;前领袖仍保留为成员
-
/eca raid defs - 列出所有已注册的突袭定义
-
/eca raid list - 列出当前维度中的活跃突袭
-
/eca raid start <definitionId> [pos] - 在其目标结构的内部位置启动突袭(默认为命令来源位置)
-
/eca raid startat <definitionId> <pos> - 以指定中心点开始一场袭击,跳过结构查找
-
/eca raid info <instanceId> - 显示一场正在进行的袭击的详细信息
-
/eca raid end <instanceId> <victory|defeat> - 结束一场袭击并清除所有幸存的袭击者
新增了新的命令选择器,通过 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.7-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) - 如果 ECA 的生命值修改分析已识别出实体的真实生命值,则返回该生命值;否则返回实体的原版生命值数据。此读取操作不会启动分析或回退到实体的 getHealth();null 实体返回 0.0f,无法读取的存储返回 NaN。
-
getRealHealth(entity) - 使用与 getHealth(entity) 相同的读取规则,但针对 null 实体返回 NaN。
-
setHealth(entity, health) - 通过原版直接写入 → 数据流反转 → 外部扫描 → 方法探测 → 数值反转的顺序尝试进行经过验证的生命值更改;玩家仅使用原版写入。数据流分析定位存储并反转读取表达式,包括可追踪的反射、Unsafe 和 VarHandle 访问。新的探测证据可以重新访问之前的通道。通道受证据、配置和预算的限制,并在尝试后进行验证,探测写入时使用快照/回滚。默认情况下提供基本的数据流反转,除非启用了强制兼容模式。Const Override、External Scan、Method Probe 和 Numeric Inversion 需要启用 Attack Radical Logic 以及 Attack → setHealth 下各自的开关,这些开关默认处于关闭状态。
-
setMaxHealth(entity, maxHealth) - 通过从当前修饰符反向计算属性基础值来设置最大生命值
-
lockMaxHealth(entity, value) - 将实体最大生命值锁定在指定值(每刻强制执行)
-
unlockMaxHealth(entity) - 解锁实体最大生命值
-
getLockedMaxHealth(entity) - 获取当前最大生命值锁定值(未锁定时为 null)
-
isMaxHealthLocked(entity) - 检查实体最大生命值是否被锁定
-
addHealthWhitelistKeyword(keyword) - 向生命值修改白名单添加关键词
-
removeHealthWhitelistKeyword(keyword) - 从生命值修改白名单移除关键词
-
getHealthWhitelistKeywords() - 获取所有生命值白名单关键词
-
addHealthBlacklistKeyword(keyword) - 向生命值修改黑名单添加关键词
-
removeHealthBlacklistKeyword(keyword) - 从生命值修改黑名单移除关键词
-
getHealthBlacklistKeywords() - 获取所有生命值黑名单关键词
-
hurt(entity, damageSource, amount) - 伤害实体并确保生命值损失生效。原版 hurt 仅在 actuallyHurt 内部通过 setHealth(getHealth() - damage) 写入一次生命值——通过实体自身的 getter 和 setter,因此对于被重写或存储解耦的实体,会运行整个管道并触发所有事件,但生命值不减少。此方法清除无敌冷却时间并首先调用原版 hurt(减伤、击退、仇恨和受伤动画均正常发生),然后在 min(1.0, amount * 50%) 范围内将生命值锚点与 before - amount 进行比较。如果不匹配,它将恢复原版会留下的伤害来源簿记(lastHurtByMob、lastHurtByPlayer/Time、lastDamageSource/Stamp、战斗跟踪器、受伤动画),并通过 setHealth 强制设置生命值,下限为零。此处永远不会强制将致命结果进入死亡路径:实体保持在零生命值,以便原版 tickDeath 播放死亡动画并移除它——如需立即杀死,请使用 kill。处于 ECA 自身生命值锁定或无敌状态下的实体由那些系统处理——原版 hurt 仍然运行,但不会尝试强制写入。
-
hurt(entity, attacker, amount) - 相同的管道,但伤害来源由攻击者派生:对玩家使用 playerAttack,对其他所有活体实体使用 mobAttack,以便击杀信用和掉落归属按预期行为
-
kill(entity, damageSource) - 杀死实体(掉落 + 进度 + 移除)
-
revive(entity) - 清除死亡状态并恢复生命值
-
revive(level, uuid) - 在指定层级中通过 UUID 清除死亡状态并恢复生命值
-
reviveAllContainers(entity) - 复活所有关键实体容器(tickList、lookup、sections、tracker)
-
reviveAllContainers(level, uuid) - 在指定层级中通过 UUID 复活所有关键实体容器
-
teleport(entity, x, y, z) - 将实体强制传送至其当前维度中的指定坐标并同步客户端。必须在服务器的主要线程上运行。
-
lockLocation(entity) - 将实体位置锁定在当前坐标
-
lockLocation(entity, position) - 将实体位置锁定在指定坐标
-
unlockLocation(entity) - 解锁实体位置
-
isLocationLocked(entity) - 检查实体位置是否被锁定
-
getLockedLocation(entity) - 获取锁定位置(未锁定时为 null)
-
remove(entity, reason) - 完全移除(AI、Boss 栏、容器、乘客)
-
memoryRemove(entity, reason) - 危险!需要 Attack Radical Logic 配置。使用 LWJGL 的内部 Unsafe 实例移除实体
-
cleanupBossBar(entity) - 移除 Boss 栏而不移除实体
-
isInvulnerable(entity) - 检查实体是否无敌(ECA 内部无敌逻辑)
-
setInvulnerable(entity, invulnerable) - 设置无敌(启用:复活 + 锁定生命值 + 阻挡伤害 + 每刻移除有害效果 + 防止怪物目标锁定 + 保护玩家物品栏;禁用:清除所有保护)
-
enableAllReturn(entity) - 危险!需要 Attack Radical Logic。为实体的模组启用 AllReturn;对于玩家,目标为其盔甲和主手/副手装备所属的模组。仅转换符合条件的布尔值和 void 方法,且受转换白名单限制。
-
disableAllReturn(entity) - 使用与启用时相同的目标规则禁用 AllReturn:对玩家为目标其盔甲和主手/副手装备所属的模组,对其他实体则为目标其自身的模组。
-
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) - 清除当前维度中的活跃实体扩展表。
-
playAnimation(entity, animation) - 手动接管控制并以速度 1 启动命名模型动作,不循环(逻辑服务器线程)。
-
playAnimation(entity, animation, speed, loop) - 手动启动/重启带有速度和循环设置的命名模型动作(逻辑服务器线程)。
-
stopAnimation(entity) - 停止托管播放,取消现有的活跃技能(如果存在),并将控制权释放给控制器/回退方案。
-
pauseAnimation(entity) - 暂停托管动作/技能的时间进度,但不冻结生命周期决策。
-
resumeAnimation(entity) - 从其保存的位置恢复托管动作/技能的时间进度。
-
isAnimationPlaying(entity[, animation]) - 查询托管播放状态,包括暂停/保持的姿势,可选地匹配动作名称。
-
triggerBlenderSkill(entity, skillId) - 通过其中断策略启动已配置的技能。
-
cancelBlenderSkill(entity) - 取消活跃技能,且不触发完成回调。
-
isBlenderSkillActive(entity) - 查询活跃技能的执行状态,包括暂停情况。
-
getBlenderSkillExecution(entity) - 获取当前的执行快照,若无则为 null。
-
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-trigger BossShows(返回启动的数量)。
-
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) - 使用自定义谓词获取所有层级中的实体
-
getNearestEntity(level, pos, filter) - 获取符合谓词的最近实体(支持 ECA 解析器,因此包含无敌实体)
-
getNearestEntity(level, pos, area, filter) - 同上,但限制在 AABB 范围内
-
getNearestEntity(level, pos, entityClass) - 获取给定类型的最近实体
-
getNearestEntity(level, pos, area, entityClass) - 获取 AABB 内给定类型的最近实体
-
shaderPreset(id) - 通过 ID 获取光影预设,并暴露其预渲染的渲染目标
-
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) - 立即手动强制复活被追踪的实体
-
createFaction(id, displayName, color) - 创建并注册一个阵营(仅内存中)
-
createFaction(id, displayName, color, level) - 创建并注册一个阵营,持久化到世界 SavedData 中
-
removeFaction(id) - 移除阵营定义(仅内存中)
-
removeFaction(id, level) - 移除阵营定义,并解除所有指向该阵营的实体绑定
-
mergeFactions(intoId, fromId, level) - 将一个阵营合并到另一个阵营:成员重新绑定,关系覆盖项合并,解散的阵营被移除。返回移动的成员数量,如果合并无法执行则返回 -1
-
getFaction(id) - 通过 ID 获取阵营定义
-
getAllFactions() - 获取所有已注册的阵营
-
joinFaction(entity, factionId) - 将实体绑定到某个阵营
-
leaveFaction(entity) - 将实体从其所属阵营中解绑
-
getEntityFaction(entity) - 获取实体所属的阵营 ID(若无则返回 null;驯服动物会回退至其主人的阵营)
-
areSameFaction(a, b) - 检查两个实体是否属于同一阵营
-
isFriendly(a, b) - 检查完整的友好关系:相同/友好的 ECA 阵营、原版记分板联盟或主人-宠物联盟(不包括创造模式、旁观者模式和 ECA 无敌状态)
-
getFactionMembers(level, factionId) - 将阵营的成员表解析为单个层级中的实时实体
-
kickAllFromFaction(factionId, level) - 全局移除所有显式成员,包括未加载和跨维度的成员
-
setFactionRelation(a, b, relation) - 设置阵营 A 对阵营 B 的关系(仅内存中)
-
setFactionRelation(a, b, relation, level) - 设置阵营 A 对 B 的关系,并持久化
-
getFactionRelation(a, b) - 获取 A 到 B 的显式关系(若无覆盖则返回 null)
-
getEffectiveFactionRelation(source, target) - 解析两个实体之间的有效关系
-
canHarm(source, target) - 检查 ECA 阵营关系是否允许源实体伤害目标实体
-
canTarget(source, target) - 检查完整的阵营和保护规则是否允许源实体故意瞄准目标实体
-
alertFactionMembers(factionId, attacker, victim, level) - 使附近未被瞄准的盟友对攻击者进行反击
-
joinFaction(uuid, typeId, isPlayer, factionId, level) - 通过 UUID 将实体绑定到阵营,无需其实体已加载
-
leaveFaction(uuid, level) - 通过 UUID 从阵营中移除成员,无需其实体已加载
-
getEntityFaction(uuid) - 获取绑定到 UUID 的阵营(纯索引查找;不涉及宠物继承,这需要实时实体)
-
isFactionMember(uuid, factionId) - 检查 UUID 是否属于特定阵营
-
getFactionMemberRecords(factionId) - 获取所有成员记录(UUID + 实体类型),无需加载实体
-
getFactionMemberUuids(factionId) - 获取所有成员 UUID,无需加载实体
-
getFactionMembersByType(factionId, typeId) - 按实体类型过滤成员,无需加载实体
-
getFactionMemberCount(factionId) - 获取阵营的成员数量,无需加载实体
-
resolveFactionMembers(factionId, level) - 将阵营的成员解析为单个层级中的实时实体
-
setFactionLeader(factionId, leader, level) - 设置阵营领袖(如需则自动加入该阵营)
-
clearFactionLeader(factionId, level) - 清除领袖;前领袖仍保留为成员
-
getFactionLeader(factionId) - 获取领袖记录,无需加载实体
-
getFactionLeaderUuid(factionId) - 获取领袖的 UUID
-
resolveFactionLeader(factionId, server) - 将领袖解析为实时实体,搜索每个维度
-
isFactionLeader(entity) - 检查实体是否为任何阵营的领袖
-
getFactionByLeader(uuid) - 查找实体领导的是哪个阵营
-
startRaid(level, pos, raidId) - 在目标结构内的位置开始袭击(中心点取自结构)
-
startRaidAt(level, center, raidId) - 以指定的中心点开始一场袭击,跳过结构查找
-
endRaid(level, raid, victory) - 结束一场袭击,并丢弃所有存活的袭击者
-
endRaid(level, raidId, victory) - 根据实例 ID 结束一场袭击,并丢弃所有存活的袭击者
-
getRaid(level, raidId) - 根据实例 ID 获取一个活跃的袭击
-
getActiveRaids(level) - 获取当前世界中所有活跃的袭击
-
getNearestRaid(level, pos, maxDistance) - 在指定距离内寻找最近的活跃袭击
-
getAllRaidDefinitions() - 获取所有已注册的袭击定义
实体扩展
本模组还提供了可定制的实体类型扩展功能,用于为你的实体添加特殊的视觉效果。你需要创建一个继承自 EntityExtension 的子类,并使用 @RegisterEntityExtension 进行注解以注册该扩展。
实体扩展可以通过 enableBossBar() 选择启用自定义 Boss 栏,通过 shouldShowBossBar(LivingEntity) 控制可见性,并通过 bossBarExtension() 提供客户端的外观表现。BossBarExtension.showValueText() 支持居中显示“当前/最大”数值文本;你可以重写 getDisplayCurrentValue(LivingEntity) 和 getDisplayMaxValue(LivingEntity) 来提供自定义的显示数值。默认情况下,这些值分别来源于实体的生命值和最大生命值。
实体、物品和方块的着色器覆盖层共享同一个 ShaderMaskPass 渲染管线。每个渲染通道(Pass)都提供一个 RenderType、一个可选的对齐 UV 的遮罩纹理、一个目标 RGB 颜色(默认为黑色)、一个近色容差以及不透明度。一个扩展可以返回多个渲染通道,以便在同一个遮罩中使用不同的着色器处理不同颜色。渲染通道按照列表顺序执行,且在选定区域重叠时,后面的通道会绘制在前面的通道之上。透明且与遮罩不匹配的像素将被丢弃。
ECA Blender 模型
ECA Blender Model 允许你使用原生的 .blend 文件或导出的 GLB 文件来制作实体模型和动画。模型可以替换实体的原始外观,也可以与其并排渲染。
你可以配置待机、移动、受伤和死亡动画,触发命名技能,并使用动画回调来实现定时效果或命中逻辑。控制器可以通过重写其方法来自定义。支持的几何体和材质节点也可以独立于角色动作进行动画播放,这使得它们非常适用于旋转光环等特效。
原生 .blend 支持目前处于实验阶段,目标版本为 Blender 5.2.1。请参阅 README 获取设置示例、回放 API 和支持的节点列表。
方块扩展
方块扩展在不替换正常模型的情况下添加着色器覆盖层。普通的烘焙方块和掉落方块使用来自 getBlockShaderPasses() 的 BLOCK-profile 渲染通道;GeckoLib 方块实体则使用来自 getGeoShaderPasses(texture) 的 NEW_ENTITY-profile 渲染通道。逻辑预设 ID 仍会为这两种配置文件提供默认的 RenderTypes。
对于烘焙方块上的外部遮罩,即使模型使用图集,也会使用精灵局部 UV 进行采样。GeckoLib 遮罩使用模型纹理的标准 UV 布局,并与 overlayGeoBones() 结合以形成交集。普通世界方块按区块索引并批处理到单独的覆盖层中;掉落方块和 GeckoLib 方块实体会自动处理。方块物品仍然属于 ItemExtension 的一部分。旧的 Color-Key 和单遮罩获取方法是已弃用的兼容性适配器。
物品扩展
你可以创建物品扩展,为特定物品添加着色器渲染效果:创建一个继承自 ItemExtension 的子类,并使用 @RegisterItemExtension 进行注解以注册。
结构化提示行可以选择自己的插入位置:
EcaTooltipLine.head(...): 位于物品名称下方。
EcaTooltipLine.body(...): 在主提示正文中,当存在高级物品 ID/NBT/禁用行时,位于这些行之前的位置。
EcaTooltipLine.tail(...): 位于提示信息的末尾。
每一行都可以接受普通的 Component 或通过 ItemUtil.of(...) 构建的 EcaText,因此提示文本支持与物品名称相同的丰富效果:渐变、彩虹、纯色、闪烁、故障艺术、加粗、斜体、下划线和删除线。当你需要直接编辑最终提示列表时,旧的 appendTooltip(ItemStack, TooltipFlag, List<Component>) 钩子仍然可用。
物品遮罩渲染通道自动使用精灵局部 UV。ShaderMaskPass.masked(...) 采样外部遮罩纹理,而 ShaderMaskPass.baseTexture(...) 直接从物品纹理中选择颜色。旧的 getRenderType()、Color-Key 和单遮罩获取方法是已弃用的兼容性适配器。
注意:与实体扩展类似,每个物品只能拥有一个扩展。重复注册会被拒绝并记录错误日志。实体层扩展(EntityLayerExtension.getAlpha(),默认值 0.5)和物品扩展(ItemExtension.getAlpha(),默认值 1.0)都支持为其着色器覆盖层调整透明度。
着色器预设
打包的 ECA 专用文件采用通用的 assets/<namespace>/eca/<system>/ 目录结构。服务器端定义使用对应的 data/<namespace>/eca/<system>/ 目录结构,而标准 Minecraft 资源(如纹理和语言文件)则保留在其原版目录中。早期 ECA 版本文档中记录的旧位置仍作为后备加载项继续生效。
本模组还为实体扩展和物品扩展系统提供了多种着色器预设,你可以直接在扩展中使用它们。只需将相应的预设类替换为你自己的 RenderType 持有者即可。每个内置预设类暴露了 4 个现成的 RenderTypes —— 实体扩展使用 BOSS_BAR、BOSS_LAYER、SKYBOX,物品扩展使用 ITEM —— 以及用于实体纹理覆盖层的 createEntityEffect(texture)。实体纹理覆盖层通过 EntityLayerExtension.getTexture() 支持——返回一个纹理即可将其叠加在实体模型上,可选择性地与着色器 RenderType 结合以实现“纹理+着色器”的效果(匹配 Boss 栏覆盖技术)。
可用的预设:
TheLastEndRenderTypes — The Last End
DreamSakuraRenderTypes — Dream Sakura
ForestRenderTypes — Forest
OceanRenderTypes — Ocean
StormRenderTypes — Storm
VolcanoRenderTypes — Volcano
ArcaneRenderTypes — Arcane
AuroraRenderTypes — Aurora
HackerRenderTypes — Hacker
StarlightRenderTypes — Starlight
CosmosRenderTypes — Cosmos
BlackHoleRenderTypes — Black Hole
屏幕滤镜
本模组提供了一组全屏后处理滤镜预设,服务器可以针对每位玩家应用这些滤镜,既可以通过命令执行,也可以通过 API 实现。滤镜会同步到客户端,并以着色器传递(shader pass)的形式渲染在场景之上。同一时间每位玩家只能激活一个滤镜——应用新的滤镜将替换当前正在使用的滤镜。
滤镜预设:
SKETCH — 素描
SPOTLIGHT — 聚光灯
MATRIX — 矩阵
RAIN — 雨
DESERT — 沙漠
SNOW — 雪
TOXIC — 有毒
COSMOS — 宇宙
着色器生成器
ECA 提供了一个游戏内的着色器预设生成器,用于构建可移植的 Minecraft 核心着色器预设,无需手动编写 GLSL。使用以下命令打开它:
/eca shaderGenerator
该生成器编辑分层合成项目。每个图层可以包含多个视觉模块,包括基本形状、星空效果、魔法符号和图像元素。编辑器支持实时预览、撤销/重做、图层可见性、图层排序、混合模式、画布编辑、项目保存/加载、五文件着色器导出以及项目删除(File -> Delete Current Project,即“删除当前项目”,此操作会请求确认,然后永久移除包含源代码、纹理和导入依赖项的项目目录)。
每个项目还拥有一个五文件源工作区。使用 File -> Source Editor(源编辑器)可将同一项目切换为手动 GLSL/JSON 编辑模式,提供单行菜单、基于注释的快速导航、撤销/重做、保存、编译快捷键以及防抖动的实时预览。右侧将预览窗口置于可滚动的编译器输出面板上方。生成的片段着色器会发出 // @eca-nav layer: ... 和 // @eca-nav element: ... 标记;手动编写的 // @eca-nav ... 注释可创建自定义导航点。返回可视化编辑器不会丢弃任一表示形式。File -> Import Shader Folder(导入着色器文件夹)会在 Forge 的标准游戏目录下打开原生文件夹选择器,并将选定的 JSON/VSH/FSH 着色器复制到新的本地 ECA 项目中。一个文件夹可能包含多个着色器程序,此时编辑器会询问要导入哪一个。当源路径位于 assets/<modid>/ 之下时,项目对话框会自动预填该 Mod ID;否则该字段保持为空。标准的三文件着色器会被复制到 BLOCK 和 NEW_ENTITY 源槽位中,以进行独立的编译验证;包含 ECA 共享片段 _block/_entity 五文件布局的文件夹会直接保留这两种配置。源文件夹永远不会被修改。
导入功能支持标准的 Minecraft 核心着色器 JSON/VSH/FSH 资源。常见的 time、camera、scale、opacity 和 cosmic-UV uniform 会接收预览绑定。如果着色器依赖于特定 mod 的渲染管线、Java 回调、纹理或 uniform,则仍可能需要专用的适配器;不支持的片段结构将被报告为编译错误,而不是被静默重写。
纹理依赖也会得到解析。当导入的着色器引用一系列编号的 PNG 文件时,ECA 会尝试复制这些文件,将它们合并为一个预览纹理,并提供匹配每个图像的 UV 范围的采样器和 uniform。带有 .mcmeta 动画部分的 PNG 文件会在该合并纹理中逐帧更新,同时保留帧顺序、每帧持续时间和插值方式。如果 ECA 无法确定文件如何对应于某个采样器或 uniform,编译器输出面板会列出未解析的依赖项及扫描目录,而不会静默失败;着色器编译本身仍可成功。
预览目标目前包括平面、物品、实体、天空盒和 Boss bar。导出的预设采用标准的核心着色器五文件布局:
assets/<namespace>/eca/shader_presets/<name>.fsh
assets/<namespace>/eca/shader_presets/<name>_block.vsh
assets/<namespace>/eca/shader_presets/<name>_block.json
assets/<namespace>/eca/shader_presets/<name>_entity.vsh
assets/<namespace>/eca/shader_presets/<name>_entity.json
片段着色器由两种配置共享。两个顶点配置是分别生成的,因为 Minecraft 对不同渲染目标使用不同的顶点格式:
<name>_block.* 使用 DefaultVertexFormat.BLOCK,适用于天空盒、平面预览和 Boss bar 渲染。
<name>_entity.* 使用 DefaultVertexFormat.NEW_ENTITY,适用于实体层、物品层和带纹理的实体效果。
导出模式:
PORTABLE:标准的 Minecraft 核心着色器输出,不包含任何 ECA 特定的 uniform。
PORTABLE_WITH_ECA_HINTS:包含 ECA uniform 钩子及其无害的默认值,同时在不使用 ECA 的情况下也可用。
ECA_ENHANCED:包含 ECA 特定的 uniform,并期望使用 ECA 的增强型着色器运行时。
项目文件保存在 config/eca/shadergenerator/<namespace>/<name>/project.json 下。使用 File -> Export As <shader>(导出为<着色器>)可将运行时可加载的五文件预设导出到 config/eca/shadergenerator/<namespace>/<name>/ 目录。ECA 会自动从模组资源和导出的配置预设中发现预设。预设 ID 始终为 <namespace>:<name>。
对于随模组打包的预设,请将这五个文件放置在 src/main/resources/assets/<namespace>/eca/shader_presets/ 下。旧的 assets/<namespace>/shaders/core/ 位置仍然受支持,但当两者定义了相同的 ID 时,标准的 ECA 路径优先。你也可以通过 @RegisterShaderPreset 声明预设。该注解会在启动扫描期间注册预设 ID,对于希望透过显式的 Java 标记类暴露自定义预设的模组非常有用。
在运行时,通过 EcaPresets 获取生成的 RenderTypes,或通过 EcaAPI.shaderPreset(id) 查询预设对象。返回的 ShaderPreset 暴露了 bossBar()、bossLayer()、skybox()、item()、block()、geoBlock(texture) 和 entityForPreview(texture);EcaPresets 则将前六个作为按预设 ID 静态查找的镜像。block() 和 geoBlock(texture) 是区块扩展所使用的 BLOCK 和 NEW_ENTITY 配置档案。对于实体纹理叠加层,请使用带有 bossLayer() 的 EntityLayerExtension.getTexture()。
AI 助手
源编辑器还配备了一个 AI 助手,可通过你选择的模型驱动同一项目。支持三种 API 格式——OpenAI Responses、兼容 OpenAI Chat 的格式以及 Anthropic Messages——每种格式都存储为一个配置文件,包含各自的基地址、模型、API 密钥(或密钥环境变量)、自定义标头,以及在 config/eca/shadergenerator/settings.json 中设置的 10–600 秒超时时间。
该模型通过工具而非自由文本进行操作:读取项目摘要和模块架构、编辑图层和元素、导入 PNG 图像、修改五个源文件中的任意一个、保存项目、导出五个着色器文件、编译并读取诊断信息、捕获预览画面,以及撤销或重做其自身的变更。有三个开关控制其自主操作的深度——允许自动编辑、每次编辑后编译、向视觉模型发送预览图像。关闭自动编辑时,它仍可检查和解释,但会拒绝所有写入操作;开启自动编译时,它会在每次编辑后重新编译并根据诊断信息进行修复,同时受限于自动修复次数上限和整体工具调用轮次上限。
MCP
AI 助手页面上的 MCP 按钮会启动本地 ECA Shader MCP,允许外部代理驱动当前的着色器项目。该服务使用 Streamable HTTP 协议,仅绑定到 127.0.0.1,且无需访问令牌;MCP 页面显示端口号和已连接的代理,端口号存储在 config/eca/shadergenerator/mcp_settings.json 中。URL 端口必须与 MCP 页面一致,并且 Minecraft 和 MCP 服务都必须保持运行状态。
操作顺序:首先在游戏中通过 着色器生成器 → AI 助手 → MCP 启动服务,然后启动并连接代理。当服务未运行时,代理无法连接。
Codex
从命令行注册:
codex mcp add eca_shader --url http://localhost:8767/mcp
Claude Code
从命令行注册:
claude mcp add --transport http eca_shader http://127.0.0.1:8767/mcp
BossShow 过场动画
BossShow 播放一段过场动画,将玩家镜头锁定在围绕目标实体预录制的路径上,并支持字幕和服务端事件回调。摄像机路径通过内置的游戏内编辑器录制——你无需手动编写关键帧。
默认编辑器按键绑定:
| 按键 |
操作 |
J |
开始/继续录制 |
I |
暂停录制 |
ENTER |
保存录制 |
ESC |
丢弃录制 |
编辑器工作流程:
- 在至少一个 LivingEntity(64 格范围内)附近运行
/eca bossShow edit。
- 在主 GUI 中,点击 + New cutscene from entity → 瞄准一个实体 → 右键单击将其选为摄像机锚点。或者,点击现有过场动画的 Edit。
- 配置触发类型(范围/自定义)、目标实体类型、电影条、允许重复等选项。
- 点击 ● Record,按
J 开始。在旁观者模式下自由移动摄像机——每个刻都被捕获为可编辑的帧。
- 录制完成后,点击时间轴上的任意刻以编辑其位置和摄像机方向。使用 Preview 播放时间轴。要从游戏视角重新采样姿势,点击 Free camera write,移动摄像机,然后按 Enter 写入当前刻。
- 按
ENTER 保存,按 ESC 丢弃。保存的文件位于 config/eca/bossshow/<namespace>/<path>.json。
时间轴编辑(录制后,在编辑器 GUI 中):每帧均可选择。点击或拖动条形图进行跳转,使用方向键进行单刻导航,并在检查器中编辑 dx/dy/dz/yaw/pitch。使用 Add content 将事件或字幕附加到当前刻。提供 Set In / Set Out、Copy / Cut / Delete、Paste、均匀/渐变范围偏移量,以及 Ctrl+Z / Ctrl+Y 用于时间轴编辑。
录制期间默认禁用飞行惯性。在配置中启用 BossShow -> Enable Recording Flight Inertia 以保留原版惯性。
给模组开发者
两种定义过场动画的方式:
-
仅 JSON —— 将文件放置在 data/<modid>/eca/bossshow/<path>.json。启动时自动加载。旧版 data/<modid>/bossshow/<path>.json 位置仍受支持。如果不需要服务端事件处理,则无需 Java 代码。
-
Java + JSON —— 扩展 BossShow 并使用 @RegisterBossShow 注解,以便在播放期间获得服务端事件回调。
当前 v4 JSON 示例。这个最小示例仅包含 3 帧(刻 0–2,在 20 TPS 下为 0.15 秒),因此其事件、字幕和效果也仅限于此范围。要制作可用的过场动画,请在编辑器中录制更长的摄像机轨迹,并在所需刻放置内容:
{
"format_version": 4,
"target_type": "minecraft:warden",
"trigger": { "type": "range", "effect_radius": 32.0 },
"cinematic": true,
"allow_repeat": false,
"anchor_yaw": 0.0,
"frames": [
{ "dx": 0.0, "dy": 1.8, "dz": -6.0, "yaw": 0.0, "pitch": 10.0 },
{ "dx": 0.0, "dy": 1.8, "dz": -5.8, "yaw": 2.0, "pitch": 10.0 },
{ "dx": 0.0, "dy": 1.8, "dz": -5.6, "yaw": 4.0, "pitch": 10.0 }
],
"events": [
{ "tick": 0, "event_id": "intro" },
{ "tick": 2, "event_id": "finisher" }
],
"subtitles": [
{ "tick": 0, "text": "mymod.bossshow.warden.intro" }
],
"effects": [
{ "tick": 0, "type": "camera_shake", "duration": 2, "fade_out": 1,
"parameters": { "yaw": 1.5, "pitch": 1.0, "roll": 0.5, "frequency": 1.2 } },
{ "tick": 2, "type": "shader_effect", "effect": "chromatic_aberration",
"duration": 1,
"parameters": { "strength": 0.012, "angle": 15.0, "pulse_amount": 0.4, "pulse_speed": 2.0 } }
]
}
format_version:当前输出为 4;位置偏移和相机偏航角使用相同的锚点局部旋转约定。旧版的基于帧的文件在加载时会通过 anchor_yaw 进行转换;不要仅通过更改版本号来迁移它们。
frames:每个对象对应一个游戏刻,按播放顺序排列。数组中帧的索引即为其对应的游戏刻——没有单独的时间字段。由编辑器生成。
frames[].dx/dy/dz:相对于锚点的相机偏移量。
frames[].yaw/pitch:相机朝向(偏航角为锚点局部角度)。
events:独立的事件轨道。每个条目包含 tick 和 event_id;这些条目会在对应的游戏刻传递给 BossShow.onKeyframeEvent()。
subtitles:独立的字幕轨道。每个条目包含 tick 和 text;文本可以是字面字符串或翻译键。
effects:客户端屏幕特效轨道,包含持续时间、淡入淡出、缓动以及特定于效果的参数。类型包括 camera_shake、shader_effect 和 filter。
frames[].keyframe:遗留兼容性字段。新文件应改用 events 和 subtitles。
trigger:{"type":"range","effect_radius":N} 当玩家进入匹配实体的范围时自动触发。{"type":"custom","event_name":"..."} 仅通过 EcaAPI.launchBossShowEvent(...) 触发。
旧的 samples + markers 格式不再被识别——使用它的文件将作为零帧过场动画加载。请重新录制或迁移到 frames 格式。
上述 JSON 中的 event_id 字符串会在对应的游戏刻在服务端分发至 onKeyframeEvent,并且过场动画也可以通过代码中的 EcaAPI.playBossShow(...) / launchBossShowEvent(...) 触发。
如果某个 @RegisterBossShow 类在首次启动时没有匹配的 JSON 文件,系统会自动在 config/eca/bossshow/<namespace>/<path>.json 生成一个空模板 JSON。
对于整合包开发者
自定义阵营
ECA 提供了一个阵营系统,用于控制目标锁定和伤害关系。绑定实体后,原版联盟检查和目标分配机制将尊重同阵营、友方和中立规则,无需额外接口。拥有阵营的实体通过 Mob.setTarget 定期获取周围具有 HOSTILE(敌对)关系的阵营实体;其现有的战斗目标仍会执行移动和攻击行为。未绑定阵营的实体不会被此阵营获取流程选中。标准的 LivingEntity 伤害路径会强制执行友方保护;直接改变状态的 API 调用者需自行负责。FactionUtil.isFriendly 用于解析联盟关系,而 FactionUtil.canAttack 还会额外检查创造模式/旁观者模式及 ECA 无敌保护状态。
EcaAPI.isFriendly(a, b) 是公开的完整友方检测接口。若双方属于同一 ECA 阵营、ECA 友好阵营、原版记分板盟友、主人-宠物组合、拥有相同主人的宠物,或主人互为记分板盟友的宠物,则返回 true。创造模式、旁观者模式和 ECA 无敌保护被有意排除在外,因为它们属于攻击保护而非联盟关系。仅在需要精确判断 ECA 阵营身份时才使用 areSameFaction;canHarm 仅检查 ECA 阵营关系,而 canTarget 除了排斥中立关系外,还完全拒绝目标免疫。
阵营通过继承 FactionDefinition 并标注 @RegisterFaction 注解来注册。定义会在 FMLLoadCompleteEvent 期间扫描;重复的 ID 会被记录日志并跳过(先扫描到的优先)。也可以通过 EcaAPI.createFaction 在运行时创建阵营,可选择是否持久化。EntityExtension 可声明 getFactionId(),使得该类型的每个实体自动加入指定阵营——必须在这些实体生成之前注册该阵营,否则绑定将被拒绝并记录日志。
共有四种关系:
SAME_FACTION(同阵营)—— 相同阵营 ID,彼此完全免疫且永远不会互相锁定为目标
FRIENDLY(友方)—— 不同阵营但结盟,无伤害且无目标锁定
NEUTRAL(中立)—— 不会被刻意锁定为目标,但仍会受到附带伤害
HOSTILE(敌对)—— 正常战斗
SAME_FACTION 是派生值,而非存储值:当双方解析为同一个阵营 ID 时便会生成该值,因此将其作为跨阵营覆盖项存储也不会被读取。因此,将两个阵营真正合并意味着执行合并操作——调用 EcaAPI.mergeFactions(intoId, fromId, level),其中 /eca faction relation A B same_faction 命令会将 A 作为幸存者。B 的成员会被重新绑定到 A,仅在 A 没有自有关系覆盖项时继承 B 的关系覆盖项,指向 B 的第三方条目会被重定向至 A 或被丢弃,随后删除 B。A 保留其自身的显示名称、颜色、默认关系和领袖,仅在 A 没有领袖时才继承 B 的领袖。
关系解析按以下顺序进行,首个匹配项生效:
- 相同的阵营 ID →
SAME_FACTION
- A 的
getRelation(self, target) 条件覆盖项
- A 的静态
hostileTo / friendlyTo / neutralTo 数组
- 对称回退 —— 从 B 的角度评估相同的两项检查
- A 的
getDefaultRelation(self, target) 条件覆盖项(仅当对方没有阵营时)
- A 的静态默认关系
每个阵营拥有自己的成员表。成员以 UUID 及其实体类型记录,因此无需加载任何实体即可列出名册、按类型过滤并计数——即使成员位于未加载区块或其他维度中,依然完全可见且可管理。阵营存储在主世界的 SavedData 中,因此成员资格跨维度全局有效,并在重启后得以保留。
当实体被永久移除时,绑定将被丢弃;区块卸载和维度变更不会移除绑定,玩家在其死亡和重生后仍保留自己的绑定。成员资格无法超越其所属阵营的生命周期——注销一个阵营会同时删除其整个成员表,若尝试加入不存在的阵营则会被拒绝,而非静默记录。
驯服的动物会自动继承其主人的阵营,因此宠物受其主人盟友的保护,并能响应附近阵营警报。继承关系在查找时解析,而非存储:继承的宠物不包含在持久化成员表、离线查询、计数或全表领袖传播中。它随主人跨阵营变更而移动,且从不创建自己的绑定——因此对这类宠物调用 leaveFaction 无效。若需让宠物属于其他阵营或参与成员表操作,请显式绑定宠物;显式绑定始终优先于继承。
一个阵营仅拥有成员资格、关系和领导力。FactionDefinition 不提供实体组成或生成权重 API;这些值属于执行生成的系统,因此不同系统可以使用相同的阵营而不共享生成规则。
领袖: 一个阵营可以指定一名成员作为其领袖。设置领袖会将其自动添加到阵营中(如果它还不是成员)——处于自己阵营之外的领袖状态将是矛盾的。离开阵营也会使职位空缺,永久移除的领袖会自动清除。
威胁传播: 当领袖攻击敌对阵营成员,或被其攻击时,该实体将被提供为阵营成员表中所有可解析生物的目标。现有目标和阵营目标权限可能仍然阻止切换。普通成员警报由受害者自身阵营及友好阵营中的附近生物响应。存在两种机制:
|
触发条件 |
范围 |
| 领袖保护 |
领袖攻击或被攻击 |
整个成员表 |
| 成员警报 |
任何成员受伤 |
受害者周围的可配置半径 |
领袖保护故意不设范围限制:直接遍历成员表,因此远离主人的召唤物仍能响应。无法在领袖所在维度解析的成员将被跳过,且传播绝不会赋予成员其被禁止攻击的目标。同一刻内对相同目标的重复传播将被丢弃,因此快速攻击的领袖不会每次命中都遍历成员表。
这两种机制完全由配置控制——没有每个阵营的覆盖项,因此给定服务器上每个阵营的行为方式相同:
Leader Protection Enabled(默认 true)
Immediate Leader Protection(默认 false)
Alert Enabled(默认 true)/ Alert Range(默认 32)/ Immediate Member Alert(默认 false)
“Immediate”关闭表示只有当前没有目标的成员才会介入;开启则表示它们会放弃正在进行的战斗。
查询: 可以从任一方向检查成员资格,且不解析实体的方法完全离线工作:
| 方向 |
方法 |
| 实体关系 |
areSameFaction(a, b)(仅限 ECA 阵营)、isFriendly(a, b)(完整的 ECA + vanilla 友好检查)、getEffectiveFactionRelation(a, b)、canHarm(a, b)(仅限 ECA 阵营伤害规则)、canTarget(a, b)(中立且免疫感知的目标检查) |
| 成员 → 阵营 |
getEntityFaction(entity)(包括宠物继承)、getEntityFaction(uuid)、isFactionMember(uuid, id) |
| 阵营 → 成员 |
getFactionMemberRecords(id)、getFactionMemberUuids(id)、getFactionMembersByType(id, typeId)、getFactionMemberCount(id) |
| 阵营 → 实体 |
resolveFactionMembers(id, level) |
| 阵营 → 领袖 |
getFactionLeader(id)、getFactionLeaderUuid(id)、resolveFactionLeader(id, server)(搜索所有维度) |
| 领袖 → 阵营 |
getFactionByLeader(uuid)、isFactionLeader(entity) |
joinFaction 和 leaveFaction 均提供 UUID 重载,用于管理其实体未加载的成员。
阵营成员还可以在其关系颜色中发光,以便附近玩家可见,此功能可配置且默认关闭。
自定义突袭
ECA 提供可定制的袭击系统。原版袭击仅在村庄生效,仅接受实现了 Raider 接口的实体,并硬编码了其胜利条件与奖励;而 ECA 袭击可以针对任何结构,使用任意实体类型,并替换所有控制其进程与结束的规则。
袭击通过扩展 RaidDefinition 并使用 @RegisterRaid 注解进行注册。扫描在派系扫描之后运行,因此袭击定义可以自由引用派系 ID。仅需实现 getId()、getDisplayName() 和 getWaves() —— 其他所有内容均具有基于原版袭击建模的默认工作模型。
目标锁定: 重写 getTargetStructure() 以指定单一结构,或使用 getTargetStructureTag() 匹配携带特定标签的任何结构,从而使一次袭击适用于多种结构类型。锚定机制驱动默认的失败条件:当目标结构不再覆盖袭击中心时,袭击即告失败。若未声明锚定,则运行无锚定袭击,此时袭击只能通过胜利、超时或显式调用结束来终止。
波次: 每个 RaidWave 自由混合两种生成源——显式实体条目,以及 addFaction(String factionId, int count, Map<EntityType<?>, Integer> typeWeights)。后者直接从该波次配置其实体类型与权重。不同的波次可以为同一派系使用不同的组成和权重。
袭击者: 使用 addEntry(...) 添加的显式条目绑定到 getRaiderFactionId(),而每个 addFaction(...) 组则绑定到该条目自身的派系 ID。波次首领也使用 getRaiderFactionId()。生成的 Mob 实例会获得一个注入的目标,使其路径指向袭击中心。该目标的优先级默认为 3,与原版的 PathfindToRaidGoal 一致——低于通常的近战攻击目标,因此袭击者会优先攻击已获取的敌对派系目标,否则继续推进。可以生成任何实体类型且无需接口,但非 Mob 实体不会获得派系目标获取、导航目标或生物回调。重写 getRaiderGoalPriority() 或返回负值以更改或禁用目标注入。
首领: 波次可通过 RaidWave.setLeader(type) 声明首领。生成的实体将成为袭击者派系的首领,因此该派系的威胁传播将免费应用于它。符合条件的已加载且无现有目标的生物默认会响应;Immediate Leader Protection(即时首领保护)允许它们取代现有目标。声明首领需要 getRaiderFactionId();若无派系,则无物可领导,该条目将作为普通袭击者生成。
请注意,传播会遍历整个派系成员表,而不仅是本次袭击的参与者。如果袭击者派系在世界其他地方有其他成员,它们也会响应。若希望响应仅限于本次袭击,请使用专属的袭击派系。
验证: 启动袭击时会验证其引用的派系。非空但未注册的袭击者派系会直接拒绝启动,因为无法应用请求的友军伤害和警报规则。故意返回 null 是允许的,这将使每个生成的实体由其自身的人工智能支配。从未注册派系生成或正实体权重为零的波次会记录错误并跳过该组,但袭击仍会启动。
进程推进: shouldAdvanceWave、checkVictity 和 checkDefeat 均可重写。默认值重现了原版语义:上一波死亡后生成下一波,当所有波次均已生成且所有袭击者消失时,防守方获胜。
时间与回调: getMaxDurationTicks() 默认为 48000,getWaveCooldownTicks() 为 300,getParticipantRadius() 为 96 格,getCelebrationTicks() 为 600。波次可以添加自己的 spawnDelay() 和 spawnRadius()。生命周期钩子包括 onStart、onWaveStart、onWaveEnd、onVictory、onDefeat 和 onStop。客户端的 bossBarExtension() 可在保留服务器同步袭击状态的同时替换袭击栏的外观。
无尽袭击: isEndless() 会无限循环波次列表,且不满足默认胜利条件。使用 EcaAPI.endRaid 完成此类袭击,这将丢弃所有幸存的袭击者。
袭击按维度运行,并在重启后自动恢复最新的定期检查点。永久性伤亡和终端操作会立即保存;普通进程每秒检查点一次。中心区块会在袭击期间强制加载,但进入其他未加载区块的袭击者不会随其一起被强制加载。
注册定义并不会启动任何内容。袭击通过 EcaAPI.startRaid(...) / startRaidAt(...) 显式启动,以便任何触发条件都能驱动它们——例如进入区域、使用物品、执行命令或定时事件。
ECA 转换器白名单
尽管我已尽可能多地向 ECA 转换器白名单中添加常见的库和模组,但仍可能有模组因 ECA 转换而崩溃。因此,我为整合包开发者准备了一个 JSON 配置文件,用于将软件包前缀添加到白名单中。你可以在 config/eca/ 文件夹下添加 JSON 文件。如果首次启动时该文件夹为空,示例文件将自动生成。
仅需 type 和 packages 字段,其他字段将被忽略:
单个模组示例(allreturn — 仅跳过 AllReturn,防御性挂钩仍然适用):
{
"type": "allreturn",
"packages": [
"com.example.yourmod."
]
}
多个模组示例(transform — 跳过所有 ECA 转换):
{
"type": "transform",
"packages": [
"com.example.modA.",
"com.example.modB.",
"net.example.modC."
]
}
任何 .json 文件名均可使用,且你可以拥有多个文件。
Due to personal reasons, this mod will stop receiving updates for the next two months. During this period, I will not be responding to any messages.
This mod provides entity manipulation APIs and commands based on CoreMod (ITransformationService), Java Agent, and Mixin technologies, plus a set of feature modules: BossShow, entity extensions, ECA Blender Model, block extensions, item extensions, screen filters, the ECA shader generator, custom factions, and custom raids. Note that while the entity-manipulation methods may share names with vanilla logic, the underlying implementation is completely different. For example, the set health API can modify entities using custom health values (including but not limited to entity data, numeric fields, and hash tables); the remove API performs low-level Minecraft container cleanup; the set invulnerable API provides a more powerful implementation than vanilla creative mode invulnerability. Additionally, this mod unlocks vanilla attribute limits to Double.MAX_VALUE by default. You can disable this in the config file with "Unlock Attribute Limits" option.
The original intent of this mod is to provide developers with simplified entity manipulation APIs while achieving a certain level of strength under the premise of ensuring performance and compatibility. Therefore, please do not use this mod for mod power comparisons or endless code arms races. Additionally, in modpack survival environments, it is best to ensure that the Attack and Defence Radical Logic config options are disabled.
This mod also provides an MCreator plugin for MCreator users to conveniently use the APIs in this mod.
Community Edition (If you want to play on newer Minecraft versions):
Usage for Players
Players can use the following /eca commands (requires permission level ≥ 2):
/eca setHealth <targets> <health> [report] - Set entity health. Add report to write one structured <entity>_health_report_<timestamp>.txt file per living target directly under logs/; the report includes the health-model judgment, channel outcome, delayed verification, complete per-source dataflow inversion trace, and related background analysis.
/eca setMaxHealth <targets> <maxHealth> - Set entity max health (reverse-calculates attribute base value)
/eca setInvulnerable <targets> <true|false> - Set entity invulnerability
/eca lockHealth <targets> true <value> - Lock entity health at specific value
/eca lockHealth <targets> false - Unlock entity health
/eca lockMaxHealth <targets> true <value> - Lock entity max health at specific value
/eca lockMaxHealth <targets> false - Unlock entity max health
/eca banHealing <targets> true [value] - Prevent affected entities' health from exceeding the configured healing ban value (optional; defaults to current health).
/eca banHealing <targets> false - Unban healing for entities
/eca hurt <targets> <amount> - Force entity damage (vanilla hurt first, forced write when the health loss does not land; kill credit goes to the executor when run by a living entity)
/eca kill <targets> - Kill entities
/eca remove <targets> [reason] - Remove entities from world
/eca memoryRemove <targets> - DANGER! Requires Attack Radical Logic config. Remove entities using LWJGL's internal Unsafe instance
/eca teleport <targets> <x> <y> <z> - Teleport entities to the specified coordinates in their current dimension.
/eca lockLocation <targets> <true|false> [x y z] - Lock/unlock entity location
/eca cleanBossBar <targets> - Clean up boss bars
/eca allReturn <targets> <true|false> - DANGER! Requires Attack Radical Logic. Enable or disable AllReturn as requested; players target mods owning items in their four armor slots and two hand slots, while other entities target their own mod. Transform whitelists apply.
/eca allReturn global <true|false> - DANGER! Enable/disable global AllReturn for all non-whitelisted mods
/eca banSpawn <targets> <seconds> - Ban spawning of selected entities' types for specified duration
/eca banSpawn clear - Unban all spawns in current dimension
/eca setForceLoading <targets> <true|false> - Enable/disable force chunk loading for entities
/eca setInvulnerable show_all - Show all invulnerable entities
/eca entityExtension get_registry - Show entity extension registry
/eca entityExtension get_active - Show active entity extension types in current dimension
/eca entityExtension get_current - Show the currently effective entity extension
/eca entityExtension clear - Clear active entity extension table and all global effects in current dimension
/eca entityExtension set_skybox <preset> - Set global skybox shader preset
/eca setFilter <targets> true <type> - Apply a screen filter to players (type: sketch, spotlight, matrix, rain, desert, snow, toxic, cosmos)
/eca setFilter <targets> false - Remove all active filters from players
/eca bossShow edit - Open the in-game cinematic editor (switches to spectator mode)
/eca bossShow exit - Exit the editor and restore the previous game mode
/eca bossShow list - List all loaded cutscenes
/eca bossShow play <viewer> <target> <id> - Force-play a cutscene
/eca bossShow stop <viewer> - Stop the viewer's current cutscene
/eca bossShow reload - Reload all cutscene JSON definitions from disk
/eca bossShow clearHistory <player> - Clear a player's "already seen" records
/eca shaderGenerator - Open the in-game shader preset generator
/eca resurrection start - Start the resurrection daemon thread
/eca resurrection stop - Stop the resurrection daemon thread
/eca resurrection status - Show daemon thread state and revival/check counts
/eca resurrection add <targets> - Add entities to resurrection tracking (auto-revived on death every poll cycle)
/eca resurrection remove <targets> - Remove entities from resurrection tracking
/eca resurrection list - List all tracked entities with container integrity status
/eca resurrection check <target> - One-shot container integrity check for an entity
/eca resurrection revive <target> - Manually force-revive a tracked entity immediately
/eca resurrection interval <ms> - Set poll interval in milliseconds (100–10000; default 25)
/eca faction create <id> <displayName> [color] - Create a faction (color accepts a preset name such as red/gold/teal)
/eca faction remove <id> - Remove a faction definition and drop every entity binding pointing at it
/eca faction join <factionId> [targets] - Bind entities to a faction (defaults to the command source entity)
/eca faction leave [targets] - Unbind entities from their current faction
/eca faction list - List all registered factions
/eca faction info [factionId] - Show a faction's color, members and relation overrides
/eca faction relation <factionA> <factionB> <relation> - Set A's relation toward B. hostile / neutral / friendly store a relation override; same_faction instead merges B into A (B's members are rebound to A, relations are folded in, and B is deleted)
/eca faction leader <factionId> - Show a faction's leader and whether it is currently loaded
/eca faction leader <factionId> set [target] - Set the leader (defaults to the command source entity; joins the faction automatically)
/eca faction leader <factionId> clear - Clear the leader; the former leader remains a member
/eca raid defs - List all registered raid definitions
/eca raid list - List active raids in the current dimension
/eca raid start <definitionId> [pos] - Start a raid at a position inside its target structure (defaults to the command source position)
/eca raid startat <definitionId> <pos> - Start a raid with an explicit center, skipping the structure lookup
/eca raid info <instanceId> - Show details of one running raid
/eca raid end <instanceId> <victory|defeat> - End a raid and clear every surviving raider
Added new command selectors, resolved through ECA's own entity lookup:
@eca_e[...] - all entities
@eca_p[...] - nearest player
@eca_a[...] - all players
@eca_r[...] - random player
@eca_s[...] - command source entity (self)
Usage for Developers
Adding ECA as Dependency
Step 1: Add Modrinth Maven repository (build.gradle)
repositories {
maven { url = "https://api.modrinth.com/maven"; content { includeGroup "maven.modrinth" } }
}
Step 2: Add ECA dependency (build.gradle)
dependencies {
implementation fg.deobf("maven.modrinth:epic-core-api:VERSION")
}
Replace VERSION with the version you need (e.g. 1.1.7-fix-fix). Go to ECA Modrinth page to find available versions.
Step 3: Declare dependency (mods.toml)
[[dependencies.your_mod_id]]
modId="eca"
mandatory=true
versionRange="[1.1.5,)"
ordering="NONE"
side="BOTH"
API Reference
lockHealth(entity, value) - Lock entity health at specific value (for invincibility, heal negation, etc.)
unlockHealth(entity) - Remove health lock
getLockedHealth(entity) - Get current health lock value (null if not locked)
isHealthLocked(entity) - Check if entity health is locked
banHealing(entity, value) - Prevent the affected entity's health from exceeding the configured healing ban value.
unbanHealing(entity) - Unban healing for entity
getHealBanValue(entity) - Get current heal ban value (null if not banned)
isHealingBanned(entity) - Check if entity has healing banned
getHealth(entity) - If ECA's health modification analysis has identified the entity's real health, return that health; otherwise, return the entity's vanilla health data. This read does not initiate analysis or fall back to the entity's getHealth(); a null entity returns 0.0f, and unreadable storage returns NaN.
getRealHealth(entity) - Uses the same read rules as getHealth(entity), but returns NaN for a null entity.
setHealth(entity, health) - Attempt a verified health change through vanilla direct write → dataflow reversal → external scan → method probe → numeric inversion; players use only the vanilla write. Dataflow analysis locates storage and inverts read expressions, including traceable reflection, Unsafe and VarHandle access. New probe evidence can revisit earlier channels. Channels are constrained by evidence, configuration and budgets, with verification after attempts and snapshots/rollback for probing writes. Immediate verification does not guarantee that entity logic will preserve the value on later ticks; delayed verification checks this separately. Basic dataflow reversal is available by default unless Force Compatibility Mode is enabled. Const Override, External Scan, Method Probe and Numeric Inversion require Attack Radical Logic and their respective switches under Attack → setHealth, which default to off.
setMaxHealth(entity, maxHealth) - Set max health by reverse-calculating attribute base value from current modifiers
lockMaxHealth(entity, value) - Lock entity max health at specific value (enforced every tick)
unlockMaxHealth(entity) - Unlock entity max health
getLockedMaxHealth(entity) - Get current max health lock value (null if not locked)
isMaxHealthLocked(entity) - Check if entity max health is locked
addHealthWhitelistKeyword(keyword) - Add keyword to health modification whitelist
removeHealthWhitelistKeyword(keyword) - Remove keyword from health modification whitelist
getHealthWhitelistKeywords() - Get all health whitelist keywords
addHealthBlacklistKeyword(keyword) - Add keyword to health modification blacklist
removeHealthBlacklistKeyword(keyword) - Remove keyword from health modification blacklist
getHealthBlacklistKeywords() - Get all health blacklist keywords
hurt(entity, damageSource, amount) - Damage an entity and guarantee the health loss lands. Vanilla hurt writes health only once, inside actuallyHurt, as setHealth(getHealth() - damage) — through the entity's own getter and setter, so an overridden or storage-decoupled entity runs the whole pipeline and fires all events while losing no health. This method clears the invulnerability cooldown and calls vanilla hurt first (mitigation, knockback, aggro and hurt animation all happen normally), then compares the health anchor against before - amount within min(1.0, amount * 50%). On mismatch it restores the damage-source bookkeeping vanilla would have left (lastHurtByMob, lastHurtByPlayer/Time, lastDamageSource/Stamp, combat tracker, hurt animation) and forces the health through setHealth, clamped at zero. A lethal result is never forced into the death path here: the entity is left at zero health so vanilla tickDeath plays the death animation and removes it — use kill when an immediate kill is wanted. Entities under ECA's own health lock or invulnerability are left to those systems — vanilla hurt still runs, but no forced write is attempted.
hurt(entity, attacker, amount) - Same pipeline with the damage source derived from the attacker: playerAttack for players, mobAttack for every other living entity, so kill credit and loot attribution behave as expected
kill(entity, damageSource) - Kill entity (loot + advancements + removal)
revive(entity) - Clear death state and restore health
revive(level, uuid) - Clear death state and restore health by UUID in specified level
reviveAllContainers(entity) - Revive all critical entity containers (tickList, lookup, sections, tracker)
reviveAllContainers(level, uuid) - Revive all critical entity containers by UUID in specified level
teleport(entity, x, y, z) - Force teleport an entity to the specified coordinates in its current dimension and synchronize clients. Must run on the server's main thread.
lockLocation(entity) - Lock entity location at current position
lockLocation(entity, position) - Lock entity location at specified position
unlockLocation(entity) - Unlock entity location
isLocationLocked(entity) - Check if entity location is locked
getLockedLocation(entity) - Get locked position (null if not locked)
remove(entity, reason) - Complete removal (AI, boss bars, containers, passengers)
memoryRemove(entity, reason) - DANGER! Requires Attack Radical Logic config. Remove entity using LWJGL's internal Unsafe instance
cleanupBossBar(entity) - Remove boss bars without removing entity
isInvulnerable(entity) - Check if entity is invulnerable (ECA internal invulnerability logic)
setInvulnerable(entity, invulnerable) - Set invulnerability (enable: revive + lock health + block damage + remove harmful effects per tick + prevent mob targeting + protect player inventory; disable: clear all protections)
enableAllReturn(entity) - DANGER! Requires Attack Radical Logic. Enables AllReturn for the entity's mod; for players, targets the mods owning their armor and main-hand/off-hand equipment. Only eligible boolean and void methods are transformed, subject to transform whitelists.
disableAllReturn(entity) - Disable AllReturn using the same target rules as enabling: armor and main-hand/off-hand equipment mods for players, or the entity's own mod for other entities.
setGlobalAllReturn(enable) - DANGER! Requires Attack Radical Logic config. Enable/disable global AllReturn for all non-whitelisted mods
disableAllReturn() - Disable AllReturn and clear targets
isAllReturnEnabled() - Check if AllReturn is enabled
addAllReturnWhitelist(prefix) - Add package prefix to AllReturn whitelist (skip AllReturn, defensive hooks still apply)
removeAllReturnWhitelist(prefix) - Remove package prefix from AllReturn whitelist (built-in entries cannot be removed)
addTransformWhitelist(prefix) - Add package prefix to transform whitelist (skip ALL ECA transformations including defensive hooks)
removeTransformWhitelist(prefix) - Remove package prefix from transform whitelist (built-in entries cannot be removed)
isAllReturnWhitelisted(className) - Check if a class is protected from AllReturn
isTransformWhitelisted(className) - Check if a class is protected from all ECA transformations
getAllWhitelistedPackages() - Get all whitelist prefixes (both levels, built-in + custom)
getEntityExtensionRegistry() - Get all registered entity extensions (Map<EntityType, EntityExtension>)
getActiveEntityExtensionTypes(level) - Get active entity extension types in current dimension (Map<EntityType, Integer>)
getActiveEntityExtension(level) - Get the currently effective entity extension (highest priority)
clearActiveEntityExtensionTable(level) - Clear active entity extension table in current dimension
playAnimation(entity, animation) - Manually take control and start a named model action at speed 1 without looping (logical server thread)
playAnimation(entity, animation, speed, loop) - Manually start/restart a named model action with speed and looping (logical server thread)
stopAnimation(entity) - Stop managed playback, cancel an active skill if present, and release control to the controller/fallback
pauseAnimation(entity) - Pause managed action/skill timing, without freezing lifecycle decisions
resumeAnimation(entity) - Resume managed action/skill timing from its preserved position
isAnimationPlaying(entity[, animation]) - Query managed playback including paused/held poses, optionally matching the action name
triggerBlenderSkill(entity, skillId) - Start a configured skill through its interruption policy
cancelBlenderSkill(entity) - Cancel the active skill without a completion callback
isBlenderSkillActive(entity) - Query active skill execution, including pauses
getBlenderSkillExecution(entity) - Get the current execution snapshot, or null
setGlobalFog(level, fogData) - Set global fog effect override for a dimension (does not change effect priority)
clearGlobalFog(level) - Clear global fog effect override
setGlobalSkybox(level, skyboxData) - Set global skybox effect override for a dimension (does not change effect priority)
clearGlobalSkybox(level) - Clear global skybox effect override
setGlobalMusic(level, musicData) - Set global combat music effect override for a dimension (does not change effect priority)
clearGlobalMusic(level) - Clear global combat music effect override
clearAllGlobalEffects(level) - Clear all global effect overrides (fog, skybox, music) for a dimension
enableFilter(player, filterType) - Apply a screen filter to a player (FilterType: SKETCH, SPOTLIGHT, MATRIX, RAIN, DESERT, SNOW, TOXIC, COSMOS)
disableFilter(player, filterType) - Remove a screen filter from a player
isFilterEnabled(player, filterType) - Check whether a filter is active on a player
getActiveFilters(player) - Get a player's active filters (unmodifiable Set<FilterType>)
playBossShow(viewer, target, cutsceneId) - Force-play a BossShow cutscene for a viewer (ignores watch history)
playBossShowIfNew(viewer, target, cutsceneId) - Play a BossShow cutscene only if the viewer hasn't seen it before
stopBossShow(viewer) - Stop the viewer's current BossShow cutscene
isBossShowPlaying(viewer) - Check whether the viewer is currently in a BossShow cutscene
launchBossShowEvent(eventName, viewer, target) - Trigger all Custom-trigger BossShows matching the event name (returns count launched)
banSpawn(level, entityType, seconds) - Ban entity type from spawning for specified duration
isSpawnBanned(level, entityType) - Check if entity type is banned from spawning
getSpawnBanTime(level, entityType) - Get remaining spawn ban time in seconds
unbanSpawn(level, entityType) - Unban entity type, allowing it to spawn again
getAllSpawnBans(level) - Get all spawn bans in level (Map<EntityType, Integer>)
unbanAllSpawns(level) - Unban all entity types in level
setForceLoading(entity, level, forceLoad) - Enable/disable force chunk loading for entity
isForceLoaded(entity) - Check if entity is force loaded (via EntityExtension or API)
getEntity(level, entityId) - Resolve entity by runtime id in specified level (ECA selector path)
getEntity(level, uuid) - Resolve entity by UUID in specified level (ECA selector path)
getEntity(level, entityId, entityClass) - Resolve typed entity by id
getEntity(level, uuid, entityClass) - Resolve typed entity by UUID
getEntity(server, entityId) - Resolve entity by id across all levels
getEntity(server, uuid) - Resolve entity by UUID across all levels
getEntities(level) - Get all entities in level
getEntities(level, area) - Get entities in AABB area
getEntities(level, filter) - Get entities using custom predicate
getEntities(level, area, filter) - Get entities in area using custom predicate
getEntities(level, entityClass) - Get all entities of specified type in level
getEntities(level, area, entityClass) - Get entities of specified type in area
getEntities(server) - Get all entities across all server levels
getEntities(server, filter) - Get entities across all levels using custom predicate
getNearestEntity(level, pos, filter) - Get the nearest entity matching a predicate (ECA resolver, so invulnerable entities are included)
getNearestEntity(level, pos, area, filter) - Same, narrowed to an AABB
getNearestEntity(level, pos, entityClass) - Get the nearest entity of a given type
getNearestEntity(level, pos, area, entityClass) - Get the nearest entity of a given type inside an AABB
shaderPreset(id) - Get a shader preset by id, exposing its ready-made render targets
startResurrection() - Start the resurrection daemon thread (idempotent)
stopResurrection() - Stop the resurrection daemon thread
isResurrectionRunning() - Check whether the daemon is running
addResurrectionTarget(entity) - Add an entity to the resurrection tracking set
removeResurrectionTarget(entity) - Remove an entity from the resurrection tracking set
isResurrectionTracked(entity) - Check whether an entity is tracked for resurrection
getResurrectionTrackedCount() - Get the number of currently tracked entities
clearAllResurrectionTargets() - Remove all entities from the tracking set
setResurrectionPollInterval(ms) - Set the daemon poll interval (ms, clamped 1–10000, default 25)
getResurrectionPollInterval() - Get the current poll interval in ms
getResurrectionTotalRevived() - Get the total number of entities revived since start
getResurrectionTotalChecks() - Get the total number of entity checks performed since start
checkResurrectionTarget(level, entity) - Perform a one-shot container integrity check
reviveResurrectionTarget(level, entity) - Manually force-revive a tracked entity immediately
createFaction(id, displayName, color) - Create and register a faction (memory only)
createFaction(id, displayName, color, level) - Create and register a faction, persisted to world SavedData
removeFaction(id) - Remove a faction definition (memory only)
removeFaction(id, level) - Remove a faction definition and drop every entity binding pointing at it
mergeFactions(intoId, fromId, level) - Merge one faction into another: members are rebound, relation overrides are folded in, and the dissolved faction is removed. Returns the number of members moved, or -1 if the merge could not run
getFaction(id) - Get a faction definition by id
getAllFactions() - Get all registered factions
joinFaction(entity, factionId) - Bind an entity to a faction
leaveFaction(entity) - Unbind an entity from its faction
getEntityFaction(entity) - Get the faction id an entity belongs to (null if none; tamed animals fall back to their owner's faction)
areSameFaction(a, b) - Check whether two entities share a faction
isFriendly(a, b) - Check the complete friendly relationship: same/friendly ECA faction, vanilla scoreboard alliance, or owner-pet alliance (excludes creative, spectator and ECA invulnerability)
getFactionMembers(level, factionId) - Resolve the faction's member table to live entities in one level
kickAllFromFaction(factionId, level) - Remove every explicit member globally, including unloaded and cross-dimension members
setFactionRelation(a, b, relation) - Set faction A's relation toward faction B (memory only)
setFactionRelation(a, b, relation, level) - Set faction A's relation toward B, persisted
getFactionRelation(a, b) - Get the explicit relation from A to B (null if no override)
getEffectiveFactionRelation(source, target) - Resolve the effective relation between two entities
canHarm(source, target) - Check whether ECA faction relations allow source to harm the target
canTarget(source, target) - Check whether complete faction and protection rules allow source to deliberately target the target
alertFactionMembers(factionId, attacker, victim, level) - Make nearby untargeted allies retaliate against an attacker
joinFaction(uuid, typeId, isPlayer, factionId, level) - Bind an entity to a faction by UUID, without requiring it to be loaded
leaveFaction(uuid, level) - Remove a member from its faction by UUID, without requiring it to be loaded
getEntityFaction(uuid) - Get the faction bound to a UUID (pure index lookup; no pet inheritance, which needs a live entity)
isFactionMember(uuid, factionId) - Check whether a UUID belongs to a specific faction
getFactionMemberRecords(factionId) - Get every member record (UUID + entity type) without loading entities
getFactionMemberUuids(factionId) - Get every member UUID without loading entities
getFactionMembersByType(factionId, typeId) - Filter members by entity type without loading entities
getFactionMemberCount(factionId) - Get a faction's member count without loading entities
resolveFactionMembers(factionId, level) - Resolve a faction's members to live entities in one level
setFactionLeader(factionId, leader, level) - Set a faction's leader (joins the faction automatically if needed)
clearFactionLeader(factionId, level) - Clear the leader; the former leader remains a member
getFactionLeader(factionId) - Get the leader record without loading the entity
getFactionLeaderUuid(factionId) - Get the leader's UUID
resolveFactionLeader(factionId, server) - Resolve the leader to a live entity, searching every dimension
isFactionLeader(entity) - Check whether an entity leads any faction
getFactionByLeader(uuid) - Find which faction an entity leads
startRaid(level, pos, raidId) - Start a raid at a position inside its target structure (center taken from the structure)
startRaidAt(level, center, raidId) - Start a raid with an explicit center, skipping the structure lookup
endRaid(level, raid, victory) - End a raid, discarding every surviving raider
endRaid(level, raidId, victory) - End a raid by its instance id, discarding every surviving raider
getRaid(level, raidId) - Get an active raid by its instance id
getActiveRaids(level) - Get every active raid in a level
getNearestRaid(level, pos, maxDistance) - Find the nearest active raid within a distance
getAllRaidDefinitions() - Get all registered raid definitions
Entity Extensions
This mod also provides a customizable entity type extension feature for adding special visual effects to your entities. You need to create a subclass extending EntityExtension and annotate it with @RegisterEntityExtension to register the extension.
Entity extensions can opt into a custom boss bar through enableBossBar(), control visibility with shouldShowBossBar(LivingEntity), and provide the client-side appearance through bossBarExtension(). BossBarExtension.showValueText() enables centered current/max text; override getDisplayCurrentValue(LivingEntity) and getDisplayMaxValue(LivingEntity) to provide custom display values. The default value sources are the entity's health and maximum health.
Entity, item, and block shader overlays share the same ShaderMaskPass pipeline. Every pass supplies a RenderType, an optional UV-aligned mask texture, a target RGB color (black by default), a near-color tolerance, and opacity. An extension may return multiple passes so different colors in one mask use different shaders. Passes render in list order, and later passes draw over earlier passes where selected regions overlap. Transparent and non-matching mask pixels are discarded.
ECA Blender Model
ECA Blender Model lets you use native .blend files or exported GLB files for entity models and animations. Models can replace an entity's original appearance or render alongside it.
You can configure idle, movement, hurt and death animations, trigger named skills, and use animation callbacks for timed effects or hit logic. Controllers can be customized by overriding their methods. Supported geometry and material nodes can also animate independently of character actions, making them useful for effects such as rotating rings.
Native .blend support is experimental and targets Blender 5.2.1. See the README for setup examples, playback APIs and supported nodes.
Block Extensions
Block extensions add shader overlays without replacing the normal model. Ordinary baked and falling blocks use BLOCK-profile passes from getBlockShaderPasses(); GeckoLib block entities use NEW_ENTITY-profile passes from getGeoShaderPasses(texture). A logical preset id still supplies the default RenderTypes for both profiles.
External masks on baked blocks are sampled with sprite-local UVs even though the model uses an atlas. Geo masks use the model texture's normal UV layout and combine with overlayGeoBones() as an intersection. Normal world blocks are indexed by section and batched into a separate overlay pass; falling blocks and GeckoLib block entities are handled automatically. Block items remain part of ItemExtension. The old Color-Key and single-mask getters are deprecated compatibility adapters.
Item Extensions
You can create item extensions to add shader rendering effects to specific items: create a subclass extending ItemExtension and annotate it with @RegisterItemExtension to register.
Structured tooltip lines can choose their own insertion position:
EcaTooltipLine.head(...): below the item name.
EcaTooltipLine.body(...): in the main tooltip body, before advanced item id/NBT/disabled lines when present.
EcaTooltipLine.tail(...): at the end of the tooltip.
Each line accepts either a normal Component or an EcaText built through ItemUtil.of(...), so tooltip text supports the same rich effects as item names: gradient, rainbow, solid color, shimmer, glitch, bold, italic, underline, and strikethrough. The older appendTooltip(ItemStack, TooltipFlag, List<Component>) hook is still available when you need to directly edit the final tooltip list.
Item mask passes use sprite-local UVs automatically. ShaderMaskPass.masked(...) samples an external mask texture, while ShaderMaskPass.baseTexture(...) selects colors directly from the item texture. The old getRenderType(), Color-Key, and single-mask getters are deprecated compatibility adapters.
Note: Like entity extensions, each item can only have one extension. Duplicate registrations are rejected with an error log. Both entity layer extensions (EntityLayerExtension.getAlpha(), default 0.5) and item extensions (ItemExtension.getAlpha(), default 1.0) support adjustable transparency for their shader overlay layers.
Shader Presets
Packaged ECA-specific files use the common assets/<namespace>/eca/<system>/ layout. Server-side definitions use the matching data/<namespace>/eca/<system>/ layout, while standard Minecraft resources such as textures and language files remain in their vanilla directories. Legacy locations documented by earlier ECA versions continue to load as fallbacks.
This mod also provides several shader presets for the entity extension and item extension systems, which can be used directly in your extensions. Simply use the corresponding preset class in place of your own RenderType holder. Each built-in preset class exposes 4 ready RenderTypes — BOSS_BAR, BOSS_LAYER, SKYBOX for entity extensions and ITEM for item extensions — plus createEntityEffect(texture) for entity texture overlays. Entity texture overlays are supported through EntityLayerExtension.getTexture() — return a texture to overlay it on the entity model, optionally combined with the shader RenderType for a texture‑plus‑shader effect (matching the boss‑bar overlay technique).
Available presets:
TheLastEndRenderTypes — The Last End
DreamSakuraRenderTypes — Dream Sakura
ForestRenderTypes — Forest
OceanRenderTypes — Ocean
StormRenderTypes — Storm
VolcanoRenderTypes — Volcano
ArcaneRenderTypes — Arcane
AuroraRenderTypes — Aurora
HackerRenderTypes — Hacker
StarlightRenderTypes — Starlight
CosmosRenderTypes — Cosmos
BlackHoleRenderTypes — Black Hole
Screen Filters
This mod provides a set of full-screen post-processing filter presets that the server can apply per player, either by command or through the API. A filter is synced to the client and rendered as a shader pass over the level. Each player can have only one filter active at a time — applying a new one replaces the current one.
Filter presets:
SKETCH — sketch
SPOTLIGHT — spotlight
MATRIX — matrix
RAIN — rain
DESERT — desert
SNOW — snow
TOXIC — toxic
COSMOS — cosmos
Shader Generator
ECA provides an in-game shader preset generator for building portable Minecraft core shader presets without writing GLSL by hand. Open it with:
/eca shaderGenerator
The generator edits a layered composition project. Each layer can contain multiple visual modules, including basic shapes, starry sky effects, magic symbols, and image elements. The editor supports live preview, undo/redo, layer visibility, layer ordering, blend modes, canvas editing, project save/load, five-file shader export, and project deletion (File -> Delete Current Project, which asks for confirmation and then permanently removes the project directory with its source, textures and imported dependencies).
Each project also owns a five-file source workspace. Use File -> Source Editor to switch the same project to manual GLSL/JSON editing with a single-row menu, comment-based quick navigation, undo/redo, save, compile shortcuts, and debounced live preview. The right side places the preview above a scrollable compiler-output panel. Generated fragment shaders emit // @eca-nav layer: ... and // @eca-nav element: ... markers; manually written // @eca-nav ... comments create custom navigation points. Returning to the visual editor does not discard either representation. File -> Import Shader Folder opens the native folder picker at Forge's canonical game directory and copies a selected JSON/VSH/FSH shader into a new local ECA project. A folder may contain multiple shader programs, in which case the editor asks which one to import. When a source path is below assets/<modid>/, the project dialog pre-fills that Mod ID; otherwise the field remains empty. Standard three-file shaders are duplicated into the BLOCK and NEW_ENTITY source slots for independent compile validation; folders containing ECA's shared-fragment _block/_entity five-file layout preserve both profiles directly. The source folder is never modified.
Import supports standard Minecraft core shader JSON/VSH/FSH resources. Common time, camera, scale, opacity, and cosmic-UV uniforms receive preview bindings. A shader that depends on a mod-specific render pipeline, Java callbacks, textures, or uniforms may still need a dedicated adapter; unsupported fragment structure is reported as a compile error instead of being silently rewritten.
Texture dependencies are resolved as well. When an imported shader references a numbered sequence of PNG files, ECA attempts to copy those files, combine them into one preview texture, and provide the matching sampler and uniform with the UV range of each image. A PNG with a .mcmeta animation section updates frame by frame inside that combined texture while preserving frame order, per-frame duration, and interpolation. If ECA cannot determine how the files correspond to a sampler or uniform, the compiler-output panel names the unresolved dependency and scanned directory instead of failing silently; the shader compilation itself can still succeed.
Preview targets currently include plane, item, entity, skybox, and Boss bar. The exported preset uses the standard core shader five-file layout:
assets/<namespace>/eca/shader_presets/<name>.fsh
assets/<namespace>/eca/shader_presets/<name>_block.vsh
assets/<namespace>/eca/shader_presets/<name>_block.json
assets/<namespace>/eca/shader_presets/<name>_entity.vsh
assets/<namespace>/eca/shader_presets/<name>_entity.json
The fragment shader is shared by both profiles. The two vertex profiles are generated separately because Minecraft uses different vertex formats for different render targets:
<name>_block.* uses DefaultVertexFormat.BLOCK, for skybox, plane preview, and Boss bar rendering.
<name>_entity.* uses DefaultVertexFormat.NEW_ENTITY, for entity layers, item layers, and textured entity effects.
Export modes:
PORTABLE: standard Minecraft core shader output with no ECA-specific uniforms.
PORTABLE_WITH_ECA_HINTS: includes ECA uniform hooks with harmless defaults, while remaining usable without ECA.
ECA_ENHANCED: includes ECA-specific uniforms and expects ECA's enhanced shader runtime.
Project files are saved under config/eca/shadergenerator/<namespace>/<name>/project.json. Use File -> Export As <shader> to export a runtime-loadable five-file preset into config/eca/shadergenerator/<namespace>/<name>/. ECA automatically discovers presets from both mod assets and exported config presets. A preset ID is always <namespace>:<name>.
For mod-packaged presets, place the five files under src/main/resources/assets/<namespace>/eca/shader_presets/. The legacy assets/<namespace>/shaders/core/ location remains supported, but the canonical ECA path takes precedence when both define the same ID. You may also declare the preset with @RegisterShaderPreset. The annotation registers the preset ID during startup scanning and is useful for mods that want to expose custom presets through an explicit Java marker class.
At runtime, obtain the generated RenderTypes through EcaPresets, or query the preset object through EcaAPI.shaderPreset(id). The returned ShaderPreset exposes bossBar(), bossLayer(), skybox(), item(), block(), geoBlock(texture) and entityForPreview(texture); EcaPresets mirrors the first six as static lookups by preset id. block() and geoBlock(texture) are the BLOCK and NEW_ENTITY profiles used by block extensions. For entity texture overlays, use EntityLayerExtension.getTexture() with bossLayer().
AI Assistant
The source editor also has an AI assistant that drives the same project through a model of your choice. Three API formats are supported — OpenAI Responses, OpenAI Chat compatible, and Anthropic Messages — each stored as a profile with its own base URL, model, API key or key environment variable, custom headers, and a 10–600 second timeout in config/eca/shadergenerator/settings.json.
The model acts through tools, not free text: read the project summary and module schemas, edit layers and elements, import PNG images, modify any of the five source files, save the project, export the five shader files, compile and read diagnostics, capture the preview, and undo or redo its own mutations. Three switches bound how far it acts alone — allow automatic edits, compile after every edit, send preview images to vision models. With automatic editing off it can still inspect and explain but every write is refused; with automatic compiling on it recompiles after each edit and repairs from the diagnostics, capped by an automatic-repair limit and an overall tool-round limit.
MCP
The MCP button on the AI assistant page starts a local ECA Shader MCP that lets an external agent drive the current shader project. The service speaks Streamable HTTP, binds only to 127.0.0.1, and needs no access token; the MCP page shows the port and connected agents, and the port is stored in config/eca/shadergenerator/mcp_settings.json. The URL port must match the MCP page, and both Minecraft and the MCP service must stay running.
Order of operations: start the service in-game first via Shader Generator → AI Assistant → MCP, then launch and connect the agent. An agent cannot connect while the service is not running.
Codex
Register from the command line:
codex mcp add eca_shader --url http://localhost:8767/mcp
Claude Code
Register from the command line:
claude mcp add --transport http eca_shader http://127.0.0.1:8767/mcp
BossShow Cinematics
BossShow plays a cutscene that locks the player's camera onto a pre-recorded path around a target entity, with subtitles and server-side event callbacks. Camera paths are recorded with the built-in in-game editor — you don't need to write keyframes by hand.
Default Editor Keybindings:
| Key |
Action |
J |
Start / resume recording |
I |
Pause recording |
ENTER |
Save recording |
ESC |
Discard recording |
Editor Workflow:
- Run
/eca bossShow edit near at least one LivingEntity (within 64 blocks).
- In the Home GUI, click + New cutscene from entity → aim at an entity → right-click to select it as the camera anchor. Or click Edit on an existing cutscene.
- Configure trigger type (Range / Custom), target entity type, cinematic bars, allow repeat, etc.
- Click ● Record, press
J to start. Move the camera freely in spectator mode — each tick is captured as an editable frame.
- After recording, click any tick on the timeline to edit its position and camera orientation. Use Preview to play the timeline. To resample a pose from the game view, click Free camera write, move the camera, then press Enter to write the current tick.
- Press
ENTER to save, ESC to discard. Saved files go to config/eca/bossshow/<namespace>/<path>.json.
Timeline editing (after recording, in the editor GUI): every frame is selectable. Click or drag the bar to scrub, use the arrow keys for single-tick navigation, and edit dx/dy/dz/yaw/pitch in the inspector. Use Add content to attach an event or subtitle to the current tick. Set In / Set Out, Copy / Cut / Delete, Paste, uniform/ramp range offsets, and Ctrl+Z / Ctrl+Y are available for timeline editing.
Flight inertia is disabled during recording by default. Enable BossShow -> Enable Recording Flight Inertia in the configuration to preserve vanilla inertia.
For Mod Developers
Two ways to define a cutscene:
-
JSON only — place a file at data/<modid>/eca/bossshow/<path>.json. Loaded automatically on startup. The legacy data/<modid>/bossshow/<path>.json location remains supported. No Java code is needed if you don't need server-side event handling.
-
Java + JSON — extend BossShow and annotate with @RegisterBossShow to get server-side event callbacks during playback.
Current v4 JSON example. This minimal example contains only 3 frames (ticks 0–2, 0.15 seconds at 20 TPS), so its events, subtitles and effects also stay within that range. For a usable cutscene, record a longer camera track in the editor and place content at the desired ticks:
{
"format_version": 4,
"target_type": "minecraft:warden",
"trigger": { "type": "range", "effect_radius": 32.0 },
"cinematic": true,
"allow_repeat": false,
"anchor_yaw": 0.0,
"frames": [
{ "dx": 0.0, "dy": 1.8, "dz": -6.0, "yaw": 0.0, "pitch": 10.0 },
{ "dx": 0.0, "dy": 1.8, "dz": -5.8, "yaw": 2.0, "pitch": 10.0 },
{ "dx": 0.0, "dy": 1.8, "dz": -5.6, "yaw": 4.0, "pitch": 10.0 }
],
"events": [
{ "tick": 0, "event_id": "intro" },
{ "tick": 2, "event_id": "finisher" }
],
"subtitles": [
{ "tick": 0, "text": "mymod.bossshow.warden.intro" }
],
"effects": [
{ "tick": 0, "type": "camera_shake", "duration": 2, "fade_out": 1,
"parameters": { "yaw": 1.5, "pitch": 1.0, "roll": 0.5, "frequency": 1.2 } },
{ "tick": 2, "type": "shader_effect", "effect": "chromatic_aberration",
"duration": 1,
"parameters": { "strength": 0.012, "angle": 15.0, "pulse_amount": 0.4, "pulse_speed": 2.0 } }
]
}
format_version: current output is 4; position offsets and camera yaw use the same anchor-local rotation convention. Older frame-based files are converted on load using anchor_yaw; do not migrate them by changing only the version number.
frames: one object per tick, in playback order. A frame's index in the array is its tick — there is no separate time field. Generated by the editor.
frames[].dx/dy/dz: camera offset in anchor-local coordinates.
frames[].yaw/pitch: camera orientation (yaw is anchor-local).
events: independent event track. Each entry contains a tick and event_id; entries are delivered to BossShow.onKeyframeEvent() at that tick.
subtitles: independent subtitle track. Each entry contains a tick and text; text may be literal or a translation key.
effects: client-side screen-effect track with duration, fade, easing, and effect-specific parameters. Types are camera_shake, shader_effect, and filter.
frames[].keyframe: legacy compatibility field. New files should use events and subtitles instead.
trigger: {"type":"range","effect_radius":N} auto-triggers when a player enters range of a matching entity. {"type":"custom","event_name":"..."} only fires via EcaAPI.launchBossShowEvent(...).
The old samples + markers format is no longer recognized — files using it load as zero-frame cutscenes. Re-record or migrate to frames.
The event_id strings in the JSON above are dispatched to onKeyframeEvent on the server at the corresponding tick, and cutscenes can also be triggered from code through EcaAPI.playBossShow(...) / launchBossShowEvent(...).
If a @RegisterBossShow class has no matching JSON on first launch, an empty template JSON is auto-generated at config/eca/bossshow/<namespace>/<path>.json.
For Modpack Developers
Custom Factions
ECA provides a faction system that controls targeting and damage relationships. Binding an entity makes vanilla alliance checks and target assignment respect same-faction, friendly and neutral rules without requiring an interface. Faction-bound mobs periodically acquire nearby faction-bound entities with a HOSTILE relation through Mob.setTarget; their existing combat goals still perform movement and attacks. Entities without a faction are never selected by this faction acquisition pass. Standard LivingEntity damage paths enforce friendly protection; direct state-changing APIs remain the caller's responsibility. FactionUtil.isFriendly resolves alliances, while FactionUtil.canAttack additionally enforces creative/spectator and ECA invulnerability protection.
EcaAPI.isFriendly(a, b) is the public complete friendly check. It returns true for the same ECA faction, friendly ECA factions, vanilla scoreboard allies, owner-pet pairs, pets with the same owner, and pets whose owners are scoreboard allies. Creative mode, spectator mode and ECA invulnerability are deliberately excluded because they are attack protections rather than alliance relationships. Use areSameFaction only when exact ECA faction identity matters; canHarm checks ECA faction relations only, while canTarget also rejects neutral relations and complete target immunity.
Factions are registered by extending FactionDefinition and annotating the class with @RegisterFaction. Definitions are scanned during FMLLoadCompleteEvent; duplicate ids are logged and skipped (first one scanned wins). Factions can also be created at runtime through EcaAPI.createFaction, with or without persistence. An EntityExtension may declare getFactionId() so that every entity of that type joins a faction automatically — the faction has to be registered before those entities spawn, otherwise the binding is refused and logged.
Four relations are available:
SAME_FACTION — same faction id, fully immune to each other and never targeted
FRIENDLY — different factions but allied, no damage and no targeting
NEUTRAL — not deliberately targeted, but incidental damage still applies
HOSTILE — normal combat
SAME_FACTION is derived, not stored: it is produced whenever both sides resolve to the same faction id, so storing it as a cross-faction override would never be read back. Making two factions genuinely one therefore means merging them — EcaAPI.mergeFactions(intoId, fromId, level), which /eca faction relation A B same_faction calls with A as the survivor. Members of B are rebound to A, B's relation overrides are inherited only where A has none of its own, third-party entries pointing at B are retargeted to A or dropped, and B is then deleted. A keeps its own display name, color, default relation and leader, inheriting B's leader only when it has none.
Relation resolution runs in this order, and the first match wins:
- Same faction id →
SAME_FACTION
- A's
getRelation(self, target) conditional override
- A's static
hostileTo / friendlyTo / neutralTo arrays
- Symmetric fallback — the same two checks evaluated from B's side
- A's
getDefaultRelation(self, target) conditional override (only when the other side has no faction)
- A's static default relation
Each faction owns its member table. A member is recorded as a UUID plus its entity type, so a roster can be listed, filtered by type and counted without loading a single entity — members sitting in unloaded chunks or other dimensions are still fully visible and manageable. Factions live in the overworld's SavedData, so membership is global across dimensions and survives restarts.
A binding is dropped when the entity is permanently removed; chunk unloads and dimension changes keep it, and players keep theirs across death and respawn. Membership cannot outlive its faction — unregistering a faction drops its whole member table, and joining a faction that does not exist is refused rather than silently recorded.
Tamed animals inherit their owner's faction automatically, so a pet is protected by its owner's allies and can answer nearby faction alerts. Inheritance is resolved at lookup time rather than stored: an inherited pet is not included in the persistent member table, offline queries, counts or table-wide leader propagation. It follows its owner across faction changes and never creates a binding of its own — calling leaveFaction on such a pet therefore does nothing. Bind a pet explicitly if it must belong elsewhere or participate in member-table operations; an explicit binding always takes precedence over inheritance.
A faction only owns membership, relations and leadership. FactionDefinition does not provide entity composition or spawn-weight APIs; those values belong to the system that performs the spawning, so different systems can use the same faction without sharing spawn rules.
Leaders: A faction may designate one member as its leader. Setting a leader adds it to the faction automatically if it was not a member — a leader outside its own faction would be a contradictory state. Leaving the faction also vacates the post, and a leader that is permanently removed is cleared automatically.
Threat propagation: When a leader attacks a hostile faction member, or is attacked by one, that entity is offered as the target of every resolvable mob in the faction member table. Existing targets and faction target permissions may still prevent a switch. Ordinary member alerts are answered by nearby mobs from both the victim's own faction and friendly factions. Two mechanisms coexist:
|
Trigger |
Range |
| Leader protection |
the leader attacks or is attacked |
the entire member table |
| Member alert |
any member is hurt |
configurable radius around the victim |
Leader protection is deliberately not range-limited: the member table is walked directly, so summons far from their master still answer. Members that cannot be resolved in the leader's dimension are skipped, and propagation never hands a member a target it is forbidden to attack. Repeat propagation of the same target within one tick is dropped, so a rapidly attacking leader does not walk the table on every hit.
Both mechanisms are governed entirely by config — there are no per-faction overrides, so every faction behaves the same way on a given server:
Leader Protection Enabled (default true)
Immediate Leader Protection (default false)
Alert Enabled (default true) / Alert Range (default 32) / Immediate Member Alert (default false)
"Immediate" off means only members that currently have no target will engage; on means they abandon whatever they were fighting.
Querying: Membership can be inspected from either direction, and the methods that do not resolve entities work entirely offline:
| Direction |
Methods |
| entity relationship |
areSameFaction(a, b) (same ECA faction only), isFriendly(a, b) (complete ECA + vanilla friendly check), getEffectiveFactionRelation(a, b), canHarm(a, b) (ECA faction harm rules only), canTarget(a, b) (neutral and immunity-aware target check) |
| member → faction |
getEntityFaction(entity) (includes pet inheritance), getEntityFaction(uuid), isFactionMember(uuid, id) |
| faction → members |
getFactionMemberRecords(id), getFactionMemberUuids(id), getFactionMembersByType(id, typeId), getFactionMemberCount(id) |
| faction → entities |
resolveFactionMembers(id, level) |
| faction → leader |
getFactionLeader(id), getFactionLeaderUuid(id), resolveFactionLeader(id, server) (searches every dimension) |
| leader → faction |
getFactionByLeader(uuid), isFactionLeader(entity) |
joinFaction and leaveFaction both have UUID overloads for managing members whose entity is not loaded.
Faction members can also glow in their relation color for nearby players, which is configurable and off by default.
Custom Raids
ECA provides a customizable raid system. The vanilla raid only works on villages, only accepts entities implementing Raider, and hardcodes its victory condition and rewards; an ECA raid can target any structure, use any entity type, and replace every rule that governs how it progresses and ends.
Raids are registered by extending RaidDefinition and annotating with @RegisterRaid. Scanning runs after faction scanning, so a raid definition may freely reference faction ids. Only getId(), getDisplayName() and getWaves() are required — everything else has a working default modelled on the vanilla raid.
Targeting: Override getTargetStructure() for a single structure, or getTargetStructureTag() to match any structure carrying a tag so one raid applies to several structure types. Anchoring drives the default defeat condition: the raid is lost when the target structure no longer covers the raid center. Declaring neither runs the raid unanchored, in which case it can only end by victory, timeout, or an explicit end call.
Waves: Each RaidWave mixes two spawn sources freely — explicit entity entries, and addFaction(String factionId, int count, Map<EntityType<?>, Integer> typeWeights) draws whose entity types and weights are configured directly on that wave. Different waves can use different compositions and weights for the same faction.
Raiders: Explicit entries added with addEntry(...) are bound to getRaiderFactionId(), while each addFaction(...) group is bound to that entry's own faction ID. Wave leaders also use getRaiderFactionId(). Spawned Mob instances receive an injected goal that paths them to the raid center. The goal sits at priority 3 by default, matching vanilla's PathfindToRaidGoal — below the usual melee attack goal, so raiders fight an already acquired hostile-faction target and otherwise advance. Any entity type can be spawned and no interface is required, but non-Mob entities receive neither faction target acquisition, the navigation goal, nor mob callbacks. Override getRaiderGoalPriority() or return a negative value to change or disable goal injection.
Boss: A wave may declare a leader with RaidWave.setLeader(type). The spawned entity becomes the leader of the raid's raider faction, so the faction's threat propagation applies to it for free. Eligible, loaded mobs without an existing target respond by default; Immediate Leader Protection allows them to replace an existing target. Declaring a leader requires getRaiderFactionId(); without a faction there is nothing to lead and the entry spawns as an ordinary raider.
Note that propagation walks the entire faction member table, not just this raid's participants. If the raider faction has other members elsewhere in the world, they answer too. Use a raid-specific faction if you want the response confined to the raid.
Validation: Starting a raid verifies the factions it references. A non-empty but unregistered raider faction refuses the start outright because the requested friendly-fire and alert rules could not be applied. Returning null intentionally is allowed and leaves each spawned entity governed by its own AI. A wave drawing from an unregistered faction or with no positive entity weights logs an error and skips that group, but the raid still starts.
Progression: shouldAdvanceWave, checkVictory and checkDefeat are all overridable. The defaults reproduce vanilla semantics: the next wave spawns once the previous one is dead, and the defenders win when every wave has spawned and every raider is gone.
Timing and callbacks: getMaxDurationTicks() defaults to 48000, getWaveCooldownTicks() to 300, getParticipantRadius() to 96 blocks and getCelebrationTicks() to 600. A wave can add its own spawnDelay() and spawnRadius(). Lifecycle hooks are onStart, onWaveStart, onWaveEnd, onVictory, onDefeat and onStop. Client-side bossBarExtension() can replace the raid bar appearance while retaining server-synced raid state.
Endless raids: isEndless() cycles the wave list forever and never satisfies the default victory condition. Finish one with EcaAPI.endRaid, which discards every surviving raider.
Raids run per dimension and automatically restore their latest periodic checkpoint after a restart. Permanent casualties and terminal operations are saved immediately; ordinary progression is checkpointed once per second. The center chunk is force-loaded for the duration, but raiders that travel into other unloaded chunks are not force-loaded with it.
Registering a definition does not start anything. Raids are started explicitly through EcaAPI.startRaid(...) / startRaidAt(...) so that any trigger condition can drive them — entering a region, using an item, a command, a scheduled event.
ECA Transformer Whitelist
Although I've added as many common libraries and mods to the ECA Transformer whitelist as possible, there may still be mods that crash due to ECA transformation. So I've prepared a JSON configuration for modpack developers to add package prefixes to the whitelist. You can add JSON files under the config/eca/ folder. If the folder is empty on first launch, example files will be generated automatically.
Only the type and packages fields are required, other fields are ignored:
Single mod example (allreturn — skip AllReturn only, defensive hooks still apply):
{
"type": "allreturn",
"packages": [
"com.example.yourmod."
]
}
Multiple mods example (transform — skip ALL ECA transformations):
{
"type": "transform",
"packages": [
"com.example.modA.",
"com.example.modB.",
"net.example.modC."
]
}
Any .json filename works, and you can have multiple files.
评论 0
登录后参与评分
还没有评论,来抢沙发吧