-Palhelm is a self-hosted web admin panel for Palworld dedicated servers. It is one Docker image and one process with no external database. It talks to your server three ways: the official REST API, RCON, and the world save file itself, which it parses directly (the 1.0 Oodle-compressed format) with a pure-Go parser. You get a live dashboard, player and pal data, a map, safe backups and restores, and a config editor that edits the thing your server actually reads.
+Palhelm is a self-hosted web admin panel for Palworld dedicated servers. It is one Docker image and one process with no external database. Its three core channels are the official REST API, RCON, and the world save file itself, which it parses directly (the 1.0 Oodle-compressed format) with a pure-Go parser. An optional, separately installed UE4SS bridge can perform tightly bounded item grants after exact-build validation. You get a live dashboard, player and pal data, a map, safe backups and restores, and a config editor that edits the thing your server actually reads.
Full documentation lives at [docs.palhelm.com](https://docs.palhelm.com). The showcase site is [palhelm.com](https://palhelm.com). A companion Discord bot lives at [github.com/8tp/palhelm-bot](https://github.com/8tp/palhelm-bot).
@@ -19,6 +19,7 @@ Full documentation lives at [docs.palhelm.com](https://docs.palhelm.com). The sh
- **Live dashboard.** Server FPS and frame-time history with charts, players-online history, per-channel health (REST, RCON, save sync), and an event feed.
- **Players and Pals.** Online and offline players merged from the live API and save data. Kick, ban, unban. Inspect per-player parties and Palboxes or search the server-wide Pal explorer by owner, placement, level, and Alpha/Lucky/Boss status. Expand a Pal for individual save stats plus version-pinned numeric work-suitability badges.
+- **Optional item grants.** Admins can queue bounded, allowlisted item grants for an online player through a separate UE4SS server bridge. The provider is disabled by default, audited, never edits saves, and stays unavailable until its catalogue and exact game build are validated.
- **Command palette.** Players, actions, navigation, and saved RCON commands from one keystroke. Destructive entries are hidden from read-only viewers.
- **Console.** A real RCON session with history, saved commands, and an honest note about what vanilla RCON cannot do.
- **Live map.** Player and base markers on Palworld 1.0 tiles with Palpagos and World Tree layers. The optional Game Data capability adds ready-only PalBox and exact-linked base-worker health/activity layers; stale or truncated snapshots are never drawn as current. Tiles are game-derived art, so they are never shipped; a one-shot script downloads them into your data volume.
@@ -100,6 +101,10 @@ scripts/fetch-pal-icons.sh ./palhelm-data/pal-icons # pal preview icons
| `PALHELM_GAME_DATA_ENABLED` | `false` | opt in to the Palworld 1.0 live world-actor snapshot poller; requires server-side game-data support |
| `PALHELM_GAME_DATA_INTERVAL` | `30s` | shared game-data snapshot cadence (minimum `15s`; never polled per browser/bot request) |
| `PALHELM_GAME_DATA_TIMEOUT` | `10s` | large snapshot request deadline (`1s`–`30s`) |
+| `PALHELM_ITEM_GRANTS_ENABLED` | `false` | explicitly enable the admin-only item mutation provider; still requires a matching validated catalogue and fresh ready bridge |
+| `PALHELM_ITEM_CATALOG_PATH` | `/item-catalog.json` | operator-installed versioned item catalogue; game data/art are not distributed |
+| `PALHELM_ITEM_ICON_DIR` | `/item-icons` | operator-installed same-origin item icons |
+| `PALHELM_ITEM_GRANT_SPOOL_DIR` | `/item-grants` | local-only request/result directory shared with a compatible server bridge |
| `PALHELM_OODLE_LIB` | unset | path to `liboo2corelinux64.so.9` if you provide your own |
| `PALHELM_INTEGRATION_RATE_LIMIT` | `60` | requests/minute per Integration API key |
@@ -109,6 +114,14 @@ complete `/data` volume before upgrading; rollback to a 0.8.x image requires res
pre-upgrade backup, because the older binary fails closed against the newer schema. See
[the v0.9.0 release notes](docs/releases/v0.9.0.md).
+The unreleased item-grant work adds migration 013 for a durable audit ledger. The
+provider remains disabled by default and is not part of the read-only Integration API.
+Its UE4SS bridge remains `validation_required` until an exact-build maintenance-window
+test proves the inventory mutation and persistence behavior. See
+[the server-mod integration plan](docs/SERVER-MOD-INTEGRATIONS-PLAN.md) before testing
+the bridge; Palworld's official server mod loader does not support the native Linux
+dedicated-server binary.
+
## Known limits
Honest notes so you know what you are getting:
diff --git a/backend/cmd/item-catalog-import/main.go b/backend/cmd/item-catalog-import/main.go
new file mode 100644
index 0000000..4464a56
--- /dev/null
+++ b/backend/cmd/item-catalog-import/main.go
@@ -0,0 +1,507 @@
+// Command item-catalog-import installs an operator-supplied Palworld item
+// manifest and its icons into Palhelm's data directory. Game art is deliberately
+// not distributed with Palhelm.
+package main
+
+import (
+ "encoding/json"
+ "errors"
+ "flag"
+ "fmt"
+ "io"
+ "log"
+ "mime"
+ "net/http"
+ "net/url"
+ "os"
+ "path/filepath"
+ "regexp"
+ "strconv"
+ "strings"
+ "time"
+
+ "github.com/8tp/palhelm/internal/itemgrant"
+)
+
+const maxIconBytes = 4 << 20
+
+var safeID = regexp.MustCompile(`^[A-Za-z0-9_]{1,160}$`)
+
+var numberedSchematic = regexp.MustCompile(`(?i)\s+Schematic\s+([1-4])$`)
+
+var schematicRarities = map[string]string{
+ "1": "Uncommon",
+ "2": "Rare",
+ "3": "Epic",
+ "4": "Legendary",
+}
+
+type manifest struct {
+ GameVersion string `json:"gameVersion"`
+ Source itemgrant.CatalogSource `json:"source"`
+ Items []manifestItem `json:"items"`
+}
+
+type manifestItem struct {
+ ID string `json:"id"`
+ Name string `json:"name"`
+ Description string `json:"description,omitempty"`
+ Category string `json:"category,omitempty"`
+ Rarity string `json:"rarity,omitempty"`
+ IconURL string `json:"iconUrl,omitempty"`
+ IconPath string `json:"iconPath,omitempty"`
+ MaxQuantity int `json:"maxQuantity"`
+ Grantable bool `json:"grantable"`
+}
+
+type palmodsEntry struct {
+ ID string `json:"id"`
+ Name string `json:"name"`
+ HasGameIcon bool `json:"hasGameIcon"`
+ Group string `json:"group"`
+ Canonical bool `json:"canonical"`
+ IconURL string `json:"iconUrl"`
+}
+
+type catalogDocument struct {
+ SchemaVersion int `json:"schemaVersion"`
+ GameVersion string `json:"gameVersion"`
+ Source itemgrant.CatalogSource `json:"source"`
+ Items []itemgrant.Item `json:"items"`
+}
+
+func main() {
+ input := flag.String("manifest", "", "operator-supplied source manifest JSON")
+ palmodsHTML := flag.String("palmods-html", "", "locally saved PalMods item reference HTML (alternative to --manifest)")
+ gameVersion := flag.String("game-version", "", "exact running Palworld version (required with --palmods-html)")
+ outCatalog := flag.String("catalog", "./data/item-catalog.json", "output Palhelm catalogue")
+ outIcons := flag.String("icons", "./data/item-icons", "output icon directory")
+ outAllowlist := flag.String("allowlist", "", "output bridge allowlist (default: item-allowlist.txt beside catalogue)")
+ delay := flag.Duration("request-delay", 750*time.Millisecond, "minimum delay between remote icon requests")
+ validateOnly := flag.Bool("validate-only", false, "validate and summarize the source without downloading or writing")
+ flag.Parse()
+ if (*input == "") == (*palmodsHTML == "") {
+ log.Fatal("set exactly one of --manifest or --palmods-html")
+ }
+ if *delay < 100*time.Millisecond {
+ log.Fatal("--request-delay must be at least 100ms")
+ }
+ if *outAllowlist == "" {
+ *outAllowlist = filepath.Join(filepath.Dir(*outCatalog), "item-allowlist.txt")
+ }
+
+ var doc manifest
+ var err error
+ if *palmodsHTML != "" {
+ if strings.TrimSpace(*gameVersion) == "" {
+ log.Fatal("--game-version is required with --palmods-html")
+ }
+ doc, err = readPalmodsHTML(*palmodsHTML, *gameVersion)
+ } else {
+ doc, err = readManifest(*input)
+ }
+ if err != nil {
+ log.Fatal(err)
+ }
+ if *validateOnly {
+ grantable, icons, err := validateManifest(doc)
+ if err != nil {
+ log.Fatal(err)
+ }
+ log.Printf("validated %d item records for Palworld %s: %d grantable, %d icons", len(doc.Items), doc.GameVersion, grantable, icons)
+ return
+ }
+ if err := os.MkdirAll(*outIcons, 0o700); err != nil {
+ log.Fatal(err)
+ }
+ client := &http.Client{Timeout: 20 * time.Second}
+ out := catalogDocument{SchemaVersion: itemgrant.CatalogSchemaVersion, GameVersion: strings.TrimSpace(doc.GameVersion), Source: doc.Source, Items: make([]itemgrant.Item, 0, len(doc.Items))}
+ seen := make(map[string]bool, len(doc.Items))
+ lastRequest := time.Time{}
+ for index, source := range doc.Items {
+ item, iconSource, err := prepareItem(source)
+ if err != nil {
+ log.Fatalf("item %d: %v", index, err)
+ }
+ key := strings.ToLower(item.ID)
+ if seen[key] {
+ log.Fatalf("item %d: duplicate id %q", index, item.ID)
+ }
+ seen[key] = true
+ if iconSource != "" {
+ ext, extErr := iconExtension(iconSource)
+ if extErr != nil {
+ log.Fatalf("item %s icon: %v", item.ID, extErr)
+ }
+ item.Icon = strings.ToLower(item.ID) + ext
+ target := filepath.Join(*outIcons, item.Icon)
+ if stat, statErr := os.Stat(target); statErr != nil || stat.Size() == 0 {
+ if strings.HasPrefix(iconSource, "https://") {
+ if wait := *delay - time.Since(lastRequest); wait > 0 {
+ time.Sleep(wait)
+ }
+ err = downloadIcon(client, iconSource, target)
+ lastRequest = time.Now()
+ } else {
+ err = copyIcon(iconSource, target)
+ }
+ if err != nil {
+ log.Fatalf("item %s icon: %v", item.ID, err)
+ }
+ if err := validateIcon(target, ext); err != nil {
+ _ = os.Remove(target)
+ log.Fatalf("item %s icon: %v", item.ID, err)
+ }
+ }
+ } else if item.Grantable {
+ log.Fatalf("item %s is grantable but has no iconUrl or iconPath", item.ID)
+ }
+ out.Items = append(out.Items, item)
+ }
+ if out.GameVersion == "" || strings.TrimSpace(out.Source.Name) == "" {
+ log.Fatal("gameVersion and source.name are required")
+ }
+ if err := writeCatalog(*outCatalog, out); err != nil {
+ log.Fatal(err)
+ }
+ if err := writeAllowlist(*outAllowlist, out); err != nil {
+ log.Fatal(err)
+ }
+ if _, err := itemgrant.LoadCatalog(*outCatalog); err != nil {
+ log.Fatalf("post-write validation failed: %v", err)
+ }
+ log.Printf("installed %d item records for Palworld %s; catalogue=%s icons=%s allowlist=%s", len(out.Items), out.GameVersion, *outCatalog, *outIcons, *outAllowlist)
+}
+
+func readPalmodsHTML(path, gameVersion string) (manifest, error) {
+ f, err := os.Open(path)
+ if err != nil {
+ return manifest{}, err
+ }
+ defer f.Close()
+ b, err := io.ReadAll(io.LimitReader(f, (32<<20)+1))
+ if err != nil {
+ return manifest{}, err
+ }
+ if len(b) > 32<<20 {
+ return manifest{}, errors.New("PalMods HTML exceeds 32 MiB")
+ }
+ entries, err := parsePalmodsEntries(string(b))
+ if err != nil {
+ return manifest{}, err
+ }
+ if len(entries) < 2000 || len(entries) > 10000 {
+ return manifest{}, fmt.Errorf("refusing implausible PalMods item count %d", len(entries))
+ }
+ doc := manifest{GameVersion: strings.TrimSpace(gameVersion), Source: itemgrant.CatalogSource{Name: "PalMods game-ID reference (operator import)", URL: "https://www.palmods.gg/docs/authors/game-ids/items", GeneratedAt: time.Now().UTC().Format(time.RFC3339)}, Items: make([]manifestItem, 0, len(entries))}
+ rarities := palmodsRarities(entries)
+ for _, entry := range entries {
+ maximum, permittedGroup := palmodsQuantityPolicy(entry.Group)
+ grantable := entry.Canonical && entry.HasGameIcon && permittedGroup
+ if !grantable {
+ maximum = 1
+ }
+ iconURL := ""
+ if entry.HasGameIcon {
+ iconURL = entry.IconURL
+ }
+ name := strings.TrimSpace(entry.Name)
+ if name == "" || name == "-" || strings.HasPrefix(name, "PV_") {
+ name = entry.ID
+ }
+ doc.Items = append(doc.Items, manifestItem{ID: entry.ID, Name: name, Category: entry.Group, Rarity: rarities[strings.ToLower(entry.ID)], IconURL: iconURL, MaxQuantity: maximum, Grantable: grantable})
+ }
+ return doc, nil
+}
+
+// palmodsRarities derives only grades that the game IDs and localized names make
+// unambiguous. Numbered schematics use Palworld's documented 1–4 quality ladder,
+// and Blueprint_Palhelm is a control panel and Discord companion for your Palworld - server. You host it yourself, in one container. It reads your world and - never writes to it. + server. You host it yourself, in one container. Save parsing is read-only; + optional item grants use a separate, audited server bridge.
Online players come from the live server, everyone else from the save file. See each player's level, playtime, guild and pal party, - with their Steam avatar. Kick, ban or whitelist from the same - screen. + with their Steam avatar. Kick, ban, or—when the disabled-by-default + UE4SS bridge has passed its exact-build checks—queue an allowlisted + item grant from the same screen.
Shown with demo data; pal art appears once icons are fetched. @@ -360,7 +361,9 @@ const DOCS_URL = "https://docs.palhelm.com/";
Under the hood: one program for the panel, one web UI, shipped as a single Docker image. Your data stays in one folder on the host. No - separate database to install or run. Full details are in + separate database to install or run. The optional item-grant bridge is + installed separately on the game server and is not required for the + ordinary read-only panel. Full details are in the docs.