VPXS YML Builder

Build VPS YML files without the screen marathon.

Search for a table above, choose its assets, then edit everything in one compact workspace.

/ focuses search

How it works

Every field is grouped below by the job it does, so one explanation covers a whole family of fields. Open a group to read it. New here? The Walkthrough tab leads you through the real thing.

Asset rows: choosing a version, Bundled, and Override

The Assets Panel has one row per asset type: VPX, Backglass, ROM, Color ROM, PUP Pack, Alt Sound, and VPU Patch. Each row is how you tell the builder the table uses that asset. Filling a row unlocks its configuration tab below.

There are three ways to fill a row, and they are not interchangeable:

  • Select a version from the dropdown. This is the normal case. The asset exists in the VPS database, so the builder records its ID and you only add a checksum and notes.
  • Bundled means the file ships inside the table download itself. There is nothing separate to link, so a bundled asset only needs Notes.
  • Override means the asset has no VPS entry at all. Because nothing can be looked up, Override requires every Advanced Config field on that tab: Notes, URL Override, and Version or Authors depending on the asset.

The Override checkbox never appears in the finished YML. It exists only to unlock the tab and make you supply the details by hand.

Once a row has something selected, its title becomes a link. It opens the page where that file is actually hosted, in a new tab. That is almost never the Virtual Pinball Spreadsheet itself: VPS catalogs the files and points elsewhere for the download, most often VPUniverse or VPForums, sometimes Pinball Nirvana, a Google Drive folder, or a MEGA link. So the row title is both how you confirm you picked the right version and how you go and get it. Rows with nothing selected, and entries whose links are all broken, stay as plain text.

One row does not behave like the others: VPU Patch. VPS does not publish patches as their own category. They sit among the table's VPX files, tagged with a VPU Patch feature, and each records the VPX it patches. So the VPU Patch row only offers a patch once you have selected that exact VPX above it, and stays empty for every other VPX on the same table. If the row looks broken, check your VPX selection first.

If the builder ever demands a URL for something you marked Bundled, that is a bug, not a rule. Bundled and Override have deliberately different requirements.

VPS ID fields (8 fields, all read-only)

Game VPS ID, VPX ID, Backglass ID, ROM ID, Color ROM ID, PUP Pack ID, Alt Sound ID, and VPU Patch ID all work the same way: you never type in them. They fill themselves from the table you searched for and the versions you picked in the Assets Panel.

If one is empty, the cause is upstream: either no table is loaded, or you have not selected that asset yet.

One field is named like these but is not one of them: Tutorial VPS ID, on the Main tab. That one is a dropdown you choose from, not a field that fills itself. It is covered under "Everything else on the Main tab" below.

One trap worth knowing. When a tab reports an error the checker cannot pin to a specific field, it drops the error dot on that tab's first read-only field. On the Main tab that is Game VPS ID. A dot there usually means something else on the tab is wrong, not the ID.

Checksum fields (8 fields plus the Additional ROM dialog)

Every checksum field behaves the same way. Drag a file onto the field and the MD5 is calculated inside your browser. Nothing is uploaded. You can also type or paste a checksum by hand.

All checksums are 32 characters, hexadecimal, and shown in uppercase. Typing stops at 32 characters, and the status line under the field tells you exactly what was hashed.

The exceptions, by field:

FieldDrop an archive on it and the builder will…
VPX Checksumreach inside and hash only the .vpx
Backglass Checksumreach inside and hash only the .directb2s
VPU Patch Checksumreach inside and hash only the .dif
ROM Checksumhash the whole archive, unless the table is made by Stern
PUP Pack Checksumhash the whole archive, and read its folder list to fill Archive Root
Alt Sound Checksumhash the whole archive, and read its folder list
Color ROM Checksumhandle a .pal and .vni pair together

Stern ROMs. When the loaded table's manufacturer is Stern, the ROM Checksum field also accepts a bare .bin, and dropping an archive scans it for the .bin inside. If the archive holds exactly one, that file alone is hashed. If it holds none or several, the whole archive is hashed instead, because there is no safe way to guess which one you meant. The status line always says which happened.

Color ROM pairs. Dropping an archive holding both a .pal and a .vni fills both checksum slots at once and ticks PAL/VNI for you. A lone .vni goes to the second slot. Single files such as .crz, .pac, or .cROMc go to the first slot with PAL/VNI cleared.

Additional ROMs use their own dialog, but the drop field inside it follows all the same rules, Stern included.

Notes fields (8 fields)

