Build once. Enforce everywhere.

1. Purpose and Non-Negotiables

Gamepad Enforcer is the shared input, overlay, cursor, diagnostic, and support layer for Puzzlum/GE-supported browser games. A GE fix should normally land in shared GE code, not in a single game, whenever the behavior is expected across all supported games.

2. Module Map and Supported Games

GE-supported games

Supported project directories are Desert-Storm-WMD-Sweeper, Dungeon, Mineshaft/2D, Mineshaft/3D, Overworld, and Roe2. Releases include official and alpha.

3. Paths, Bootstrapping, and Safe Roots

Keep a strict difference between repository/filesystem paths and browser runtime URLs.

Boot order

<!-- Runtime example: no /public in browser URLs. -->
<script src="/Gamepad-Enforcer/js/ge.js"></script>
<script src="/Gamepad-Enforcer/js/gamepad-input.js"></script>
<script src="/Gamepad-Enforcer/js/ge-overlay.js"></script>

Safe roots

• JavaScript-based file manipulation is limited to ${ink.origin}/Gamepad-Enforcer/ and ${ink.origin}/${ink.release_dir}/${ink.project_dir}/.
• Extra allowlisted roots such as /Gamepad-Enforcer/, /GE/, and /Gamepads/ require ge_paths truthy. Default is false.
• Do not hard-code local vhosts, private GoDaddy paths, or development-only hostnames.

4. Runtime State Contract

GE-owned UI reads the GE runtime. GE-supported games consume the resolved GE state; they do not reinterpret raw browser input on their own.

window.ge = window.ge || {
	state: [],              // per-slot resolved runtime state
	raw: [],                // raw sampled gamepad state for diagnostics
	config: {},             // loaded controller mappings/configs
	aliases: {},            // semantic alias tables
	chords: {},             // chord definitions such as SS
	combos: {},             // combo definitions such as Full-Hold
	hud: {},                // GE HUD surfaces and hitboxes
	overlay: {},            // GE Overlay model
	cursor: {},             // GE Cursor state
	dump: {}                // GE Dump diagnostics helpers
};

Polling cadence

GE/GEDU diagnostic polling should target 20fps, with refresh delay clamped to a 50ms minimum. Render animations may use the browser frame loop, but raw input state should not be sampled by multiple unsynchronized loops.

5. Input Pipeline

The input pipeline turns unstable browser/gamepad data into stable, semantic game actions.

Raw state rules

• When a gamepad slot timestamp freezes, maintain the last known raw input state for that slot rather than zeroing it.
• Raw axes are not assigned consistently across all controller types. Use resolved aliases/config mappings for gameplay and cursor movement.
• Gamepad Faces map through the alias chain, not raw browser input indexes.
• Raw A, B, X, Y labels are Xbox-style by default. Nintendo-style labels are selected only when the config/device indicates Nintendo/Switch/Joy-Con/8BitDo Nintendo layout or face labels are in Nintendo order.

Labeled Input Processing

Labeled Input Processing should be its own class. The class receives raw slot samples plus the selected controller config and emits stable labeled values such as Face South, Left Stick X, Overlay Toggle, Cursor Click, or a game-specific action alias.

class LabeledInputProcessor {
	constructor({ aliases, chords, combos, config }) {
		this.aliases = aliases;
		this.chords = chords;
		this.combos = combos;
		this.config = config;
		this.previous = new Map();
	}

	processSlot(slotIndex, rawSample, nowMs) {
		const mapped = this.applyControllerConfig(rawSample);
		const labels = this.applyAliases(mapped);
		const chords = this.applyChords(labels, nowMs);
		const combos = this.applyCombos(labels, chords, nowMs);

		return {
			slotIndex,
			timestamp: rawSample.timestamp,
			mapped,
			labels,
			chords,
			combos
		};
	}
}

6. Chords, Combos, and Repeats

GE combos are semantic. Do not encode raw buttons into game logic.

7. GE Overlay

GE Overlay is GE-owned UI. It displays controller state and GE feature status by reading window.ge, not by scraping game input handlers.

Responsibilities

• Show active gamepad slots, resolved aliases, pressed/held/released states, and meaningful GE feature toggles.
• Display the actual physical controller-based face symbols for the selected family/layout.
• Do not display the family name inside face activations. Show the symbol and the value.
• For face buttons and D-pad directions, render the label above the value. Sticks may use a stick-specific visual layout.
• Toggle through the shared combo path: Overlay Toggle → SS: Full-Hold → Released when that mapping is configured.
• SS: Full-Hold must toggle the overlay both on and off, regardless of current slot.

Controller family display rules

