定位、术语与核心数据流

SealAttributes 是服务端的权威属性与战斗运行时。它负责定义属性、汇总多个来源、生成只读快照、计算战斗/治疗/资源结果，并把玩家最大生命和移动速度投影到 Paper。它不是物品编辑器、职业系统、脚本引擎或跨服同步服务。

功能边界

插件实际支持：

• 22 项内置属性与扩展属性定义；
• ADD、TOTAL_PERCENT 两种来源贡献；
• 运行时、永久、定时来源；
• 六个原版装备槽读取，结构化 PDC 或 Lore 二选一；
• 实体对实体的命中、闪避、暴击、防御、格挡、攻速、吸血和反伤；
• 主动治疗、周期恢复、可扩展资源；
• SQLite/MySQL 持久化健康检查点、永久来源和资源状态；
• MythicMobs 5.x、PlaceholderAPI、DecentHolograms 和 SealItems 的明确联动契约；
• Bukkit Services 公开 API 与启动期 ServiceLoader 扩展。

插件不支持：Folia、1.21 之前版本、Redis、Velocity 数据同步、在线跨服同一玩家多写、NMS、热加载扩展、任意脚本公式、自动迁移 SQLite 与 MySQL、资源管理员 set/转账、离线资源恢复、任意自定义装备槽的内置读取。

核心术语

术语	含义
Attribute Definition	属性的 ID、默认值、类别和允许的 operation；不是某个玩家的当前数值。
Subject	被计算的玩家或实体。玩家通常用 UUID；实体是当前运行期主体。
Base Profile	主体创建时使用的基础属性来源。默认玩家与实体分别为 player-default、entity-default。
Provider	来源/定义的所有者命名空间，如 sealitems。绑定后只能写自己的命名空间。
SourceKey	providerId + sourceId 组成的稳定来源键，如 sealitems:equipment/main_hand。
SourceSnapshot	某个来源在某一修订号的完整、不可变替换值；再次发布不是追加。
Contribution	一项属性贡献，由属性 ID、operation 和有限数值组成。
Runtime Source	只在当前会话存在，不写数据库。
Persistent Source	先持久化，再尽力提交到仍有效的在线会话。
Subject Snapshot	已聚合、可被查询和战斗使用的只读快照。
Publisher	提交、替换或撤销来源的 API 门面。
Plan / Gate / Extension	战斗计划、准入闸门和后处理扩展。
READY	主体已完成配置、持久数据和初始来源装配，可以查询与战斗。
Fail closed	不确定、过期、超限或回调异常时拒绝操作，不用猜测值继续运行。

数据流

flowchart LR
  A["base profile"] --> G["按 SourceKey 聚合"]
  B["六槽装备或 SealItems"] --> G
  C["职业、任务等 API 来源"] --> G
  D["永久与定时来源"] --> G
  G --> S["SubjectSnapshot"]
  S --> Q["O(1) 属性查询"]
  S --> CMB["战斗/治疗/恢复"]
  S --> P["生命与移速投影"]
  CMB --> E["提交后事件与显示"]
  CMB --> DB["健康/资源检查点"]

1. 启动时加载八份配置、扩展定义和数据库；任一硬性条件失败会停止启用。
2. 玩家加入后进入预加载，读取永久来源、健康检查点和资源状态；完成前不是 READY。
3. 每个 provider 按 SourceKey 发布完整快照。相同键的新修订整体替换旧修订。
4. 聚合器使用当前定义和所有有效来源生成新快照，然后原子替换；读者不会看到半成品。
5. 查询只读当前快照；战斗在合法服务器线程用一组一致快照结算。
6. 快照提交后再发事件。监听器不能把事件当作可取消的“提交前”钩子。

为什么来源必须完整替换

假设主手原来提供攻击力和生命：

r1 = { physical_attack +20, max_health +40 }

换装后只剩攻击力，正确做法是发布：

r2 = { physical_attack +12 }

max_health +40 会随 r1 一起消失。若把 r2 当成“补丁”，旧生命会残留。撤下装备则用更高修订号撤销整个来源。

安全与权威性

• Lore 是不可信兼容输入，只适合迁移旧物品；高价值物品应由可信插件写规范 JSON PDC。
• 扩展 JAR 是可信服务器代码，不是沙箱；只安装你审计过的文件。
• 默认战斗不自动叠加其他战斗插件、原版附魔或药水额外伤害。共存必须明确设计 Gate/Plan/Extension，避免重复结算。
• MySQL/SQLite 存的是可恢复状态，不是完整实时战斗流水；/sa combat trace 也只是有界内存中的最近一次结果。

下一步：兼容性、安装与首次启动。