Epic Core API

模组

· 作者 cjiangqiu

一个通过 CoreMod(ITransformationService)、Java Agent 和 Mixin 技术提供强大实体操作 API 的库模组。

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

最新 1.1.9-fix · 1.20.1 · Forge

一键开服(送7天)

由于个人原因,本模组将在未来两个月内停止更新。在此期间,我将不会回复任何消息。

本模组基于 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 丢弃录制

编辑器工作流程:

  1. 在至少一个 LivingEntity(64 格范围内)附近运行 /eca bossShow edit。
  2. 在主 GUI 中,点击 + New cutscene from entity → 瞄准一个实体 → 右键单击将其选为摄像机锚点。或者,点击现有过场动画的 Edit。
  3. 配置触发类型(范围/自定义)、目标实体类型、电影条、允许重复等选项。
  4. 点击 ● Record,按 J 开始。在旁观者模式下自由移动摄像机——每个刻都被捕获为可编辑的帧。
  5. 录制完成后,点击时间轴上的任意刻以编辑其位置和摄像机方向。使用 Preview 播放时间轴。要从游戏视角重新采样姿势,点击 Free camera write,移动摄像机,然后按 Enter 写入当前刻。
  6. 按 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 以保留原版惯性。

给模组开发者

两种定义过场动画的方式:

  1. 仅 JSON —— 将文件放置在 data/<modid>/eca/bossshow/<path>.json。启动时自动加载。旧版 data/<modid>/bossshow/<path>.json 位置仍受支持。如果不需要服务端事件处理,则无需 Java 代码。

  2. 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。

对于整合包开发者

  • 覆盖过场动画 —— 将你修改后的 JSON 放置在 config/eca/bossshow/<namespace>/<path>.json。配置文件会覆盖模组内置的定义(位于 data/<modid>/eca/bossshow/,同时也支持旧版路径 data/<modid>/bossshow/),前提是 ID 相同。
  • 在游戏中编辑 —— /eca bossShow edit 命令允许你重新录制相机路径、编辑任意游戏刻的姿态、调整触发器、添加事件/字幕提示,并对帧范围进行操作(复制 / 剪切 / 删除 / 粘贴)。保存内容写入 config/eca/bossshow/,不会触碰模组 jar 包。
  • 翻译或重写字幕 —— 创建 config/eca/bossshow/lang/<locale>.json(例如 en_us.json、zh_cn.json)。这些文件中的字幕键优先级高于模组自带的语言文件:
    {
      "mymod.bossshow.warden.intro": "A sound echoes from the deep..."
    }
    
  • 热重载 —— /eca bossShow reload 可在不重启的情况下读取所有 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 的领袖。

关系解析按以下顺序进行,首个匹配项生效:

  1. 相同的阵营 ID → SAME_FACTION
  2. A 的 getRelation(self, target) 条件覆盖项
  3. A 的静态 hostileTo / friendlyTo / neutralTo 数组
  4. 对称回退 —— 从 B 的角度评估相同的两项检查
  5. A 的 getDefaultRelation(self, target) 条件覆盖项(仅当对方没有阵营时)
  6. 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 文件名均可使用,且你可以拥有多个文件。

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

评论 0

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

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源