[Foundry] "Send to live scene": place pushed NPC token into the active scene #152
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Motivation/Context
This is the headline feature requested by the original ask: "while actively playing, let the GM push stats/backstory/character tokens to Foundry in real time — e.g. spin up an NPC just generated in Quest Board directly into the live Foundry scene." Everything else in the Foundry pillar up to this point (#9, and its live-push extensions #146/#148/#150) gets an NPC into Foundry's actor directory; this issue is the entire delta that makes it "live" — placing a token for that actor onto the scene the GM currently has open, during play.
Approach
After the actor create/update path (#9 + #148's stat mapping + #150's token image) completes, place a
TokenDocumentfor the resulting actor on the currently viewed/active scene using the REST module's active-scene query and token-creation APIs (validate exact API shape during #143's module testing pass). Default placement: scene center,hidden: true— the GM positions and reveals the token manually in Foundry rather than the push deciding placement/visibility for them.API surface:
POST /api/campaigns/{campaign_id}/lore/{entry_id}/foundry-pushwith{"target": "directory" | "active_scene"}, GM-authorized viarequire_gm.target=directoryreuses #9's existing behavior unchanged;target=active_sceneis new in this issue — create/update the actor exactly as #9 does, then additionally place the scene token.Execution: run as a short Celery task, consistent with the existing "queue a task, POST out, fall through gracefully" pattern already used in
app/tasks/reminder_tasks.py. The API returns immediately with a push-status the UI polls or receives via existing toast plumbing (UI itself is tracked separately). Feedback states: queued → pushed (actor name + scene) → failed, with the "no Foundry client connected" relay failure surfaced as an actionable, specific error message rather than a generic failure. All errors follow the repo-wide{"detail": "..."}shape.Uses
foundry_links(#146) to determine create-vs-update for the underlying actor, so repeated live pushes of the same NPC don't spawn duplicate actors — only the scene-token placement is genuinely new each time. Default to always creating a new token instance on the active scene per push, since GMs may want the same NPC on stage twice; refining this is left to the follow-on "Push update" work.Dependencies
npc_to_actor+ directory-level "Send to Foundry") — this issue is #9 plus scene placement, not a replacement for it.foundry_links) — needed for actor-level idempotency before adding a token on top.Out of scope
Acceptance criteria
POST .../lore/{entry_id}/foundry-pushwithtarget=active_scenecreates/updates the actor (via #9 + #146's link table) and places a token for it on Foundry's currently active scene.hidden: true.