FOLOSA BRIDGE HANDBOOK

From Folosa idea to playable Foundry Actor.

A complete operating guide for Game Masters: install the module, connect safely, choose among three creation modes, follow a render, import new or previous generations, and troubleshoot the full path.

Download Bridge Foundry manifest Open web Forge

Foundry: V13 or later; V14 verified
Access: Game Master permission
Inputs: Build, Prompt, or Upload
Delivery: Verified WebM + PNG imported as Actors

1. Before you begin

Confirm the account, file, permission, and browser requirements before installing anything.

Use the correct Folosa account

Use the same verified Folosa account that owns your credits and previous generations. Bridge history is account-specific.

Open Foundry as a Game Master

Only a GM can connect Bridge, submit paid tasks, write files to Foundry Data, or create Actors.

Check the Foundry version

Use Foundry V13 or later. V14 is the currently verified target. Update the module before diagnosing an old client.

Prepare image uploads

Use PNG, JPG, or WebP, at least 300x300 px and no larger than 10 MB. A centered full-body subject with room around limbs, weapons, hair, wings, and effects gives the model usable motion space.

2. Install and enable the module

Use the ZIP for manual installation or the manifest URL when your Foundry package manager allows it.

Back up the world

Create a Foundry world backup before adding or updating any module.

Install the package

Download the Bridge ZIP. In Foundry Setup, install it as a module using the manifest or extract the folder named folosa-bridge into Data/modules.

Restart Foundry

Restart the Foundry application or server so the new module code and templates are loaded.

Enable it in the world

Open Manage Modules in the target world, enable Folosa Bridge, confirm dependencies if Foundry asks, and save.

Open the panel

As GM, open Settings and choose Folosa Bridge, or use Ctrl+B. The panel can be closed while a render continues.

3. Connect the account securely

Bridge uses a short-lived device code and a scoped, revocable credential. Your Folosa password is never entered in Foundry.

Start connection

Select Connect Folosa. Bridge opens a Folosa approval page and displays a temporary code.

Sign in on Folosa

Approve the device

Approve only the Foundry client and world you recognize. The code expires and can be used only for this authorization.

Confirm the account bar

Return to Foundry and wait for Connected, your email, credit balance, and tier. The panel refreshes status automatically.

Know the scopes

The credential can read credits, create/read jobs, read owned assets, and create a checkout handoff. It cannot read your password or another user's assets.

4. Choose one of the three creation modes

The three modes match the website input paths but submit one Foundry-ready task at a time.

Build

Choose lineage, archetype, setting, and action. Bridge assembles a structured full-body token prompt with transparent-background and clean-silhouette requirements.

Prompt

Write one precise character brief, up to 800 characters. Describe one subject, visible equipment, action, and style. Avoid conflicting camera or anatomy instructions.

Upload

Choose an image you have the right to use. An optional motion intent can tell the model to raise an existing sword, cast with an existing hand, or shift into a guarded stance.

Do not combine modes

Only the active mode is submitted. Values left in another mode are ignored, preventing a hidden prompt from contaminating an upload.

Choose style

Dark Fantasy, Anime, and Ink change visual direction. For an upload, the reference image remains the identity source.

Keep composition practical

For uploads, do not start from a close crop or cut limbs. For prompts, explicitly request one centered, full-body subject and a readable silhouette.

5. Select quality and understand credits

Quality controls the delivery tier and credit reservation; it does not create a separate account or task history.

Standard VTT

Costs 80 CRD per token and targets a compact 512p transparent WebM suited to live scenes.

HD Pro

Costs 200 CRD per token and provides a sharper 1080p delivery for hero characters and presentation.

4K Master

Costs 280 CRD per token and includes the highest-resolution archive-oriented output.

Reservation and capture

Credits are reserved when the job is accepted and captured on success. Verified system failures release the reservation. Do not resubmit a task merely because rendering takes several minutes.

6. Submit, wait, refresh, or cancel

The task list is the source of truth for the current state. There is one Refresh control for account and task history.

Review the active mode

Confirm the mode, source image or prompt, style, quality, and visible credit balance.

Create the token

Select Create token once. Bridge uses an idempotency key so the same accepted submission is not intentionally charged twice.

Read the status

Queued means waiting for a render slot; Processing means a worker or model is active; Completed means artifacts are available; Partial failed means at least one output succeeded.

