One- or Two-Button Game Design Guide

Building accessible games and apps for Ben and families like ours. This guide provides comprehensive principles, input models, and best practices for creating experiences that work with just two keys: Spacebar and Return.

This page is the overview. The full implementation reference — shared module APIs, the exact input contract, per-game input models, and known traps — lives in bennyshub/ACCESSIBILITY.md in the repo. Where the two ever disagree, that file is the authority, because it is written from the shipped code.

Core Principles

Entire app and every game must be fully usable with only two keys: Spacebar and Return, plus optional mouse or touch for caregivers or users who have those access options.
And fully usable with one key. With Auto Scan on, Return alone must reach everything. One switch is the real floor, not two.
No reflex or precision demands. Nothing may depend on reacting fast or hitting a small target. Where a game does use time pressure or a fail state, it must come with a no-fail or menu-based alternative.
All actions should be available through scanning and selection.
Independence is the measure. A player must get from the hub's front page, into a game, through its menus, into a round, out to pause and settings, and back to the hub, alone. A screen that quietly needs a second person is a serious bug.
"One switch" describes an input, not a person. Build for the range: difficulty options, no-fail modes, and editors that let a caregiver tune content to the player.

Input Model

Spacebar Controls

Short press (release): Move highlight forward in the current scan list. Activates on release so accidental holds don't trigger selection.
Hold: Scan backwards through the list, repeating at the player's chosen scan speed. Release stops it. (Auto-scan is a saved setting, not a hold gesture — see Scanning Behavior.)

Return Controls

Short press (release): Select the currently highlighted item.
Hold: Open the pause or context menu, or exit a sub-mode. Use this for options, help, or a safe back button. Always pair it with an on-screen button that does the same thing.

Mouse or Touch (Optional)

For caregiver support or for individuals who have mouse, touch, or eye-tracking access.
Click to select, click and hold to open context menus when appropriate.
Never require dragging.

Scanning Behavior

Two schemes, and every game supports both. The player picks once, in Settings, and the choice is shared across the whole hub by NarbeScanManager. Auto Scan off (default) = two switches: Spacebar moves the highlight, Return selects. Auto Scan on = one switch: the highlight advances by itself and Return is the only key needed.
Scan speed is the player's setting, not yours. 1, 2, 3, or 4 seconds, read from NarbeScanManager.getScanInterval(). Never hard-code a scan interval, and never print one in help text.
Know what the scan manager does and does not own. It owns the scan interval (which is also the repeat rate once backwards scanning starts) and the 250 ms debounce — nothing else. The hold thresholds are not in it: each game hard-codes its own, and the same 3000 appears in more than a dozen files under a different name each time. So match the convention — roughly 3s to start scanning backwards, roughly 5s to pause — but never state a duration as a promise, because nothing enforces it.
With Auto Scan off, scanning starts on the first Spacebar press in a scene. With Auto Scan on it starts by itself — a one-switch player must never have to press anything to get the cursor moving.
Row scanning: Spacebar cycles rows, Return enters a row. Within a row, Spacebar cycles buttons, Return selects. This is how the grid games (Battle Boats, Connect Four, Chess & Checkers) stay reachable with one switch.
Predictable loop order: Top to bottom, left to right. Never reorder during a session.
Focus memory: When returning from a submenu, restore highlight to the last focused item.
Debounce is already handled. scan-manager.js enforces a 250 ms global cooldown after any release, so a bouncing switch or a tremor produces one clean press. Do not add your own.

Recommended but not yet standard: a "deadzone" step with no highlight before a list wraps back to the top, letting the screen rest and making the wrap audible. Only Benny Says does this today.

Visibility and Audio

Visual Design

High-contrast UI by default, large hit targets, generous spacing
Never signal state with colour alone, and make the highlight unmistakable — colour and thickness
The hub itself offers UI size (Default, Large, Larger, Largest), highlight colour (6), highlight style (Outline or Full Cell), text colour (7) and background theme (11). Match that vocabulary rather than inventing your own naming

Text-to-Speech

TTS for all labels, menu names, states, and outcomes, through NarbeVoiceManager
Speak on focus and on selection, and speak outcomes
Treat the voice manager as the single source of truth for whether TTS is on and which voice is selected — never keep your own copy of that state
Expose TTS on/off and Voice in your settings. Rate, pitch and volume exist in the manager and can be passed per-utterance, but no game currently surfaces them as controls
Keep spoken labels short — they are read at every scan step, and at a 1-second scan speed a long label becomes a drone
TTS should never block input

Sound Effects

Use SafeAudio, never the Web Audio API — an AudioContext can take down the renderer in the Electron desktop build
SafeAudio.preload(name) with no URL synthesises a built-in blip. Passing a URL that 404s permanently shadows the built-in, and it fails silently

Layout and Components

Consistent header: Title, Help, Settings, Exit to Main Menu
Footer: Current mode, current scan target name, and a simple legend: Space = next, Return = select, Return hold = menu
All dialogs and menus scannable using the same pattern as gameplay
Large buttons, minimum 64px height on tablet
Avoid small tap targets
Never require keyboard keys other than Spacebar and Return

