Canvasia Engine

A creator-friendly visual novel / galgame engine prototype.
Build playable stories with assets, dialogue, buttons, previews, and export tools instead of code.

Language: 简体中文 · English · 日本語

Quick Start · Core Features · Feature Status · Exports · Share Kit · Testing · Contributing

---

Project Positioning

Canvasia Engine is currently a source-available preview for visual novel and galgame creators.

It is best suited for:

• trying small visual novel prototypes
• testing editor and export workflows
• building small creator projects
• collecting feedback before a stable commercial release

The project already includes a visual editor, export pipeline, native runtime preview, project recovery tools, and automated smoke tests. It is still published as Preview / Early Access because signing, notarization, installers, and long manual QA still need more release hardening.

Core Features

• Visual story editor with scenes, cards, dialogue, narration, choices, variables, and conditional branches
• Project center with blank projects, beginner mode, and advanced mode
• Asset management for backgrounds, character sprites, CGs, BGM, SFX, voice, fonts, UI assets, Live2D files, 3D models, and 3D scenes
• Multi-language project settings for default language and player-selectable languages
• Localized runtime text for scene names, chapter names, dialogue, choices, and character names, with safe fallback when a translation is missing
• Canvasia Assistant with local template mode and optional creator-provided OpenAI, DeepSeek, Qwen, Kimi, Zhipu GLM, or compatible API providers
• Optional OpenAI Image asset generation for backgrounds, sprites, CGs, and UI materials, with style-hint presets, sprite-to-character expression binding, prompt/model validation, and local-only API key handling
• Formal save/load, quick save/load, system menu, text history, autoplay, skip-read, and voice replay
• Custom game UI skins, UI Kit binding, nine-slice textures, button states, layout controls, and visual novel textbox design
• Extra galleries: CG replay, music room, character archive, location archive, narration archive, relationship archive, achievements, chapter replay, ending replay, and voice replay
• Advanced particle presets, project particle libraries, camera effects, screen filters, flashes, shakes, and fade transitions
• Live2D / 3D character and 3D scene asset import, plus native-runtime 3D inspection reports for glTF / GLB / VRM assets
• Web playable export, desktop exports, editor desktop builds, and native Runtime preview packages
• Automated checks: local CI precheck, backend smoke tests, Playwright browser smoke tests, action wiring scans, release-control reports, and package integrity verification

Feature Status

Area	Status	Notes
Story and Branch Editing	Available	Visual cards, choices, jumps, variables, conditions, and scene graph inspection.
Asset Management	Available	Import, replace, delete, usage protection, file-size budget hints, and optional OpenAI Image generation with style presets, sprite expression binding, prompt, model, format, and returned-file validation.
Multi-language / i18n	Preview	Project language settings, export metadata, Web Runtime language switching, native Runtime language switching, and fallback behavior.
Canvasia Assistant	Available	Local template mode plus optional creator-owned API keys for major compatible providers.
Project Safety Net	Available	Snapshots, restore, crash recovery, project doctor, repair queue, release gates, and release-control reports.
Game UI Customization	Available	Project UI skins, button states, nine-slice images, layout tuning, and textbox styling.
Extras / Replay Systems	Available	CG, music, character, location, narration, relationship, achievement, chapter, ending, and voice replay systems.
Particles and Presentation	Available	Particle presets, custom particle settings, camera, filters, flashes, shakes, fades, and character presentation effects.
Live2D / 3D Assets	Preview	Live2D, 3D character models, and 3D scene assets can be imported; native Runtime exports 3D structure and risk reports.
Web / Desktop Exports	Preview	Web playable packages and desktop packages are available; signing and notarization depend on release notes.
Native Runtime	Preview	Covers the core playback path, settings, saves, history, autoplay, video fallback, 3D reports, and first archive systems.
Mobile Runtime	Experimental planning	Touch, audio policy, and layout adaptation are still being explored.

Screenshots

Story Editor and Assistant	Preview and Export
Visual story cards, scene structure, Canvasia Assistant, idea vault, and insertable generated cards.	Preview, runtime settings, release checks, and multi-platform export entry points.

Project Site and Share Kit

• Landing page source: docs/index.html
• Social preview image: docs/github/canvasia-social-preview.png
• Exposure kit: docs/marketing/exposure-kit.md
• Expected GitHub Pages URL after enabling Pages from /docs: https://tonyna-code.github.io/canvasia-engine/

Repository Layout

• run_editor.py: local editor server, project management, export pipeline, and packaging entry point
• prototype_editor: visual editor frontend
• prototype_editor/modules: frontend pure-logic modules with standalone test coverage
• export_player_template: exported Web Runtime template
• native_runtime: native Runtime player and related desktop runtime logic
• template_project: blank starter project template
• tests: automated smoke and regression tests

Quick Start

The editor only requires Python 3 for the source-based path.

If this is your first time opening Canvasia, follow the short route below:

1. Launch the editor.
2. Create or open a project.
3. Use the one-click starter kit to add the first character, background, and BGM.
4. Let the starter kit wire those basics into the first scene, then replace the placeholder assets when ready.
5. Write 10 to 20 lines, run preview, then export a Web or desktop demo.

One-click scripts

• macOS: double-click start_editor.command
• Windows: double-click start_editor.cmd
• Linux: run start_editor.sh

Command line

macOS / Linux:

git clone https://github.com/TonyNa-code/canvasia-engine.git
cd canvasia-engine
python3 run_editor.py

Windows:

git clone https://github.com/TonyNa-code/canvasia-engine.git
cd canvasia-engine
py -3 run_editor.py

If the Windows py launcher is unavailable, try:

python run_editor.py

After launch, the editor opens in your browser on a local 127.0.0.1 address. The project files stay on your computer.

Recommended First Project

For a first five-minute demo, start small:

• 1 background
• 1 character sprite
• 1 BGM track
• 10 to 20 lines of dialogue
• 1 choice
• 1 simple ending

Build one complete path first, then add branches, effects, UI skins, galleries, voice, and extra polish. The starter kit can create the first character/background/BGM records and connect them to the first scene, so you can begin from a playable skeleton instead of wiring every card by hand.

Multi-language Projects

Canvasia supports a first i18n workflow:

1. Finish the main story in your primary language.
2. Open project runtime settings and choose the default language.
3. Enable player-selectable languages such as zh-CN, ja-JP, or en-US.
4. Add translations for character names, scene names, chapter names, dialogue, narration, and choices.
5. Export and switch language in the Web Runtime or native Runtime settings menu.

If a translation is missing, the runtime falls back to the default text instead of breaking the game.

Exports

Open a project and go to the preview/export area to generate:

• Web playable package
• Windows desktop package
• macOS desktop package
• Linux desktop package
• Native Runtime package preview with standalone-app build scaffolding

The Web playable package is the easiest option for quick sharing. The native Runtime package is the route for testing a more app-like desktop playback flow.

Release Packages

Preview editor builds are distributed through GitHub Releases when available:

• macos.tar.gz
• windows.zip
• linux.tar.gz

Unsigned preview builds may trigger macOS Gatekeeper, Windows SmartScreen, or antivirus warnings. Download only from the official repository release page and verify SHA-256 files when provided.

Testing

Useful local checks:

python3 -m unittest tests.test_run_editor_smoke -v
python3 -m unittest tests.test_frontend_particle_effects_module -v
node --check prototype_editor/app.js
node --check export_player_template/player.js

Some browser or native-rendering checks may require additional local dependencies.

License

This project uses the Creator License 1.0 included in LICENSE. Games made with the engine may be commercialized, while redistribution or commercialization of modified engine copies is limited by the license terms.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md before opening issues or pull requests.