‹ Plugin Player docs

The controller

0. Plug in your controller

Xbox, PlayStation and 8BitDo Micro controllers work the moment they are connected. Plug it in with a USB cable that carries data (or pair it over Bluetooth: CONTROLS → CONNECT A CONTROLLER walks you through it; on Windows, Plugin Player can pair an 8BitDo Micro or a PlayStation controller for you, and on a Mac you pair in System Settings → Bluetooth; CONNECT_A_CONTROLLER.md), press any button, and every scene reacts. You do not set anything up.

• Plugin Player draws your controller on screen (the small plate on the PERFORM screen, the big one on the CONTROLS tab) and names every button the way it is printed on it.
• A short note appears over the picture on your laptop screen: XBOX CONTROLLER CONNECTED: READY (or PLAYSTATION, or 8BITDO MICRO). It never shows on the projector.
• Windows only shows a controller to an app after its first button press, so if the chip at the top says CONNECTED · PRESS ANY BUTTON, press one.

The buttons are the same job on every controller, in the same spot. A scene that says "A: random look" means the button on the right of the four, whatever your controller prints there:

The legends, the footer bar and the CONTROLS table always print your controller's own symbols, so you never translate in your head. The right stick moves the camera in a few scenes (see below); the Xbox guide button and the PlayStation PS button are left to the operating system.

Wrong picture? Some controllers look like another to the computer (an 8BitDo switched to X mode shows up as an Xbox controller). Open CONTROLS and pick yours in the CONTROLLER dropdown: Auto (what was found) · 8BitDo Micro · Xbox · PlayStation · Other (standard). Plugin Player remembers your choice. Pick Auto to go back.

Other controllers. Most USB and Bluetooth game controllers that the computer treats as a standard gamepad work too; they get a plain plate with L1 / R1 / SELECT / START. Want yours drawn and named properly? The line under the dropdown says Want your controller added? Tell us.

The 8BitDo Micro

Plugin Player was designed on the 8BitDo Micro. It is small, Bluetooth, about $25, and every button on it has one job. The rest of this page is written for it; on another controller, read the table above for the names.

Buy: [buy link]

1. The one rule

Slide the mode switch to D before you pair. In D the Micro is a gamepad and Plugin Player sees it. In K it is a keyboard and in S it is a Switch controller; in both it shows CONTROLLER NONE forever, even though Windows says Connected.

2. Pair it

In Plugin Player: CONTROLS → CONNECT A CONTROLLER → 8BitDo Micro. On paper: CONNECT_A_CONTROLLER.md (every controller), and PAIRING_8BITDO.md. It is step-numbered and lists what Windows shows at each step and what every failure looks like.

The short form on Windows: switch to D, hold PAIR (the small button on the bottom edge) for 3 seconds, wait — with Plugin Player open. The CONTROLLER card goes CONTROLLER LOST → PAIRING… → CONTROLLER READY; press any button and the controller name appears (Windows hands a controller to an app only after its first button press). On a Mac, switch to D and hold PAIR, then choose 8BitDo Micro gamepad in System Settings → Bluetooth and click Connect.

3. What every button does (every scene, every screen)

One press, one action. The triggers move you around; every other button plays the scene.

Music (L2 + ▲ ▼): hold L2 and press ▲ on every beat = TAP TEMPO (4 taps; one tap after a pause = this is the ONE). Hold L2 + ▼ = AUDIO ON / OFF. Keyboard: T / Shift+T. See AUDIO.md.

Blackout (L2 + R2 + ▼): a song ends and you want the stage dark, not a transition? Hold L2 and R2, then hold ▼ for one second. A ring fills around the word BLACKOUT on your laptop screen while you hold (KEEP HOLDING ▼); let go early and nothing happens. When it fills, the projector, the Spout / Syphon feed and the recording fade to black in about a second and stay black until you do it again (the ring then says BACK ON). The scene keeps playing underneath, music reaction too, so it comes back in time. While it is on, a big BLACKOUT sits on your laptop's picture (which stays visible, dimmed, so you can pick the next scene or preset in the dark) and the BLACKOUT button in the top bar is lit. Changing scenes and RESET SCENE leave it on. Also: the BLACKOUT button next to ⧉ OUTPUT, keyboard B, MIDI / OSC /pp/blackout (MIDI_OSC.md). Same move on every controller and in both channels (scene and fluid).