Game Mechanics That Work Well

Golden rule: remove the precision and reaction demand from a genre — not the genre itself. Almost any kind of game can be made switch-accessible. What cannot be made accessible is a control that requires fast, accurate, continuous input.

An earlier version of this guide ruled out whole genres — racing, action, anything with a fail state. The hub has since shipped all of them successfully, so the guidance below reflects what actually works in practice.

The patterns that make hard genres work

These four patterns are what let a one-switch player do things that normally need a mouse and fast hands. Reach for them before concluding a mechanic is impossible.

Oscillate and stop — instead of aiming, a marker travels along the arc and the player stops it where they want it. This replaces pointing entirely. It has two forms, and a game should offer whichever matches the player's scheme: player-driven (the marker moves only while the switch is held, and each press reverses it — full control, needs a hold) and self-driven (the marker sweeps continuously and a single press commits — needs no hold at all). Bowling, P3GL and Basketball Shooter all use this; P3GL switches between the two forms with Auto Scan
Charge and release — instead of setting a power level, hold and let go; longer hold, more power, on a non-linear curve so short taps stay usable. Bowling, Football, Mini Golf. Always plan a select-based alternative for players who cannot sustain a hold
Row, then column — two-stage scanning reaches any 2-D grid with one switch. Battle Boats, Connect Four, Chess & Checkers, Tic Tac Toe
Armed direction — one switch drives two directions by making release meaningful: press moves the armed way, letting go arms the other, so a quick tap swaps sides. Race Tracks' one-switch steering

Genres already proven here

Turn-based and puzzle — matching, memory, sequencing, sorting, word building, trivia, logic, board games. The easiest to adapt and still the backbone of the hub
Sports — Baseball and Football play a whole season through play-calling menus with no reaction element at all; Bowling, Mini Golf and Basketball use oscillate-and-stop
Racing and action — Race Tracks steers with one switch and pairs a ten-level ladder with a no-fail Cruise mode. Bug Blaster is turn-paced tower defence
Cause and effect — one press, immediate audio-visual payoff, no strategy required. Mega Slot and Show n Sound. Genuinely valuable for players who are building the idea that their action causes a result, and often the right first game for someone new to switch access
Creative and editor-driven — Trivia Master, Matchy Match, Mini Golf's course editor. Highest replay value of anything in the hub, because a caregiver can tune the content to the player

Genre vocabulary in use in games.json: Strategy, Sports, Arcade, Classic, Board, Educational, Memory, Interactive, Simulation, Action, Puzzle, Trivia, Casino, Racing. Reuse one of these where it fits — the hub's genre filter is built from this list.

What to actually avoid

Never require: reaction tests or quick-time events; continuous multi-axis control (steering plus speed at once); precise pointing at small targets; dragging; anything that punishes a slow or accidental press; and any fail state the player cannot see coming.

Use with care, always paired with an alternative: timers, health or lives, and hold-to-charge. All three exist in shipped games and all three work — but only because a no-fail mode, generous limits, or a menu-based alternative sits alongside them.

Feedback and State

On focus change: Speak the item name and show a strong highlight
On selection: Speak confirmation and show a brief glow or scale pulse
On error or locked action: Speak a short helpful line (e.g., "Need the key for this door")
Always provide Undo or Back in the context menu reached by Return hold

Menus and Pause

Holding Return opens Pause anywhere in gameplay. Include Continue, Restart, Settings, Main Menu and Exit Game
Always pair the hold with an on-screen Pause button that does the same thing, for mouse, touch and caregivers
Make the hold visible while it happens — a filling ring and a rising beep, as Race Tracks does. A long hold with no feedback reads as a broken control
Hold Return should also back out of sub-rows to row-select mode
Settings must be reachable from the pause menu as well as the main menu — a scan speed that turns out to be too fast has to be fixable without abandoning the round
Exit Game must tell the hub: window.parent.postMessage({ action: 'focusBackButton' }, '*'). Without it the player finishes your game and is stranded with focus on a dead screen

Direction of travel: holding a switch is itself an ability, and some players cannot sustain one. Pause is moving toward being a scannable item in every game, with the hold kept as a convenience. Favour a scannable pause entry in anything new.

But know what it costs. A scannable control is another stop on the scan cycle, and the player passes it on every pass, all session. If firing is the only in-play action, the player can just play; add a scannable Pause and every shot means cycling past Pause to reach Fire — a tax paid even by players who never pause. Hold gestures cost nothing during play but exclude players who cannot hold; scannable controls include everyone but tax every action. Neither is simply better.

Where you can, keep the primary gameplay action off the scan cycle, put the scannable pause somewhere it does not sit between the player and the thing they came to do, or make it a setting so only the players who need it pay for it.

Warn before a one-way door

A mis-timed Enter is the normal failure mode of switch access, not a rare accident. If a mis-scan opens a screen the player cannot operate or exit — an editor, an external tool, a file picker, anything that leaves the site — they are stranded until somebody walks past. Anything mouse-only must sit behind a confirmation.

