Project Setup

Relevant source files

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

• package.json
• README.md
• main.js
• vite.config.js
• renderer/index.html
• src/utils/SaveSlotManager.js
• src/scenes/GameScene.js

The Souless project is a 2D roguelike game developed using the Phaser 3 game engine. It is architected to run both in a web browser for rapid development and testing, and as a standalone desktop application packaged with Electron. This setup leverages Vite as a fast build tool and development server.

The core of the setup involves a separation between the Electron main process, which manages the native application window and file system access, and the renderer process, which runs the Phaser game itself. During development, the renderer process loads the game from a Vite dev server, while in production, it loads from a pre-built set of static files.

Sources: README.md, package.json, main.js

Core Technologies

The project is built upon a foundation of modern JavaScript technologies to create a cross-platform desktop game.

Category	Technology	Description
Game Engine	Phaser 3	The primary engine for rendering, physics, and game logic.
Framework	Electron	Wraps the web-based game into a native desktop application.
Build Tool	Vite	Provides a fast development server and bundles the project for production.
Language	JavaScript (ES6)	The programming language used for the entire project.
Package Manager	Yarn	Used for managing project dependencies.

Sources: README.md:29-35, package.json:30-33

Project Structure

The project is organized to separate the game source code (src/), the renderer entry point (renderer/), and the Electron-specific files.

This diagram shows the high-level folder structure of the project.

• src/: Contains all Phaser-related game logic, including scenes, entities (characters, enemies), and systems.
• renderer/: The root for the Vite development server. It contains the main index.html file that hosts the game canvas.
• main.js: The entry point for the Electron main process.
• vite.config.js: Configuration file for the Vite build tool.
• package.json: Defines project metadata, dependencies, and scripts.

Sources: README.md:41-50, vite.config.js:10

Build & Development Scripts

The package.json file defines several scripts for development, building, and packaging the application.

Script	Description
dev:vite	Starts the Vite development server.
dev:electron	Starts Electron in development mode, waiting for the Vite server to be ready.
dev	Runs dev:vite and dev:electron concurrently for a complete development environment.
build	Builds the Phaser game using Vite, outputting to the dist/ directory.
start	Starts the Electron application using the pre-built files in dist/.
pack	Packages the application for the current OS into a directory using electron-builder.
dist	Creates distributable installers/packages (e.g., NSIS, DMG, AppImage) for all platforms.

Sources: package.json:6-14

Development Flow

The dev script provides a live-reloading environment by running the Vite server and Electron simultaneously.

This diagram illustrates the sequence of events when running yarn dev. concurrently starts both processes, and wait-on ensures Electron doesn't launch until the Vite server is active.

Sources: package.json:8-10

Production Flow

In production, Electron loads the game from the static files generated by the yarn build command.

This flow shows how the application is built and then run in a production-like environment.

Sources: package.json:11,12, main.js:34-36

Application Entry Points

The application has two main entry points: one for the Electron host process and one for the game renderer.

Electron Main Process (main.js)

This script is responsible for creating and managing the application window and handling native OS interactions.

• Window Creation: A BrowserWindow is created with fullscreen: true and resizable: false.
• Development vs. Production:
  • In development (isDev), it loads the URL from the Vite server (http://localhost:5173).
  • In production, it loads the local dist/index.html file.
• IPC Handling: It sets up Inter-Process Communication (IPC) handlers to allow the renderer process to interact with the host system, primarily for saving and loading game data.

// main.js
function createWindow() {
  // ...
  mainWindow = new BrowserWindow({
    // ...
    fullscreen: true,
    // ...
  });

  if (isDev) {
    mainWindow.loadURL('http://localhost:5173');
    mainWindow.webContents.openDevTools();
  } else {
    mainWindow.loadFile(join(__dirname, 'dist/index.html'));
  }
  // ...
}

Sources: main.js:18-42

Renderer Process (renderer/index.html)

This is the entry point for the Vite server and the web content that runs inside the Electron BrowserWindow. It's a standard HTML file that includes the main game script.

<!-- renderer/index.html -->
<!DOCTYPE html>
<html lang="ko">
  <head>
    <meta charset="UTF-8" />
    <title>Soul Game</title>
    <!-- ... styles ... -->
  </head>
  <body>
    <div id="game-container"></div>
    <script type="module" src="./renderer.js"></script>
  </body>
</html>

The <div id="game-container"></div> is where the Phaser game canvas is injected. The main logic is initiated by renderer.js.

Sources: renderer/index.html

Configuration

Vite Configuration (vite.config.js)

Vite's configuration is central to the development and build process.

• root: Sets the project root to ./renderer, meaning Vite will serve renderer/index.html as the main page.
• base: Configured as ./ to ensure relative asset paths work correctly after being built for Electron.
• build.outDir: Specifies that build artifacts should be placed in ../dist, outside the renderer directory.
• resolve.alias: Defines path aliases (e.g., @/, @scenes) for cleaner import statements within the src/ directory.

// vite.config.js
export default defineConfig({
  root: './renderer',
  base: './',

  resolve: {
    alias: {
      '@': path.resolve(srcRootPath, './'),
      '@scenes': path.resolve(srcRootPath, './scenes'),
      // ... other aliases
    },
  },

  build: {
    outDir: '../dist',
    // ...
  },
});

Sources: vite.config.js:10-33

Electron Builder Configuration (package.json)

The build section in package.json configures electron-builder for creating distributable packages.

Property	Description
appId	A unique identifier for the application.
productName	The name of the application displayed to the user.
directories.output	The directory where distributables will be created (release).
files	An array of files and folders to include in the final package, such as dist/**/* and main.js.
win, mac, linux	Platform-specific settings, including target package formats (e.g., nsis, dmg, AppImage) and icons.

Sources: package.json:34-66

Save System IPC

To persist game data, the renderer process (Phaser) cannot directly access the file system. It communicates with the Electron main process via IPC. main.js exposes handlers for saving, loading, and deleting files.

This diagram shows the flow for saving game data. The SaveSlotManager in the renderer process calls a function exposed on the window.electron object (defined in preload.js), which triggers an ipcMain handler in main.js. The main process then performs the file system operation and returns the result.

The following IPC handlers are defined in main.js:

• load-save: Reads a save_slot_X.json file.
• save-save: Writes data to a save_slot_X.json file.
• clear-save: Deletes a save_slot_X.json file.
• get-save-path: Returns the absolute path to a save file for debugging.

Sources: main.js:70-138, src/utils/SaveSlotManager.js:89-100