legendsunchained/vpx-standalone-alp4k

Purpose and Consumers

This is a content/configuration repository for running Visual Pinball X (VPX) tables on the AtGames Legends Pinball 4K through the Legends Unchained Loader/Table Manager. It is not an application runtime: the primary consumers are the external loader, launcher, and table manager, which discover table directories and apply their assets and overrides. Entry points are the table catalog at README.md, per-table directories under external/, and the generated/static documentation under doc/.

Table Package Model

Each external/vpx-* directory is an independently installable table support package. The stable package identifier is the directory name, which the Table Manager relies on. A package generally supplies:

• Required wizard metadata: table.yml

• Optional VPX runtime overrides: table.ini, table.vbs

• Optional persistent/emulated machine state: nvram.nv, VPReg.ini

• Optional launcher controls: launcher.cfg

• Per-table installation notes: README.md

Representative packages: external/vpx-t2/table.yml, external/vpx-t2/table.ini, external/vpx-t2/pinmame.ini; external/vpx-deadpool/table.yml, external/vpx-deadpool/launcher.cfg; external/vpx-123/table.yml, external/vpx-123/table.vbs.

Installation and Runtime Boundary

The loader/Table Manager selects a package, interprets table.yml, stages its named assets, and launches VPX with table-specific configuration and script substitutions. VPX itself, ROM emulation/PinMAME where required, and optional Puppack media remain external dependencies rather than repository code. The repo provides compatibility material only; it does not contain VPX tables or the Legends Unchained software. Default_VPinballX.ini provides a repository-wide VPX baseline, while per-table table.ini files override it.

Catalog Classification

The top-level catalog separates “Wizard Tables,” intended for managed installation, from “Manual Install Tables,” which require user intervention or are not fully supported by the wizard path. This classification is presented in README.md and reflected by the presence or absence of table.yml in package directories—for example, external/vpx-2001/table.yml versus external/vpx-301bullseye/table.ini. problem-tables/ isolates known problematic configurations from the normal external/ catalog, e.g. problem-tables/vpx-got/README.md and problem-tables/vpx-splatterhouse/table.ini.

Validation and Publication Pipeline

GitHub Actions enforce the repository’s data contract and publish derived artifacts. YAML validation targets table descriptors through .github/workflows/validate-table-yaml.yml and .github/workflows/scripts/validate-table-yaml.py; VPX INI validation uses .github/workflows/check-vpx-ini.yml and .github/workflows/scripts/check-table-ini.py. Release automation is centered on .github/workflows/create-external-releases.yml, with Python scripts such as .github/workflows/scripts/generate-manifest.py and .github/workflows/scripts/generate-release.py. These workflows run in GitHub-hosted CI and produce manifests/releases for external consumers.

Documentation and Contribution Contract

Contributor-facing schema and naming expectations are defined by table.yml.example and table-template_README.md; the required package naming convention is architecturally important because discovery is file-name based. User documentation is a separate static documentation tree rooted at doc/home.adoc, with onboarding at doc/beginner/gettingstarted.adoc and advanced setup guidance at doc/advanced/newtable.adoc. Documentation publishing is automated by .github/workflows/asciidoc-publish.yml.