Adding a background to an actor bug #54

Closed
opened 2026-10-15 11:24:37 +00:00 by Syndria98 · 10 comments
Owner

I added a class into a character in foundry, and when it synced, dragonroll synced to foundry a background that does not exist. And then foundry gets an error when I add a background because of that. Can you fix it?

I added a class into a character in foundry, and when it synced, dragonroll synced to foundry a background that does not exist. And then foundry gets an error when I add a background because of that. Can you fix it?
Syndria98 added the ai-ready label 2026-10-15 11:24:37 +00:00
Agent added the working label 2026-10-15 12:46:37 +00:00
Collaborator

I'll start by exploring how Foundry sync maps actor fields, especially classes and backgrounds.

I'll start by exploring how Foundry sync maps actor fields, especially classes and backgrounds.
Collaborator

Now I have decisive evidence. Let me verify the key Foundry semantics once more and then implement:

Now I have decisive evidence. Let me verify the key Foundry semantics once more and then implement:
Collaborator

Root cause confirmed. Now the backend mapper fix:

Root cause confirmed. Now the backend mapper fix:
Collaborator

Now the Foundry module side — the fields that hold item references:

Now the Foundry module side — the fields that hold item references:
Collaborator

Now the tests:

Now the tests:
Collaborator

Tests pass — now let me verify they actually catch the bug by temporarily reverting the source changes:

Tests pass — now let me verify they actually catch the bug by temporarily reverting the source changes:
Collaborator

Pre-existing failures are identical before and after (23 in both runs). Let me review my final diff:

Pre-existing failures are identical before and after (23 in both runs). Let me review my final diff:
Collaborator

Fixed

Root cause. D&D 5e does not store an actor's background as a name: system.details.background is a LocalDocumentField — it holds the id of the embedded background item on that actor (same for system.details.race; verified against the dnd5e system's own schema in v3, v4, v5 and v6). Dragonroll holds names, and both sides of the sync confused the two:

  1. backend/src/services/actor-foundry.js read system.details.background as if it were a name, so the Foundry item id (aB3cD9eF1gH2iJ4k) landed in the campaign's Background field.
  2. Pushing the character back, dragonroll-foundry/scripts/api.js created a background item literally named after that id — the background that does not exist — and wrote the name into system.details.background, leaving a reference that resolves to nothing. Adding a real background in Foundry then failed.

Any actor change triggers that round trip, which is why adding a class is what surfaced it.

Changes

  • backend/src/services/actor-foundry.js: a new detailsName() reads those system.details entries through the actor's items — an id resolves to that item's name, plain text (older system releases) is kept as the name, and an id that resolves to nothing is dropped instead of becoming a name. Applied to background, className, subclass and species.
  • dragonroll-foundry/scripts/api.js: a name is never written into those reference fields. embeddedDetailReferenceData() points system.details.background at the background item the sync manages (and clears it when the campaign holds no background, which also repairs actors an earlier sync corrupted), and points system.details.race at the world's own race item when it carries the species name — otherwise that reference is left to the GM. Run after the embedded items are reconciled, and right after a character is created.

Tests — tests/foundry-actor-details.test.js (12 new, node --test): the backend mapper resolving references, dropping a dead id, keeping plain text; and the module applying a campaign character to a stubbed Foundry world (background item referenced by id, the bogus item an earlier sync invented removed, a cleared background leaving no dangling reference, a species never written as a name, and a character created from Dragonroll referencing the item it was created with). 9 of them fail on the previous code.

Full suite: 145 pass / 23 fail — the 23 failures (map pins, map tokens, item info window, item-folder-sync) are pre-existing; I confirmed the same list and count on an unmodified checkout.

## Fixed **Root cause.** D&D 5e does not store an actor's background as a name: `system.details.background` is a `LocalDocumentField` — it holds the **id of the embedded background item** on that actor (same for `system.details.race`; verified against the dnd5e system's own schema in v3, v4, v5 and v6). Dragonroll holds names, and both sides of the sync confused the two: 1. `backend/src/services/actor-foundry.js` read `system.details.background` as if it were a name, so the Foundry item id (`aB3cD9eF1gH2iJ4k`) landed in the campaign's *Background* field. 2. Pushing the character back, `dragonroll-foundry/scripts/api.js` created a `background` item literally **named after that id** — the background that does not exist — and wrote the name into `system.details.background`, leaving a reference that resolves to nothing. Adding a real background in Foundry then failed. Any actor change triggers that round trip, which is why adding a class is what surfaced it. **Changes** - `backend/src/services/actor-foundry.js`: a new `detailsName()` reads those `system.details` entries through the actor's items — an id resolves to that item's name, plain text (older system releases) is kept as the name, and an id that resolves to nothing is dropped instead of becoming a name. Applied to `background`, `className`, `subclass` and `species`. - `dragonroll-foundry/scripts/api.js`: a name is never written into those reference fields. `embeddedDetailReferenceData()` points `system.details.background` at the background item the sync manages (and clears it when the campaign holds no background, which also repairs actors an earlier sync corrupted), and points `system.details.race` at the world's own race item when it carries the species name — otherwise that reference is left to the GM. Run after the embedded items are reconciled, and right after a character is created. **Tests** — `tests/foundry-actor-details.test.js` (12 new, `node --test`): the backend mapper resolving references, dropping a dead id, keeping plain text; and the module applying a campaign character to a stubbed Foundry world (background item referenced by id, the bogus item an earlier sync invented removed, a cleared background leaving no dangling reference, a species never written as a name, and a character created from Dragonroll referencing the item it was created with). 9 of them fail on the previous code. Full suite: `145 pass / 23 fail` — the 23 failures (map pins, map tokens, item info window, item-folder-sync) are pre-existing; I confirmed the same list and count on an unmodified checkout.
Collaborator

Implementation is ready for review: #60

Implementation is ready for review: https://git.aranroig.com/Syndria98/dragonroll/pulls/60
Collaborator

The automated implementation stopped because of an internal error. Please check the worker logs for details.

The automated implementation stopped because of an internal error. Please check the worker logs for details.
Agent removed the working label 2026-10-15 13:14:37 +00:00
Sign in to join this conversation.
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Syndria98/dragonroll#54