UTPE — Psych Engine Mod Toolkit

English | 中文

UTPE (Unified Tool for Psych Engine) is a .NET 8 WPF desktop application for visually creating and managing Psych Engine mods. Instead of hand-editing JSON or juggling directory structures, you fill in forms, pick files, and export a ready-to-play mod directly into PsychEngine's mods/ folder.

Features

Project Management

One-click mod project creation from embedded templates (no external dependencies)
Open / save existing mod projects via .utpt marker + pack.json dual identification
Export directly to the PsychEngine mods/ directory — edit and play instantly

Character Editor

Character basics (name, scale, sing duration, health bar RGB, flip)
Animation system (name, prefix, FPS, loop, offsets, indices) with Sparrow XML import
Multi-character management with instant EntityRegistry sync on create / delete / edit

Song Manager

Song metadata (BPM, speed, character assignment, stage, artist, charter)
Multi-difficulty chart import (easy / normal / hard) — re-saving preserves notes data
Audio management (Inst / Voices) with automatic filename fixing
Stage selector with 14 built-in stages

Week Editor

Week basics (name, story-mode ordering, previous week) + menu character slots
Song list management (reorder, difficulty, color tags) + week icon live preview
Auto-generated weekList.txt

Dialogue Editor

-编辑data/<song>/dialogue.json with add / remove / reorder

Per-line portrait, animation, speed, expression settings

Script Manager

Scans scripts/ for .lua / .hx files
Integrated AvalonEdit editor with Lua syntax highlighting

Stage Editor

Visual stage layout on a 1280×720 Canvas
Character position markers (BF / GF / Opponent) + camera settings

Global Services

EntityRegistry — global registry scanning characters/ + data/; all editors share the same character / song / stage lists
IDialogService — unified dark-theme dialogs (confirm / error / warning / file picker / input)
TemplateService — embedded template system with {{VAR}} placeholder substitution

Tech Stack

Tech	Purpose
.NET 8 + WPF	Desktop application framework
CommunityToolkit.Mvvm 8.2.2	MVVM source generators (ObservableProperty / RelayCommand)
Microsoft.Extensions.Hosting	Dependency injection
AvalonEdit	Code editor control
System.Text.Json	JSON serialization
Java 17 + Spring Boot 3.3.5	Spade orchestration core (HTTP poll / object registry / mod generation)
Lua (Psych Engine)	In-game polling script consuming `utpe-poll.json`

Project Structure

UTPE/
├── UTPE.Main/              # Main project (publish entry point)
│   ├── Models/             # Data models + DTOs
│   ├── ViewModels/         # MVVM ViewModels
│   ├── Views/              # XAML views
│   ├── Services/           # Services (Template / Project / EntityRegistry / Dialog)
│   ├── Themes/             # Dark theme styles
│   └── Resources/          # Embedded resources (modTemplate.zip, Templates/)
├── docs/                   # Docs: project experience + PE helper manual
├── readme.md               # This README
└── UTPE.sln                # Solution file

Quick Start

Prerequisites

.NET 8 SDK
Windows 10/11 x64

Build

git clone https://github.com/wait-code/UTPE.git
cd UTPE
dotnet build UTPE.Main/UTPE.Main.csproj

Publish (self-contained — no .NET runtime needed on target machine)

dotnet publish UTPE.Main/UTPE.Main.csproj -c Release -r win-x64 --self-contained true -o publish

Copy the entire publish/ folder to any Windows x64 machine and run UTPE.Main.exe directly.

Configuration

On first launch you are guided to set your PsychEngine path. Config is stored at %APPDATA%/UTPE/config.json.

License

MIT

中文说明

UTPE（Unified Tool for Psych Engine）是一个 .NET 8 WPF 桌面应用，用于可视化创建和管理 Psych Engine mod。无需手动编辑 JSON 或整理目录结构——填表单、选文件，一键导出可直接运行的 mod 到 PsychEngine 的 mods/ 目录。

功能

项目管理

内置模板一键创建 mod 项目（无外部依赖）
通过 .utpt 标记文件 + pack.json 双重标识，打开 / 保存已有 mod 项目
直接导出到 PsychEngine mods/ 目录——编辑即可玩

角色编辑器

角色基础属性（名称、缩放、演唱时长、血条 RGB、翻转）
动画系统（名称、前缀、帧率、循环、偏移、索引），支持 Sparrow XML 动画导入
多角色管理，创建 / 删除 / 编辑即时同步 EntityRegistry

歌曲管理器

歌曲元数据（BPM、速度、角色分配、舞台、艺术家、编曲者）
多难度谱面导入（easy / normal / hard）——重复保存不丢 notes 数据
音频文件管理（Inst / Voices，自动修复文件名）
舞台选择器（14 个内置舞台）

周目编辑器

周目基础属性（名称、故事模式排序、前置周目）+ 菜单角色槽位
歌曲列表管理（排序、难度选择、颜色标签）+ 周目图标实时预览
自动生成 weekList.txt

