Essentials Game Manager
Essentials Game Manager adds pages for the games your servers run: a game's configuration file as a form instead of a text file, who is playing right now, and Minecraft modpacks, mods and plugins from Modrinth. It also puts a game picture on each egg, so server cards stop showing Pelican's default bird. It is for panels that host game servers. Apart from the Palworld page, nothing appears inside a server until you tell the plugin which of your eggs runs which game.
At a glance
| Plugin ID | essentials-game-manager |
| Current version | 1.4.4 |
| Pelican Panel | 1.0 (tested on 1.0.0-rc.2) |
| Needs | The queue worker (modpack installs and the bulk artwork fetch). Node.js and Yarn on the panel server for Pelican's frontend build at install time. For live player lists: the panel server must be able to reach your game servers' ports. |
| Works with (optional) | Essentials Core (module list, Parts window, artwork library settings), Essentials Arranger (Player count element), Essentials API, Essentials Insights and Essentials Monitoring (they ask Game Manager for player counts), IGDB through a free Twitch developer application (extra egg artwork) |
| Adds | Admin area, sidebar group Essentials Game Manager: pages Minecraft, Other games and Egg artwork. Inside servers whose egg you ticked: Minecraft, Players, Modpacks and Mods & plugins (Minecraft), Server settings, World settings (ARK) or Player lists (Valheim), Players (games that answer Valve's query) and Palworld. |
| Permissions | Role editor section Essentials Game Manager: View, Update, Minecraft, View Minecraft, Games, View Games, Artwork, View Artwork |
Before you install
- Make sure the older all-in-one Essentials plugin (plugin id
essentials) is not running on this panel. See "Things to watch out for". - Know which of your eggs run which game. An egg is Pelican's template for one kind of game server: it says what to install and how to start it, and every server is created from one egg. The plugin cannot guess this from egg names, so you will tick the eggs per game after installing.
- If you want live player lists: the panel server must be able to open a connection to each game server's main address and port (its primary allocation). Minecraft is asked over TCP, the other games over UDP (Valve's server query). A firewall between the panel and the nodes, or nodes on a network the panel cannot reach, means no player list.
- The panel server needs outgoing internet access to Modrinth (search), Steam and
artwork.essentialsplugins.nl(egg artwork). Your nodes need to reach Modrinth's download servers, because mods and modpack files are downloaded by the node itself. - Pelican Panel 1.0 (tested on 1.0.0-rc.2), which needs PHP 8.4 or 8.5.
- Node.js and Yarn on the panel server. The plugin ships a stylesheet, and Pelican builds it into the panel's frontend when it installs the plugin. The build must run as the panel's web user.
- The queue worker (Pelican's background worker, usually the systemd service
pelican-queue). Installs started from the admin area, modpack installs and the bulk artwork fetch all run there. - The
storagefolder must be writable by the web server user. Settings are kept in a file, not in the database.
Command examples in this guide assume Pelican is installed in /var/www/pelican and the web server user is www-data (Debian/Ubuntu). On another setup, adapt the path and the user (for example nginx on some systems).
Check the queue worker with:
systemctl status pelican-queue
Recommended for the worker's systemd unit: Restart=always, and a drop-in with StartLimitIntervalSec=0 under [Unit], so systemd never gives up restarting it after repeated crashes. If it has given up, bring it back with:
sudo systemctl reset-failed pelican-queue && sudo systemctl start pelican-queue
Installing
Download the plugin from the Essentials website, https://essentialsplugins.nl: sign in, open the catalogue, pick Essentials Game Manager and a version, and download the zip. x.y.z is a stable release, x.y.z-beta a test release and x.y.z-dev a development build. Use a stable release on a live panel.
Pick one of these routes. The first is the easiest.
-
From the admin area. Go to Admin -> Plugins -> Import from File and choose the zip. The plugin appears in the list; press Install. Pelican says "Plugin install started in the background". Refresh after a minute until the plugin shows Enabled. (Pelican also has Import from URL.)
-
From the Essentials website. Connect your panel on the website with a Pelican application key (made on the panel under Admin -> API keys, with read and write on Plugins; it starts with
papp_). Then press Install on the plugin's page on the website. -
With Essentials Auto Updater. Its Plugin updates page offers Essentials modules that are not installed yet.
-
Command line (advanced). Unzip so the folder is exactly
/var/www/pelican/plugins/essentials-game-manager, then:sudo chown -R www-data:www-data /var/www/pelican/plugins/essentials-game-manager cd /var/www/pelican sudo -u www-data php artisan p:plugin:install essentials-game-manager sudo -u www-data php artisan p:plugin:listThe list must say the plugin is enabled. Unzipping over an existing plugin folder resets it to "not installed", so always run the install command again after unzipping.
What the install does:
- It creates no database tables. Settings live in
storage/app/private/essentials/game-manager/settings.json. - It clears Pelican's route and view caches and asks the queue worker to restart.
- If the panel ran the all-in-one Essentials plugin before, Game Manager starts with that plugin's egg lists, switches and IGDB keys (the
LEGEND_THEME_*lines in.env) until you save a page here. Permissions that roles held under the all-in-one are copied over once.
After every install or update:
-
If a new page answers 404 or an old version still shows, reload PHP-FPM and restart the worker:
sudo systemctl reload php8.4-fpm sudo systemctl restart pelican-queueUse your own PHP version in the service name.
-
Run artisan, yarn and file commands as the web user (
sudo -u www-data ...), never as root. Files created by root (cache files,public/build) cause errors and failed updates later. -
If styling is missing on the game pages, run the frontend build as the web user:
cd /var/www/pelican && sudo -u www-data yarn build. With Essentials Core installed, the Panel health section on the Essentials page reports missing built assets.
First-time setup
- Give your admin roles access: Admin -> Roles, section Essentials Game Manager. Root Admins already have everything.
- View opens every page of the plugin read-only. Update may change everything.
- Minecraft / View Minecraft: change or only see the Minecraft page.
- Games / View Games: change or only see the Other games page.
- Artwork / View Artwork: change or only see the Egg artwork page.
- The egg list for player counts and the switches for Players, other games and Palworld settings need Update.
- Open Admin -> Essentials Game Manager -> Other games. The section What this plugin adds holds a switch for each part: Other games, Players, other games, Palworld settings, Minecraft and Egg artwork. All are on after a fresh install. Switch off what you do not need and press Save.
- Tick the eggs for each game you host, as described below. Until a part has eggs, its section shows "On, and showing nothing: name the eggs it applies to first."
The pages inside a server follow Pelican's own subuser permissions: a settings page needs permission to read file contents (and to update files to save), the Valve query Players page needs console access, and Mods & plugins needs permission to read and update files, to create files to install one, and to delete files for Remove (changing a version keeps the old file for somebody who may not delete). Modpacks needs permission to update, create, archive and delete files, because installing a pack does all four (from 1.4.4 on).
Minecraft
On Admin -> Essentials Game Manager -> Minecraft:
- Under Which eggs are Minecraft, tick every egg that runs a Minecraft server (Vanilla, Paper, Purpur, Fabric, Forge, whatever yours are called). The list is searchable.
- Optional: switch on Ask servers who is playing. This adds a live list of connected players to the Players page. It is off by default because the panel then connects straight to the game port over TCP. Nothing has to be enabled on the game server.
- Press Save.
Inside each Minecraft server this adds:
- Minecraft: the server's
server.propertiesas a form (message in the server list, game mode, difficulty, players, whitelist, world, view distance, resource pack address and more). Settings the form does not show are listed under Everything else in the file and left untouched. You can only change and save it while the server is stopped, because Minecraft writes this file back when it stops: while it runs, the page says "Stop the server to change these settings" and the fields are locked (from 1.4.2 on). Press Stop the server in that notice (from 1.4.3 on, for anybody allowed to stop the server); the page unlocks by itself once the server has stopped, then change and save. Changes take effect on the next start. - Players: the whitelist, operators, bans and everyone who has played there. Changes (Add to whitelist, Make operator, Ban, Kick and so on) are sent as console commands, so the server must be running and the person needs console access. With Ask servers who is playing on, Online now shows who is connected.
- Modpacks: search Modrinth for server-side packs and install one. No Modrinth account or key is needed. The server must be stopped and stays stopped. The install runs in the background on the queue worker, and you get a notification when it is done.
- Mods & plugins: install a single mod (into
mods/, for Fabric, Forge or NeoForge) or plugin (intoplugins/, for Bukkit, Spigot or Paper) from Modrinth, change its version, Check for updates or Remove it. The server must be stopped.
Other games
On Admin -> Essentials Game Manager -> Other games, each game has its own section with an egg list. Tick the eggs that run that game and press Save. A page then appears inside those servers:
| Game | Page inside the server | File it edits |
|---|---|---|
| ARK | World settings | ShooterGame/Saved/Config/LinuxServer/GameUserSettings.ini |
| Don't Starve Together | Server settings | cluster.ini, Master/server.ini and Caves/server.ini under DoNotStarveTogether/config/server |
| Enshrouded | Server settings | enshrouded_server.json |
| Factorio | Server settings | config-controller.json and config-host.json |
| Satisfactory | Server settings | Game.ini and Engine.ini under FactoryGame/Saved/Config/LinuxServer |
| Terraria (vanilla or tModLoader) | Server settings | serverconfig.txt |
| V Rising | Server settings | save-data/Settings/ServerHostSettings.json |
| Onset | Server settings | server_config.json |
| Craftopia | Server settings | ServerSetting.ini |
| Project Zomboid | Server settings | .cache/Server/servertest.ini, .cache/Server/pzserver.ini or Zomboid/Server/servertest.ini |
| Conan Exiles | Server settings | ConanSandbox/Saved/Config/WindowsServer/ServerSettings.ini |
| Arma Reforger | Server settings | config.json |
| Valheim | Player lists | adminlist.txt, banlist.txt and permittedlist.txt |
How these pages work:
- Server settings pages show every setting the file contains, with the names the game itself uses. Nothing is translated or grouped. Comments, blank lines, the order of the file and unknown keys are kept exactly as they were when you save.
- World settings (ARK) shows the settings people change most, with labels.
- Player lists (Valheim) edits admins, bans and the permitted list as three lists. Saving creates the files you fill in.
- The game reads its file when it starts, so restart the server after saving. Valheim's player lists are the exception: Valheim reads them while it runs, so changes apply without a restart.
- A game writes its config file the first time it runs. On a server that has never been started, the page says the file is not there yet ("This server has no settings file yet"). Start the server once and the page fills in.
- Everything else about these games is set through their startup variables, which Pelican's own Startup page already edits.
Players for other games
On the Other games page, the section Player counts has the list Eggs that answer the Valve query. Tick the eggs of games that answer Valve's server query: Rust, ARK, Valheim, 7 Days to Die and most games on Source or Unreal. Press Save.
Those servers then get a Players page that shows who is connected, their score and how long they have been on. It only reads; it cannot kick or ban. Ask again refreshes it (answers are kept for about twenty seconds).
The same list decides which servers other Essentials modules can show a player count for. The panel asks the game on the server's main port over UDP, so a game that only answers the query on a separate query port shows no list. If that port cannot be reached from the panel, the page says "The server did not answer" and no number is shown.
Palworld
Palworld needs no egg list. With Palworld settings switched on, a Palworld page appears inside any server whose egg name contains "palworld", or that has a PalWorldSettings.ini file. It edits the world settings from that file. You can only save while the server is stopped, because Palworld writes the file again when it stops. Changes take effect on the next start.
Egg artwork
Open Admin -> Essentials Game Manager -> Egg artwork. Every egg is listed with its picture. Per egg you can:
- Library: pick a logo from the Essentials artwork library (
artwork.essentialsplugins.nl). No key is needed. - Steam: enter the Steam App ID (the number in the store address, for example
892970instore.steampowered.com/app/892970). - IGDB: search IGDB by game name. Only shown once IGDB credentials are saved.
- Upload: your own picture, up to 4 MB. Anything other than PNG, JPEG or WebP (an SVG, for example) is converted to WebP.
- Lock / Unlock: a locked picture is never replaced by a bulk fetch. Choosing a library logo, entering a Steam App ID or uploading locks it automatically.
- Clear: removes the picture, the Steam App ID and the library logo.
Fetch all missing looks up every egg that has no picture and is not locked: first in the artwork library, then on Steam by name, then on IGDB if credentials are saved. It runs in the background on the queue worker and sends you a notification when it is done.
Optional IGDB credentials, for games the library and Steam do not have (console games, many modded eggs):
- Sign in at https://dev.twitch.tv/console with a Twitch account and register an application. It is free.
- Generate a client secret.
- On the Egg artwork page, press Credentials, paste the Twitch client ID and Twitch client secret, and confirm the window.
The secret is stored encrypted and never shown again. Leave the field empty later to keep it, or type a new one to replace it.
With Essentials Core installed, the artwork library is reached through Core, which holds the library's address and an optional key.
Essentials Arranger element (optional)
With Essentials Arranger installed, the page editor offers a Player count element. It shows how many people are on the server a page is about, with a Title (default "Players online") and List who is on. Names are only shown to people the server's own players page would show them to, and only for games that report names. It uses the same answers as the Players pages, so the egg lists above apply.
Things to watch out for
- Nothing shows until eggs are ticked. This is on purpose. All five parts are switched on after install, and three of them (Minecraft, Other games and Players, other games) do nothing until their egg list is filled in. With Essentials Core installed, the module list says which parts are still waiting.
- The Valve query egg list opens connections. Ticking eggs there makes the panel send UDP packets straight to those game ports. It also decides which servers get a Players page.
- Live Minecraft players is off by default. Switch on Ask servers who is playing on the Minecraft page if you want it; the panel must reach the game port over TCP.
- Stop the server first for the Minecraft page, the Palworld page, Modpacks and Mods & plugins. The Players page for Minecraft is the opposite: it needs the server running.
- Modpacks never delete anything. Not your world, not your old mods, not a config. A pack installed on top of another leaves both, so remove the previous pack's mods yourself first if you want a clean switch. Pick the version whose loader matches the egg: installing a pack does not change the egg or the startup command.
- Only Modrinth downloads. Files a pack asks for from anywhere other than Modrinth's download servers are skipped, and the result notification says how many.
- Nothing checks mod compatibility. Check for updates only knows what is newer on Modrinth, not what fits your Minecraft version or loader. Check that before starting the server. Files that were already in the folder show as unknown until you use Change version once to say what they are. Remove cannot be undone from the panel.
- Egg tags. The artwork feature stores the Steam App ID, the library logo and the lock in the egg's own tags (
steam:...,library:...,icon:protected). They are visible in Pelican's egg editor. Deleting them there loses that link or lock. - IGDB secret and
APP_KEY. The Twitch client secret is encrypted with the panel'sAPP_KEY. If that key changes (for example after moving the panel without copying.env), the secret can no longer be read. Paste it again. - Project Zomboid sandbox settings (zombie counts, loot) are not offered, because the game rewrites that file on every start.
- Some games report odd player lists. What the Valve query returns is what the game chooses to report; some games list bots as players, and some list nobody while their player count says otherwise.
- Saving a role while this plugin is switched off removes its permissions from that role. Pelican only keeps the permissions of plugins that are running when a role is saved. Switch the plugin back on before editing roles.
- Do not run it next to the all-in-one Essentials plugin. "Essentials" (plugin id
essentials) is the older plugin that contains what the modules now do separately. Installing a module switches the all-in-one off; installing the all-in-one on a panel with modules can switch modules off; and uninstalling the all-in-one deletes database tables the modules share (shop, tickets, API keys), which loses that data. Pick one: the all-in-one, or the modules. An all-in-one release too old to hand the game pages over makes this plugin refuse to start, with a message saying so.
Things to keep an eye on
- Waiting notes. With Essentials Core, the module list shows "Minecraft pages are on, but no egg is marked as Minecraft.", "Game settings pages are on, but no egg is assigned to any game." or "Player lists are on, but no egg is marked as answering the Steam query." when a part has nothing to do. Tick the eggs or switch the part off.
- New eggs. An egg you import later is not in any list and has no picture. Tick it on the right page and run Fetch all missing on Egg artwork.
- The queue worker. If modpack installs or the bulk artwork fetch never report back, check
systemctl status pelican-queue. - Mods. Run Check for updates on Mods & plugins now and then. Versions with a newer release are marked in the list.
- Logs. Errors go to
storage/logs/laravel-YYYY-MM-DD.log(orlaravel.log). Pelican's log viewer reads the whole file, so very large logs (around 100 MB) make it fail; Essentials Core warns above 50 MB. - Backups. Include
storage/app/private/essentials,storage/app/private/legend-theme/resourcesand the database in your backups.
Updating
- Download the new version and import it the same way (Pelican shows Update on the plugin when an update is known), or let Essentials Auto Updater do it.
- The plugin switches itself back on after an update through the admin area. Egg lists, switches, credentials and artwork are kept.
- It keeps no data in database tables of its own, but egg artwork lives on the eggs, so a normal database backup before updating is still a good idea.
- After the update, do the "After every install or update" checks above if a page still shows the old version.
Removing it
Uninstalling the plugin through Admin -> Plugins removes its code and its pages. It does not delete:
storage/app/private/essentials/game-manager/: the settings file (egg lists, switches, the encrypted IGDB credentials) and small marker files.storage/app/private/legend-theme/resources/: one file per server recording which Modrinth project each installed mod came from. The all-in-one Essentials plugin uses the same folder.- Egg pictures. They are stored as Pelican's own egg icons, so they keep showing after the plugin is gone. Remove them with Clear before uninstalling, or in Pelican's egg editor.
- The
steam:,library:andicon:protectedtags on your eggs. - Anything the plugin changed inside servers: saved config files, installed modpacks and mods stay as they are.
- The permissions you gave roles. They have no effect once the plugin is gone.
Reinstalling later picks the settings up again. To remove the files by hand:
sudo rm -r /var/www/pelican/storage/app/private/essentials/game-manager
Only delete storage/app/private/legend-theme/resources as well if the all-in-one Essentials plugin is not used on this panel.
Troubleshooting
| Problem | What to do |
|---|---|
| No game page appears inside a server | Check that the part is switched on (Other games page, What this plugin adds), that the server's egg is ticked in that game's section, and that the person has the subuser permission to read file contents on that server. |
| The Minecraft or Egg artwork page is missing from the sidebar | That part is switched off. Switch it on again on the Other games page, which always stays. Otherwise give the role the matching permission in the Essentials Game Manager section of Admin -> Roles. |
| "This server has no settings file yet" or "No server.properties found" | The game writes its file on the first start. Start the server once, then reload the page. |
| "The server is running" when saving | Stop the server and save again. Minecraft and Palworld write their files when they stop, which would undo your change. |
| The Valve query Players page says "The server did not answer" | The server may still be starting, or the panel cannot reach its game port over UDP. Check firewalls between the panel server and the node. The panel asks the IP address on the server's main allocation; for an allocation on 0.0.0.0 it asks the allocation's alias, or the node's address when there is no alias (from 1.4.1 on; 1.4.0 asked 0.0.0.0 itself, which only answers when the game runs on the panel's own machine). If the node's address is behind a proxy such as Cloudflare, give the allocation an alias the panel can reach. |
| No Online now line on the Minecraft Players page | Switch on Ask servers who is playing on the Minecraft page, and make sure the panel can reach the game port over TCP. |
| "The install could not be queued" (modpacks) or "It could not be handed to the queue" (artwork), or nothing ever finishes | The queue worker is not running or was started before the plugin was installed. Run sudo systemctl restart pelican-queue and check systemctl status pelican-queue. |
| "The pack could not be fetched or unpacked" or "The node refused the download" | The node could not reach Modrinth or is out of disk space. Check the node's internet access and free space. |
| The IGDB button is missing on Egg artwork | No IGDB credentials are saved. Use Credentials to add the Twitch client ID and secret. |
| "Twitch would not issue a token" | The client ID or secret is wrong, or the secret was regenerated. Paste both again under Credentials. After moving the panel, the APP_KEY may have changed; paste the secret again. |
| "The picture could not be written" | Run sudo chown -R www-data:www-data /var/www/pelican/storage and make sure php artisan storage:link has been run (as www-data). |
| "Could not save the settings" with "Could not save the Essentials Game Manager settings. Check that storage/app belongs to the user the panel runs as." | The web user cannot write to storage/app. Fix the ownership as above; the exact reason is in storage/logs. |
| The plugin will not start: "Update legacy Essentials to a version supporting standalone Game Manager, or disable legacy Essentials before enabling this plugin" | An older all-in-one Essentials plugin is enabled. Switch it off under Admin -> Plugins. Read "Things to watch out for" before uninstalling it. |
| Minecraft settings do not save, or there is no Save button | The server is running. Press Stop the server in the notice at the top (1.4.3 and later) or stop it from the console; the page unlocks once it has stopped. On 1.4.1 and older, stop it and reload the page. |
Essentials is a community project by Legend Development. Not affiliated with or endorsed by the Pelican team.