Overlay visual contract

• GE Overlay and Rankings must use the same press/bump feedback on hitbox click/release.
• GE Overlay and Rankings must use the same active/brighter outline behavior when toggled on or open.
• Overlay hitboxes participate in the shared GE HUD ZIndex hit-test, not in an independent click stack.
• Overlay should remain readable when a game modal consumes gameplay input, unless that modal explicitly hides GE UI.

8. GE HUD Features

GE HUD is the shared on-screen control surface for GE features such as Overlay, Rankings, Cursor, Dump, and diagnostics.

Hitbox rules

• Every GE HUD hitbox has a ZIndex and participates in topmost-first hit testing.
• Only the winning topmost hitbox should receive a pointer/gamepad activation for a given press.
• Click/release feedback must be consistent across HUD items: bump on press/release, brighter outline when active/open.
• The first HUD click must be fully actionable. Do not require a warm-up click to arm a hitbox.
• HUD hitbox geometry updates must happen before input dispatch for the current frame/tick.

Input consumption

function dispatchPointerPress(pointer) {
	const hudHit = ge.hud.hitTest(pointer, { topmostOnly: true });

	if (hudHit) {
		ge.hud.activate(hudHit, pointer);
		return { consumedBy: 'GE HUD', allowGame: false };
	}

	if (game.modalConsumesInput()) {
		return { consumedBy: 'Game Modal', allowGame: false };
	}

	return game.dispatchPointerPress(pointer);
}

HUD feature registry

9. GE Cursor

GE Cursor is the shared virtual cursor system for mouse/gamepad-supported UI and game surfaces. It must feel consistent across supported games while allowing game-specific hover rendering.

Core rules

• Gamepad cursor motion uses GE-resolved stick aliases/config mappings, never fixed raw axes.
• Mouse-based cursor motion and gamepad-based cursor motion update the same cursor state object.
• Cursor render should sit above game canvas layers and below deliberate modal overlays when those overlays own input.
• Cursor hover hit testing honors GE HUD ZIndex first, then game UI, then game world.
• Cursor click uses resolved labels such as Cursor Click or a mapped face alias, not raw button[0].

Magnitude-aware movement

Stick motion should throttle based on inverse stick magnitude while applying a configurable gain. Small stick values move precisely; strong stick values move quickly and smoothly. This system belongs in GE Cursor itself, not in one game adapter.

function updateGeCursorFromStick(cursor, stick, dtMs, config) {
	const deadzone = config.deadzone ?? 0.15;
	const gain = config.cursorGain ?? 1.0;
	const maxSpeed = config.cursorMaxSpeed ?? 1200;
	const magnitude = Math.hypot(stick.x, stick.y);

	if (magnitude < deadzone) {
		cursor.velocity.x = 0;
		cursor.velocity.y = 0;
		return cursor;
	}

	const normalized = Math.min(1, (magnitude - deadzone) / (1 - deadzone));
	const speed = maxSpeed * gain * normalized;
	const nx = stick.x / magnitude;
	const ny = stick.y / magnitude;

	cursor.x += nx * speed * (dtMs / 1000);
	cursor.y += ny * speed * (dtMs / 1000);
	cursor.x = clamp(cursor.x, 0, cursor.bounds.width - 1);
	cursor.y = clamp(cursor.y, 0, cursor.bounds.height - 1);
	return cursor;
}

Game-specific hover responsibilities

10. GE Dump Diagnostics

GE Dump creates a structured diagnostic snapshot for debugging input mapping, overlay state, HUD hitboxes, GE Cursor movement, and GE-Ink loading without disturbing gameplay.

Dump payload

Reference helper

function createGeDump() {
	const ge = window.ge || {};
	const ink = window.ink || {};

	return {
		meta: {
			createdAt: new Date().toISOString(),
			location: String(location.pathname + location.search),
			userAgent: navigator.userAgent
		},
		gamepads: {
			raw: ge.raw || [],
			state: ge.state || []
		},
		aliases: {
			aliases: ge.aliases || {},
			chords: ge.chords || {},
			combos: ge.combos || {}
		},
		overlay: ge.overlay || {},
		hud: ge.hud || {},
		cursor: ge.cursor || {},
		ink: {
			origin: ink.origin,
			release_dir: ink.release_dir,
			project_dir: ink.project_dir,
			ge_paths: !!ink.ge_paths
		},
		game: window.geGameAdapter?.diagnostics?.() || null
	};
}

11. GE-Ink Integration

GE-Ink is the shared safe loader/converter for GE-supported games. It should expose window.ink reliably and avoid overwriting GE-Ink-derived server globals.