While you hold L2 or R2, the d-pad belongs to the trigger: the scene does not also react to those arrow presses. Let go of the trigger after choosing and nothing else happens (only a clean tap jumps to the next one).

To pick a scene from the library by sight, use the mouse or the arrow keys and Enter (§7).

3b. The effect layer (a second channel on the centre button)

Press the centre button of your controller to switch the face buttons from the scene to the effect layer, a fluid you lay over whatever is playing. Press it again to get the scene back. The fluid stays on (or off) when you switch back.

• Centre button: PS on PlayStation (L3 works too), ⊡ on the 8BitDo Micro, the Xbox button on Xbox. If Windows opens the Game Bar instead, hold View + Menu together for half a second (works on every controller: − + on the Micro, Create + Options on PlayStation), or turn the Game Bar's controller shortcut off in Windows Settings › Gaming.
• Turn the effect on and off: in the effect channel, + turns it on (OPTIONS on PlayStation, MENU on Xbox) and − turns it off (CREATE / VIEW): one tap, whatever effect the layer holds. Switching to the effect channel with it off tells you (+ TO START). Any face button also starts it. More ways to turn it off: hold ✕ for a second (you still get the shockwave on the press, then it turns off; a bar fills while you hold) or hold the centre button (PS / ⊡ / Xbox) for a second in either channel: you end up back in the channel you started in, with the effect off (a quick press still just switches channels). + or ✕ turns it back on. The camera's + / − work in the scene channel; holding + (next tab) and holding − (MAP) work in both.
• □ REACTION (the coral pattern over the fluid): □ turns it on, □ again turns it off; the monitor says REACTION ON / REACTION OFF.
• In the effect channel: ◀ ▶ change the fluid. The face buttons play over the fluid you picked and never change it: ✕ shockwave (every press, in the shock style you picked with hold R1 + ◀ ▶) · ○ ink burst (a big pour of fluid, on the beat) · △ electric (a black-and-white electric look over your fluid; △ again = back to your fluid) · □ reaction (the coral-like reaction-diffusion pattern on / off over your fluid).
• The fluid is Goop. The effect layer runs the same fluid as the Goop scene (and the Goop plugin for Resolume): the same ten looks, the same energy and dissipation. A Goop look on the layer is exactly the Goop look in the scene, only laid over whatever is playing.
• What the fluid comes from (SOURCE, on R in the effect channel and on the EFFECT LAYER card):
  • SCENE: the fluid comes off the things moving in the scene: the cubes in Cube Bloom, the panels in Corridor Panels, the particles, the blobs. It is born on their edges and where they move, it lives around them (never inside them) and it stays behind them, so they stay sharp on top: a spinning cube pushes the liquid out of its way and the fluid trails after it, the way Frame Stack's own fluid swirls around its cards and the way it trails after your hand when you wipe it across a camera.
  • YOU: the fluid comes off you, the person in front of the camera (the camera learns the empty room and treats whatever is different as you; with no camera the demo clip stands in). Over a scene with objects, your fluid still goes behind the objects.
  • AUTO (the default): SCENE whenever the playing scene shows your camera (every scene in the beta does: your camera is on its cubes, cards and panels), so pressing + never turns the fluid into a copy of your raw camera; YOU only on a scene that does not show the camera.
  • A quick tap of L1 steps AUTO → SCENE → YOU (it was R1 until Oct 31); the card shows what AUTO picked (AUTO · SCENE). Holding L1 for a second is LEARN BACKGROUND, as before.
