Running the Game

Relevant source files

The following files were used as context for generating this wiki page:

• package.json
• main.js
• README.md
• src/scenes/MainMenuScene.js
• src/scenes/GameScene.js
• src/utils/SaveSlotManager.js
• src/systems/Tutorial.js
• renderer/index.html

This document outlines the technical architecture and processes involved in running the "Souless" game, from setting up the development environment to launching the packaged application. The project is a 2D roguelike game built with the Phaser 3 game engine, wrapped in an Electron framework to function as a desktop application. Vite is used as the build tool and development server.

The game can be run in two primary modes: a development mode for testing in a browser and Electron, and a production mode as a standalone desktop application. The execution flow involves the Electron main process, which creates a browser window, and the renderer process, where the Phaser game itself runs.

1. Core Technologies & Project Structure

The project leverages a combination of web and desktop technologies to deliver a standalone game experience.

This diagram illustrates the relationship between the main technologies.

Key Technologies

Technology	Role
Phaser 3	The core game engine for rendering, physics, and game logic.
Electron	A framework for creating native desktop applications with web technologies. It provides the window and access to the local file system for features like saving game data.
Vite	A build tool that provides a fast development server with Hot Module Replacement (HMR) and bundles the game assets for production.
JavaScript (ES6)	The primary programming language used for the game logic.

Sources: README.md:30-37, package.json:15-22

Folder Structure

The project is organized into several key directories that separate game logic, assets, and configuration.

souless/
 ┣ 📁 src/             → Game source code
 ┃ ┣ 📁 assets/       → Image, sound, and other resources
 ┃ ┣ 📁 scenes/       → Phaser Scene classes (e.g., MainMenuScene, GameScene)
 ┃ ┣ 📁 entities/     → Player, enemy, and other game object classes
 ┃ ┗ ...
 ┣ 📜 main.js         → Electron main process entry point
 ┣ 📜 renderer/index.html → HTML entry point for the game
 ┣ 📜 vite.config.js  → Vite configuration file
 ┗ 📜 package.json    → Project dependencies, scripts, and build configuration

Sources: README.md:41-51

2. Execution Environments

The game can be launched in a development environment for quick iteration or built into a distributable package for end-users.

Development Environment

The development environment is initiated using the yarn dev command. This command uses concurrently to run two scripts in parallel: dev:vite and dev:electron.

"scripts": {
  "dev:vite": "vite",
  "dev:electron": "wait-on http://localhost:5173 && cross-env NODE_ENV=development electron .",
  "dev": "concurrently \"yarn dev:vite\" \"yarn dev:electron\""
}

Sources: package.json:7-9

The following diagram shows the startup flow for the development environment.

1. yarn dev:vite: Starts the Vite development server, which serves the game files at http://localhost:5173.
2. yarn dev:electron: The wait-on command pauses execution until the Vite server is ready. Once the server is active, it launches the Electron application. The Electron BrowserWindow is configured to load the URL from the Vite server.

Production and Standalone Execution

For distribution, the game is first built and then packaged.

Script	Description
yarn build	Uses Vite to compile and bundle the game's web assets (HTML, JS, CSS) into the dist/ directory.
yarn start	Runs the Electron application directly. It will load the game from the dist/index.html file if it exists.
yarn dist	Uses electron-builder to create distributable packages (e.g., .exe, .dmg, .AppImage) for Windows, macOS, and Linux based on the configuration in package.json.

Sources: package.json:10-13, package.json:23-43

The electron-builder configuration specifies which files to include in the final package and the output directory.

"build": {
  "appId": "com.mycompany.mygame",
  "productName": "MyElectronGame",
  "directories": {
    "output": "release"
  },
  "files": [
    "dist/**/*",
    "main.js",
    "preload.js"
  ],
  "win": { ... },
  "mac": { ... },
  "linux": { ... }
}

Sources: package.json:23-43

3. Game Launch and Scene Management

When the application starts, it follows a specific sequence to initialize the game and display the main menu.

Electron and Renderer Initialization

1. The Electron main.js script is the application's entry point. It creates a BrowserWindow in fullscreen mode.
2. The window loads either the Vite dev server URL or the static dist/index.html file.
3. The index.html file loads the renderer script, which in turn initializes the Phaser game defined in the game's main.js.
4. The Electron main.js also sets up IPC (Inter-Process Communication) handlers (load-save, save-save, clear-save) to manage reading and writing game data to the user's local file system. This allows the Phaser game (renderer process) to persist data via the Electron main process.

Sources: main.js:18-31, main.js:63-112, renderer/index.html:21

Main Menu and Game Start

The MainMenuScene is the first interactive scene presented to the player. It manages the options to start a new game or load an existing one.

The sequence diagram below illustrates the process of starting a new game.

• New Game: When a player selects "NEW GAME" and an empty slot, MainMenuScene calls SaveSlotManager.selectSlot(). This function initializes a new save file for that slot. The game then transitions to the IntroScene, which eventually leads to the GameScene for the tutorial.
• Load Game: When a player selects "LOAD GAME" and a slot with existing data, SaveSlotManager.selectSlot() is called to set the active slot. The game then starts the GameScene directly, passing the saved map key and character type to load the player's last state.

Sources: src/scenes/MainMenuScene.js:340-357, src/utils/SaveSlotManager.js:288-318

Entering the Game World (GameScene)

The GameScene is the core of the gameplay. Its init() and create() methods are responsible for setting up the entire game world.

1. Initialization (init): Receives data from the previous scene, such as mapKey, characterType, and flags like isTutorial or isRespawn.
2. Asset Loading (preload): Loads all necessary assets for the current map, characters, enemies, and effects.
3. World Creation (create):
   • Launches the UIScene.
   • Initializes the SaveSlotManager and loads kill/portal data.
   • Sets up the player character using PlayerSpawnSystem, which determines the spawn location based on saved data, portal entry, or default map positions.
   • Initializes the LevelSystem and SkillUnlockSystem.
   • Creates the map background and physics boundaries using MapModel.
   • Spawns enemies using EnemyManager.
   • Sets up the camera to follow the player.
   • If it's a new game in the other_cave map, the TutorialSystem is started.

Sources: src/scenes/GameScene.js:47-233, src/systems/Tutorial.js:20-27

4. Summary

Running the "Souless" game involves a coordinated effort between Electron, Vite, and Phaser. The package.json scripts orchestrate the launch for both development and production. Electron provides the native window and file system access for saving progress, while Vite handles the web asset pipeline. Once the application is running, Phaser's scene manager takes over, starting with the MainMenuScene for game selection and transitioning to the dynamic GameScene where the core gameplay loop resides.