Getting Started

This guide will walk you through the basics of setting up and using the Foundry Companion App with your Foundry VTT server running the D&D5e system.

Important requirement:

• A GM user must stay connected to Foundry in a browser so the Companion Bridge module code is running.
• If no GM-hosted browser session is active, live character loading and bridge interactions will not work.

1. Connect To Your Foundry Server

1. Open the app.
2. Enter your server URL in the first login screen.
3. Select Connect.
4. Choose your user.
5. Enter password if your user has one.
6. Select Done.
7. Choose your character and select Start.

Expected result:

• The sheet opens on Core Stats.
• All your actor data appears in the tabs.

2. Resume A Previous Session

When the app is reopened or becomes active again, it attempts to restore your previous state.

Expected behavior:

• If your auth session is still valid and the server is reachable, the app restores your actor and opens sheet view.
• If not, the app returns to login.

3. Change Server, User, Or Character

Use navigation controls to switch context safely:

• Change Server: disconnects from the server and brings you back to the login screen.
• Change User: disconnects the current user session but stays on the same server, brings you back to the user login screen.
• Change Character: keeps the current user session and returns to the actor selection step.

4. Load A Local Cached Actor

Use this when your server is unavailable or you want quick offline access.

1. In login, open the local actor section.
2. Choose an actor from Select Local Actor.
3. Select Load Local Actor.

Expected result:

• The sheet opens on Core Stats.
• All your actor data appears in the tabs.
• You can edit and manage some of the actor's data (e.g. HP, hit dice, spell slots, favourites, etc.).
• Interactions with the server (e.g., casting spells, using items, rolling, etc.) are unavailable.

5. Manage Local Cache

Use this to view and manage your locally cached actors.

1. Select Clear Actor Cache.
2. In the local cache dialog, select entries to remove.
3. Confirm deletion.

Notes:

• Deletion cannot be undone.
• Removing cache does not delete the actor from Foundry; it only clears local stored copies.