对话编辑器

编辑 data/<song>/dialogue.json，支持增删改 + 上移 / 下移排序
每行可设置头像、动画、语速、表情

脚本管理器

扫描 scripts/ 目录中的 .lua / .hx 文件
集成 AvalonEdit 编辑器，内建 Lua 语法高亮

舞台编辑器

1280×720 Canvas 可视化舞台布局
角色站位标记（BF / GF / 对手）+ 相机设置

全局服务

EntityRegistry —— 全局注册表，扫描 characters/ + data/ 目录；所有编辑器共享同一份可用角色 / 歌曲 / 舞台列表
IDialogService —— 统一深色主题对话框（确认 / 错误 / 警告 / 文件选择 / 输入）
TemplateService —— 内置模板系统，支持 {{VAR}} 占位符替换

技术栈

技术	用途
.NET 8 + WPF	桌面应用框架
CommunityToolkit.Mvvm 8.2.2	MVVM 源代码生成器（ObservableProperty / RelayCommand）
Microsoft.Extensions.Hosting	依赖注入
AvalonEdit	代码编辑器控件
System.Text.Json	JSON 序列化
Java 17 + Spring Boot 3.3.5	黑桃调度核心（HTTP poll / 对象库 / mod 生成）
Lua（Psych Engine）	游戏内轮询脚本，消费 `utpe-poll.json`

项目结构

UTPE/
├── UTPE.Main/              # 正式工程（发布入口）
│   ├── Models/             # 数据模型 + DTO
│   ├── ViewModels/         # MVVM 视图模型
│   ├── Views/              # XAML 视图
│   ├── Services/           # 服务（模板 / 项目 / 注册表 / 对话框）
│   ├── Themes/             # 深色主题样式
│   └── Resources/          # 嵌入资源（modTemplate.zip、Templates/）
├── docs/                   # 开发文档（项目经验、PE 助手手册）
├── readme.md               # 本说明文件
└── UTPE.sln                # 解决方案文件

开发进度与架构

UTPE 正在演进为三段式流水线：UTPE（C# WPF 客户端）→ 黑桃（Java 调度中枢）→ PsychEngine（Lua 轮询）。配置变更通过统一 JSON 协议流转，近实时在游戏内生效，无需手改 mod 文件。

阶段	状态	说明
P0	✅ 已完成	Lua 桥验证：读文件 / 解析 JSON / 写文件
P1	✅ 已完成	预览闭环 v0：改指令文件 → 游戏画面实时变
P2	✅ 已完成	黑桃骨架：Spring Boot 服务接管「写指令文件」
P3	✅ 已完成（2026-08-26）	执行器 + API 目录：舞台 / 角色 / 摄像机 / 血条 API 实时可调；协议 / 数据分离多 yaml 对象库；per-mod poll + 自动分配 id
P4	⬜ 未开始	生成闭环：黑桃按 JSON 规则表生成可玩 mod
P5	⬜ 未开始	C# 通过 read / generate / preview 三接口对接黑桃
P6	⬜ 未开始	全量 API + 打磨（Step 3.3 script 白名单顺延至此）

黑桃（调度核心）

Java 17 + Spring Boot 3.3.5，监听 127.0.0.1:8080，打包为 spade.jar。
POST /poll：接收 api + args 指令，翻译为 Lua，写入按 mod 归属的 utpe-poll.json（[{id, api, script, ts}]）。
DeclTranslator + ApiRegistryService 完成 decl→Lua 翻译；LuaInjectorService 按 songs + modpath 注入轮询脚本。
对象库：objects/normal.yaml 默认库 + 按 mod 独立 objects/<modId>.yaml，互不污染；GET/POST /objects、PUT/GET /objects/active、/objects/items CRUD（items 变更须带 name 定位所属 yaml）；变更先校验、通过后自动写回。
poll id 自动分配（PollFileService.submit() 已 synchronized），客户端不再维护 id。

快速开始

前置条件

.NET 8 SDK
Windows 10/11 x64

编译

git clone https://github.com/wait-code/UTPE.git
cd UTPE
dotnet build UTPE.Main/UTPE.Main.csproj

发布（独立部署——目标机器无需安装 .NET 运行时）

dotnet publish UTPE.Main/UTPE.Main.csproj -c Release -r win-x64 --self-contained true -o publish

将整个 publish/ 文件夹拷到任意 Windows x64 机器，双击 UTPE.Main.exe 即可运行。

配置

首次启动时会引导设置 PsychEngine 路径。配置文件存储在 %APPDATA%/UTPE/config.json。

开源协议

MIT

Name		Name	Last commit message	Last commit date
.project-memory		.project-memory
Spade		Spade
UTPE.Main		UTPE.Main
.gitignore		.gitignore
README.md		README.md
UTPE.sln		UTPE.sln

Latest commit

History

Folders and files

Repository files navigation