Skip to content

About

Community schema registry for Palworld PalSchema raw-table mods - 31 SDK-verified DataTable schemas + validator CLI

Topics

Resources

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

 

History

98 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

🧩 palschema-hub

registry 0.13.0 PalSchema 0.6.71 UE4SS 2281fa31 Palworld 1.0.5 license MIT

A public schema registry + browser + validator CLI for Palworld PalSchema mods.

PalSchema lets modders patch Palworld's DataTables with JSON. But there has been no browsable list of what fields each table actually has — the community has literally been asking for this (PalSchema issue #53, open since Aug 2025). palschema-hub fills that gap:

  • /schemas/v1.0/*.schema.json — 31 JSON Schemas, one per moddable DataTable.
  • /schemas/index.json — machine-readable table-name → schema-path listing.
  • /schemas/info-json.schema.json — JSON Schema for an official Workshop package's Info.json (Palworld's first-party mod system, alongside the UE4SS-era PalSchema format above).
  • /values/<Table>.json — the current row values for 28 of those tables (41,402 rows), read out of the game's own cooked DataTables. Browse them at values.html.
  • /index.html — a zero-build schema browser (GitHub Pages), searchable.
  • /cli/ — palschema-validate, a CLI (ajv) that validates mod JSON/JSONC in CI or locally.
  • /.github/workflows/palschema-ci.yml.example — drop-in CI for mod repos.

Compatible with PalSchema 0.6.71 + the UE4SS build it requires (UE4SS commit 2281fa31, released September 3 2026). No DataTable field, path, or row-validation behavior changed in 0.6.1 → 0.6.71 (checked against the diffs, not just the release notes). What did change: 0.6.4's loader lets new pals carry ranch suitability through RanchActionData in pals json (#143) — a key that exists only in PalSchema's loader, never on a UE row struct, so this registry tracks it (and every other loader-implemented key) in structs/loader-overlay.json, read off the loader source with per-entry provenance. 0.6.5 rewrote the constraints in PalSchema's own assets/schemas/items.schema.json (#145) — those are now ported into this registry's item-loader schema (see structs/upstream-constraints.json), so the validator catches bad icon paths, out-of-range values and missing new-item fields it used to wave through. 0.6.6, 0.6.7 and 0.6.71 touch nothing this registry derives from: 0.6.6 is only the UE4SS bump to 2281fa31, 0.6.7 fixes an FSoftObjectPtr crash in the appearance loader (#149), and 0.6.71 is a signature refresh (include/SDK/PalSignatures.h, two lines) on the same UE4SS build. That is a finding, not an assumption: the upstream 0.6.4...0.6.71 compare leaves assets/schemas/items.schema.json at blob b41a965 for all four tags, and adds no loader key to any of PalItemModLoader, PalMonsterModLoader or PalHumanModLoader. 0.6.3 also fixed .jsonc schema application (#139) and added unknown-property warnings to the item loader (#138) — the same warn-don't-reject semantics palschema-validate adopted in 0.4.0. Validated against real published PalSchema mods — see tests/real-mods/SOURCES.md.


⚠️ About the schema data (provenance — read this)

The schemas are built from two real game-data sources, cross-checked:

  1. Observed row data from the public FModel DataTable dump in blaynem/paldex (Jan 2024) — provides real example values and observed serialization shapes.
  2. Current-game row structs from the decompiled SDK localcc/PalworldModdingKit (commit 62fad41, pushed 2026-07-11) — authoritative field names and C++ types for today's Palworld 1.x. Every schema's field list is verified against its row struct header (scripts/augment-from-sdk.mjs): fields the game added since the dump are included (e.g. InstallMaxNumInBaseCamp, CraftExpRate, drop slots 6–10), and fields the game removed/renamed are dropped (e.g. RedialIndex→SortId, PalID→PalId, HP→Hp). A few moddable tables that postdate the dump entirely (e.g. DT_FieldLotteryNameDataTable, used by drop-rate mods) are emitted from the SDK headers alone via scripts/derive-sdk-tables.mjs, with each table→struct mapping confirmed by a real mod that patches it.

Typing conventions match PalSchema's own generator and loader (verified in its JsonSchemaGenerator.cpp / PropertyHelper.cpp / PalRawTableLoader.cpp):

  • ints → integer, floats → number, FName/FString/FText → string. Integer-ness comes from the SDK header, not from the dump: JSON has no integer type, so 158 int32 columns were typed number (and accepted 1.5) until 0.7.0 aligned them.
  • Arrays accept both PalSchema forms: a plain [...] (replaces the game array) or {"Action": "Clear", "Items": [...]} (optionally clear, then append).
  • Enum fields are string and list the current game's enum values in their description (both EEnum::Value and short Value spellings are accepted in-game).
  • $Filters (PalSchema's wildcard-row filter metadata) is allowed in any row.

This is a community-derived registry, not the output of PalSchema's own Schema Generator (UE4SS Debugging Tools → Pal Schema tab → Generate JSON Schema Files — a local-only artifact that is not published anywhere). If you run the official generator, its output can supersede these files with zero code changes: drop the *.schema.json files into schemas/v<palworld_version>/ and run npm run index.

Data credit: DataTable dumps © their extractors (blaynem/paldex); SDK headers via localcc/PalworldModdingKit. PalSchema © Okaetsu. This repo only redistributes derived structure (field names/types), not game assets.

Proven against real published mods

npm test validates four real PalSchema mods from Nexus (provenance: tests/real-mods/SOURCES.md): Palvolve, Unlimited Buildings, and Old School Loot validate clean (10/10 files); Accessory Condenser gets a warning for one genuinely stale field (RedialIndex, removed from the game) — the same thing PalSchema logs as Property 'RedialIndex' not found in Row ... at load time, caught here before you ever launch the game (and promoted to a failing error with --strict).


The validator CLI: palschema-validate

Validates PalSchema mod files. A mod file targets one or more DataTables by name:

{
  "DT_PalDropItem": {
    "ChickenPal000": { "ItemId3": "Pizza", "Rate3": 100.0, "min3": 1, "Max3": 1 }
  }
}

The CLI recognizes all three PalSchema mod-file shapes: raw table files (top-level DT_* keys, or a $schema field / DT_*-prefixed filename), pal-loader files ({ "<CharacterId>": {...} }, from a pals/ folder or by their fields), and item-loader files ({ "<ItemId>": {...} }, items/ folder or fields; a null entry is the delete syntax). It fetches the right schema from the registry — DT_PalMonsterParameter plus the loader overlay for pals, PalStaticItemData (derived from the UPalStaticItemData* class headers, the set the item loader actually matches against) for items — validates every row with ajv, and prints field-level errors. .json and .jsonc behave identically.

Item-loader files also get the value constraints from PalSchema's own items.schema.json (0.6.5), ported field by field in structs/upstream-constraints.json: IconTexture must be a /Game path whose asset name repeats after the dot (T_icon_X.T_icon_X — a mismatch is reported naming both parts) or a $resource/<Mod>/<Image> import; VisualBlueprintClassSoft needs the _C class suffix; Rarity is 0–4, Rank/Price ≥ 0, MaxStackCount ≥ 1 (above 9999 warns — the game duplicates items past that); and Weight, CorruptionFactor, Durability, SneakAttackRate and Recipe.WorkAmount must be float literals (1.0, not 1) — checked on the raw file text, because JSON.parse erases the difference. The upstream required list (Type, IconTexture, TypeA, TypeB, Rank, Rarity, MaxStackCount, plus Product_Count/WorkAmount/Material1_Id/Material1_Count inside Recipe) applies only when the entry has a Type key: Type is required when adding and ignored when editing, so a partial patch of an existing item stays valid. A field used outside its item class — WazaID on a Weapon, HPValue on a Consumable — warns with the class that declares it (the loader ignores it; the game also warns since 0.6.3). The scoping is keyed on Type with if/then, derived from the SDK class headers — upstream's own per-Type anyOf branches don't actually enforce scope, and its Weapon branch's AttackPower is a typo for AttackValue (this registry scopes the real name and doesn't add the typo).

A key the schema doesn't declare is a warning with a did-you-mean suggestion, not a rejection — the semantics PalSchema itself is adopting (Okaetsu/PalSchema#134) — so a legitimately-new game field can never turn into a build-breaking false positive. Each warning also says whether the game would catch it:

  • Item-loader files: since 0.6.3 PalSchema itself warns about unknown properties at load time (#138), so there this scan duplicates the in-game warning — its value is catching the typo in CI, before anyone launches the game.
  • Pal-loader files: the pal loader has no warning branch at all — an unknown key is silently dropped in game (#134, still open). A typo'd pal field is caught by this scan and by nothing else.
  • Raw table files: the raw loader has always warned in game; behavior here is unchanged.

PalSchema's pseudo-keys ($Filters, the {"Action":"Clear","Items":[…]} array wrapper) and its loader-implemented keys (RanchActionData, Loot, AbilitiesByLevel, Recipe, Type, ... — see structs/loader-overlay.json) never warn:

WARN mods/pals/mypal.json:Lamball unknown field "rarity" — did you mean "Rarity"? (not caught in game: PalSchema's pal loader silently ignores unknown fields — Okaetsu/PalSchema#134)
1 file validated, 0 errors, 1 unknown-key warning

--palschema-version <v> targets a specific PalSchema release: loader keys newer than the target are flagged with the release they need, not a generic unknown-field message —

$ palschema-validate --palschema-version 0.6.3 pals/mynewpal.json
WARN pals/mynewpal.json:MyNewPal "RanchActionData" requires PalSchema >= 0.6.4 when adding new pals; edits to existing pals are unaffected (you targeted 0.6.3) — https://github.com/Okaetsu/PalSchema/pull/143

Exit codes: 0 = all files pass (warnings alone never fail a run) · 1 = any type/shape error, breaking --migrate field, or bad usage — or any warning when --strict (the CI mode) is given · 2 = the registry itself could not be read (bad --registry, network failure, or a GitHub rate limit), so nothing was validated. A table this registry simply does not carry stays a warning; only a registry that could not answer at all is exit 2.

# From any mod repo (schemas fetched from this registry):
npx palschema-validate ./mods/                       # newest known game version
npx palschema-validate --palschema-version 0.6.3 mod.json

# Against the schemas in THIS checkout (no publish needed):
node cli/dist/index.js --registry . tests/valid-mod.json    # exit 0
node cli/dist/index.js --registry . tests/invalid-mod.json  # exit 1

Options

flag meaning
--version <v> Palworld version to validate against (default: the newest the registry knows)
--palschema-version <v> PalSchema release to target (e.g. 0.6.3); loader keys newer than it are flagged. Unknown values fail loudly
--migrate <a>..<b> scan mods for fields removed/retyped between two game versions (e.g. 0.7.2..1.0) — mutually exclusive with --version
--registry <r> schema source: a base URL, or a local repo-root path (.). Default: https://raw.githubusercontent.com/<owner>/palschema-hub/main
--owner <o> GitHub owner for the default registry URL (default Booyaka101, or $PALSCHEMA_OWNER)
--strict CI mode: promote warnings to errors (exit 1)
-h, --help usage

Official mods (Workshop)

Palworld now also ships a first-party mod system: packages live under Mods/Workshop/<folder>/Info.json, declare an array of InstallRule entries, and on the next launch the loader deploys them — creating Mods/ManagedMods/<PackageName>/InstallManifest.json — while selection happens via ActiveModList in Mods/PalModSettings.ini (or a -workshopdir launch argument). A rule names a Type — the install root inside the game directory (UE4SS, Lua, PalSchema, LogicMods, Paks) — and Targets: the package-relative paths to copy there. That is a second, older-ecosystem format than the PalSchema (UE4SS) JSON this registry started with, and this hub validates both, so it stays usable as the ecosystem migrates.

The new CLI mode is check-package (alias: palsc, same binary):

npx palschema-validate check-package ./MyMod

Real run against the labelled example package in examples/official-mod/:

✓ examples\official-mod — "ExampleMod" v1.0.0
    rule 1: Lua -> Mods/NativeMods/UE4SS/Mods/ExampleMod  (./Scripts)
    rule 2: Paks -> Pal/Content/Paks/~WorkshopMods/ExampleMod  (./Paks/ExampleMod_P.pak · server)
official package OK: 2 rules validated
1 package checked, 0 errors, 0 warnings

And a broken one — after changing rule 2's target to ../save:

✗ tests\fixtures\packages\escape — "MyMod" v1.0.0
    rule 1: Lua -> Mods/NativeMods/UE4SS/Mods/MyMod  (./Scripts)
    rule 2: Destination escapes game directory: ../save
1 package checked, 1 error, 0 warnings

What it checks (exit 0 = valid, 1 = errors; warnings and notes never fail a run, --strict promotes them):

  • Info.json parses — UTF-8 BOM and UTF-16 encodings are detected, decoded and reported, so a file saved by a scripting tool is checked instead of rejected.
  • Required keys: PackageName (non-empty string) and the InstallRule array. The InstallRules spelling is accepted as an alias with a warning — the official key is singular (read off Pocketpair's own uploader source, Models/ModInfo.cs).
  • Every rule: a Type (unknown values warn, official ones name their install root), Targets as a non-empty array of non-empty strings, IsServer a boolean when present. A package with no IsServer: true rule gets a note: dedicated servers will not run it.
  • Every Target exists inside the package folder, and no Target escapes the game directory — any .. segment is the error above, because the rule's destination would land outside the game.
  • Duplicate PackageNames fail, naming every declaring path — across a Workshop root and nested inside one package. Only one of them would ever be enabled, and the order is not guaranteed.
  • A Mods/ConfigOverrides directory next to the package is scanned: folders keyed by a scanned PackageName or a numeric Workshop ID have their JSON files parsed; any other folder is an informational note only.
  • When a scan covers a Workshop root or game directory, a sibling Mods/PalModSettings.ini is linted too: bGlobalEnableMod=false warns (nothing will load), a package absent from ActiveModList is noted as present-but-not-enabled, and an ActiveModList entry naming no scanned package is noted in the other direction. Single-package scans skip this — checking one mod of ten would only produce noise about the other nine.
  • Extras: an absent Version is noted (the loader detects updates by comparing Version strings), declared Dependencies are surfaced, and a declared Thumbnail that is not in the package warns.

--json prints one machine-readable object (packages / palModSettings / configOverrides / summary) instead of human output — same exit codes, nothing else on stdout — so a mod repo can turn findings into CI annotations.

Like --migrate, this mode needs no registry, no network and no dependencies — it reads only the package folder, so it runs straight from the offline archive and in CI. The field contract also ships as a standalone JSON Schema: schemas/info-json.schema.json.

The hub gained a package checker page showing the official / UE4SS badge for any pasted JSON (or a loaded file, or the labelled examples it fetches from examples/) plus the same JSON-level rules; the CLI remains the full check because only it can see the package folder. Test fixtures for every case above live in tests/fixtures/packages/.


Every table's values, from the game itself

values.html browses the current row values for 28 of the 31 registry tables — 41,402 rows — pals, passives, waza, recipes, drops, lotteries and the rest, each row with a paste-ready raw-table patch. values/<Table>.json is the same data as plain JSON, and values/index.json lists what shipped, the row struct each table uses, and which three tables do not extract yet (with the reason).

This is read out of the game's own cooked DataTables by scripts/extract-tables.mjs (npm run extract), not scraped: Pal-Windows.pak (pak v11) → full directory index → the file's own block table → Oodle → the package name table → unversioned properties, resolved through a .usmap mappings file. Palworld statically links Oodle and ships no redistributable oo2core, so decompression goes through tools/ooz-decompress, a small Rust helper built on the pure-Rust oozextract crate. You only need any of that to re-extract — the registry ships the JSON, and the CLI never touches it.

The gate is the interesting half. npm run check:values validates every extracted row against the published schema for its table. The two come from independent sources (schemas from SDK headers plus a community dump, values from the game), so them agreeing is real evidence for both — and it immediately caught seven asset-reference fields typed object that would have rejected the plain asset paths the game itself stores. It also cross-checks the extracted item table against the scraped items.json, which is how you find out a scrape has drifted.

Values are derived data — numbers and identifiers only, the same class of content the item and building references already carried. No game asset is redistributed.

Item asset reference (values, not just schemas)

items.html is a searchable per-item value reference for DT_ItemDataTable — 2,445 rows, current-game (Palworld 1.0.4, 2026-09-07): row name → ItemActorClass / ItemStaticClass / ItemDynamicClass / visual fields, plus stats (SortId, Rarity, Durability, Defense/Health) and the full row JSON to copy as a base for variants. Motivated by PalSchema #53: cloning an equipment row without its ItemActorClass silently loses the model in-game (the game ships variants by pointing at another item's actor, e.g. LightzHelmet → "IronHelmet"). Machine-readable: items.json.

Where the data comes from (the 0.4.0 source change). Until 0.4.0 the values came from the public paldex FModel dump — frozen at Jan-2024 (947 rows, and the dead field SortID, which the current game renamed to SortId, so the file failed our own schema). Now scripts/build-items.mjs scrapes paldb.cc (robots.txt Allow: /; the site tracks the live game — 2,466 listed rows at 1.0.4), one cached page per item, one row per rarity variant. The scrape reads paldb's own version footer and refuses to write if it disagrees with the build the script claims to be capturing, and the page cache is keyed by game version so a balance patch can't be rebuilt from the previous build's HTML. Merge rule: fields paldb.cc doesn't render (VisualBlueprintClassSoft, DropItemType, GrantEffect*, TechnologyTreeLock, …) are filled from the old paldex file where the row existed in Jan-2024; paldb wins every conflict; the per-row split is recorded in the top-level fieldSources object; rows only in the old file are kept (marked by fieldSources[row].paldb = []). A few TEST/untranslated rows have no paldb page and are absent (~20 of 2,466 — reported by the build).

The data is gated: npm run check:items validates every row against schemas/v1.0/DT_ItemDataTable.schema.json (ajv strict, additionalProperties: false) and asserts freshness — ≥ 2,400 rows, no SortID anywhere, the 1.0-only SFHelmet row (Hexolite Helmet) present, ≥ 200 real ItemActorClass values, fieldSources complete. It runs in npm test, so a stale regeneration cannot ship silently. Regenerate any time with npm run items (re-runs are free — pages cache under .cache/paldb/); parsed fields that are not in the schema are printed at the end, which is how new game fields get noticed.

Building reference (two tables, one row name)

buildings.html is the same idea for buildings — 483 rows, current-game (Palworld 1.0.4) — and untangles the part people trip on (issue #21): a building spans two DataTables sharing one row name. The Egg Incubator is HatchingPalEgg in DT_MapObjectMasterDataTable (world-object side: Hp, Defense, DeteriorationDamage, …) and in DT_BuildObjectDataTable (build side: TypeA/TypeB, Rank, SortId, BuildExpRate, …), while the unlocking DT_TechnologyRecipeUnlock row prefixes it (Special_HatchingPalEgg, with UnlockBuildObjects: ["HatchingPalEgg"]). Each building page shows both rows, the materials mapped back to item Codes, and copy/paste JSON for a raw-table mod.

scripts/build-buildings.mjs scrapes paldb.cc's ten construction category pages (which render the raw field names), routes every field to the table whose schema declares it (the two schemas share no field name), and refuses to write when paldb's version footer disagrees with the build it claims to capture. Fields paldb doesn't render (BlueprintClassName, RequiredBuildWorkAmount, the raw Material1..4 columns) are absent, not zero. Gate: npm run check:buildings, run by npm test.

Those category indexes cover a shifting subset. The 1.0.4 crawl stopped listing 16 buildings whose detail pages are still live and whose rows the game still ships (DT_BuildObjectDataTable is byte-identical across 1.0.3 and 1.0.4), HatchingPalEgg among them, so a plain re-scrape would have deleted them. Anything the previous file carried is queued by display name instead and re-read from its own page like every other row; _provenance.carriedForwardRows counts them.

Lottery buildings (the Ancient Relic Recycler)

Not every producing building uses DT_ItemRecipeDataTable. The Ancient Relic Recycler (AncientRelicRecycler) has no recipe rows at all, which is why searching for AncientRelicRecycler_WorldTreeRelic_01…_05 turns up nothing (asked on the Nexus posts tab). Those names are lottery names, and the chain runs through three places, only two of which PalSchema can reach:

  1. The building blueprint holds UPalMapObjectRecyclerParameterComponent, whose RelicItemSettings is a TMap<ItemId, FPalRecyclerRelicItemSetting> mapping each input relic (WorldTreeRelic_01…_05) to a LotteryName plus a RequiredWorkAmount. This is blueprint data, not a DataTable, so which relic feeds which lottery (and how long it takes) is out of PalSchema's reach.
  2. DT_FieldLotteryNameDataTable — one row per lottery name, holding only ItemSlot1_ProbabilityPercent … ItemSlot15_ProbabilityPercent: the chance each slot rolls at all.
  3. DT_ItemLotteryDataTable — the contents. Row keys here are meaningless counters ("1", "2", "3", …); the join back to the lottery is the FieldName column, with SlotNo / WeightInSlot / StaticItemId / MinNum / MaxNum per entry.

So a new recycler output is a new DT_ItemLotteryDataTable row under a key the table doesn't already have (PalRawTableLoader::Apply sends unknown keys to AddRow):

{
  "DT_ItemLotteryDataTable": {
    "90001": {
      "FieldName": "AncientRelicRecycler_WorldTreeRelic_05",
      "SlotNo": 1,
      "WeightInSlot": 10,
      "StaticItemId": "Blueprint_AncientHelmet_4",
      "MinNum": 1, "MaxNum": 1, "NumUnit": 1
    }
  }
}

Two traps. SlotNo must be a slot the matching DT_FieldLotteryNameDataTable row actually rolls (ItemSlotN_ProbabilityPercent > 0) or the entry can never come out, and WeightInSlot is relative to the other entries sharing that FieldName + SlotNo, so adding one dilutes the existing pool rather than stacking on top of it. The same wiring drives the other lottery consumers (treasure boxes, field drops), which is why FieldName values like Grass01 sit in the same table.

The short version of this rides on both tables in the schema browser — per-table notes live in table-notes.json, which scripts/build-index.mjs bakes into index.json and npm run check gates against drift.

Provenance: read off PalMapObjectRecyclerParameterComponent.h and PalRecyclerRelicItemSetting.h in the SDK headers this registry already tracks (localcc/PalworldModdingKit@62fad41). The structure is verified; the recycler's own vanilla rows are not in the value set, so dump both tables in FModel and filter on FieldName before picking slot numbers or weights.

What changed between game versions

Every Palworld patch can add, remove, or rename DataTable row-struct fields — and a PalSchema mod that sets a field the game no longer has silently does nothing (or errors at load). diff.html shows the field-level delta between any two game versions, and the CLI scans your mod for it:

npx palschema-validate --migrate 0.7.2..1.0 ./mods/

Real output (a mod setting the pre-1.0 partner-skill text field):

palschema-validate · migrate 0.7.2 → 1.0 · 1 file(s)

  ✗ tests/migrate-fixtures/partner-skill.json
      tests/migrate-fixtures/partner-skill.json > DT_PalMonsterParameter > ChickenPal000 > OverridePartnerSkillTextID: removed in 1.0 (was FName) — possible rename to OverridePartnerSkillNameTextID (medium confidence)

1 file(s) scanned · 1 breaking field(s) in 1 file(s)

That is a real, verified 1.0 change to PalCharacterParameterDatabaseRow (used by both DT_PalMonsterParameter and DT_PalHumanParameter): OverridePartnerSkillTextID was removed; OverridePartnerSkillNameTextID, OverridePartnerSkillDescTextID, EnemyWazaCoolTimeRate (float) and BestWorkSuitability (EPalWorkSuitability) were added. Rename suggestions are heuristic and labelled: high confidence means an identical C++ type and the same name up to case/underscores (HP→Hp); medium means the same type and one name derivable from the other by one inserted/deleted substring (the partner-skill case above); anything else is reported plainly as removed + added with no rename claim.

Each version is pinned to the localcc/PalworldModdingKit commit that regenerated Source/Pal/Public for that game build (versions.json); the parsed field snapshots are committed under structs/ and the pairwise deltas under diffs/:

Palworld SDK commit date
0.3.1 5e2ce8f 2024-06-28
0.3.7 42e4865 2024-09-18
0.3.8 8532ae7 2024-09-27
0.3.9 2592597 2024-10-01
0.4.11 41acdeb 2025-01-09
0.5.0 4a2e161 2025-03-21
0.6.0 cac6969 2025-06-25
0.6.4 10354a8 2025-07-31
0.7.0 b08d51a 2025-12-17
0.7.1 e66b515 2026-01-26
0.7.2 4dcdc78 2026-02-16
1.0 98ee60d 2026-07-11

Alias caveat: Palworld 0.7.3, 1.0.1, the 1.0.2 patch line (v1.0.2 · v1.0.2.100993 "Mod Support Improvement" · v1.0.2.101103), 1.0.3 ("Balance Adjustments & Bug Fixes") and 1.0.4 (same title) shipped no row-struct (header) changes, so they alias 0.7.2 / 1.0 / 1.0 / 1.0 / 1.0 respectively — the CLI and diff page say so explicitly (--migrate 1.0.1..1.0.2 → "no row-struct changes … both alias Palworld 1.0, SDK e663245") instead of pretending a diff exists. Those claims are not assumed: the SDK's Source/Pal/Public was last regenerated at 98ee60d (2026-07-11), the commit 1.0 pins, and each alias records the shas it was checked against in versions.json aliases[...].aliasReason. Note also that 0.7.0→0.7.2 changed no row structs (those SDK updates touched other classes).

1.0.4 is where the SDK proxy shows its limit. Source/Pal/Public did not regenerate, but the game's own cooked tables did move: PalCharacterParameterDatabaseRow gained a 91st property (a 1-byte value at index 90, set on 103 of the 753 DT_PalMonsterParameter rows and on none of DT_PalHumanParameter's 433), which the pinned headers cannot name. That was read out of the 1.0.4 pak, not inferred: skipping one byte for it parses every row and lands exactly on the trailing package tag, and only 16 monster and 4 human rows differ from 1.0.3 at all. No property a mod can already write was removed, retyped or reordered, so "no row-struct changes" holds for every field the registry describes; it just does not also mean "nothing was added". versions.json aliases["1.0.4"].gameDelta records the delta and how it was read, and values/index.json records the unmapped property beside the two tables that carry it.

Staleness detection: npm run versions:check compares this repo against the live world on seven axes: the Steam news API's patch titles (newest game version), the PalworldModdingKit commit list (SDK head, and whether Source/Pal/Public regenerated), the most recently published PalSchema release vs the version this README claims compatibility with (versions.json upstream.palSchema; publish time rather than a version max, because upstream tagged 0.6.71 after 0.6.7 and that sorts above a later 0.6.8), the live blob sha of PalSchema's assets/schemas/items.schema.json vs the sha the ported item constraints pin (an upstream schema edit stales the port even before it reaches a release), the UE4SS commit the claimed PalSchema release says it must run against (read out of that release's own body) vs the ue4ssCommit this README quotes, and the game version each of the three value lanes records (items.json, buildings.json and values/index.json) vs the newest game label. Those last ones exist because a balance patch moves row VALUES while every struct and sha stays put: 1.0.3 changed World Tree Holy Water's weight from 1 to 0.1 with an unchanged SDK, so every sha-based check would have said "current" while the shipped values were a patch behind. The UE4SS axis has the same shape one level up: PalSchema 0.6.6 shipped nothing but a UE4SS bump, and a reader left on the old build gets signature errors rather than anything a schema could report. Exit 0 in sync (registry current: game 1.0.4, SDK e663245, PalSchema 0.6.71, item values 1.0.4, building values 1.0.4, extracted values 1.0.4, items.schema.json blob b41a965, UE4SS 2281fa31), exit 1 stale with one line naming exactly what moved, exit 2 on network failure — never conflated. It runs as an informational CI step and in the daily cron, which opens an issue when something actually moved.

The eighth axis cannot be a network check. None of the seven above reads the game's own struct layout, which is how 1.0.4's added property got past all of them: it was found by re-running npm run extract, where the mapped struct stopped accounting for every property in the row. Reading that needs the pak, a Rust toolchain and a .usmap, so it lives where the evidence does. The extractor records what it found in values/index.json (unmappedTrailingProperty), and npm run check:values — which runs in npm test, no game required — fails unless versions.json acknowledges it in that version's gameDelta.tables. It fails in both directions: an unmapped property nobody recorded, and a recorded claim the current extraction no longer shows (which is what the SDK catching up looks like). So the registry cannot ship "this version changed no row struct" while its own extraction says otherwise.

Auto-bump: npm run versions:bump (scripts/bump-version.mjs) handles the one case that is fully derivable: the game shipped a patch and Source/Pal/Public did not regenerate, so the new label is an alias. It re-verifies that against both live sources, writes the versions.json alias entry (evidence in aliasReason), and re-runs snapshot:all + diff:all. Exit 0 wrote it, 3 refuses because the SDK regenerated and the row structs really changed (that needs a new pin and a human reading the delta), 4 nothing to do, 2 network. The daily cron runs it, gates it on the acceptance suite and opens a PR; merging stays manual. --dry-run, --no-build and --check-format are there for local use.

Regenerate from scratch with npm run snapshot:all (downloads the 12 pinned SDK tarballs into .cache/) and npm run diff:all. Only derived field names/types ship here — never game assets.

Run it locally

# 1. (Re)generate the schema seed + catalog from real game data
#    derive (paldex dump) -> augment (verify fields vs current-game SDK headers,
#    needs the SDK tarball in .cache/ — augment-from-sdk.mjs prints the curl
#    command if missing) -> index
npm run seed          # (needs internet)

# 2. Build the CLI (TypeScript -> JS)
npm run cli:build

# 3. Run the acceptance tests (valid passes, invalid fails, index has >=10 tables)
npm test

# 4. Preview the browser (GitHub Pages serves these exact files, no build)
npm run serve         # -> http://localhost:8080

# Optional: re-extract values/ from a local Palworld install. Needs the game and
# a Rust toolchain (once, for tools/ooz-decompress); everything else works without.
npm run extract -- --game "D:/SteamLibrary/steamapps/common/Palworld" --usmap Mappings.usmap
npm run check:values  # every extracted row must validate against its published schema

Requirements: Node.js ≥ 18 (uses global fetch). Verified on Node 22.


Repo layout

schemas/v1.0/*.schema.json   31 per-table JSON Schemas (+ _manifest.json)
schemas/index.json             table-name -> schema-path listing (for Pages consumers)
schemas/info-json.schema.json  JSON Schema for an official Workshop package's Info.json
index.json                     { versions, schemas:{ver:[tables]}, tables:{...} } catalog
table-notes.json               hand-written per-table notes (source; baked into index.json)
index.html                     schema browser (vanilla HTML/CSS/JS, no build step)
package.html                   mod package checker (official/UE4SS badge; loads examples/)
items.html + items.json        per-item value reference for DT_ItemDataTable (asset reuse)
values.html + values/*.json    current row values for 28 tables, read from the game's DataTables
tools/ooz-decompress/          Rust helper: Oodle decompression for the extractor (build on demand)
diff.html                      version-diff viewer (what changed between game versions)
versions.json                  Palworld version -> pinned SDK commit (plus 0.7.3/1.0.1/1.0.2/1.0.3/1.0.4 aliases + sdkHead)
structs/<ver>.json             12 committed row-struct snapshots (field -> C++ type, ordered) + alias copies
diffs/<a>..<b>.json + .md      pairwise struct deltas (added/removed/retyped + rename notes)
cli/                           palschema-validate (TypeScript -> dist/*.js), ajv strict
examples/                      labelled sample inputs for the package checker (not real mods)
tests/                         valid-mod.json, invalid-mod.json, example .jsonc, wrapper-typo
tests/fixtures/packages/       official-package fixtures (valid, escape, duplicates, encodings, ConfigOverrides)
tests/real-mods/               4 real published PalSchema mods (see SOURCES.md)
tests/real-mods-broken/        deliberately-broken real mods (typed-error tests)
tests/migrate-fixtures/        --migrate scan fixtures (partner-skill rename case)
tests/currency-fixtures/       saved Steam-news/commit-list API shapes (the tests re-anchor them to versions.json)
scripts/                       derive-schemas, augment-from-sdk, derive-sdk-tables, snapshot-structs, build-diff, build-index, build-items, check-currency, bump-version, check-index, build-nexus-zip, serve (+ lib/sdk-parse.mjs, lib/version-sources.mjs, lib/paldb-parse.mjs)
nexus/                         offline archive published on Nexus Mods (zip rebuilt by npm run nexus:zip; nexus:check gates it in CI)
.github/workflows/
  pages.yml                    deploys browser + schemas to GitHub Pages (tests gate it)
  palschema-ci.yml.example     CI template for MOD repos
  self-test.yml                this repo's own CI (build + acceptance checks + currency info step)
  refresh-items.yml            daily cron: upstream-dump SHA watch, registry currency check, auto-alias PR

🚀 Live deployments

License

MIT (code). See provenance note above for the derived data.

About

Community schema registry for Palworld PalSchema raw-table mods - 31 SDK-verified DataTable schemas + validator CLI

Topics

Resources

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages