# GalEngine

**Repository Path**: MillenTec/GalEngine

## Basic Information

- **Project Name**: GalEngine
- **Description**: A Unity project, a GalGame framework based on UGC, you can write standardized story JSON files to play in GalEngine.
- **Primary Language**: C#
- **License**: CC0-1.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-27
- **Last Updated**: 2025-12-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
    <h1>GalEngine</h1>
    <strong>剧情引擎</strong>
    <p>🚧目前它仍然在开发阶段🚧</p>
    <hr>
</div>

最近`GalGame`这个游戏品类成为了[bilibili](https://www.bilibili.com)中讨论比较多的话题，于是初学Unity的我就决定要不做个GalGame试试看吧(绝对不是为了蹭热度🤨)
## 1.简介
### 1.1.什么是`GalGame`
`GalGame`本质是一个游戏分类，源自于日本，意思是`美少女游戏`，"Gal"即是日语`ギャル`("美少女")一词的音译；
GalGame也被称为"视觉小说"，其剧情内容以恋爱为主，本质就是一种剧情游戏分支，但是GalGame这一分类要求以剧情为主导，也就是说有其他非剧情主要玩法的游戏不能被归类的GalGame；
所以说，GalGame本身是一个比较正常的游戏分类，不过在bilibili由于某些特殊原因成为了一个梗

### 1.2.关于GalEngine
正如其名字，这是一个用来制作GalGame的引擎，我搭建了一个GalGame的基本框架，通过规范格式编写记录剧情内容的JSON文件，即可在GalEngine中播放这段剧情；
你可以将制作好的剧情包放置在特定的目录(`{Application.persistentDataPath}/Packs`)，GalEngine会扫描那个目录并列出其中所有包，用户可以点击列出的包以进入剧情；
这是我的第一个Unity且是第一个C#项目，最早的代码(剧情播放部分，即`DisplayTalkingInformation`类)甚至是在我接触C#仅2周、Unity仅4天后写出来的，直至撰写此文本时(2025.12.27)我也才接触Unity约一个多月，所以可能有很多逻辑不甚清晰、解决方案并不算完美，请各位谅解，我还有很多要学

### 1.3.开源
#### 1.3.1.代码
该项目的所有代码脚本使用[MIT LICENSE](https://mit-license.org/)开源，这意味着你可以:
- 自由**使用、复制、修改、合并、发布、分发、再许可和/或销售**本软件的副本
但是你应当需要:
- **署名**: 你应当在项目中署以我的名并携带此许可证的副本

#### 1.3.2.资源
该项目的所有UI以[CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/legalcode.txt)协议开源，这以为这你可以:
- 随意以任何形式使用资源，并且无需署名等
> 该协议仅作用于UI，即`/Resources/Image/Illustration`下的所有`.ai`文件

## 2.创作
### 2.1.剧情包创作
首先，在未来我会开发GalCraft项目，届时将可以使用图形化界面制作剧情包而无需手动操作JSON文件；不过当前仍需要手动编写JSON文件，接下来讲解的是JSON文件的格式以及一个标准剧情包的规范
**配置文件**:
首先，你的包应该需要一个`config.json`配置文件，并将其放在包的根目录，格式应该像这样:
```json
{
    "title": "Your Pack Title",              // 包的标题
    "author": "Your_name",                   // 你的名字
    "link": "https://your.social.link",      // 你的链接，可选
    "id": "your_pack_id",                    // 包的唯一标识码
    "version": "1.0.0",                      // 包的版本，可选
    "description": "Your pack description",  // 对于包的描述，可选
    "license": "MIT",                        // 包的协议，可选
    "cover": "cover.png",                    // 封面图，可选，1556*1182或778:591的比例(这比例很诡异，请原谅我搞出了如此怪异的比例)，否则会被拉伸
    "index": "plot/index.json"               // 开始的文件(剧情JSON文件)
}
```

**剧情文件**:
这是你的包的核心，它包含了整个剧情的内容，目前它有着**node**(普通节点)和**branch**(选择分支)两种节点类型
```json
[  //你的整个JSON文件应当包裹在一个Array里

    // 简单节点示例
    {
        "node": 0,                                                   // 节点的编号，从0开始，与父级Array索引相同
        "type": "node",                                              // 节点类型(node或branch)
        "character": "character_name",                               // 角色名字，留空则无
        "description": "the character description",                  // 对于角色的描述（如“陌生的女孩”、“咖啡店店员”等描述性词汇），以小字体显示在角色名字旁边
        "value": "character talk",                                   // 说话的内容，显示在对话框
        "background": "image/background/background.png",             // 画面背景，没有则沿用上一节点的(测试中)
        "voice": "sounds/vocals/voice.ogg",                          // 配音(开发中)
        "sound": "sounds/effects/sound.ogg",                         // 音效(开发中)
        "character_illustration": "image/char/character.png",        // 留空则无(开发中)
        "facial_differential": "image/diff/character_name.feel.png"  // 角色面部差分，留空则沿用上一个，如果没有则使用默认差分(开发中)
    },

    // 分支节点示例
    {
        "node": 1,
        "type": "branch",
        "choice": [
            {
                "ordinal": 0,        // 选项ID，从0开始，与Array索引对应
                "value": "Choice1",  // 选项文本
                "branch": [
                    // 内部放置其他节点，相当于开了第二个顶层Array
                ]
            },
            {
                "ordinal": 1,
                "value": "Choice2",
                "branch": [

                ]
            }
        ]
    },
]
```
> 注意，以上所有涉及路径的字段都使用相对路径(相对于包的根目录)

**目录结构**:
建议的目录结构应该为:
```bash
.
├─config.json     # 配置文件
├─cover.png       # 封面
├─LICENSE.txt     # 许可证
├─image
│  ├─background   # 背景图
│  ├─char         # 角色立绘
│  └─diff         # 面部差分
├─plot
│   └─index.json  # 入口JSON文件
└─sounds
    ├─effects     # 音效
    ├─music       # 音乐
    └─vocals      # 配音
```

### 2.2.其他自定义
目前仅开放了对于页面背景的自定义，后续可能会开放如UI等的自定义
**页面背景**:
你应该在`Application.persistentDataPath`下操作这些内容，这个目录的位置视情况而定，如在Windows下直接编译好的这个游戏的这个目录就应该在`C:\Users\Your_name\AppData\LocalLow\MillenTec\GalEngine`；
你可以新建一个`UI`文件夹，并在其下建立`pageBackground`子目录，其中应该包含config.json以及你的背景图片
```json
{
  "image": "background.png"  // 背景图的相对路径
}
```

## 3.开发环境
- **Unity**: Unity 2022.3.62f1c1 LTS
- **IDE**: JetBrains Rider 2025.3.1 非商业用途授权
- **.NET框架**: .NETFramework v4.7.1
- **语言版本**: C# 9.0
- **操作系统**: Windows 11 Pro 25H2
- **UI设计**: Adobe Illustrator 2024

## 4.快速开始
1. 克隆仓库
  ```bash
  git clone https://github.com/MillenTec/GalEngine.git
  ```
2. 在Unity Hub使用对应版本的Unity Engine打开文件夹
3. 点击播放以在Unity编辑器内运行
4. 或者点击`文件`->`生成设置`->选择目标平台->`生成`->选择目录以构建为`.exe`可执行文件

## 5.第三方
**Newtonsoft.Json**:
- LICENSE: [MIT LICENSE](https://github.com/JamesNK/Newtonsoft.Json/blob/master/LICENSE.md)
- GitHub: https://github.com/JamesNK/Newtonsoft.Json

**HarmonyOS Sans**:
- Website: [汉仪字库](https://www.hanyi.com.cn/custom-font-case-7)
- LICENSE: [LICENSE](third_party\LICENSE.HarmonyOS-Sans)

## 6.关于我
你好，我是来自中国的MillenTec，一个还在学习中的C#新手，一个二次元技术宅；
你可以叫我“Millen”或者“米伦”，不过当然这不是我的真实名字

**联系我**:
- GitHub: [MillenTec](https://github.com/MillenTec)
- bilibili: [MillenTec](https://space.bilibili.com/3546591566760474)
- Email: MillenTec@outlook.com