Skip to content

Show each Chronicle transformation layer as one Active Effect - #316

Draft
keyxmakerx wants to merge 1 commit into
mainfrom
claude/project-thread-0dcrlx
Draft

keyxmakerx wants to merge 1 commit into
mainfrom
claude/project-thread-0dcrlx

Conversation

@keyxmakerx

Copy link
Copy Markdown
Owner

Requested by Key Maker · project thread

Fixes: none

Security implication: a read only (GET /entities/:id/layers) with the existing key. Layers are visible to anyone who can see the page, so no GM-only content goes into the effect. The layer's note is escaped before it goes into the effect description.
Consumer-verified: keyxmakerx/Chronicle#2232. It serves internal/plugins/syncapi/layers_api.go GetEntityLayers (route in internal/plugins/syncapi/routes.go, layersGroup.GET), publishes hero_layers.changed (internal/app/transformations_adapters.go transformationsLayersPublisher) and records the feed type hero_layers (internal/plugins/syncapi/sync_change_bus.go). It is verified by this repo's sync bench, run against that branch.
Foundry compatibility: written to the v12 to v14 Active Effect shape (name, img, description, changes, disabled, transfer). Not yet run in a live Foundry; see the live check.
Mockup: n/a. The signed mockup transformations-preview-2025 (option A) says "Foundry gets one effect per layer"; this is that.

What this changes

When the Director puts a transformation on a hero in Chronicle (a vampire's bite, rising as a revenant), the linked Foundry actor now gets one Active Effect named after it. Taking the layer off in Chronicle removes that effect. The actor's own data is never written, so it ends up exactly as it was, the same rule Chronicle keeps for the hero's own fields.

  • What an effect carries. A set or add on a field whose foundry_path is under system. becomes an override or an add. A set of an object (a revenant's immunities) becomes one override per member, and "@level" becomes the hero's level. Anything that can't be an effect is listed in the effect's description: an ancestry (that's an item), or a trait added or set aside.
  • When it updates.
    • When the hero_layers.changed message arrives.
    • At connect, for the heroes the change feed lists under hero_layers, or for every linked hero without the feed.
    • On every Chronicle copy, re-planned from the layers stored on the effects with no extra read, so "@level" follows the hero.
  • What it never touches. Only effects carrying the layer flag are ever changed or deleted. An unchanged layer writes nothing. A rewrite keeps the GM's on/off choice.
  • No double counting. While a layer is on, the fields it changes are left out of pushes. The actor reads them with the effect applied, and pushing that would bake the layer into the hero's own fields, where Chronicle would apply it a second time.

Load-bearing lines

  • scripts/_layer-effects.mjs planLayerEffects: duplicates and gone layers are deleted, an unchanged signature is skipped, and disabled is dropped on a rewrite.
  • scripts/actor-sync.mjs:
    • _syncLayers: 404 or 403 addon_disabled means off until the next message, kept out of the error log.
    • _withoutLayered: in _pushActorUpdate and repushActor.
    • _replanLayers: in _updateActorFromEntity.
  • scripts/api-client.mjs: the hero_layers. allowlist prefix.
  • scripts/adapters/generic-adapter.mjs: exposes fieldDefs.

Why

This is part of keyxmakerx/Chronicle#2025, the last item of the signed mockup.

Honest deviations

  • Deleting effects. "Sync never deletes without asking" is about the GM's documents. These effects are sync's own mirror of a layer the Director took off after a preview, and they carry the flag, so they are deleted. The GM's own effects are never touched.
  • Layered fields don't push. While a layer is on, a GM's Foundry edit to a field it changes stays in Foundry (bench chr-layer-effect pins this).
  • Ancestry. A layer's new ancestry stays words in the description. The actor's ancestry item isn't swapped, because the layer never writes Chronicle's ancestry field.
  • Unnamed members. An object set overrides only the members it names. Other immunities the hero has are kept, not cleared.
  • Derived values. Speed, stability, immunities and weaknesses are derived in Draw Steel. Whether the system re-derives over an effect can only be confirmed in a live world (live check step 3).
  • Bench fake. The fake Foundry's embedded item class now also serves ActiveEffect. The items bench is green after the change.

Test plan

  • node --test tools/test-*.mjs: 1723 tests, 1719 pass, 0 fail (the rest are skips). tools/test-layer-effects.mjs adds 14:
    • what an effect carries, escaping, and values that can't be effects
    • create, skip and update on a level change, and remove including duplicates
    • stored order and layered keys
    • the message path, and a page with no actor
    • a 404 or addon_disabled stopping reads
    • the push filter, a re-plan with no read, and feed-listed heroes only
  • CHRONICLE_DIR=../Chronicle bench/run.sh actors against Transformations: let Foundry read a hero's layers and hear when they change Chronicle#2232: 13 of 13 pass, including the new chr-layer-effect and chr-layer-offline. The bench is what found the 403 addon_disabled answer.
  • CHRONICLE_DIR=../Chronicle bench/run.sh items: green after the fake's change.
  • ./tools/check-comment-clutter.sh: OK.
  • Manual verification in Foundry (below).
  • CI passes.

Tenet self-check

  • T-B1 security: read only, the note is escaped, and the error log stays clean for expected refusals.
  • T-B2 plugin isolation: changes stay in this module.
  • T-B3 production UI: n/a, no new UI. The effect shows in Foundry's own Effects tab.
  • T-B4 dual-audience docs: .ai.md (sync rules and files) and API-CONTRACT.md (route, message, what the module does with it).

Live check (after this and keyxmakerx/Chronicle#2232 are deployed)

  1. In Chronicle, open <your Chronicle>/campaigns/<campaign id>/addons/settings and make sure Transformations is on.
  2. In Foundry, open the world with Chronicle Sync connected. Open a linked Draw Steel hero's sheet on its Effects tab.
  3. In Chronicle, open that hero as the Director. Click Changes, then Revenant, then Push.
    • Working: within a few seconds Foundry shows an effect named "Revenant". Its description lists "Adds Tough But Withered", and the hero's fire weakness reads 5.
    • Broken: no effect; or the effect is there but the weakness is unchanged (Draw Steel re-derived over it: tell me and I'll move those fields into the description).
  4. Make an effect of your own on the hero, then untick Revenant in Chronicle and press Take it off.
    • Working: Revenant's effect is gone and yours stays.
  5. Close Foundry, push Revenant again in Chronicle, then reopen Foundry.
    • Working: the effect appears once, on open.

Generated by Claude Code

A layer the Director puts on a hero in Chronicle (a vampire's bite,
rising as a revenant) becomes one effect on the linked actor, named after
the layer. A set or add on a mapped system field is an effect change; an
object set is one override per member; the rest is listed in the effect's
description. Only effects sync made are ever changed or removed, an
unchanged layer writes nothing, and fields a layer changes are left out of
pushes so the layer never lands in the hero's own fields. The module
re-reads on hero_layers.changed and at connect for the heroes the change
feed lists.

Part of keyxmakerx/Chronicle#2025.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CZefPjAyBR36R6s4Ju2m6c
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants