Skip to content

FAQ

Jump to bottom
BiosSystem edited this page May 22, 2026 · 1 revision

FAQ — Frequently Asked Questions

Answers to common questions about installing, using, and developing Universal Retro Arcade.

General

Q: Does this require any external ROMs or game files?

No. All 11 games are built completely from scratch in TypeScript + Phaser 4. There are no ROM files, no emulation layers, and no third-party game assets required. Everything is self-contained in the binary.

Q: Is this free and open source?

Yes. The project is licensed under the MIT License. You can use, modify, and distribute it freely. See LICENSE for full terms.

Q: Which platforms are supported?

Platform Status
Windows 10/11 (x64) ✅ Fully supported
macOS (arm64 / Intel) ✅ Fully supported
Android (arm64) ✅ Touch-optimized
Linux 🔶 Build from source (no prebuilt binary)
iOS ❌ Not currently supported
Web Browser 🔶 Run npm run dev and open localhost:5173

Q: How large is the installed app?

The Tauri v2 binary is under 15 MB on Windows and macOS. This is because Tauri uses the system's built-in WebView (Edge WebView2 on Windows, WKWebView on macOS) rather than bundling a full browser like Electron does.

Q: What is the "B-I-O-S" easter egg?

From the lobby, type the letters B, I, O, S sequentially on your keyboard (any case). A neon diagnostic overlay will flash:

⚡ BIOSYSTEM KERNEL ⚡
Tauri Quantum Core v2.0 — Active

The secret buffer is checked against the last 10 keystrokes, so you can type it at any speed.

Installation Issues

Q: Windows says "Windows protected your PC" — is the installer safe?

Yes. This is Windows SmartScreen blocking unsigned installers from unknown publishers. Because the installer is not code-signed with a paid EV certificate, SmartScreen flags it. Click More info → Run anyway to proceed. The source code is fully auditable on GitHub.

Q: The app doesn't open on Windows — "WebView2 Runtime missing" error

Tauri v2 requires Microsoft Edge WebView2 Runtime. This is pre-installed on Windows 10 (1803+) and Windows 11. If it is missing on your system (e.g., older or stripped-down Windows installs), download the Evergreen installer from: https://developer.microsoft.com/microsoft-edge/webview2/

The app installer should prompt for this automatically.

Q: macOS says the app is "damaged and can't be opened"

This is macOS Gatekeeper blocking unsigned apps. Run this command in Terminal to clear the quarantine flag:

xattr -cr "/Applications/Retro Arcade Launcher.app"

Then try opening it again.

Q: The Android APK won't install — "App not installed" error

  1. Ensure Install from unknown sources is enabled in Settings → Security → Unknown sources (exact location varies by Android version/OEM).
  2. Check that your device has at least Android 7.0 (API 24) — the minimum supported by Tauri's Android target.
  3. If a previous version is installed, uninstall it first before installing a new version to avoid signature conflicts.

Gameplay

Q: My high scores disappeared

High scores are stored in the browser's localStorage, keyed to the app's origin (com.biossystem.retroarcade). They can be lost if:

  • The app was reinstalled with a different identifier
  • The user manually cleared browser storage (does not affect Tauri by default)
  • The OS profile was reset

There is currently no cloud sync or export feature.

Q: Gamepad is not being detected

  1. Connect the controller before launching the app, or connect it while on the lobby screen (game screens may not re-trigger the connected event).
  2. Only the first connected gamepad (index 0) is polled.
  3. Non-standard controllers (cheap USB gamepads without the standard mapping) may not map correctly. Use a generic driver like ViGEm Bus (Windows) or ds4drv (Linux) to emulate Xbox input.
  4. Bluetooth controllers may have a slight connection delay — wait for the OS to confirm pairing before opening the app.

Q: The game runs at a low frame rate on my machine

  • Ensure hardware acceleration is enabled in your system's WebView settings.
  • On Windows, open Edge Settings → System and Performance → Use hardware acceleration.
  • The game targets 60 fps. On low-end hardware, the pixelArt: true setting in Phaser config disables anti-aliasing, which actually improves performance compared to smooth scaling.
  • Disable the CRT shader (Ctrl+Shift+C) — though the postFX pipeline is GPU-accelerated, on integrated graphics it may have a small impact.

Q: Tetris Pulse shows a ghost piece — can I disable it?

Not via a UI toggle. The ghost piece is rendered in the draw() method of TetrisScene.ts. You can disable it by commenting out the ghost-drawing block in the source and rebuilding.

Q: How do I reset all high scores?

Open your browser's developer tools (in the Tauri window: right-click → Inspect Element, or press F12) and run:

Object.keys(localStorage)
  .filter(k => k.startsWith('arcade_score_'))
  .forEach(k => localStorage.removeItem(k));

CRT Shader

Q: The CRT shader isn't doing anything visible

Make sure:

  1. Your GPU supports WebGL (almost all modern hardware does — Tauri always uses WebGL 2.0).
  2. You're pressing Ctrl+Shift+C on the lobby screen specifically (not inside a game scene).
  3. Check localStorage.getItem('arcade_crt') in the DevTools console — it should return 'true' when enabled.

Q: Can I use a custom CRT shader?

Yes, but it requires modifying the source code. Phaser 4 supports custom PostFXPipeline classes:

class MyCrtPipeline extends Phaser.Renderer.WebGL.Pipelines.PostFXPipeline {
  constructor(game: Phaser.Game) {
    super({ game, fragShader: `
      precision mediump float;
      uniform sampler2D uMainSampler;
      varying vec2 outTexCoord;
      void main() {
        // Your GLSL here
        gl_FragColor = texture2D(uMainSampler, outTexCoord);
      }
    `});
  }
}

Register with this.game.renderer.addPipeline('MyCrt', MyCrtPipeline) and apply with this.cameras.main.setPostPipeline('MyCrt').

Development

Q: npm run tauri dev fails with "cargo build error"

  1. Ensure Rust is installed: rustc --version
  2. Update Rust: rustup update stable
  3. On Windows, make sure the Microsoft C++ Build Tools or Visual Studio (with the "Desktop development with C++" workload) is installed — Rust requires MSVC linker on Windows.
  4. Try clearing the Cargo cache: cargo clean inside src-tauri/

Q: TypeScript build fails with "Cannot find module 'phaser'"

Run npm install from the project root to restore node_modules. The phaser package is listed as a production dependency in package.json.

Q: How do I add touch controls for a new game?

Use Phaser 4's InputPlugin pointer events, which unify mouse and touch:

this.input.on('pointerdown', (pointer: Phaser.Input.Pointer) => {
  // Works for both mouse clicks and finger taps
  this.handleTap(pointer.x, pointer.y);
});

For on-screen buttons (D-pad, action buttons), create Phaser Rectangle or Image GameObjects with .setInteractive() and listen for pointerdown/pointerup.

Q: Can I deploy this as a web app (not Tauri)?

Yes. Run:

npm run dev     # Dev server at localhost:5173
npm run build   # Builds to /dist — serve with any static host

The Phaser game runs entirely in the browser. Tauri is only needed for the native desktop/mobile wrapper and file-system access (which this project does not use — all storage is via localStorage).

Q: How do I contribute?

  1. Fork the repository on GitHub.
  2. Create a feature branch: git checkout -b feat/my-new-game
  3. Follow the Adding a New Game guide.
  4. Submit a pull request with a description of your changes.

Please ensure:

  • TypeScript strict mode passes (npx tsc --noEmit)
  • All games return to the lobby via Esc
  • New games respect the difficulty data parameter
  • High scores are saved using the standard key pattern

Back to Home

Clone this wiki locally