[Foundry] Token image on pushed actors #150

New issue

Open

opened 2026-07-15 22:03:23 +00:00 by claude-bot · 0 comments

claude-bot commented

2026-07-15 22:03:23 +00:00

Contributor

Motivation/Context

A pushed NPC actor with no token art is a flat, generic token in Foundry — undercuts the value of pushing at all during live play, where the GM wants a recognizable token to drop onto the scene. LoreEntry.image_url (webapp/backend/app/models/lore_entry.py:232) already stores the portrait/token art source for npc/creature entries, so the data already exists; this issue wires it into the pushed actor's prototypeToken.

Approach

Set prototypeToken.texture.src on the pushed Actor from LoreEntry.image_url. Two possible mechanisms, per the live-push investigation (2026-07-15):

v1 (ship first): hotlink the Quest Board image_url directly. This works today with zero extra API surface, since Foundry just needs the URL reachable from Foundry clients — true for this deployment, since Quest Board is the group's web app and players' Foundry clients already reach it.
Later, if available: upload the image into the world's data directory via the module's file-upload API, if #143's Phase 1 validation confirms the module exposes one. Do not build this speculatively — only pursue it if #143 / #4's validation pass found the capability.

Document the caveat explicitly (in code comments and campaign-facing docs if applicable): hotlinking means the image URL is technically fetchable by anyone who obtains it, including for entries whose art is meant to be GM-only. This is an accepted v1 trade-off, not a security gap to silently ship — flag it in the same place #24's other residual-risk notes live.

Dependencies

Depends on #148 (npc_to_actor stat mapping) or at minimum #9's base actor-push path existing — token image is set on an actor that must already be created/updated by the push flow.
Depends on #143's connectivity validation to know whether module file-upload is available (only relevant if pursuing the non-hotlink path).
Uses #146 (foundry_links) implicitly via the actor push path — no direct table interaction of its own.

Out of scope

File-upload-based token art (only if validated available in #143 — otherwise hotlink-only for v1).
Scene placement of the token — this issue only sets the actor's prototype token image, not a placed instance on a scene.
Any UI for choosing/cropping token art beyond reusing the existing image_url.

Acceptance criteria

Pushed pf2e actors have prototypeToken.texture.src populated from LoreEntry.image_url when present.
Behavior verified against the real Foundry test instance — token art actually renders.
The GM-art-leak-via-hotlink caveat is documented (issue comment or code comment) as an accepted v1 trade-off.
Entries without image_url degrade gracefully (default Foundry token, no error).

## Motivation/Context A pushed NPC actor with no token art is a flat, generic token in Foundry — undercuts the value of pushing at all during live play, where the GM wants a recognizable token to drop onto the scene. `LoreEntry.image_url` (`webapp/backend/app/models/lore_entry.py:232`) already stores the portrait/token art source for npc/creature entries, so the data already exists; this issue wires it into the pushed actor's `prototypeToken`. ## Approach Set `prototypeToken.texture.src` on the pushed Actor from `LoreEntry.image_url`. Two possible mechanisms, per the live-push investigation (2026-07-15): - **v1 (ship first): hotlink** the Quest Board `image_url` directly. This works today with zero extra API surface, since Foundry just needs the URL reachable *from Foundry clients* — true for this deployment, since Quest Board is the group's web app and players' Foundry clients already reach it. - **Later, if available**: upload the image into the world's data directory via the module's file-upload API, if #143's Phase 1 validation confirms the module exposes one. Do not build this speculatively — only pursue it if #143 / #4's validation pass found the capability. Document the caveat explicitly (in code comments and campaign-facing docs if applicable): hotlinking means the image URL is technically fetchable by anyone who obtains it, including for entries whose art is meant to be GM-only. This is an accepted v1 trade-off, not a security gap to silently ship — flag it in the same place #24's other residual-risk notes live. ## Dependencies - Depends on #148 (`npc_to_actor` stat mapping) or at minimum #9's base actor-push path existing — token image is set on an actor that must already be created/updated by the push flow. - Depends on #143's connectivity validation to know whether module file-upload is available (only relevant if pursuing the non-hotlink path). - Uses #146 (`foundry_links`) implicitly via the actor push path — no direct table interaction of its own. ## Out of scope - File-upload-based token art (only if validated available in #143 — otherwise hotlink-only for v1). - Scene placement of the token — this issue only sets the actor's *prototype* token image, not a placed instance on a scene. - Any UI for choosing/cropping token art beyond reusing the existing `image_url`. ## Acceptance criteria - Pushed pf2e actors have `prototypeToken.texture.src` populated from `LoreEntry.image_url` when present. - Behavior verified against the real Foundry test instance — token art actually renders. - The GM-art-leak-via-hotlink caveat is documented (issue comment or code comment) as an accepted v1 trade-off. - Entries without `image_url` degrade gracefully (default Foundry token, no error).

claude-bot added this to the v5.2.0 - FoundryVTT Phase 2.5: Live Scene Push milestone

2026-07-15 22:03:26 +00:00

claude-bot added the

backend

enhancement

labels

2026-07-15 22:03:26 +00:00

claude-bot referenced this issue

2026-07-15 22:03:41 +00:00

[Foundry] "Send to live scene": place pushed NPC token into the active scene #152

claude-bot referenced this issue

2026-07-15 22:04:10 +00:00