# Red Alert Node Editor

**Repository Path**: Nicolas_Z_013/red-alert-node-editor

## Basic Information

- **Project Name**: Red Alert Node Editor
- **Description**: 基于 React Flow 的红色警戒 2 / 尤里的复仇 INI 配置可视化节点编辑器。
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-12-24
- **Last Updated**: 2026-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 红警节点编辑器 · Red Alert Node Editor

基于 **React Flow** 的红色警戒 2 / 尤里的复仇 INI 配置可视化节点编辑器。以节点图方式构建游戏模组配置，支持类型安全的连线验证、双模端口、Customized data 自定义注入、实时预览，生成 rulesmd.ini / artmd.ini / soundmd.ini。

> 后端仓库：[simple-creator](https://gitee.com/Nicolas_Z_013/simple-creator)（Spring Boot 4 + Java 21）

---

## 功能特性

| 特性 | 说明 |
|------|------|
| **可视化节点编辑** | 拖拽节点到画布，拖拽连线建立逻辑关系 |
| **15 种节点类型** | Weapons / Warheads / Projectiles / BuildingTypes / InfantryTypes / VehicleTypes / AircraftTypes / SuperWeaponTypes / Animations / Sounds / ParticleSystems / VoxelAnims / General / BurstDelay / Customized data |
| **6 种输入控件** | STRING / INTEGER（步进±1）/ DOUBLE（步进±0.1）/ BOOLEAN（复选框）/ LIST（标签输入）/ CUSTOM（多行文本） |
| **双模端口** | 同时支持连线输入和手动输入，值自动合并 |
| **智能连接验证** | 基于 `acceptedNodes` 白名单限制连线类型 |
| **Customized data 注入** | 拖入 Customized data 节点编写自定义 INI 行，连线后拼接到目标 Section |
| **INI 预览** | 点击「预览」实时查看生成结果（文件名 + 内容），无需下载 |
| **平台标签** | 每个参数标注所属平台（YR=绿 / Ares=橙 / Phobos=蓝） |
| **自动命名** | Name 字段自动生成（取自 customName 或随机后缀） |
| **可选参数管理** | 弹窗搜索/过滤可选参数，含平台标签和描述 |
| **空值校验** | 生成代码前检测必填字段，列出空值警告 |
| **INI 格式校验** | 检测 Customized data 内容是否符合 key=value 规范 |
| **JSON 导入导出** | 完整项目状态序列化，含版本号 + 兼容性检查 |
| **键盘快捷键** | Delete 删节点、Ctrl+S 导出、Ctrl+O 导入、Ctrl+D 复制 |
| **Toast 通知** | 操作成功/失败/警告的非阻塞通知系统（零依赖） |

## 技术栈

| 类别 | 技术 | 版本 |
|------|------|------|
| 前端框架 | React | 19.2 |
| 语言 | TypeScript | 5.9 |
| 节点编辑器 | @xyflow/react (React Flow) | 12.10 |
| 构建工具 | Vite | 7.3 |
| 代码检查 | ESLint | 9.39 |
| 样式 | CSS 内联 + 设计令牌常量 | — |
| 通知 | 自建 Toast（零依赖） | — |

## 项目结构

```
src/
├── main.tsx                        # 应用入口，挂载 ToastProvider
├── App.tsx                          # 根组件，包裹 ReactFlowProvider
├── components/
│   ├── ReactFlowCanvas.tsx          # 主画布：拖放、连线、快捷键、生成/导入/导出/预览
│   ├── Sidebar.tsx                  # 侧边栏：节点分类列表、拖拽模板、重试机制
│   ├── SideHandleNode.tsx           # 自定义节点：端口渲染、双模布局、Customized data 端口、连接验证
│   └── toast/
│       └── ToastProvider.tsx        # Toast 通知系统（Context + 动画）
├── constants/
│   ├── api.ts                       # API 路径常量（含 preview）
│   ├── editor.ts                    # 编辑器常量（节点类型、拖拽 key、版本号）
│   └── theme.ts                     # 设计令牌（颜色、平台配色）
├── types/
│   └── node.ts                      # TypeScript 类型定义
├── utils/
│   ├── api.ts                       # 统一 fetch 封装（apiGet / apiPost）
│   ├── download.ts                  # Blob 下载工具
│   ├── inputControlRenderer.tsx     # 动态输入控件渲染器（含 ListTagInput）
│   ├── nodes.ts                     # 节点状态更新工具
│   └── platform.ts                  # 平台标签样式工具
└── public/
    ├── favicon.ico
    └── favicon.png
```

## 架构设计

```
┌─────────────────────────────────────────────────────────────┐
│                     index.html                               │
│                   main.tsx (ToastProvider)                   │
│                      App.tsx (ReactFlowProvider)             │
├─────────────────────────────────────────────────────────────┤
│   ReactFlowCanvas                                           │
│   ┌──────────┬───────────────────────────────────────────┐  │
│   │ Sidebar  │  ReactFlow 画布                             │  │
│   │          │  ┌──────────┐    ┌──────────────┐         │  │
│   │ 分类列表  │  │ Weapons  │───▶│ VehicleTypes │         │  │
│   │ 拖拽模板  │  │ CustomData│    │ Primary ◀━━━━│         │  │
│   │          │  └──────────┘    │ CustomData ◀━━│         │  │
│   │          │                  └──────────────┘         │  │
│   └──────────┴───────────────────────────────────────────┘  │
│                    Vite 代理 → localhost:8080                │
└─────────────────────────────────────────────────────────────┘
```

### 数据流

```
用户拖拽节点 → Sidebar.handleDragStart
                  │
                  ▼
         ReactFlowCanvas.onDrop (创建 Node)
                  │
                  ▼
         SideHandleNode.useEffect (调用 getNodeInfo API)
                  │
                  ▼
  Name 自动生成 + 渲染三类端口（Handle-only / 双模 / 纯控件）
                  │
  Customized data 端口按 acceptCustomData 配置显示
                  │
        用户连线 → onConnect（白名单验证 + Customized data 专用验证）
                  │
        点击「预览」→ previewCode（实时查看 INI 内容）
        点击「生成代码」→ generateCode（空值校验 + INI 格式校验）
                  │
                  ▼
            POST /generate → 下载 ZIP
```

## 部署模式

### 开发模式（前后端分离）

```bash
npm run dev
# 访问 http://localhost:5173
# Vite 自动代理 /simple-creator 到 localhost:8080
```

### 生产模式（后端内嵌 SPA）

```bash
npm run build
cp -r dist/* ../simple-creator/src/main/resources/static/
# 启动后端 → 访问 http://localhost:8080/simple-creator
```

## 后端依赖

| API | 用途 |
|-----|------|
| `GET /simple-creator/api/v1/getTypeList` | 获取节点分类列表 |
| `GET /simple-creator/api/v1/getNodes` | 获取节点名→分类映射 |
| `GET /simple-creator/api/v1/getNodeInfo?nodeName=X` | 获取节点输入端口定义（含 acceptCustomData） |
| `POST /simple-creator/api/v1/generate` | 提交节点数据，返回 INI ZIP |
| `POST /simple-creator/api/v1/preview` | 提交节点数据，返回文件名+内容 JSON（预览用） |

## 快速开始

### 环境要求

- Node.js ≥ 18
- 后端服务运行在 `localhost:8080`（参见 [simple-creator](https://gitee.com/Nicolas_Z_013/simple-creator)）

### 安装

```bash
git clone https://gitee.com/Nicolas_Z_013/red-alert-node-editor.git
cd red-alert-node-editor
npm install
```

### 开发

```bash
npm run dev
# 访问 http://localhost:5173
```

### 构建

```bash
npm run build     # 输出到 dist/
npm run preview   # 本地预览生产构建
```

## 使用指南

### 基本操作

| 操作 | 方式 |
|------|------|
| 添加节点 | 从左侧侧边栏拖拽节点到画布 |
| 移动节点 | 拖拽节点到任意位置 |
| 缩放画布 | 鼠标滚轮 / 左下角控件 |
| 建立连线 | 从节点输出 handle 拖到目标节点端口 handle |
| 删除连线 | 双击连线 |
| 删除节点 | 点击节点 ⋮ 菜单 → 删除 / 选中后按 Delete |
| 复制节点 | 点击节点 ⋮ 菜单 → 复制 / 选中后按 Ctrl+D |
| 重命名节点 | 双击节点名称处编辑 |

### 配置参数

- **必填参数**：节点放置后自动显示，Name 自动生成
- **可选参数**：点击「+ 添加可选参数」按钮，弹窗中搜索/选择
- **LIST 标签输入**：回车添加标签，× 删除标签，双击标签可编辑内容
- **双模端口**：handle 点接受连线，输入框可手动填写

### Customized data 节点

- 拖入 `Customized data` 节点，在 `input` 字段写入原始 INI 行（key=value 格式）
- 从 Customized data 连到目标节点的紫色 `Customized data` 端口
- 目标节点的 YAML 需设置 `acceptCustomData: true` 才会显示该端口
- 允许多个 Customized data 节点连到同一目标，内容自动合并
- 生成前自动校验 INI 格式：不能含 `[...]` section 头，每行需为 `key=value`

### 连线规则

- 只有 `acceptNodes: true` 的端口才能接受连线
- 连线来源节点必须在目标端口的 `acceptedNodes` 白名单中
- Customized data 端口仅接受 Customized data 源节点
- 不符合规则的连线会被拒绝

### 导入/导出

- **导出**：点击「导出为文件」或 Ctrl+S，下载 `.json` 文件
- **导入**：点击「从文件导入」或 Ctrl+O，选择之前导出的 `.json` 文件
- 导入时自动检查格式版本兼容性
- 导入时自动恢复连线状态和可选端口

### 预览 + 生成

- **预览**：点击紫色「预览」按钮，弹窗显示各 INI 文件名、行数和完整内容
- **生成代码**：点击「生成代码」按钮，下载 INI 配置 ZIP 包

## 键盘快捷键

| 快捷键 | 功能 |
|--------|------|
| `Delete` / `Backspace` | 删除选中节点（输入框内不触发） |
| `Ctrl+D` | 复制选中节点 |
| `Ctrl+S` | 导出为 JSON 文件 |
| `Ctrl+O` | 从文件导入 |
| `Shift+拖拽` | 多选节点 |

## 许可证

Apache License 2.0 © 2024-2026 Frostlock Zhou

本项目使用 [ModEnc](https://modenc.renegadeprojects.com) 提供的 RA2/YR INI 标志参考数据。

---

**AI 辅助创作声明**：本项目在开发过程中使用了 AI 辅助工具（WorkBuddy），参与了代码编写、架构设计、节点定义补全和代码审查优化。