# legendsunchained/vpx-standalone-alp4k architecture

> Architecture diagram of the GitHub repository legendsunchained/vpx-standalone-alp4k, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/legendsunchained/vpx-standalone-alp4k
- Repository: https://github.com/legendsunchained/vpx-standalone-alp4k

## Overview

#### 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`.

Main entry points: [`external/vpx-t2/table.ini`](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/external/vpx-t2/table.ini) (VPX overrides), [`external/vpx-t2/table.yml`](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/external/vpx-t2/table.yml) (Wizard descriptor), [`.github/workflows/create-external-releases.yml`](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/.github/workflows/create-external-releases.yml) (External release builder), [`README.md`](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/README.md) (Table catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_packages["Table packages"]
  node_package_dirs["External package directories<br/>package collection"]
  node_wizard_metadata["Wizard descriptor<br/>YAML metadata<br/>[table.yml]"]
  node_runtime_overrides["VPX overrides<br/>runtime config<br/>[table.ini]"]
  node_machine_state["Emulated machine state<br/>state files<br/>[pinmame.ini]"]
  node_launcher_controls["Launcher controls<br/>launcher config<br/>[launcher.cfg]"]
  node_manual_packages["Manual-install packages<br/>package variant<br/>[table.ini]"]
end

subgraph group_automation["CI and publication"]
  node_yaml_validation["Table YAML validation<br/>CI workflow"]
  node_ini_validation["VPX INI validation<br/>CI workflow<br/>[check-vpx-ini.yml]"]
  node_release_automation["External release builder<br/>CI workflow"]
  node_docs_publish["Documentation publishing<br/>CI workflow"]
end

subgraph group_docs["Documentation"]
  node_catalog["Table catalog<br/>[README.md]"]
  node_contribution_contract["Package authoring contract<br/>templates<br/>[table.yml.example]"]
  node_user_docs["Static user documentation<br/>AsciiDoc site<br/>[home.adoc]"]
end

node_baseline_ini["VPX baseline<br/>global runtime config"]
node_problem_tables["Problem tables<br/>isolated package collection"]
node_loader{{"Loader / Table Manager<br/>external consumer"}}
node_vpx_runtime{{"VPX and emulation<br/>external runtime"}}
node_published_releases["Manifests and releases<br/>published artifact"]

node_catalog -->|"indexes wizard tables"| node_package_dirs
node_catalog -->|"classifies separately"| node_manual_packages
node_package_dirs -->|"contains"| node_wizard_metadata
node_package_dirs -->|"may contain"| node_runtime_overrides
node_package_dirs -->|"may contain"| node_machine_state
node_package_dirs -->|"may contain"| node_launcher_controls
node_baseline_ini -->|"base overridden by"| node_runtime_overrides
node_loader -->|"discovers by directory name"| node_package_dirs
node_loader -->|"interprets"| node_wizard_metadata
node_loader -->|"applies"| node_runtime_overrides
node_loader -->|"uses"| node_launcher_controls
node_loader -->|"launches"| node_vpx_runtime
node_yaml_validation -->|"validates"| node_wizard_metadata
node_ini_validation -->|"validates"| node_runtime_overrides
node_release_automation -->|"packages"| node_package_dirs
node_release_automation -->|"produces"| node_published_releases
node_contribution_contract -.->|"governs naming and metadata"| node_package_dirs
node_docs_publish -->|"publishes"| node_user_docs
node_problem_tables -.->|"kept separate from"| node_package_dirs

click node_catalog "https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/README.md"
click node_wizard_metadata "https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/external/vpx-t2/table.yml"
click node_runtime_overrides "https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/external/vpx-t2/table.ini"
click node_machine_state "https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/external/vpx-t2/pinmame.ini"
click node_launcher_controls "https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/external/vpx-deadpool/launcher.cfg"
click node_baseline_ini "https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/Default_VPinballX.ini"
click node_manual_packages "https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/external/vpx-301bullseye/table.ini"
click node_yaml_validation "https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/.github/workflows/validate-table-yaml.yml"
click node_ini_validation "https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/.github/workflows/check-vpx-ini.yml"
click node_release_automation "https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/.github/workflows/create-external-releases.yml"
click node_contribution_contract "https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/table.yml.example"
click node_user_docs "https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/doc/home.adoc"
click node_docs_publish "https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/.github/workflows/asciidoc-publish.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_package_dirs,node_wizard_metadata,node_runtime_overrides,node_machine_state,node_launcher_controls,node_manual_packages toneBlue
class node_yaml_validation,node_ini_validation,node_release_automation,node_docs_publish toneAmber
class node_catalog,node_contribution_contract,node_user_docs toneMint
class node_baseline_ini,node_problem_tables,node_loader,node_vpx_runtime,node_published_releases toneNeutral
```

## Components

### Table packages

File-name discovery contract for installable VPX support packages.

- **External package directories**: package collection · Each external/vpx-* directory is an independently installable package.
- [Wizard descriptor](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/external/vpx-t2/table.yml): YAML metadata · Required for managed wizard installation. · `external/vpx-t2/table.yml`
- [VPX overrides](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/external/vpx-t2/table.ini): runtime config · Per-table INI and VBS substitutions. · `external/vpx-t2/table.ini`
- [Emulated machine state](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/external/vpx-t2/pinmame.ini): state files · Optional persistent VPX or PinMAME state. · `external/vpx-t2/pinmame.ini`
- [Launcher controls](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/external/vpx-deadpool/launcher.cfg): launcher config · Optional per-table launcher behavior. · `external/vpx-deadpool/launcher.cfg`
- [Manual-install packages](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/external/vpx-301bullseye/table.ini): package variant · Packages without wizard metadata require user intervention. · `external/vpx-301bullseye/table.ini`

### CI and publication

GitHub-hosted validation and release automation.

- [Table YAML validation](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/.github/workflows/validate-table-yaml.yml): CI workflow · Validates table descriptors. · `.github/workflows/validate-table-yaml.yml`
- [VPX INI validation](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/.github/workflows/check-vpx-ini.yml): CI workflow · Checks table INI configuration. · `.github/workflows/check-vpx-ini.yml`
- [External release builder](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/.github/workflows/create-external-releases.yml): CI workflow · Generates manifests and releases for external consumers. · `.github/workflows/create-external-releases.yml`
- [Documentation publishing](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/.github/workflows/asciidoc-publish.yml): CI workflow · Publishes the static documentation tree. · `.github/workflows/asciidoc-publish.yml`

### Documentation

Catalog, contributor contract, and static user guidance.

- [Table catalog](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/README.md): catalog · Classifies Wizard Tables and Manual Install Tables. · `README.md`
- [Package authoring contract](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/table.yml.example): templates · Defines descriptor schema and naming expectations. · `table.yml.example`
- [Static user documentation](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/doc/home.adoc): AsciiDoc site · Onboarding and advanced table setup guidance. · `doc/home.adoc`

### Other components

- [VPX baseline](https://github.com/legendsunchained/vpx-standalone-alp4k/blob/main/Default_VPinballX.ini): global runtime config · Repository-wide defaults overridden by table.ini. · `Default_VPinballX.ini`
- **Problem tables**: isolated package collection · Known problematic configurations excluded from the normal catalog.
- **Loader / Table Manager**: external consumer · Discovers packages, stages assets, and applies descriptors.
- **VPX and emulation**: external runtime · VPX, PinMAME, ROMs, and optional Puppack remain external.
- **Manifests and releases**: published artifact · Derived package distribution artifacts.

## Connections

- Table catalog → External package directories: indexes wizard tables
- Table catalog → Manual-install packages: classifies separately
- External package directories → Wizard descriptor: contains
- External package directories → VPX overrides: may contain
- External package directories → Emulated machine state: may contain
- External package directories → Launcher controls: may contain
- VPX baseline → VPX overrides: base overridden by
- Loader / Table Manager → External package directories: discovers by directory name
- Loader / Table Manager → Wizard descriptor: interprets
- Loader / Table Manager → VPX overrides: applies
- Loader / Table Manager → Launcher controls: uses
- Loader / Table Manager → VPX and emulation: launches
- Table YAML validation → Wizard descriptor: validates
- VPX INI validation → VPX overrides: validates
- External release builder → External package directories: packages
- External release builder → Manifests and releases: produces
- Package authoring contract → External package directories: governs naming and metadata
- Documentation publishing → Static user documentation: publishes
- Problem tables → External package directories: kept separate from