Remember to NOT mention Plutonium in any public FoundryVTT space, such as their Discord server. This also includes hosting providers such as The Forge.
Plutonium support will only be available in the 5etools Discord server
¶ Installing Plutonium
Here you will find instructions to install Plutonium in FoundryVTT. Manifest URL will be sufficient for most installs, but for hosting services that block it you can use the Manuall install.
Be aware that Plutonium (normally) works with the latest STABLE FoundryVTT release, not ALPHA or BETA. As a general rule, make sure your D&D5e system is up to date as well, unless it has been released very recently. To know the exact compatible versions, check the #plutonium-general pins in the 5etools Discord server.
Plutonium also requires libwrapper to ensure compatibility with other Foundry modules. Without it installed you won’t be able to use Plutonium.
You may also want to install Rivet for quick importing directly from 5eTools webpages.
¶ Manifest URL
Using FoundryVTT’s native way of installing modules is the fastest and easiest.
- Visit the 5etools Discord server and check the pinned messages in #plutonium-general for the
module.jsonlink. - Go to the FoundryVTT app, to the Add-on Modules section.
- Choose Install Module and search for libwrapper which is a plutonium dependency, then install it.
- Then paste the plutonium URL into the Manifest URL field at the bottom.
- Click install
If everything went correctly, you should see Plutonium in the Add-ons listing. Remember to activate the module once inside the game.
Finally, if you want to use the Art Repository function inside the game, make sure you have Modified the Backend.
¶ Manual Install
- Ensure your have installed libwrapper, which plutonium depends upon.
- Visit the 5etools Discord server and check the pinned messages in #plutonium-general for the module .zip file dowload link.
- Extract these files to the Foundry Appliaction Data folder. Its location depends on your Operating System:
- Extract files to your
C:\Users\<You>\Appdata\Local\FoundryVTT\Data\modules\plutoniumdirectory
You can also paste this into the Explorer address bar
%localappdata%/FoundryVTTto open into the directory quickly.
Or right mouse click on the FoundryVTT’s icon on the taskbar and choose Browse User Data
- Extract files to your
$foundryDATAdir/Data/modules/
- Extract files in
Users ▸ Username ▸ Library ▸ Application Support ▸FoundryVTT ▸ Data ▸ modules
- Confirm that the directory is named
...Data\modules\plutonium and NOT...Data\modules\Plutonium (it is case sensitive) and isn’t nested under a subdirectory. - Restart the FoundryVTT server, or close and reopen the program.
- Confirm that Plutonium shows up in the Add-on Modules tab.
You have successfully installed Plutonium. Remember to activate the module once inside the game.
Finally, if you want to use the Art Repository function inside the game, make sure you have Modified the Backend.
¶ How to Modify the Backend
Backend modification requires you to have direct access to Foundry installation files.
This means that if you are using any partnered hosting provider, such as The Forge/FoundryServer/etc., you will NOT be able to do it.
What this does
The modification allows Plutonium to copy files you select to your server, bypassing certain restrictions FoundryVTT has. This addresses some errors from attempting to use the Art Repo, Importing Packages, and issues with Foundry’s included app Electron.
For more information, see the [Backend FAQ])/Plutonium/Plutonium_FAQ#backend)
⚠️Modifying the backend can create security vulnerabilities, making your game more susceptible to attack.! Please ensure you read the
README.mdfile and make an informed decision about this step.
⚠️Some known vulnerabilities are highlighted below, but this is not a complete list.⚠️
¶ Add backend library
Copy the plutonium-backend.mjs file from FoundryVTT\Data\modules\plutonium\server\v9 directory of your installed Plutonium Module, depending on your Operating System:
- If you installed “for current user only” on Windows:
%appdata%\..\Local\Programs\FoundryVTT\resources\app - If you installed “for all users” on Windows:
Program Files\FoundryVTT\resources\app - Or right mouse click on the App in the taskbar and choose Browse Application Data
- Look for one of the following directories (different flavors and systems may install to a different)
/home/$USER/.local/share/FoundryVTT/resources/app /home/$USER/FoundryVTT/resources/app /local/FoundryVTT/resources/app
Additionally you can find a linux-only community created bash-script to automate the backend installation here.
This script is provided with no support or assistance; please ensure you have backup of your data.
\Applications▸ clickShow Package Contents>Resources>app>main.mjs- Or you can open a terminal and do a
find / -name main.mjs
¶ Modify FoundryVTT’s main.mjs
Locate the main.mjs file in your installation - it should be in the same folder you copied the plutonium-backend.mjs file to.
Make a copy of the main.mjs file, name it backupmain.mjs
If you do not modify the
main.mjsfile correctly, Foundry will crash on startup.
You can delete the modifiedmain.mjsand renamebackupmain.mjstomain.mjs(If you you made the backup copy), or another way to fix this is to uninstall and reinstall Foundry as a whole.
Open the main.mjs as an adminstrator and locate the following lines at the end of the file:
init.default({
args: process.argv,
root: root,
messages: startupMessages,
debug: isDebug
})
})();
Select it all, and paste the following instead
await init.default({
args: process.argv,
root: root,
messages: startupMessages,
debug: isDebug
});
(await import("./plutonium-backend.mjs")).Plutonium.init();
})();
Now, make sure you restart the server/close and reopen the Foundry app.
If everything is working, the in-game Foundry logo (in the top-left of the screen) will show the running Plutonium backend version.
If you follow any of the additional steps below you will need to restart Foundry again.
¶ Additional Server-Side Addons
Plutonium offers some additional server-side addons that you can enable or disable.
¶ Custom Login Screen Addon
This addon allows custom CSS and JavaScript to be loaded when viewing a world’s login screen, allowing additional styling/functionality to be applied on a per-world basis.
⚠️ Enabling this addon allows any user with upload permissions to create potentially-malicious scripts and styles which will automatically be executed when a client visits the login page. ⚠️
Installation: copy the plutonium-backend-addon-custom-login.mjs file to the same directory as plutonium-backend.mjs.
Usage: create a login.css and/or a login.js in a world’s directory. These files will then be loaded, if they exist, when a client visits the login screen (/join) for a world.
For example, filling worlds/my-world/login.css with the CSS found in this Reddit post will have the same effect as modifying Foundry’s style.css (as per the post), but the changes will only be applied to the login page for my-world. Aside from allowing per-world customization, this circumvents the need to re-apply the CSS changes after each Foundry update (assuming the Plutonium backend mod is re-applied instead!).
Further examples can be found in the server/<foundry version>/custom-login-samples directory.
¶ Electron Addon
An additional file, plutonium-backend-addon-electron.js, can be installed in order to enable additional functionality when running Foundry as a “native” (Electron) app.
Installation: copy the plutonium-backend-addon-electron.js file to the same directory as plutonium-backend.mjs.
This addon allows the Foundry app to open popup windows, enabling Plutonium’s “Pop Out” feature (among possible others, depending on your installed modules).
¶ Package Operations
Note that this addon is unused by Plutonium, and installation is therefore not recommended.
An additional file, plutonium-backend-addon-package-operations.mjs, can be installed in order to allow access to package lookup/installation while a game is running. This theoretically allows Plutonium to install e.g. adventure worlds from within the Importer, but in practice, this feature is not currently used.
⚠️ Enabling this addon allows any web client to check the status of/install modules and worlds. ⚠️
Installation: copy the plutonium-backend-addon-package-operations.mjs file to the same directory as plutonium-backend.mjs.
¶ TheForge / FoundryServer / Molten
Manifest URL installation may not work.
Some Foundry hosting providers have blocked the Manifest URL install of Plutonium. You will have to manually install the module, using each provider’s feature to do so.
FOR FORGE ▸
- See, this tutorial/video on How to install on The Forge manually through their interface.
- Then proceed with Manual Installation. You will not be able to modify the backend; you will not have World/Module/Package importing options and Art Browser will not work for you.