The editors are the main case: they need a mouse and keyboard and are not switch-operable. Every game that has one already guards it — Trivia Master, Mini Golf, Show n Sound, Matchy Match, Word Jumble and P3GL. Match that pattern:

Confirm first. Never let a single select open a mouse-only screen
Cancel before Continue in the scan order — if the player mis-scans again inside the warning, the accident should land on the way out
Trap the scan inside the dialog — while it is open the scan list contains only its own buttons. A warning you can scan straight past is not a warning
Speak it the moment the dialog opens — not when the player scans onto an option. Many players do not read, and for them an unspoken warning is not a weak warning, it is no warning at all: they see a screen change they cannot interpret and press their switch again. Speaking only the option labels is not enough; "Continue" and "Cancel" say there is a choice but not what makes one of them dangerous
Say what will happen in plain words — "you will not be able to scan and select with your switch" beats "this feature is advanced". Name the thing they lose, which is scanning

Settings to Include

Every game uses the same list, in this order. The consistency is part of the accessibility — a player who learns one settings screen has learned all of them.

Text to Speech — On / Off
Voice — cycles the available voices
Game-specific options — difficulty, theme, ball style, direction help, and so on
Auto Scan — labelled On — One Switch / Off — Two Switches, not just On/Off. It is the control-scheme selector, and the person changing it is often a caregiver setting the game up for someone else
Scan Speed — 1s / 2s / 3s / 4s
Sound Effects — On / Off
Reset Progress — must be two-step; a single mis-scan should never erase everything
← Back

Auto Scan, Scan Speed, TTS and Voice are global — read and write them through NarbeScanManager and NarbeVoiceManager so a player configures their access once for the whole hub, not once per game. Game-specific options are yours to store.

Data and Persistence

Auto-save progress on each selection that changes state
Resume puts the player back in the exact frame with the previous highlight restored
Access settings are global via the shared managers; game progress is the game's own

QA Checklist Before You Ship

✓ Can every action be performed with only Spacebar and Return?
✓ Can every action be performed with Return alone, with Auto Scan on?
✓ Can the same action be performed with mouse or touch, with no dragging anywhere?
✓ Does anything mouse-only or off-site sit behind a spoken confirm, with Cancel first and the scan trapped in the dialog?
✓ Do menu actions fire on release, not on press?
✓ Does holding Spacebar scan backwards in every menu?
✓ Does holding Return open Pause from anywhere in gameplay, with visible and audible feedback while holding?
✓ Is there an on-screen Pause button that does the same?
✓ Are Settings reachable from both the main menu and the pause menu?
✓ Do Auto Scan and Scan Speed read from NarbeScanManager, with no hard-coded interval?
✓ Does TTS read focus, selection, errors, and outcomes via NarbeVoiceManager?
✓ Is all sound through SafeAudio, with no AudioContext?
✓ Is Reset Progress two-step?
✓ Does Exit Game send postMessage({ action: 'focusBackButton' })?
✓ Does help text describe holds without quoting a number of seconds?
✓ Is there nothing that demands a fast reaction or a precise target?
✓ If the game has a fail state, timer, or hold-to-charge, is there a no-fail or menu-based alternative?
✓ Is it readable at 100% on a tablet?
✓ Does the game auto-save and resume correctly?
✓ Is it listed in games.json with a thumbnail and genres?
✓ Has someone who is not you played it start to finish with one switch?

Example: P3GL (Peggle-style Game) Input Setup

P3GL is worth studying because the same game presents a different aiming model in each control scheme — and that is what lets one build serve both a two-switch player who wants control and a one-switch player who cannot hold a switch at all.

Two switches (Auto Scan off)

The player drives the aimer by holding. It does not sweep on its own.

Spacebar (hold): the aimer sweeps while the switch is down, and stops the instant it is released. A brief press nudges it a little; a long hold moves it far
Each new press reverses direction, so the player walks the aimer onto the target — over, back, in — instead of chasing a moving marker
The aimer also turns around by itself at the edges of its arc, so it can never be driven off the end
Return (press): fires
Return (hold): opens the pause menu

One switch (Auto Scan on)

The aimer oscillates continuously on its own and Spacebar is not needed for aiming at all.

Return (press): fires at the current angle — the only input the game requires
Return (hold): opens the pause menu

Aimer Speed

Four presets — Fast, Medium, Slow, Super Slow — defaulting to Super Slow. This is the difficulty dial for the whole game, and defaulting to the slowest setting is deliberate: it makes the game winnable first, and a player who wants more challenge can speed it up.

Two things to take from this. The same mechanic can be expressed as "hold to move" or "press to commit" depending on the player's scheme — build both rather than picking one. And the speed of anything that moves on its own should be a setting, defaulted to the accessible end.

P3GL is deliberately hold-first, and that is a considered trade rather than an oversight. Keeping aim, fire and pause on holds and presses means play costs the fewest possible switch actions — nothing sits between the player and the shot. Scannable aim-to-shoot and Pause buttons are both easy to add and are wanted eventually, for players who cannot hold at all; they would also add steps to every shot. For this game, as it stands, the hold-based build is the right call and it works.

Get in Touch

Have questions or want to contribute? Reach out to us.