• Scenes that have their own fluid (Frame Stack, Plane Drift, and Goop and Flashpoint, which ARE the fluid) do not take the effect layer: the centre button stays on the scene and tells you that scene's own fluid buttons (Frame Stack: △ turns its fluid on / off, ◀ ▶ change its look). A layer you turned on pauses there and comes back on the next scene.
• Shock waves: R1 sends one. Press R1 and a wave goes out through the fluid at once (if the layer was off, it comes on for it). Tap it again and again for more: up to four waves travel at once. Hold R1 and press ◀ ▶ to pick its style: IRIS RING (a ring from the centre), OBJECT BURST (the water bursts out of the cubes, panels or cards that are playing, or out of you on YOU) and the Goop scene's other shock styles; each pick sends one. Hold R1 + ▲ ▼ = how hard it pushes. Hold R1 for a second on its own = PULSE: a wave every 4.5 seconds until you hold it again. The SHOCK button on the EFFECT LAYER card sends one with the mouse.
• On Frame Stack and Plane Drift (their own fluid): hold R1 and press ✕ = a shock out of the cards / planes.
• On Goop: tap R1 = one wave, the moment you let go. Keep tapping for more: up to four travel at once. Hold R1 and press ◀ ▶ to pick its style (a small note names it); the next tap sends it. △ repeats it every 4.5 seconds. Hold L1 + ▲ ▼ = how hard it pushes. Hold L1 + ◀ ▶ = how long the water keeps flowing. A long hold of R1 = bloom.
• R2 = the next of the ten Goop looks. ◀ ▶ = the previous / next favorite fluid. ▲ ▼ = energy. Hold L1 + ◀ ▶ = dissipation (how fast the fluid fades). Hold L1 + ▲ ▼ = how strong the layer is. L2 still changes the scene underneath.
• If the objects fill the whole frame (a close fly-through), there is little room behind them, so you will see less fluid; the layer also eases itself down when the fluid would cover everything.
• The header shows CH SCENE or CH FX; the bottom bar, the controller plate and CONTROLS show what the buttons do in the channel you are in. The EFFECT LAYER card in PERFORM does the same with the mouse (and has HALF RES, a cheaper half-size layer for weak graphics cards).

4. Per-scene moves: the legend at the bottom changes with the scene

Each scene uses the d-pad, A, B, X, Y, L, R its own way while it is playing. L2, R2, ⊡, −, + never change. The moment another scene plays, its own moves take over.

You do not have to remember any of it. The footer bar and the CONTROLLER card show the legend for the scene that is playing, and it changes when the scene changes.

Example, Cube Bloom (what the legend reads while it plays):

Example, Corridor Panels: ○ FLASH (one ring down the tunnel per press, carrying your picture; press quickly and the rings stack; hold L1 + ◀ ▶ for the style: burst, ring, spiral, checker, scatter, wave front, shockwave) · hold L1 + ○ THE TRAIN (a train of seven rings in one press) · ✕ BARREL ROLL (hold to keep rolling) · □ ROLL ⟲/⟳ (the next barrel roll turns the other way: clockwise ↔ counter-clockwise) · △ NEW PANELS (the panels flow into a fresh deal) · hold L1 + □ AUTO NEW PANELS: the panels keep flowing into new ones in time with the speed, again for WITH LIGHT LINES (the same, with the seams lighting up as each panel changes), again for off · ▲ ▼ FASTER / SLOWER (hold to ride; three times faster at the top than before) · ◀ ▶ what the flash carries (LIGHT · YOUR VIDEO · SPRITES) · L1 FASTER · R1 DEEPER RINGS.

Example, Cube Stack: ○ TURN THE CUBES · ✕ SPIN THE STACK · △ FLUID ON / OFF (the fluid layer over the stack: the last fluid you played, else the first favorite) · □ SPIN THE CAMERA · ▲ ▼ climbs FASTER / SLOWER: a tap jolts it, holding glides it smoothly (bottom to top in about 4 seconds) and it eases to a stop when you let go · ◀ ▶ PREVIOUS / NEXT FAVORITE FLUID (turns the fluid on if it was off) · hold L1 and press ◀ ▶ for LESS / MORE ECHO: each screen plays your picture further back or catches up (ECHO 7.50; tap fast for bigger steps, hold to glide) · L1 tap CAMERA MOVE: picks the move □ plays, and the readout names it (CAMERA · CIRCLE PUSH, SWOOP, CUBE WAVE, ORBIT) · R1 PULL BACK (tap to lock) · hold R1 and press ▲ ▼: ▲ = closer (zoom in), ▼ = farther (zoom out) (DISTANCE 6.2; hold the arrow to glide). Using R1 with the arrows never also pulls back.

L1 / R1 boosts lock with a tap. Tap L1 or R1 quickly and the boost stays on; tap again to let it go. Hold it instead and it lasts only while you hold.

