通用效果模块

脚本入口： eve.Effects()

Effects 按 subject 保存临时或永久效果。效果具有类型、来源、优先级、持续时间、强度、堆叠键、标签和 JSON 载荷；容器还保留 applied/refreshed/removed/expired 事件，适合状态效果、政策修正和临时增益。容器由模块拥有，脚本拿到的是带世代的句柄，不要跨模块重载保存内部 Effect、EffectEvent 或 EffectPayload 引用。

创建容器并施加效果

local effectsResult = eve.Effects().newContainer();
if (!effectsResult.ok) throw effectsResult.status.summary;
local effects = effectsResult.value;

local idResult = effects.apply("hero:1", "buff.speed", "potion:7",
                               10, 8.0, "speed-buff", "refresh");
if (!idResult.ok) throw idResult.status.summary;
local effect = effects.find(idResult.value);
effect.addTag("positive");
effect.getPayload().setNumber("multiplier", 1.25);

apply(subject, type, source, priority, duration, stackKey, policy) 返回 Result。 policy 的可用值和堆叠行为由定义/运行时策略决定；不要把失败当作空 ID。 applyCanonical(...) 用已注册的效果定义创建效果。每帧调用 update(dt) 推进剩余时间；消费完事件后调用 clearEvents()，否则事件会继续保留。

查询主体和标签

effects.update(dt);
for (local i = 0; i < effects.subjectCount("hero:1"); ++i) {
    local e = effects.subjectAt("hero:1", i);
    print(e.getType() + " remaining=" + e.getRemaining() + "\n");
}
for (local i = 0; i < effects.taggedCount("positive"); ++i)
    print(effects.taggedAt("positive", i).getId() + "\n");

查询返回借用引用：容器发生 apply、remove、clear、update 或释放后重新查询，不要长期缓存。release() 会主动释放容器；isStale() 可检查句柄是否已经失效。

API 快查

`Effects` 与拥有型容器

API	说明
`getName()`	返回模块名。
`newContainer()`	返回 `{ ok, value, status }`，其中 value 是模块拥有的容器。
`ownership()` / `handle()` / `isStale()` / `release()`	查询所有权和句柄、检测失效或提前释放。
`apply(...)` / `applyCanonical(...)`	施加临时效果或按 canonical 定义施加效果，返回 Result。
`remove(id, reason)` / `clear()` / `update(dt)`	删除、清空或推进效果时间。
`find(id)` / `effectCount()` / `effectAt(i)`	按 ID 或稳定的当前索引查询效果。
`subjectCount(subject)` / `subjectAt(subject, i)`	查询某主体的效果。
`taggedCount(tag)` / `taggedAt(tag, i)`	查询带指定标签的效果。
`eventCount()` / `eventAt(i)` / `clearEvents()`	读取并清空变更事件。

`Effect`、载荷与事件

API	说明
`getId()` / `getSubject()` / `getType()` / `getSource()`	效果身份和来源。
`getStackKey()` / `getPriority()` / `getDuration()` / `getRemaining()`	堆叠和时间信息。
`getMagnitude()` / `getStackCount()` / `getPayload()`	强度、层数和结构化载荷。
`addTag(tag)` / `removeTag(tag)` / `hasTag(tag)`	修改或测试标签，修改操作返回 Result。
`tagCount()` / `tagAt(i)`	枚举标签。
`setString()` / `setNumber()` / `setBool()` / `setNull()`	设置载荷字段。
`setJson()` / `getJson()` / `toJson()`	写入规范 JSON、读取单字段或序列化整个载荷。
`has()` / `erase()` / `clear()`	测试、删除或清空载荷字段。
`getSequence()` / `getKind()` / `getEffectId()` / `getReason()`	事件序号、类型、效果 ID 和原因。事件也提供 `getSubject()`、`getType()`、`getSource()`。

生命周期与确定性

容器是 owned 对象；模块卸载、显式 release() 或世代变化后句柄 stale。
update(dt) 的 dt 由游戏传入，回放时必须使用相同的模拟步长。
遍历事件或效果时不要在循环中结构性修改容器；先记录 ID，再统一修改。
Payload 接受 JSON 值而不是任意 Squirrel 对象；持久化时保存 canonical JSON。

4.1 KiB Raw Blame History