Ir para o conteúdo

User Guide

Project Versions

The project supports two main workflows:

  1. Launcher Version (Multi-game): Use Scenes/Launcher/Launcher.tscn as the main scene. It allows users to browse games in the res://games/ folder and choose models dynamically.
  2. Standalone Version (Single-game): Designed for distributing a specific game (e.g., Steam).
    • Configuration: See the detailed Standalone Configuration guide for instructions on how to set the Game Path in the Inspector.
    • Main Scene: To boot directly into your game, you must set your Standalone scene as the Main Scene in Project > Project Settings > Application > Run.

Game Previews (Covers)

To display a cover or screenshot for your games in the Launcher:

  1. Place an image file (PNG, JPG) or a Spectrum screen file (SCR) in the res://games/ folder.
  2. Ensure the image has the exact same name as your game file (e.g., manic_miner.tap and manic_miner.png).
  3. The Launcher will automatically detect and display the image when the game is selected.

Core Components

Emulator (Main48K / Main128K)

This is the heart of the project. It integrates the Rust library to handle:

  • Video Rendering: Converts the Spectrum's memory buffer into a Godot Texture2D in real-time.
  • Audio Dynamic: Uses Godot's AudioStreamGenerator to process high-fidelity sound samples generated by the Rust core.
  • Input Mapping: Translates modern Godot Input Actions into the classic ZX Spectrum key matrix.
  • Arrow Mapping Profiles: Support for Dual Mapping (QAOP vs Sinclair) toggleable via Caps Lock (Main Emulator only).

GameMenu (Overlay)

An intuitive UI layer that appears when the game is paused. It provides:

  • State Management: Instantly save or load your current game progress (snapshots).
  • Audio Control: Real-time volume adjustment via sliders.
  • Navigation: Quick access to resume the game, return to the Launcher, or exit the application.

System Configuration (Config.gd)

The Config centralized static class manages:

  • Automatic directory verification on startup.
  • Global paths for ROMs and Games.
  • Data exchange between the Launcher and the Emulator.

Extra Features

  • .TAP Optimization: The emulator is now exclusively optimized for .tap files for reliable cassette loading.
  • Gamepad Ready: All menus and the emulator are mappable via Godot's Input Map.
  • Mouse Support: Full support for mouse input (Kempston Mouse emulation) in games and menus.
  • Steam Ready: Structure prepared to generate single executables with an embedded game using the Standalone scene.
  • Save States: Snapshot system to save and load game progress instantly.
  • Web Persistence: Save states are stored in user:// (IndexedDB on Web).
  • Mobile vs Desktop: Automatic UI adaptation (hides virtual controls on PC).
  • Custom ROMs: Supports custom .rom files via the Inspector.