Remember to never mention Plutonium in any public FoundryVTT space, such as their Discord server. This also includes partnered hosting services.
Plutonium support is only available in the 5etools Discord server.
¶ Installing Plutonium
Most of the time, all you need to install Plutonium is its manifest URL.
Be aware that Plutonium (normally) works with the latest stable FoundryVTT release. As a general rule, make sure your dnd5e system is up to date. To know the exact compatible versions, check the pinned messages in #plutonium-general of the 5etools Discord server.
Plutonium requires the module libwrapper to ensure compatibility with other Foundry modules. You must install it first.
After installing Plutonium, you can also modify the back-end to unlock some optional bonus features.
You may also want to install Rivet for quick importing directly from 5eTools webpages.
¶ Manifest URL
Installing modules with a manifest URL is FoundryVTT’s native, fastest, and easiest method.
- Copy Plutonium’s manifest URL. This is available in a few places:
- On 5eTools’ homepage.
- Pinned in the #plutonium-general channel of the 5eTools Discord server.
- Connect to your FoundryVTT installation and access the setup panel.
- Go to the ‘Add-on Modules’ section.
- Click the ‘Install Module’ button, and paste Plutonium’s manifest URL into the ‘Manifest URL’ field at the bottom.
- Click ‘Install’. If a notification pops up asking you to install a package dependency (notably the
lib-wrappermodule), click ‘Install dependency automatically’.
If everything went correctly, you should see Plutonium (and libWrapper!) in your list of installed add-on modules. Remember to activate the module once you’ve loaded your world!
Installing or using Plutonium violates some partner hosting services’ terms of service. Consequently, some services have blocked Plutonium’s manifest URL.
Although you might be able to Plutonium manually (please follow your service’s own instructions for this), some services have more comprehensive blocking methods. We do not provide solutions or workarounds to these restrictions.
¶ Manual Install
- Install libwrapper, either through the setup panel (see above) or otherwise.
- Visit the 5etools Discord server and read the pinned messages in #plutonium-general to find a download link to the module’s
.zipfile. - Extract these files to your Foundry application data folder. Its location depends on your operating system:
- Extract the
.zipfile’s contents toC:\Users\<your username>\AppData\Local\FoundryVTT\Data\modules\plutonium
The
AppDatadirectory is usually hidden. If you can’t see it, you can access it quickly in two ways:
- Paste
%localappdata%\FoundryVTT\Data\modulesinto Windows Explorer’s address bar.- Right-mouse click on the FoundryVTT’s icon in the taskbar and click Browse User Data.
- Extract the
.zipfile’s contents to$foundryDATAdir/Data/modules/plutonium
- Extract the
.zipfile’s contents toUsers ▸ <your username> ▸ Library ▸ Application Support ▸ FoundryVTT ▸ Data ▸ modules
- Confirm that the directory is named
.../modules/plutonium and not.../modules/Plutonium (it is case sensitive). Also verify that it isn’t nested (that is, there isn’t any.../modules/plutonium/plutonium). - Restart the FoundryVTT server, or close and reopen the program.
- Confirm that Plutonium shows up in the Add-on Modules tab.
You have now successfully installed Plutonium. Remember to activate the module once you’ve loaded your world!
¶ Modifying the Back-end
After installing Plutonium, you can modify FoundryVTT’s internal files to enable some additional functionality. Notably, this allows Plutonium to access your filesystem to install files via its user interface, and resolves some errors associated with the Art Repo.
Modifying the back-end is entirely optional. The core functionalities of Plutonium don’t depend on it. If you are unsure about any step in this section, it’s okay to skip. For more information, please see the FAQ.
Modifying the back-end requires you to have direct access to Foundry installation files. It cannot be done on partnered hosting services.
Modifying the backend can create security vulnerabilities. Please read the
README.mdfile and make an informed decision before continuing. Some known vulnerabilities are highlighted below, but please note that this is an incomplete list.
¶ Adding the Back-end Library
This information may become outdated. Always refer to the
README.mdfile for guidance modifying the back-end.
- Locate the
Data\modules\plutonium\server\<FoundryVTT version>\plutonium-backend.mjsfile. - Copy this file into the FoundryVTT
appdirectory:
- If you installed FoundryVTT ‘for current user only’, this will be
%localappdata%\Programs\FoundryVTT\resources\app. - If you installed ‘for all users’, this will be
%programfiles%\FoundryVTT\resources\app. - You can also right-click on the FoundryVTT icon in the taskbar and choose Browser Application Data.
The path to this directory depends on your distribution. Here are some possibilities:
/home/$USER/.local/share/FoundryVTT/resources/apphome/$USER/FoundryVTT/resources/app/local/FoundryVTT/resources/app
There is a community-created bash script to automate the back-end installation.
This script is provided with no support or assistance. Please ensure you have backup of your data and direct any questions or concerns to the author.
Applications ▸ FoundryVTT ▸(right-click ▸ Show Package Contents)▸ Resources ▸ app
You now have to modify the main.mjs file within the same app directory.
If you do not modify the
main.mjsfile correctly, Foundry will crash on start-up.You should make a copy of the
main.mjsfile (rename it tomain.mjs_backupor similar) so you can restore it in the case of a mistake. You can also uninstall and reinstall Foundry entirely to fix any problem.
- Open
main.mjsas an adminstrator. - Locate the following lines at the end of the file:
init.default({ args: process.argv, root: root, messages: startupMessages, debug: isDebug }) })(); - Delete those lines and replace them with the following:
await init.default({ args: process.argv, root: root, messages: startupMessages, debug: isDebug }); (await import("./plutonium-backend.mjs")).Plutonium.init(); })(); - Restart the FoundryVTT server, or close and reopen the program.
- Confirm that, after launching a D&D5e world with Plutonium enabled, the in-game Foundry logo (top-left of the screen) has turned green.
As the
appdirectory is reset when you update FoundryVTT, you will need to redo these steps each time you update.
¶ Additional Server-side Add-ons
Plutonium offers some additional server-side add-ons. If you have installed the back-end, you can also install these.
Remember to restart the FoundryVTT server, or close and reopen the app, after applying the add-ons.
¶ Custom Setup Screen Add-on
This addon allows custom CSS and JavaScript to be automatically loaded when viewing the setup screen, allowing additional styling and functionality to be applied.
Installation: copy the plutonium-backend-addon-custom-setup.mjs file to the app directory above.
Usage: create a setup.css and/or a setup.js in your Foundry Data folder (alongside the modules, systems, and worlds directories). These files will then be loaded, if they exist, when a client visits the setup screen (/setup).
Examples can be found in the server/<foundry version>/custom-setup-samples directory.
Any user with upload permissions can maliciously modify or replace the
setup.cssandsetup.jsfiles. Ensure that you trust your users and that each user has a strong password.
¶ Custom World Login Screen Addon
This addon allows custom CSS and JavaScript to be loaded when viewing a world’s login screen, allowing additional styling and functionality to be applied on a per-world basis.
Installation: copy the plutonium-backend-addon-custom-login.mjs file to the app directory above.
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.
Any user with upload permissions can maliciously modify or replace the
login.cssandlogin.jsfiles. Ensure that you trust your users and that each user has a strong password.
¶ Electron Add-on
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 pop-up windows, enabling Plutonium’s ‘Pop Out’ feature (among possible others, depending on your installed modules).
Note that accessing Foundry via a browser is still recommended over the Electron app.
OUTDATED: Package Operations Add-on
This tool has been removed from all current versions of Plutonium. Installation and use is 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, for example, adventure worlds from within the Importer. In practice, this feature is not currently used.
Enabling this addon allows any web client to inspect/install modules and worlds.
Installation: copy the plutonium-backend-addon-package-operations.mjs file to the same directory as plutonium-backend.mjs.