Example, Frame Stack: the camera orbits the cards on its own and a liquid glow lives around the cards · ✕ THE FLIP (the cards spin over, smooth in and out) · ○ NEW TREATMENTS on the cards · △ FLUID on / off (it stays as you change presets) · ◀ ▶ FLUID PRESET (ten looks for the liquid, the cards stay as they are) · ▲ ▼ ORBIT FASTER / SLOWER, all the way down to a stop (hold to ride) · □ LAYOUT (stack → orb → river) · L1 ORBIT BOOST · R1 PUSH IN.

Example, Plane Drift: ○ SPIN THE DRIFT · ✕ SPIN EVERY PLANE ON ITS OWN · △ MOTION (drift → wave → beat sway) · ◀ ▶ FLUID STYLE (8 colour recipes for the fluid, the planes stay as they are) · hold R1 + ○ TURN THE PATH · hold R1 + △ YOUR VIDEO IN THE PLANES ON / OFF · □ SHAPES · hold L1 ENERGY SURGE · hold R1 THICKER PLANES.

Example, Flashpoint (the fire): ○ NEXT PRESET + a burst · ✕ SPIN KICK · △ FLARE · □ COLOUR KICK · ▲ ▼ MORE / LESS FIRE · ◀ ▶ FLAME COLOURS · hold L1 ENERGY BURST · hold R1 GLOW · tap R1 MACHINE VISION on / off (hold R1 + ▲ ▼ how much, + ◀ ▶ how big, + ○ the next of four looks, which also turns it on). Viral Embers: the embers are letters; type your own in CUSTOM TEXT, at the top of PARAMS. Styles: hold L1 and press ◀ ▶ to give the camera picture under the fire a look (STYLE · THERMAL, BLUEPRINT, INKED OUTLINE, SOLARIZE … ten of them, then OFF; the fire still comes off whoever moves). Hold L1 + ▲ ▼ = how much style (down blends it back toward the real camera), hold L1 + ✕ = style off, hold L1 + △ = the style on the picture only or on the fire too. The style stays when you change presets; hold R2 (reset) turns it off. L1 held on its own is still the energy burst; it starts a moment later, so a chord never bursts.

