| name | pst-build-ci |
| description | The build system (Nuitka primary for CI/release → dist/, cx_Freeze for Windows installer → PST_standalone/), Inno Setup installer, GitHub Actions CI (5 workflows), standalone-mode signaling (runtime.cfg), verify_build checks, and utility scripts (update_game_data ETL, translation automation via Google Translate, theme linter, import validator). Load when building, releasing, or maintaining CI. |
PST Build System, CI, Scripts
Two build backends
Nuitka (build/nuitka/build_nuitka.py) = CI/release PRIMARY. Entry src/palworld_aio/main.py. --onefile (default) or --standalone. Output dist/PalworldSaveTools-V{ver}-nk-{platform}. Forces palsav submodules via --include-module (21-39), excludes tkinter/unittest/numpy + ~20 Qt submodules (41-52). Bundles resources/ + src/data/ + games.json. macOS: --macos-create-app-bundle.
cx_Freeze (build/cx_freeze/setup_freeze.py + build_cx.py) = Windows INSTALLER path. Output PST_standalone/ (NOT dist/). Entry Executable('src/palworld_aio/main.py', base='gui'). build_cx.py orchestrates: clean→venv→deps→sync_version→build→7z archive (LZMA2/max). Excludes palsav.pyooz (25).
Which is primary: Nuitka for all CI workflows + cross-platform release. cx_Freeze for the Windows .iss installer. Interactive builder (build_interactively.py) labels cx_Freeze="standard distribution", Nuitka="C-compiled".
Standalone-mode signaling
runtime.cfg flag: [build] standalone=true written before build, reset to false after. Read by common.is_standalone() (40-50). Consumers: updater (auto-download vs git-pull), main_window path resolution.
verify_build.py (build/verify_build.py)
Post-build checks: binary exists+executable, size>1MiB, resources bundled, headless smoke test (exe Level.sav --logs --fix, 30s timeout), --version contains APP_VERSION.
clean_code.py (build/clean_code.py — ONLY copy, NOT in scripts/scrs/)
AST-based docstring+comment+blank stripper. DESTRUCTIVE — rewrites source in place via ast.unparse. DocstringRemover(14).
Inno Setup installer (build/installer/pst.windows.iss)
Packages PST_standalone/* (cx_Freeze output). AppId {B0E3F1A2-...}. Compression=lzma2/max SolidCompression=yes. PrivilegesRequired=lowest. Output: PalworldSaveTools-{ver}-windows-setup.exe. Desktop shortcut (checkedonce). Full clean uninstall.
CI (5 workflows, all use checkout@v4 + setup-python@v5 3.12 + uv)
- ci.yml — push/PR gating. 3 parallel jobs (win/linux/mac), Nuitka build, upload artifacts. NO tests, NO release.
- build-{windows,linux,mac}.yml — workflow_dispatch only. Single-OS Nuitka build → draft+prerelease GH release.
- build-all-and-release.yml — workflow_dispatch with inputs (version, release_name, draft, prerelease). 5 jobs: prepare-source(tarball) + 3 builds + create-release(aggregates). THE canonical release pipeline.
Utility scripts (scripts/scrs/)
update_game_data.py (2362 lines) — game-data ETL
Ingests UE asset exports from Exports/Pal/Content/ → resources/game_data/. 21 sequential steps with spinner. Reads DT_*.json data tables + L10N + textures. Produces merged files: characters.json←{pals,npcs}, skills.json←{passives,skills,elements}, world.json←{structures,technology}, items.json←{items}. Then deletes per-entity files, cleans stale icons, PNG→WEBP via Pillow. Legacy fallback(129) maps old→merged names.
Translation automation (deep-translator / Google Translate)
- translate_readme.py — README.md→7 locales. PlaceholderManager protects code/URLs/game terms. Parallel ThreadPoolExecutor.
- translate_tab_guide.py — tab_guide/en/*.html→7 locales. Protects HTML tags. Parallel max 10 workers.
- update_translation_keys.py — update EXISTING key text + re-translate all locales.
- add_translation_keys.py — add NEW keys + optionally prune OLD_KEYS.
Validation
- validate_imports.py — smoke-test imports 16 core modules, asserts expected attrs. Exit 1 on failure.
- check_theme_violations.py (483) — linter enforcing centralized theming. Detects hardcoded hex/rgba (error), inline qss blocks ≥3 props (warning), hardcoded fonts (warning). Whitelist: styles.py, constants.py, edit_pals.py. Flags: --ruthless (no whitelist), --strict (warnings=fail).
Other scripts
- scan_ft_guids.py — harvest fast-travel/area/unlock GUIDs from player .sav RecordData → reference_unlock_data.json (additive merge).
- clear_fog.py — dev utility, zeroes fog mask in a .sav.
- auto_update.py — 5-line shim → runpy palsav.commands.auto_update.
- test_interactively.py (348) — menu-driven pytest orchestrator. --quick=fast, --all=incl slow.
.cmd launchers (scripts/tests/ + scripts/)
9 test .cmd runners (identical template: check uv→wipe venv→uv sync→run pytest target→del uv.lock→pause). Scripts/ has .cmd wrappers for each .py (uv venv bootstrap + run).
GOTCHAS
- scripts/scrs/clean_code.py does NOT exist — only build/clean_code.py.
- setup_freeze.py:30 hardcodes version="2.0.0" (kept in sync only by build_cx.sync_version); .iss also hardcodes 2.0.0.
- ci.yml does NOT run pytest — test running is local-only (.cmd/test_interactively.py).
- palsav/palooz in frozen builds: Nuitka forces via --include-module for every submodule; cx_Freeze via _BUILD_PACKAGES. Both inject src/+resources/ on sys.path.