Continue other work

You may close Bridge or continue preparing the Foundry world. The render runs server-side, and Bridge checks status every ten seconds while connected.

Cancel only when offered

The Cancel button appears only for a queued Bridge task that has not been claimed. Once work starts, wait for the final state instead of submitting a duplicate.

Important: a task that is processing cannot be cancelled safely after a provider has claimed it. A queued task can be cancelled only before that point.

7. Use new and previous generations

The list shows the latest 50 tasks owned by the connected account, including website Forge history.

Identify the source

Foundry marks tasks created in Bridge. Website marks tasks created on folosa.com.

Automatic import

When enabled, only newly completed Bridge tasks import automatically. Existing website history never bulk-imports by itself.

Manual import

Select Import on any completed compatible task. Bridge obtains signed artifact URLs, verifies size and SHA-256, uploads files into Foundry Data, and creates Actors.

Open an existing Actor

When a task is already imported, select Open Actor. Drag that Actor from the Actors directory into a Scene whenever you want to reuse it.

Restore a deleted Actor

If the imported Actor was deleted, Refresh makes Import available again. Import recreates the missing Actor without generating or charging for the asset again.

8. Use the imported Actor in play

Bridge stores each job in a predictable Foundry Data folder and keeps the animated token separate from the portrait.

Locate the files

Imported assets are stored under Data/folosa/tokens/<job-id>. Do not rename or move them while Actors still reference those paths.

Inspect the Actor

Open the Actor and confirm the PNG portrait and WebM Prototype Token texture. System-specific NPC fields can be completed normally.

Place and test

Drag the Actor to a small test Scene, unpause, zoom in and out, and confirm transparency, loop motion, scale, and performance.

Reuse safely

Reuse the Actor in additional Scenes instead of importing duplicate files. Duplicate the Actor only when you need different game statistics or token settings.

9. Credits, checkout, and credential security

Account and payment actions open folosa.com through a short-lived handoff; the credential is not placed in the checkout URL.

Buy credits

Select Credits to open the connected account and checkout. Verify the email and pack before paying, then return to Foundry and use the single Refresh button.

Rotate the key

Select Rotate key if the device credential may have been exposed. The old credential is revoked and replaced for this client.

Disconnect

Disconnect revokes the current credential and removes it from this Foundry browser profile. It does not delete Folosa jobs, assets, or Actors.

Shared machines

Disconnect before another person uses the same Foundry client profile. Never paste the credential into chat, support messages, macros, or module settings screenshots.

10. Troubleshooting

Work down the table in order. Avoid resubmitting until you know whether the original task was accepted.

Symptom	Check	Resolution
Not connected	The approval page, email, and code expiry.	Start a new connection and approve the new code. Do not reuse an expired code.
401 or credential invalid	Whether the credential was rotated, revoked, or copied between profiles.	Disconnect and connect again. Keep one credential per client profile.
Balance looks old	Whether checkout completed for the same email.	Use the single Refresh button. If still wrong, verify the Folosa account transaction before creating a task.
Task stays queued	Task ID and time; do not create another copy.	Leave it queued or cancel only if Cancel is still offered. Open support if the queue is abnormal.
Task is processing for minutes	Provider work is active.	Wait. Closing the panel is safe; duplicate submission is not.
Completed but Import fails	GM permission, Foundry Data write access, free disk space, and browser console.	Correct storage permission, Refresh, then Import again. This does not regenerate or charge.
Actor exists but video is blank	Prototype Token texture path, WebM support, scene pause, and client hardware.	Open Actor, verify the WebM path, test in a small unpaused Scene, and use Standard VTT for lower-power clients.
Previous website task is absent	Connected email and whether the task is within the latest 50.	Refresh. For older records, open the Folosa account history and download manually.

11. Final pre-session checklist

Use this short acceptance pass before relying on a generated token in a live game.

Account

The expected email is connected and the credit balance is current.

Task

The task is Completed or Partial failed, and only one submission exists for the intended token.

Files

The Actor opens, the PNG portrait loads, and the WebM token texture plays.

Scene

Transparency, scale, loop, performance, and visibility work on a representative player device.

Support evidence

For a genuine defect, keep the task ID, time, mode, quality, screenshot, and a short description, then open a support ticket. Never include your credential.