Reference

External software

Pinman works with two categories of external software, stored and used differently.

Category 1: Tracked Software (Emulators & Frontends)#

These are the pinball programs installed on your cabinet. Pinman tracks them to understand your ecosystem — which emulator runs your games, which frontend manages them, which display zones each program owns.

Where defined: YAML catalog files in data/schemas/ — any file with a top-level software: section.

What comes pre-loaded#

Software	Catalog ID	Class
Visual Pinball X (64-bit)	`visual_pinball:vpx64`	emulator
Visual Pinball X (32-bit)	`visual_pinball:vpx32`	emulator
Visual Pinball X (OpenGL 64-bit)	`visual_pinball:vpx_gl64`	emulator
Visual Pinball 9	`visual_pinball:vp9`	emulator
Visual Pinball 8	`visual_pinball:vp8`	emulator
VPinMAME (runtime)	`visual_pinball:vpinmame`	emulator
VPinMAME Setup (config tool)	`visual_pinball:vpinmame_setup`	utility
DirectB2S / B2S Server	`visual_pinball:directb2s`	frontend
Future Pinball	`future_pinball`	emulator
PinUP Popper	`pinupsystem:popper`	frontend
DOF (DirectOutput Framework)	`dof`	utility

Detection is automatic. Pinman checks Windows uninstall keys, known install paths, registry keys, and process names. Software that isn't found is simply absent from the UI.

How detection works#

Each catalog entry declares a detection block with any combination of:

