Performance Tuning and Player Capacity
RAM requirements, player capacity limits, and practical tuning tips to keep Foundry VTT running smoothly under load.
Overview
Foundry VTT runs on a single-threaded Node.js process. There is no hard player cap — one license supports unlimited concurrent players — but practical limits exist based on server resources, module count, and world complexity. Understanding where these limits come from helps you plan hardware and tune the server for your group's needs.
Hardware Requirements
| Configuration | RAM | CPU |
|---|---|---|
| Minimum | 2 GB | Any modern CPU |
| Recommended | 4 GB | High single-core clock speed |
| Heavy use (many modules, large maps) | 8 GB+ | Fast single-core |
Node.js is single-threaded. Additional CPU cores do not improve Foundry's throughput. Clock speed matters more than core count. If you are choosing between a 4-core 2.5 GHz and a 2-core 4.0 GHz server for a Foundry deployment, the 2-core machine will likely perform better.
Practical Player Limits
There is no license-imposed player limit. Practical limits based on typical server configurations:
- Small group (1–8 players): Almost any server handles this without issue
- Medium group (8–20 players): 4 GB RAM, minimal module load
- Large group (20–30 players): 8 GB RAM, optimized module list
- 30+ players: Possible but diminishing returns; world and module complexity becomes the bottleneck
The biggest factors affecting performance are not player count but world complexity (number of active scenes, entities loaded) and module count.
Reducing Module Load
Every active module consumes memory and adds JavaScript execution on the server and client side. The single most impactful performance tuning step is reducing the active module list.
Audit your active modules:
- Launch your world
- Go to Settings → Manage Modules
- Disable any module that is not actively used in the current campaign
Modules that handle visual effects, animations, and large asset libraries have the highest memory and CPU impact. Disable them if you are experiencing lag or high memory usage.
Check for module conflicts:
Some modules iterate over large datasets on every scene load or game event. If performance degrades after installing a specific module, disable it and test.
Memory Usage Monitoring
Check current memory usage of the Foundry process:
# Find the Node.js process and inspect memory
ps aux | grep main.mjs
# Or use top/htop
top -p $(pgrep -f main.mjs)
If the process is consistently using more than 3–4 GB of RAM on a 4 GB server, the system will begin swapping. Add RAM or reduce module load.
Startup Time
Foundry's startup time scales with the number of installed modules (even disabled ones are scanned at startup). If startup is slow:
# Check total module count
ls /foundry-data/Data/modules/ | wc -l
Uninstall modules you no longer need through the Setup menu rather than simply disabling them in a world.
Large World Performance
Worlds with many actors, large scene counts, or significant embedded media can become slow to load. Strategies:
- Split large campaigns across multiple worlds (create a new world for major arcs)
- Compress or resize large images before uploading as maps or tokens
- Archive completed scenes rather than keeping all scenes active in a single world
Node.js Memory Limit
By default, Node.js caps memory at ~1.5 GB. For large worlds, increase the heap limit:
node --max-old-space-size=4096 /foundry-app/main.mjs --dataPath=/foundry-data
Set 4096 to approximately 75% of your total available RAM. In Pterodactyl/WISP, add this flag to the startup command in your egg configuration.