GalEngine

A development engine focused on visual novels, galgames, and text adventure games

Introduction

GalEngine is an open-source visual novel game engine that enables developers to quickly create galgames, text adventures, and point-and-click puzzle games using JSON or Markdown scripts.

Core Features

• Dual Script Formats — Supports both JSON (auto-generated by GUI editor) and Markdown (hand-written) script formats
• Zero-Config Development — Developers only need to prepare assets and scripts; no development environment setup required
• Standalone Compilation & Packaging — Compile game projects into standalone executables and data packs; players can download and play directly
• Graphical Editors — Multiple editor implementations: Electron + React (TypeScript rewrite), PyWebView (legacy JS), and Qt (Python desktop)
• Multilingual Support — Developer guides and LLM prompt references in Chinese, English, and Japanese
• Patch/DLC System — Compile additional content into independent data packs; players can simply copy and use them
• Dual Licensing — Open-source (Apache 2.0) + Commercial license

---

Environment Setup

Step 1: Install Python

GalEngine requires Python 3.10 or higher.

• Download: https://www.python.org/downloads/
• Windows users: Make sure to check "Add Python to PATH" during installation
• Verify installation:

python --version
# Expected output: Python 3.10.x or higher

Step 2: Install GalEngine

Option A: Install from PyPI (recommended for users, currently unavailable)

pip install galengine

Option B: Editable install from source (recommended for developers)

git clone https://github.com/Unk1ndledAC/GalEngine.git
cd GalEngine
pip install -e .

This automatically installs all dependencies: pygame-ce, click, jsonschema, markdown, Pillow, pywebview.

Step 3: Verify Installation

# View CLI help
galengine-cli --help

# Launch the graphical editor (opens a native desktop window)
galengine-editor

---

Quick Start

Create a New Project

galengine-cli new my_game

Build a Project

galengine-cli build my_game/

Run a Project

galengine-cli run my_game/

Launch the Graphical Editor

galengine-editor

The editor opens as a standalone desktop window (using the system's native WebView), no browser required.

---

Project Structure

GalEngine/
├── galengine/              # Engine core (Python)
│   ├── core/               # Core engine, configuration management
│   ├── loader/             # Project loader
│   ├── parser/             # JSON/Markdown script parser
│   ├── scene/              # Scene manager
│   ├── dialogue/           # Dialogue system
│   ├── audio/              # Audio manager
│   ├── save/               # Save manager
│   ├── ui/                 # UI manager
│   ├── flowchart/          # Flowchart system
│   └── build/              # Build & packaging system
├── editor_ts/              # Editor — TypeScript rewrite (Electron + React)
│   ├── src/                # TypeScript source code
│   ├── scripts/            # Build & packaging scripts
│   └── resources/          # Icons, platform configs
├── editor_js/              # Editor — legacy JS (PyWebView)
├── editor_qt/              # Editor — legacy Python Qt
├── cli/                    # Command-line tools
├── docs/                   # Multilingual documentation
├── schemas/                # JSON Schema definitions
├── examples/               # Example projects
└── tests/                  # Tests

---

TypeScript Editor (editor_ts/)

The primary editor implementation is a TypeScript rewrite using Electron + React, currently at v0.2.0.

Development

cd editor_ts
npm install
npm run dev              # Vite dev server + HMR
npm run electron:dev     # Dev mode with live reload

Build & Package

cd editor_ts
npm run build            # Compile TypeScript + build renderer
npm run start            # Build + launch Electron (production)
npm run package          # Full packaging pipeline → NSIS installer

The packaging uses electron-builder with asar: true for closed-source distribution. Output goes to editor_ts/release/.

---

Documentation

• 中文开发指引
• English Guide
• 日本語ガイド
• JSON Schema Spec
• Markdown Script Spec
• Data Pack Format Spec
• TypeScript Architecture

---

Packaging for Distribution

Engine Runtime (Python)

Package the engine runtime as a standalone executable (players don't need Python):

pip install pyinstaller
pyinstaller --onefile --windowed cli/package.py

Editor (TypeScript + Electron)

The TypeScript editor is packaged via electron-builder:

cd editor_ts
npm run package          # Windows NSIS installer
npm run package:linux    # Linux AppImage + deb

---

License

GalEngine adopts a dual licensing model:

• Open-source Edition: Apache License 2.0 — suitable for open-source projects and personal learning
• Commercial Edition: Please contact the project maintainer for commercial licensing

---

Contributing

Issues and Pull Requests are welcome!

---

GalEngine — Making story creation simpler