uninstall_key — Windows uninstall registry name (most reliable)
locations — list of candidate install paths or schema_var references (e.g. VPX_ROOT, resolved from the schema's global: block at detect time)
registry_keys — registry paths that confirm installation
process_names — exe names if the program is currently running

Category 2: Configuration Tools (Guided Mode)#

These are Windows utilities and vendor apps that Pinman cannot control programmatically. When a profile needs a setting that Pinman can't write directly — an NVIDIA 3D graphics setting, a default audio device — Pinman enters guided mode: it opens the right tool automatically and walks you through numbered steps.

What comes pre-loaded#

Windows OS tools (core_os.yaml):

windows:device_manager, windows:display, windows:sound, windows:sound_classic, windows:power, windows:disk_management

NVIDIA (core_nvidia.yaml):

nvidia:app, nvidia:control_panel

AMD / Other GPU (core_gpu.yaml):

amd:adrenalin, asus:armoury_crate

The `group:member` ID Format#

All catalog IDs use group:member format:

visual_pinball:vpx64      → group: visual_pinball, member: vpx64
nvidia:app                → group: nvidia, member: app
windows:device_manager    → group: windows, member: device_manager
dof                       → bare ID — no sub-members defined yet

Group prefix matching: software filter queries use the group prefix — visual_pinball matches all visual_pinball:* entries.

Bare IDs (like dof, future_pinball) are valid but have no sub-members. Use a bare ID when there's only one entry for that software ecosystem.

`software_refs:` Blocks in Schema YAML#

The software_refs: block is a virtual container in schema YAML — it propagates a list of catalog IDs to all child items. It is not saved as a DB item.

Basic usage#

# All items in this subtree get software_refs: [visual_pinball]
- software_refs: [visual_pinball]
  const:
    VPX_DATA: '{{APPDATA_ROOT}}/Roaming/VPinballX'
  items:
    - location: "{{VPX_ROOT}}"
      itemtype: directory
      ...

Narrowing (override)#

A child software_refs: block replaces the parent's list — it does not merge:

- software_refs: [visual_pinball]
  items:
    - location: "{{VPX_ROOT}}"
      ...

    # VPinMAME subtree — narrowed to a specific member
    - software_refs: [visual_pinball:vpinmame]
      items:
        - location: "{{VPX_ROOT}}/VPinMAME"
          ...

    # DirectB2S files — narrowed to a different member
    - software_refs: [visual_pinball:directb2s]
      items:
        - location: "{{VPX_ROOT}}/Tables"
          items:
            - for:
                B2S: "*.directb2s"
              items:
                - selector: "{{B2S}}"

Multiple refs#

An item can reference multiple catalog entries — for resources shared by several programs:

- software_refs: [visual_pinball:vp8, visual_pinball:vp9]
  items:
    - location: "{{VPX_ROOT}}/Tables"
      items:
        - for:
            VPT: "*.vpt"
          items:
            - selector: "{{VPT}}"

The `relationships:` Field#

Catalog entries can declare typed edges to other entries. These are an extension hook for future graph features (visualization, dependency-aware backup):

- id: visual_pinball:vpx64
  relationships:
    - type: invokes
      target: visual_pinball:vpinmame
    - type: invokes
      target: visual_pinball:directb2s

Defined types: invokes, configures, shares_dir, reads, writes, listens

Unknown type values are silently ignored.

Catalog YAML Format#

Catalog files live in data/schemas/. Any YAML file with a top-level software: section is a catalog file.

Software-only catalog file#

# core_os.yaml — Windows OS built-in tools

software:
  - id: windows:device_manager
    name: Device Manager
    command: devmgmt.msc
    launch_type: msc
    vendor: microsoft
    program_class: os_builtin
    device_classes: [display, audio, usb, computer]
    detect: null
    icon: TechnicianIcon
    relationships:
      - type: invokes
        target: windows:mmc

Key fields#

Field	Required	Description
`id`	Yes	Unique `group:member` ID (or bare ID)
`name`	Yes	Human-readable display name
`exe`	No	Executable filename
`command`	No	How to launch: an exe name, a `ms-settings:` URI, or a `.msc` name
`launch_type`	No	`exe`, `uri`, or `msc`
`vendor`	No	Vendor name
`program_class`	No	`emulator`, `frontend`, `utility`, `os_builtin`
`device_classes`	No	Hardware categories that surface this tool: `display`, `audio`, `usb`, `computer`
`default_for_group`	No	`true` to mark this as the default entry in its group
`detect`	No	Detection command or path; `null` for always-present OS tools
`detection`	No	Full detection block with `uninstall_key`, `locations`, `registry_keys`, `process_names`
`icon`	No	Icon name
`relationships`	No	Typed edge list

The Configuration Package Pattern#

A configuration package is the downloadable content bundle that adds support for a tool or setup: a Schema, Profiles for known/useful configurations, and supporting guidance. (Pinman-released packages are "Pinman configuration packages"; contributor-maintained ones are "community configuration packages".)

The simplest configuration package ships one YAML file containing both its software catalog entry and its schema items:

# pinscape_package.yaml

software:
  - id: pinscape:config
    name: Pinscape Config Tool
    exe: PinscapeConfigTool.exe
    vendor: mjrnet.org
    program_class: utility
    device_classes: [usb]
    relationships:
      - type: configures
        target: pinscape:firmware
    detection:
      locations:
        - path: "C:\\PinscapeConfigTool"
      process_names: [PinscapeConfigTool.exe]

items:
  - software_refs: [pinscape:firmware]
    items:
      - location: "fs:/C/PinscapeConfigTool/Config"

pinman schema import path/to/pinscape_package.yaml registers the catalog entry and imports the schema items in one pass.

To import a whole directory of packages:

pinman schema import data/schemas/          # imports all *.yaml files
pinman schema import data/schemas/ --strict  # fail on undefined software_refs IDs

How Guided Mode Works#

When a profile step requires manual action, Pinman:

Looks up the relevant tool in the catalog
Launches it (launch_type is uri, exe, or msc)
Displays the step list from instructions.d/, with template variables filled in
Optionally prompts you to confirm and re-reads the value to verify

Example guided step sequence for an NVIDIA setting:

Open NVIDIA App → Navigate to Graphics > Global Settings → Find 'Power Management Mode' → Set to Maximum Performance → Click Apply

In the CLI#

# Apply: direct targets write automatically, then guided actions are listed
pinman profile apply "My GPU Profile"
  Guided Actions (2 settings need manual changes):

    NVIDIA App:
      1. Set Vertical Sync to ForceOff
         - Open NVIDIA App
         - Navigate to Graphics > Global Settings
         - Find 'Vertical Sync'
         - Set to ForceOff
         - Click Apply

Add --interactive for a step-by-step flow with prompts:

pinman profile apply "My GPU Profile" --interactive

  NVIDIA App:
  Open NVIDIA App? [Y/n] y
    1. Set Vertical Sync to ForceOff
       ...
     Done/Skip/Quit [d/s/q]: d
     Verifying... [VERIFIED]

In the Web UI#

When applying a profile with guided targets, a guided action dialog appears after direct targets complete:

Instructions are always visible
"Open Tool" launches the tool on the cabinet
"Done" triggers verification
"Skip" moves to the next action

A guided-action banner appears on profile cards when drift is detected on a guided property.

Adding New Software#

Step 1: Add to a catalog YAML file#

Add an entry to an existing file in data/schemas/, or create a new one:

software:
  - id: myvendor:mytool
    name: My Config Utility
    exe: MyTool.exe
    command: MyTool.exe
    launch_type: exe
    vendor: myvendor
    program_class: utility
    device_classes: [display]
    detection:
      locations:
        - path: "C:\\MyTool"
      process_names: [MyTool.exe]

Step 2: (Optional) Add schema items#

If this software manages files that Pinman should track, add an items: section to the same file or another schema YAML:

items:
  - software_refs: [myvendor:mytool]
    items:
      - location: "fs:/C/MyTool/Config"

Step 3: Import#

pinman schema import data/schemas/

Step 4: (Optional) Add guided instructions#

Add an entry to instructions.d/ for guided step templates. The software_ref field must match your catalog ID:

{
  "my_tool_setting": {
    "software_ref": "myvendor:mytool",
    "summary_template": "Configure {label}",
    "steps": [
      "Open My Config Utility",
      "Find '{label}'",
      "Set to {target_value}",
      "Save"
    ],
    "verify": true
  }
}

Then reference it in profiles:

p.guided("winrt:/MyCategory/MySetting", "value", software="myvendor:mytool")

Summary#

	Tracked software	Configuration tools
Examples	VPX, VPinMAME, PinUP Popper	Device Manager, NVIDIA App
Purpose	Cabinet ecosystem, detection, zone filtering	Guided manual settings changes
Defined in	`data/schemas/*.yaml` (`software:` section)	`data/schemas/*.yaml` (`software:` section)
Has detection logic	Yes (uninstall key, paths, registry, process)	Yes, or `null` for always-present OS tools
Launched by Pinman	No	Yes (guided mode)
Schema items	Associated via `software_refs:` blocks	Referenced via property catalog `software_refs` field

External software

Category 1: Tracked Software (Emulators & Frontends)#

What comes pre-loaded#

How detection works#

Category 2: Configuration Tools (Guided Mode)#

What comes pre-loaded#

The group:member ID Format#

software_refs: Blocks in Schema YAML#

Basic usage#

Narrowing (override)#

Multiple refs#

The relationships: Field#

Catalog YAML Format#

Software-only catalog file#

Key fields#

The Configuration Package Pattern#

How Guided Mode Works#

In the CLI#

In the Web UI#

Adding New Software#

Step 1: Add to a catalog YAML file#

Step 2: (Optional) Add schema items#

Step 3: Import#

Step 4: (Optional) Add guided instructions#

Summary#

The `group:member` ID Format#

`software_refs:` Blocks in Schema YAML#

The `relationships:` Field#