Data conversion rules

• .csv files are comma-separated value files.
• GE-Ink should directly convert CSV to JSON unless plain or raw flags are present.
• CSV should convert to PNG only when the png flag is set.
• Flags do not need assigned values. ?png and ?png=1 should both be acceptable.
• Every image produced by GE-Ink must render onto a transparent alpha base.

Asset path expansion

// Request string used by a game or support module:
assets/textures/json/WATR_004_24.json?png=1&frame=0&w=8&h=8&style=cover

// GE-Ink expands according to origin/release/project rules:
${ink.origin}/${ink.release_dir}/${ink.project_dir}/assets/textures/json/WATR_004_24.json?png=1&frame=0&w=8&h=8&style=cover

Obsolete route policy

12. GEDU Developer Utility

GEDU is the development utility for inspecting and assigning gamepad mappings without hiding raw browser behavior.

GEDU raw table rules

• Refresh the raw diagnostic table immediately from navigator.getGamepads().
• Do not wait to load /Gamepads/<controller>.json before showing raw rows.
• Auto detection stays behind an explicit Auto button.
• The table starts with raw input rows, then assignable types and labels.
• Raw polling owns raw table construction. Layout/config application must not re-trigger polling.
• Diagnostics refresh should not reapply config/layout or dispatch layout/config events.

Duplicate fetch prevention

Use a shared cached JSON getter for aliases, defaults, chords, combos, and controller configs. Do not let Main.js, gamepad-input.js, GamepadConfigSelect.js, GamepadOverlay.js, and helpers independently fetch the same GE JSON tables.

13. Game Integration Contract

A GE-supported game integrates by consuming the shared GE state and declaring its game-specific action meanings.

Adapter shape

window.geGameAdapter = {
	name: 'Dungeon',
	projectDir: 'Dungeon',
	releaseDir: 'alpha',

	consumeGeState(state, ge) {
		// Read resolved aliases and combos only.
		// Do not sample navigator.getGamepads() here.
	},

	consumeHudAction(action, ge) {
		// Handle GE HUD feature actions or return false.
		return false;
	},

	diagnostics() {
		return {
			modalConsumesInput: this.modalConsumesInput?.() || false,
			activePanel: this.activePanel || null
		};
	}
};

Integration checklist

• Load GE support once per page refresh for GE-supported games, GEDU, and Gamepad-Enforcer.
• Use runtime URLs without /public.
• Use direct public paths / JS GE-Ink, not obsolete ink.php.
• Read window.ge.state[slot] for gameplay input.
• Route face buttons through alias mappings and family display rules.
• Let GE HUD hitboxes receive their activation before modal gameplay input consumes the event.
• Use GE Cursor for gamepad cursor motion; implement only game-specific hover/render behavior in the adapter.
• Expose a safe diagnostics object for GE Dump.

14. Per-Game Notes

15. Troubleshooting

16. Smoke Tests and Release Checks

Shared GE smoke tests

• Connect an Xbox-style controller; confirm raw A/B/X/Y displays as Xbox by default.
• Connect Nintendo/Switch/Joy-Con/8BitDo Nintendo-style layout; confirm face labels display in Nintendo order only when config/device indicates it.
• Hold Start + Select; confirm SS: Full-Hold toggles GE Overlay on and off regardless of slot.
• Click/toggle GE Overlay and Rankings; confirm identical bump and active/brighter outline behavior.
• Click each GE HUD item from a cold page load; confirm no first-click misses.
• Move GE Cursor with mouse and gamepad; confirm both update the same cursor state and topmost hit target.
• Open GE Dump; confirm payload contains gamepads, aliases, overlay, HUD, cursor, Ink, and game diagnostics without private filesystem roots.
• Open GEDU; confirm raw table appears immediately before Auto/config selection.

Packaging rules

• Use path-preserving deltas. Modified files must land at their real project paths.
• Include obsolete-file removal scripts when replacing duplicate GE files. Keep the new /public/Gamepad-Enforcer/js/ and PHP boot paths intact.
• Do not delete rankings, saves, GE state, or other non-image localStorage tables when clearing stale image caches.
• Zip artifacts must be valid and complete. No placeholder files, stubs, or “TODO” implementations.

17. Coding Style and Patch Discipline

Patch discipline

• Prefer narrow shared fixes over duplicate per-game patches.
• Do not rewrite unrelated game systems to fix a GE support bug.
• Do not let diagnostics mutate gameplay state.
• Keep raw input, resolved input, rendered overlay, and game actions as separate layers.
• When fixing an input regression, test at least one Xbox-style mapping and one non-Xbox family mapping.

18. Glossary