Reading a machine definition

Identity: machine, driver, device

Three identifiers do three different jobs, and keeping them apart is what lets a table survive a catalog update.

machine.idstern.metallica-pro.2013

The physical product. One playfield, one wiring loom, one definition — however many ROM revisions exist.

driver idmtl_180h

An exact PinMAME ROM set. Many drivers resolve to one machine; clones share its definition unless a hardware difference is recorded.

device idswitch.fuel-lane-rollover

A stable semantic name for one input or output. This is what a table should bind to. If a controller number ever changes, the device id does not.

Addresses and bindings

Every device carries a binding: a group plus a signed device number. The group names the address space — pinmame.input.switch, pinmame.output.solenoid, pinmame.output.lamp — and the platform profile says which numbers are legal in it.

Numbers are the values PinMAME's public API reports, not hardware pins. WPC-family machines address the matrix as column·row, so 52 is column 5 row 2. SAM and later platforms number sequentially. Negative numbers are real: they carry diagnostic and dedicated inputs that sit outside the matrix.

Device kinds

A small taxonomy, used consistently. The colour of a chip means the same thing on every page.

• Switch A matrix or dedicated input the ROM polls. The address is the public PinMAME switch number, not a hardware pin.
• DIP switch Configuration bits on the CPU board. Not playfield hardware — they set replay levels, country and options.
• Coil A driver output that moves something: kickers, ejects, posts, drop-target resets, flippers.
• Flasher A driver output whose only job is light. Same address space as coils on most platforms.
• Lamp A lamp-matrix channel. Insert lighting, controlled per address.
• RGB lamp A colour-addressable lamp, modelled as a parent with explicit channel bindings.
• General illumination General illumination string. Often a single aggregate channel switching the whole string at once.
• Magnet A holding or steering electromagnet. Strength and timing come from the recreation notes.
• Motor A continuously driven mechanism — spinning toys, moving targets, gun turrets.
• Relay Switches a circuit rather than driving a device directly.
• Virtual Not physical hardware. A state the emulator exposes on an output address, such as SAM’s game-on flag.

Polarity belongs to hardware, not to your table

Platform profiles declare inversion_applied_by_emulator. Where it is true, PinMAME has already normalised the signal and reports logical active state. Inverting again in a table produces a machine that boots with every optical switch backwards.

Separately, a switch may be marked normally_closed. That is a physical fact about the real part — an opto that conducts at rest, a drop target closed while raised. Build the right hardware behaviour; do not convert it into a runtime flip.

Portable roles

Cabinet and service inputs carry roles like cabinet.start, flipper.lower.left and service.up. They are deliberately engine-neutral: the catalog says which address is the start button, and the consuming engine decides which key or input action that maps to.

ball.position marks the switches a ball rests on at boot — build balls there and the ROM finds a full trough. position.* marks mechanism home, up, down and index sensors.

Mechanisms and direct wiring

A mechanism ties actuators and sensors together and describes how the assembly behaves — which output ejects, which switch confirms, what state it starts in. Where a known-working table exists, the note carries its tested strengths, angles and timings as a starting point rather than a guess.

Relationships are the connections that exist in copper. A pulse relationship means closing that switch fires the coil in hardware — pop bumpers and slingshots do this — so it must fire whether or not a game is running. Do not wait for the ROM.

Coverage and confidence are two different things

Coverage is the lifecycle of the whole definition: stub, partial, or author-ready. It is fail-closed — only the completeness validator can grant author-ready, and it refuses while any address is unnamed, any mechanism lacks its topology, or the recreation note is missing.

Provenance is per assertion: unknown, candidate, observed, validated, conflicted, deprecated. Observing that output 11 toggled is not the same as knowing it is the gun motor, and failing to observe an output is not evidence that it is unused.

When sources disagree

Precedence is domain-specific, not a single ranking:

• A known-working VPX script wins on controller addresses, callbacks, ball routing and mechanism causality. It is proof that a real ROM accepts those bindings.

• The operator manual wins on wiring, connectors and wire colours, part numbers, switch construction and polarity, and assembly geometry.

• Pinned PinMAME source wins on emulator group routing, display layout, output typing, and whatever the public API normalises before you see it.

A lower-priority source can still open a conflict when the higher-priority one is ambiguous, incomplete, or is clearly implementing a virtual simplification rather than the physical mechanism. Unresolved conflicts stay visible at the top of a machine page rather than being quietly decided.

A working order

1. 1

   Look up your ROM set to find the physical machine it resolves to, and check the coverage badge before you rely on anything.

2. 2

   Read the “Wire it up” panel: platform, display geometry, address ranges, ball positions at boot, cabinet and flipper roles.

3. 3

   Build the switches from the switch map, keeping unused addresses genuinely empty so the ROM sees the real machine.

4. 4

   Wire the coils, flashers, lamps and GI, then add the direct-wired pulse relationships so pops and slings fire in hardware.

5. 5

   Implement each mechanism using its actuators, sensors and behaviour text — and the tuning values from the recreation note.

6. 6

   Read the recreation note end to end before shipping. It is where edition differences and the “do not copy this” warnings live.

The specification

Everything above is a reading of one document. These link to the section that defines it.

• Identity hierarchy
• Group and routing model
• Device and mechanism model
• Provenance and validation states
• Inheritance and merge rules