Example, Typewriter Terrain (the camera drives the type: where you move it wakes, it follows the light, and the ink is the picture's colour; the left stick steers a brush that wakes it the same way): ✕ and ○ are hits, made for the beat: ✕ FLASHES THE TYPE TO WHITE PANELS · ○ SLAMS IN GIANT LETTERS and re-deals the field · △ YOUR WORD ↔ SCRAMBLE · □ HOW IT TYPES (typewriter → code lines → cascade → glitch burst → scan sweep) · ▲ ▼ TYPE FASTER / SLOWER · ◀ ▶ LESS / MORE TYPE · L1 BIG TYPE (tap to lock, hold to boost) · R1 TYPE ONLY: the picture drops and the type fills the frame while you hold it. Your word goes in the CUSTOM TEXT box at the top of PARAMS.

Example, Test Stage (the first scene you see; the controller check): every button, the d-pad, both sticks and both triggers light up on the controller on screen, and the analog triggers fill as you pull them. The sticks steer the two fluid balls, ✕ sends a shock wave, ◀ ▶ change the fluid style, △ the coral burst. Here the controller belongs to the scene, so L2 and R2 do not switch scenes:

• Hold L2 + R2 (pulled all the way) to leave: a bar fills on the monitor, then the next scene plays. Clicking another scene or the keyboard works as usual.
• HIDE CONTROLLER: hold L1 + tap R1 (or hold R1 + tap L1), or the HIDE CONTROLLER button on the monitor: the controller fades away and only the fluid and the balls stay. The same again shows it. Test Stage is free to play; with the controller hidden, your output (projector, Spout, recording) carries the watermark unless Test Stage is unlocked. Your own monitor never does.

Hold a shoulder, use the arrows. In some scenes, holding L1 or R1 turns ▲ ▼ to what that shoulder controls (Cube Stack: R1 + ▲ ▼ = camera distance, ▲ closer; L1 + ◀ ▶ = echo). The legend says so (R1 + ▲▼ DISTANCE). A quick tap of the shoulder alone still does its own thing.

Hold an arrow to ride. On every scene, an arrow that changes a level (speed, glow, a mode) keeps going while you hold it (stepping, or gliding smoothly where the legend says hold: glide) and stops the moment you let go. While you hold L2 or R2 the arrows choose scenes / presets instead and never ride. In the effect channel, holding ▲ ▼ ◀ ▶ glides the fluid's energy / dissipation the same way.

Tap fast = bigger steps. Tap an arrow again quickly (within about a third of a second) and that tap moves the level twice as far: ▼▼ fast slows the speed down at double the rate, ▲▲ fast speeds it up at double. A slower tap is back to one step, a hold still glides at its normal rate, and it never goes past the scene's lowest / highest setting. Arrows that walk through a list (a palette, a flash mode) always move one at a time. The effect channel's arrows do the same.

When a press moves a value (speed, energy, a hold), a small readout over the picture shows it live (ENERGY 92 % ▲) and fades a second after it settles. It is on your screen only, never on the projector.

Every scene has its own rows. The on-screen legend is always the truth.

While the output mapper is open (hold −, or the MAP tab) the controller does only mapping: d-pad nudges the corner, A/B walk the corners, X 10 px ↔ 1 px, Y test grid, L/R slice, + done, hold − cancel, ⊡ fullscreen. The legend bar and the plate relabel themselves for it. MAPPING.md §5.

The analog sticks (PlayStation and Xbox)

The 8BitDo Micro has no sticks, so nothing on it changes. On a PlayStation or Xbox controller, the right stick moves the camera in these scenes. In every one of them, push up = look up and pull down = look down:

On Corridor Panels the left stick squeezes the tunnel wider, narrower, taller or flatter, and it springs back when you let go. Otherwise the left stick is free for now. A stick never changes a saved preset: SAVE PRESET keeps the preset as it is without the sway. The CONTROLS tab lists the stick rows for the playing scene (marked STICK · READ-ONLY: sticks cannot be remapped yet). On PlayStation, clicking the right stick (R3) is the scene button, so push it without pressing down.

5. Presets: favorites first

Each scene ships with a short list of favorite presets; tap R2 for the next one, double-tap R2 for the one before, or hold R2 and press ◀ ▶ to walk them either way. The PRESETS strip under the picture shows FAVORITES by default; click ▾ to see EVERY PRESET plus your own (MINE).

• ★ on any preset adds it to (or removes it from) your favorites for that scene. Once you star something, your list replaces the shipped one.
• Love what's on screen? Save it. Click SAVE PRESET (or Ctrl+P, or on the controller hold R2 and press ▲). The preset is kept exactly as it is now, named for you (Mine 1, Mine 2, …), starred, and selected; the picture says PRESET SAVED · MINE 1 ★. (Ctrl+S saves the whole show: see below.) Because it is starred it is already on R2: tap R2 to walk your favorites and you will reach it. It survives a restart.
• Put them in your order. The order of the favorites strip is the order R2 (and ◀ ▶ while R2 is held) walks. Drag a favorite tile left or right in the strip and drop it where you want it (the accent line shows where it lands). From the keyboard, Alt+← / Alt+→ move the playing preset one place earlier / later (Alt+Shift+← / → = to the front / the end). On the controller, hold R2, hold L1 and press ◀ ▶. The picture says MOVED · NAME → 2/6. RESET ORDER (in the PRESETS header, there once your order differs) puts them back the way the scene ships; your stars stay. The order is yours on this computer, saved with your stars; it changes nothing for anyone else. EVERY PRESET keeps the scene's own order: only the favorites are walked, so only they move.
• Rename it: double-click its name in the strip, type, Enter (Esc keeps the old name). × on the tile deletes it; ★ takes it out of your favorites.
• RANDOM appears on scenes that have a random-look button (Cube Bloom's A). If a roll comes out nearly black (nothing to see), the player quietly rolls again, up to four times; darker, moody rolls are kept.

LIGHT: brighten a scene that is too dark

Keys only (the buttons left the monitor, Nov 9): L lifts the dark parts of the playing scene (up to 2.5×), K goes darker (down to 0.5×), Shift+L back to 1×. The setting is remembered per scene, and only the picture is lifted, never your projector levels (those stay in MAP). While it is not 1× the line under the scene name says LIGHT 1.4×.

AUTO is a soft floor: when the picture gets so dark you can't tell what's going on, it slowly turns the light up (a few seconds), and eases it back down when the picture brightens. Moody, darker presets you can still read are left alone. While it is lifting the line under the scene name says AUTO LIGHT 1.6×. It is on for Cube Bloom; Shift+K turns it off or on for the playing scene (remembered).

6. The controller plate

• The CONTROLS tab (F3, or hold +) shows the plate large with the playing scene's button table beside it. A button the scene leaves free says free; when a scene uses only part of the d-pad (Cube Bloom: ▲ ▼), the free arrows are listed too. MIDI and OSC are learned on the same rows: MIDI_OSC.md.
• The CONTROLLER card on the right draws a small picture of your controller (the Micro, an Xbox or a PlayStation controller) with labels on the buttons and the legend beside it.
• Shift+P opens the big plate: a full-window drawing of the controller with the legend. Press again to close.
• The pin icon in the card's corner keeps the plate docked. The − + FULL controls at the top of the big plate resize it.
• OVERLAY ON OUTPUT (the toggle under the legend) will draw the plate into the projector picture [coming]. Today the switch does nothing.

7. Keyboard fallback (laptop without a controller)

With Ctrl, Cmd or Alt held, these letters do nothing: Ctrl+Z, Ctrl+X, Ctrl+0, Ctrl+N, Ctrl+F… never change the preset, the scene or the window. The only combos are Ctrl+S (save the show), Ctrl+Shift+S (save the show as), Ctrl+P (save the preset) and, on a Mac, Cmd+1 / 2 / 3 (the tabs). Ctrl+Z is undo in MAP (one step = your last move); in PERFORM it changes nothing.

Remap your buttons

Every scene starts on its default mapping: the full list, every button of every scene, is CONTROLLER_MAP.md (generated from the scenes themselves, so it is always right). If you want something on another button, change it in about three seconds:

1. Go to CONTROLS (F3). The BUTTONS card lists every action of the scene that is playing, with the button it is on.
2. Move the mouse over a row: it lights up and an EDIT chip appears between the button and the name. Click EDIT.
3. The row says PRESS A BUTTON… (Esc cancels). Press the button you want on your controller. That press does nothing else (it does not fire the old action or change the scene).
4. Done. If that button was doing something else in this scene, that action now has NO BUTTON (shown dimmed, with NO BUTTON · EDIT so you can give it one). The message at the bottom offers UNDO or SWAP INSTEAD (the other action takes your old button).
5. Two-button moves (chords): some scenes do something extra while you hold a shoulder, shown as e.g. R1 + ▲ (hold R1, press ▲). These have their own rows. To put any action on a chord, click EDIT, then hold one button and press another.
6. No controller connected? EDIT shows the buttons to click instead.
7. A scene action can go on A B X Y, L1 / R1 (LB / RB) or the d-pad. The triggers and + / − are navigation (the GLOBAL section further down): you can move those too, but they always swap places with the button you press, so you can never lose the way to change scenes. The d-pad cannot take navigation (it is the hold + ◀ ▶ choose move).
8. ↺ RESET on a row puts that one action back; RESET SCENE, RESET GLOBAL and RESET EVERYTHING TO DEFAULT do more. Lost? Ctrl+Shift+R resets every control at once (with UNDO).
9. Your changes are kept on this computer (controls.json in the app's data folder) and never change the scenes themselves.

Button layouts (the bar at the top of the BUTTONS card; a button layout is your controller mapping, not to be confused with a scene's presets):

• LAYOUT ▾: Default (the scenes' own mapping) and every layout you saved. A * means you changed something since you picked it.
• SAVE LAYOUT: name it, choose THIS SCENE or EVERY SCENE + NAVIGATION, then SAVE AS NEW (or OVERWRITE if the name exists).
• EXPORT writes a .ppcontrols file (Documents by default) you can send to anyone. Buttons are saved by position, so a PlayStation layout works on an Xbox or 8BitDo controller.
• IMPORT opens a .ppcontrols file, lists what changes before anything happens, then APPLY + KEEP AS LAYOUT. Scenes you do not have yet are kept for later.
• SHEET shows one printable page with every scene's buttons as they are now (PRINT / CLOSE).

8. Battery and sleep

Windows does not report the Micro's battery in D mode. The LED blinks when it is low. Charge over USB-C; it works while charging. It sleeps after a while idle; press Start to wake it, then press any button so Plugin Player sees it again.