letsgal-ai — AI-Assisted LetsGal Studio Creation Toolchain

Reverse-engineer the LetsGal Studio project format from scratch, turning it into something AI can create directly: One-line story DSL → fully runnable project (chapters/characters/scenes/branches/performances), with both CLI and MCP access, zero dependencies.

• Format reference (reverse-engineered from official templates + v1.11.0 installer): docs/letsgal-format.md

• Story DSL specification: docs/STORY-DSL.md

Why

LetsGal Studio is a desktop GUI editor (no MCP, no CLI), but everything it works with is just plain JSON on disk. This project fully programmatizes that format:

• AI generates the script → one command compiles it into a project → Studio opens it and it just works (fine-tune performances/assets as needed)

• Format is fully aligned with the official one (project.json / characters.json / scenes.json / chapters/*.json / assets/.manifest.json) — Studio opens it with zero errors, auto-fixes merged character expressions, and swaps assets naturally.

Quick Start

# 安装（无需依赖，直接 clone 或 npm link）
npm link                    # 或 node bin/letsgal-ai.js …

# 1. 初始化工程骨架
letsgal-ai init my-game --name "时间的河流"

# 2. 写故事（见 examples/example.dsl）→ 编译
letsgal-ai build story.dsl -o my-game --name "时间的河流"

# 3. 校验
letsgal-ai validate my-game

# 4. 用 LetsGal Studio 打开 my-game → 播放

MCP (Direct AI Agent Invocation)

letsgal-ai mcp     # stdio JSON-RPC 2.0，零依赖实现

Exposed tools:

Any MCP client (Claude Code / DSH / custom) just configures node bin/letsgal-ai.js mcp.

CLI

letsgal-ai init <dir> [--name 标题]
letsgal-ai build <story.dsl> -o <dir> [--name 标题]
letsgal-ai validate <dir>
letsgal-ai list <dir>
letsgal-ai mcp

Use as a Library

import { compileStory, initProject, validateProject, applyCharacterFlow, dialogue, narration, scene } from '@lilyco-42/letsgal-ai';

Development

npm test        # 冒烟测试：init → build → validate → MCP 握手

License & Credits

• This tool is MIT licensed; contains no assets. Generated projects can directly use LetsGal Studio's official template assets (bundled with the engine).

• Reverse-engineering based on: LetsGal Studio v1.1.0 (Windows) installer + official template project.

Roadmap

• Ren'Py-style code ↔ Block bidirectional conversion (aligned with the official code editor syntax)

• Headless build (reuse official build-worker to produce web version)

• lilyco (Rust) native component: lilyco-letsgal (see docs/lyco-integration.md)