Main Notes, VPX Notes, Backglass Notes, ROM Notes, Color ROM Notes, PUP Pack Notes, Alt Sound Notes, and Patch Notes are free text for anything the person installing the table needs to know.

Notes are usually optional, with two exceptions that will stop you:

  • A Bundled asset requires its Notes field, because Notes are the only thing it carries.
  • Filling any URL Override requires the matching Notes field, so nobody is handed a raw link with no explanation.
URL Override fields (6 fields, all under Advanced Config)

Backglass, ROM, Color ROM, Alt Sound, and VPU Patch each have a URL Override, and Backglass also has an Image Override. Use one when the file lives somewhere the VPS database does not point to.

Two rules apply to all of them:

  • A URL Override requires its matching Notes field.
  • A URL Override conflicts with a selected VPS ID for the same asset. Use one or the other, never both. The builder flags it if you do.

Long links are fine. If a link pushes the generated line past 120 characters, the builder adds the comment that keeps YAML linters quiet. That limit measures the finished line, not the link on its own, so a shorter link can still trip it.

Version and Authors Override fields (7 fields)

Version Override appears on ROM, Color ROM, Alt Sound, and VPU Patch. Authors Override appears on Backglass, Alt Sound, and VPU Patch. Both do the same job: supply by hand a detail that would normally come from the VPS database.

You need them when a tab is in Override mode, since there is no database entry to read. A ROM URL Override specifically requires a ROM Version Override alongside it.

Authors fields take a comma separated list. Type name, name, name and the builder splits it for you.

Archive Root and Archive Format (PUP Pack and Alt Sound)

These two assets ship as archives, and the installer needs to know two things: which folder inside the archive is the real root, and what kind of archive it is.

You rarely type either. Drop the archive on that tab's checksum field and the builder reads the folder list into a dropdown beside Archive Root, then sets Archive Format from the file extension.

PUP Pack requires Version, Archive Root, and Archive Format whenever the tab is on, whether or not you used Override.

Table Name, Manufacturer, and Year Override (Main tab, Advanced Config)

These three correct the table's own details when the VPS database has them wrong, or formatted differently to how you want them published. Leave them empty and the database values are used.

Manufacturer Override does more than rename things. The builder reads it when deciding manufacturer specific behavior, and it takes priority over the database. Setting it to Stern switches on the Stern ROM rules described in the checksum section, which is the intended way to fix a table the database has mislabelled. Capitalization does not matter.

NSFW flags

There is one NSFW control on the table strip and one on each asset row, and they are exclusive.

Tick the table level NSFW and every per asset box is cleared and disabled, because flagging the whole table already covers everything inside it. The output carries a single nsfw: true.

Untick it and the per asset boxes come back, all unticked, so you can flag individual pieces instead.

Everything else on the Main tab
  • FPS sets the frame rate the table should run at. Numbers only.
  • Wizard Disabled is ticked by default on a new table and after Clear section. Leave it as you find it unless you specifically want the installer wizard turned off for this table. Imported files and restored drafts keep whatever they arrived with.
  • Tagline is the one line description shown alongside the table.
  • Testers is a comma separated list of who tested the build.
  • Tutorial VPS ID links a tutorial entry from the database, chosen from a dropdown.
Special controls: PAL/VNI, PUP Pack Required, Additional ROMs
  • PAL/VNI on the Color ROM tab switches that tab into two checksum mode for Pin2DMD color files and enables Color ROM Checksum #2. Dropping a matching archive ticks it for you. Toggling it by hand keeps a checksum that came from a .pal file and clears anything else, since only a .pal is valid in both modes.
  • PUP Pack Required marks the pack as mandatory rather than optional. It does not require you to select a PUP Pack ID.
  • Additional ROMs on the ROM tab is for tables needing more than one ROM. Each entry opens its own dialog with its own VPS ID, checksum, and overrides. An entry cannot reuse the primary ROM's ID, and if the ROM tab is in Override mode the ID picker is switched off for additional entries too.
Validating, downloading, and starting over

The YAML Generated Preview updates as you work, and its colored dot summarizes the whole build. Click the dot to jump to the first outstanding error. Green asset badges on the table strip jump to their tab.

A tab turns red only for errors. Warnings leave it green, and a tab stays green once its required fields are complete, even after you move away.

Copy and Download stay blocked while any error remains. Warnings never block anything.

Clear section at the bottom of a tab empties that tab but keeps its ID and its Bundled or Override state. Clear in the preview panel starts a whole new build. Your work autosaves as you go, and Recent keeps your build history.

Build check

Validation results

Recent Build History