How to Use RomM's Console Mode: Complete Guide for Developers and Users

RomM's console mode provides a classic game-console-style interface accessible via the /console route, utilizing a dedicated Pinia store (consoleMode), specialized router constants (CONSOLE_HOME, CONSOLE_PLAY), and a universal input system to enable controller-based navigation through platforms, collections, and ROMs.

RomM is a self-hosted retro game library manager that offers both a standard web interface and a specialized console mode optimized for TV screens and gamepad navigation. Understanding how to use RomM's console mode requires familiarity with its routing architecture, state management, and input handling systems as implemented in the rommapp/romm repository. This guide explains the complete workflow from activation to gameplay, backed by actual source code references.

Architecture and Key Source Files

RomM's console implementation spans multiple layers of the frontend architecture, from route definitions to reactive state management.

Router Configuration in frontend/src/plugins/router.ts

The console mode operates under a distinct route namespace defined in the router plugin. According to the source code, the router registers specific CONSOLE_* constants that isolate console-specific views from the standard web interface.

• CONSOLE_HOME: Loads the main platform and collection browser
• CONSOLE_PLAY: Routes to /console/play/:romId for emulator instantiation

These routes ensure that console navigation remains separate from the standard UI, allowing for full-screen, focus-based layouts optimized for controller input.

State Management in frontend/src/stores/console.ts

The console store provides a Pinia-based state container that tracks whether the application is rendering in console mode. The store exports a reactive consoleMode boolean that components throughout the application use to conditionally render TV-optimized layouts.

When consoleMode is true, the UI switches to larger tile sizes, vertical scrolling layouts, and focus-based navigation indicators. This state persists across route changes until explicitly disabled or the user exits the console route.

Universal Input Handling in frontend/src/v2/composables/useInputModality/index.ts

Version 2 of RomM merges console behavior into the main UI through a universal input system. This abstraction layer translates keyboard, mouse, touch, and gamepad inputs into standardized navigation events. The same useInputModality composable powers both standard and console interfaces, ensuring consistent behavior across input devices while allowing console mode to prioritize directional pad navigation.

Emulator Integration in frontend/src/views/Player/EmulatorJS/Player.vue

When you launch a game from console mode, the router loads the emulator component. This Vue component handles ROM streaming, controller mapping, and error logging via console.error statements. The component detects when the user presses Esc or the back button to emit a "quit" event, triggering a router redirect back to the previous console route.

How to Activate and Navigate Console Mode

Step 1: Access the Console Interface

Navigate to /console in your browser or click the Console icon in the main navigation. The router detects this route and sets consoleMode to true in the console store, immediately switching the layout to the TV-friendly interface.

Step 2: Navigate Platforms and Collections

Use arrow keys on your keyboard or the D-pad on your gamepad to move through the grid of platforms and collections. The universal input system maps these physical inputs to navigation events that update the focused item in the reactive state. Each movement triggers visual focus indicators designed for distant viewing.

Step 3: Select and Launch ROMs

Press Enter (keyboard) or the A button (gamepad) to select a platform or collection. Navigate to your desired ROM and press the select button again. The router programmatically pushes the CONSOLE_PLAY route, passing the ROM ID as a parameter. The emulator mounts immediately and begins streaming the game.

Step 4: Return to Browsing

During gameplay, press Esc (keyboard) or the B button (gamepad) to exit. The Player.vue component captures this input, emits a quit event, and the router redirects back to the console home or previous list view.

Programmatic Control for Developers

You can interact with console mode programmatically using the exposed stores and router utilities.

Enable console mode manually:

import { useConsoleStore } '@/stores/console'

const consoleStore = useConsoleStore()
consoleStore.consoleMode = true  // Forces console UI rendering

Navigate to a specific ROM programmatically:

import { useRouter } from 'vue-router'

const router = useRouter()

function launchRom(romId: string) {
  router.push({ 
    name: 'CONSOLE_PLAY', 
    params: { romId } 
  })
}

Detect console mode in components:

import { storeToRefs } from 'pinia'
import { useConsoleStore } from '@/stores/console'

const { consoleMode } = storeToRefs(useConsoleStore())

if (consoleMode.value) {
  // Render console-optimized layout with larger tiles
}

Summary

• RomM's console mode is accessed via the /console route and toggled through the consoleMode state in frontend/src/stores/console.ts.
• The router defines console-specific paths (CONSOLE_HOME, CONSOLE_PLAY) in frontend/src/plugins/router.ts that load specialized views.
• Navigation works through the universal input system (useInputModality), supporting keyboard, mouse, and gamepad inputs interchangeably.
• Gameplay launches through the emulator component in frontend/src/views/Player/EmulatorJS/Player.vue, which handles streaming and exit events.
• Developers can programmatically control console mode using the Pinia store and Vue Router APIs.

Frequently Asked Questions

How do I enable console mode in RomM?

Navigate to the /console URL path or click the Console icon in the main interface. The application automatically sets consoleMode to true in the console store, triggering the TV-optimized layout. Alternatively, import useConsoleStore from frontend/src/stores/console.ts and set consoleMode = true programmatically.

What input devices work with RomM's console mode?

The universal input system in frontend/src/v2/composables/useInputModality/index.ts supports keyboard arrow keys, mouse clicks, touch gestures, and standard gamepad D-pads. Console mode prioritizes directional navigation, making gamepads and remote controls the optimal input methods for TV viewing.

How does console mode differ between RomM v1 and v2?

Version 1 isolated console functionality in separate route namespaces with dedicated input handling. Version 2 merges console behavior into the main UI through the universal input system, allowing the same components to adapt to both standard and console modes while maintaining the consoleMode state flag for layout differences.

Can I customize which ROMs appear in console mode?

Yes. The console view uses the same underlying data layer as the standard interface. Filters applied in the main UI persist when entering console mode. Developers can also modify the route guards in frontend/src/plugins/router.ts or adjust the console store's filtering logic to customize the visible ROM list for console navigation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}