GraphView Skill System

Visual skill graph authoring, deterministic GSKL compilation, and bounded multi-entity execution for Unity 6.

GraphView Skill System is a data-driven skill and behavior execution pipeline. Authors connect event, control-flow, and action nodes in an Editor-only GraphView tool; the compiler converts the graph into a fixed-layout GSKL binary program; the runtime validates that program and executes it through preallocated state arrays and data-injection hooks.

The included runtime demo runs 1,000 entities against one shared immutable program and routes movement, damage, and combat-audio commands to a separate presentation layer.

English	简体中文

Capabilities / 已实现能力

• Graph authoring：基于 UI Toolkit 与 GraphView 的无限画布，支持平移、缩放、节点连线、分类创建、参数编辑和编译诊断。
• Live runtime debugging：Editor 内置按实体过滤的固定容量轨迹、节点定位、断点、暂停/继续和单逻辑 Tick 执行；诊断与运行时节点均可回到精确画布位置。
• Loss-aware authoring：缺失节点描述时使用可往返保存的 Missing Node；重复 ID、悬空边、无效端口或不可表示的视图会阻止保存，避免静默丢失配置。
• Editor dependency isolation：UnityEditor.Experimental.GraphView 仅存在于 Editor assembly；authoring schema、compiler 和 runtime ABI 不依赖 GraphView。
• Deterministic compilation：使用带稳定 tie-breaker 的 Kahn 拓扑排序规范化节点与边；编辑器坐标不进入运行时产物。
• Compile-time validation：检查唯一入口、悬空边、重复边、端口约束、Stable ID 碰撞、Sequence order、不可达节点、cycle、有界 Repeat、WaitTicks、continuation stack 和 instruction budget。
• Versioned binary ABI：GSKL v1 使用固定 header/state/edge 布局、little-endian 编码、16-byte section alignment、固定 opcode 数值和多层 hash。
• Validated program snapshot：加载前先执行最大长度门禁，再取得私有字节快照并校验 ABI、唯一 Event/entry、布局、语义、DAG、registry hash 和 content hash，调用方后续修改源数组不会影响已发布 program。
• Identity-safe atomic publish：校验 schema、Graph GUID 与 Unity Asset GUID；普通图使用稳定资产 GUID 命名，先写同卷 staging、回读校验，再原子替换旧 .bytes。
• Bounded transactional runtime：实体状态、continuation stack 与 command buffer 在 world 构造时一次性分配；每实体具有独立命令配额，fault 会回滚该实体本 tick 已写入的命令。
• Data injection：ISkillDataSource 提供逻辑输入，ISkillCommandSink 消费值类型命令；VM 不直接引用 GameObject、字符串、动画或音频 API。
• Combat-audio separation：PlayCombatAudio 输出稳定的 AssetKey，由表现层映射到 AudioClip 或外部音频中间件事件。
• Bilingual presentation：Runtime HUD、GraphView 编辑器和 Inspector 支持中英文即时切换；语言状态不会进入图资产、二进制、hash 或 VM 状态。
• Validated reload boundary：本地 bytes provider 支持 load/validate/publish；YooAsset、HybridCLR 和远端发布治理尚未集成。
• Reproducible performance baseline：内置 EditMode benchmark 输出机器可读 JSON、提交号、program hash、分位耗时、指令/命令/fault 与当前线程分配；BatchMode 违反契约时返回失败。

Architecture / 架构

flowchart LR
    subgraph E["Editor / allocation allowed"]
        G["GraphView"] --> A["Flat SkillGraphAsset"]
        A --> C["Validation + deterministic compiler"]
        C --> B["GSKL .bytes"]
        X["Runtime debugger + diagnostics"]
    end

    subgraph L["Load or patch boundary"]
        B --> V["TryCreate: ABI + layout + hash"]
        V --> P["Private immutable SkillProgram snapshot"]
    end

    subgraph R["Logic tick / bounded execution"]
        P --> W["SkillVmWorld x 1,000 entities"]
        D["ISkillDataSource snapshot"] --> W
        W --> Q["Transactional fixed SkillCommandBuffer"]
        Q --> S["ISkillCommandSink / presentation"]
    end

    W --> T["Fixed SkillVmTraceBuffer"]
    T --> H["SkillRuntimeDebugHub"] --> X
    X -.-> H
    H -.-> W

Loading

完整的依赖规则、编译算法、内存模型和 ABI 演进约束见 Architecture。

Quick Start

Requirements

• Unity 6000.3.9f1
• Built-in Render Pipeline
• Unity Test Framework 1.6.0

Build and run the runtime demo

1. 使用 Unity Hub 打开仓库根目录。
2. 选择 Tools/Graph Skill System/Build Runtime Demo，刷新示例图、GSKL bytes 与演示资源；已有场景默认复用，不覆盖本地场景编辑。
3. 选择 Tools/Graph Skill System/Open Demo Scene。
4. 进入 Play Mode。

需要有意重建生成场景时，使用 Tools/Graph Skill System/Rebuild Runtime Demo Scene 并确认覆盖。Builder 不修改 Company、Product、Color Space、Serialization Mode 或 Build Settings 场景列表。

固定资源路径：

• Scene：Assets/GraphSkillSystem/Demo/Scenes/GraphSkillDemo.unity
• Authoring graph：Assets/GraphSkillSystem/Demo/Graphs/CombatShowcase.asset
• Runtime bytes：Assets/StreamingAssets/SkillGraphs/CombatShowcase.bytes

运行键位：

Key	Action
Space	触发所有实体的当前技能 program
B	启用或暂停自动负载循环
R	重新读取、校验并发布 CombatShowcase.bytes
H	显示或隐藏 HUD
L	切换中英文界面

HUD 提供 Entities、VM Tick µs、VM GC bytes、Instructions、Commands、Faults 和 Program Hash。性能数据仅在 Faults == 0 时有效。

Author a graph

1. 选择 Tools/Graph Skill System/Skill Graph Editor。
2. 打开 CombatShowcase.asset，或通过 Assets/Create/Graph Skill System/Skill Graph 创建资源。
3. 在画布中创建并连接 Event、Control Flow 与 Action 节点。
4. 保存并编译；所有 diagnostics 通过后生成 .bytes。
5. 回到 Runtime Demo 按 R，在加载边界验证新的 program。

编辑器工具栏的 中文 / EN 按钮会原位刷新工具栏、状态栏、右键菜单、节点标题、端口和参数字段，不会重建 GraphView 或修改未保存的图数据。

Debug a running graph

1. 在 Skill Graph Editor 中打开已编译的 CombatShowcase.asset，并进入 Demo Play Mode。
2. 在右侧 Runtime Debugger 选择观察实体；示例默认只追踪实体 0。
3. 点击轨迹行可定位对应节点；选中节点后可添加或移除断点。
4. 使用 Pause、Resume 与 Step Tick 在完整逻辑 Tick 边界控制执行。

只有当前画布重新编译得到的 SourceHash 与运行中 program 一致时，轨迹和断点才会映射到节点。未保存、编译失败或版本不一致的图会关闭映射，防止把旧程序状态投射到新画布。完整语义与容量边界见 Runtime Debugging。

当前 opcode：

Event       EventSkillPressed, EventTargetEnteredRange
Control     Branch, Sequence, Repeat, WaitTicks
Action      Move, ApplyDamage, PlayCombatAudio
Terminal    End

GSKL v1 使用 bounded DAG，任意回边都会在编译期被拒绝。时间推进与重复分别由 WaitTicks 和有界 Repeat 表达。

GSKL v1 binary layout / 二进制布局

Section	Layout	Purpose
Header	64 bytes	magic、version、size、count、offset、budget、compiler、registry、hash
State array	32 bytes / state	opcode、edge slice、两个 int、两个 float、stable ID
Alignment padding	16-byte section alignment	与 CLR struct packing 解耦
Edge array	8 bytes / edge	target state index、source port、flags

0                     64                aligned N                   EOF
+---------------------+------------------+------------+---------------+
| GSKL v1 Header      | State[0..n)     | Padding    | Edge[0..m)    |
+---------------------+------------------+------------+---------------+

Loader 采用 fail-closed 策略。远端资源仍需在该内部校验之外提供强 hash、签名、授权版本和 anti-rollback 机制；FNV 只用于确定性与损坏检测。

GSKL v1 的 contentHash 覆盖 state/padding/edge payload，不覆盖 header。Loader 会逐字段检查 header 范围与兼容性，但线上清单仍必须对整个文件做强 hash/签名；将预算字段纳入格式内部完整性保护属于 v2 路线。

Performance contract / 性能边界

本仓库中的 Zero-GC 目标仅指以下测量范围：

.bytes 已加载并通过校验、SkillVmWorld 已构造、实体与 hooks 已预热后，只测量 Trigger、Tick 和 DispatchCommands。调用方 hooks 不分配且固定容量未溢出时，VM hot path 的目标为 0 B managed GC Alloc；可选轨迹必须使用构造时分配的固定容量缓冲区。

该范围不包含 GraphView、编译器、文件与资源加载、第一次 JIT/domain warm-up、业务 sink、Unity rendering、physics 或 audio。HUD 的 VM GC bytes 仅表示 VM 测量段，不代表整个 frame。

跨平台性能结论需要在目标平台的 Development Player 中复验，并记录平台、backend、program hash、实体数量、预热 ticks、采样窗口、CPU time、GC bytes、instructions、commands 和 faults。

仓库附带可复现的 EditMode 回归基线。当前 Apple M5 Pro / Unity 6000.3.9f1 / Mono 快照在 60 ticks 预热、300 ticks 采样下得到：

Entities	p50	p95	p99	Managed allocation	Faults
100	32.2 µs	35.6 µs	38.0 µs	0 B	0
1,000	325.2 µs	345.4 µs	362.5 µs	0 B	0
10,000	3,293.3 µs	3,377.3 µs	3,405.8 µs	0 B	0

该工具只计时 TriggerAll + Tick，命令 hash 位于计时窗外。完整环境、口径、复现命令与原始 JSON 见 Performance Baseline。这些数字是 Editor 回归证据，不代表 Player、IL2CPP 或其他设备性能。

Verification / 验证

当前 Unity 6000.3.9f1 EditMode 验收快照为 61/61 Passed，0 failed / 0 skipped。测试明细与复现命令见 Test Results。

当前测试覆盖：

• 确定性编译与 source/content hash；
• cycle、dangling、duplicate、invalid port、Stable ID 碰撞、duplicate Sequence order 和非法参数诊断；
• header、compiler version、registry、offset、flags、opcode、back-edge 与 payload 损坏时 fail closed；
• 私有 program 快照、唯一 Event/entry，以及输入数组在发布后被修改的隔离；
• Branch、Sequence、Repeat、WaitTicks、action command 顺序与每实体事务回滚；
• command buffer、continuation stack、instruction budget fault 与跨实体命令配额隔离；
• 缺失 opcode 节点无损往返、悬空边阻止保存、Graph GUID 冲突与原子发布；
• 固定轨迹环覆盖、实体过滤、合法零值 Stable ID、断点首次命中保留、Tick 边界暂停与单 Tick 执行；
• GraphView 精确节点定位、diagnostic/debug/breakpoint 高亮，以及完整调试面板 UI 契约；
• 1,000 entities 的 deterministic command ABI hash、预热后单次 Tick 当前线程分配与 benchmark JSON 契约；
• 1,000 entities 下启用固定轨迹后的预热 Tick 当前线程 0 B 分配回归；
• 中英文 Catalog 完整性、占位符一致性、切换事件幂等，以及切换前后 bytes/source hash 一致性。

Implementation status / 实现状态

Capability	Status	Boundary
Flat authoring asset	Implemented	runtime 只消费 compiled bytes
GraphView editor	Implemented	Editor-only assembly；缺失节点保真，损失性保存被阻止
Reflection-based node discovery	Implemented	菜单由 metadata discovery 生成
Deterministic compiler	Implemented	bounded DAG、稳定排序、静态预算
GSKL v1 writer/reader	Implemented	固定布局、私有快照、ABI/hash、语义校验
Atomic graph publication	Implemented	唯一身份、同卷 staging、回读验证、原子替换
Preallocated multi-entity VM	Implemented	shared program + fixed arrays + per-entity command transactions
Data injection and audio command	Implemented	query/sink interfaces + stable AssetKey
Runtime demo and telemetry HUD	Implemented	1,000 entities、手动/自动负载、reload
Runtime debugger	Implemented	固定容量 trace、实体过滤、节点定位、断点与完整 Tick 单步；非指令级暂停
Runtime / Editor localization	Implemented	中英文原位刷新，不进入编译数据
Local bytes reload	Implemented	validate-before-publish
EditMode performance baseline	Implemented	JSON、分位耗时、0 B/fault 契约；非 Player 证据
YooAsset delivery	Not integrated	provider seam 与接入设计已定义
HybridCLR hot-update DLL	Not integrated	尚无动态 handler registry
Signing, rollout, telemetry, rollback	Not implemented	production roadmap
In-flight VM state migration	Not implemented	需要上层 tick-barrier policy
Sub-graph support	Planned	尚未进入 GSKL v1

热更新能力矩阵和未实现项见 Hot Update Boundary。

Repository layout

Assets/GraphSkillSystem/
├── Core/
│   ├── Binary/          # GSKL ABI, validator, private immutable snapshot
│   ├── Commands/        # fixed-capacity transactional value commands
│   ├── Compilation/     # validation, topo sort, static budgets
│   ├── Localization/    # bilingual catalog and stable language codes
│   └── Runtime/         # managed-array VM, hooks, fixed trace and tick debugger
├── Authoring/           # flat SkillGraphAsset records
├── Editor/              # GraphView, loss-aware authoring, atomic export, benchmark
├── Runtime/
│   ├── Demo/            # runtime controller and presentation adapters
│   ├── Debugging/       # in-process Runtime-to-Editor debug session bridge
│   ├── Localization/    # PlayerPrefs preference adapter
│   └── HotUpdate/       # provider and validated publish boundary
├── Demo/                # scene, sample graph, audio and materials
└── Tests/EditMode/      # compiler, binary, localization and VM tests

Design decisions / 设计决策

• Fixed binary instead of runtime JSON parsing：可编辑数据保留在 authoring asset，构建边界生成固定布局 bytes，避免运行时对象图和字符串解析。
• Bounded DAG instead of arbitrary cycles：v1 优先保证可静态推导的 stack 与 instruction budget；未来循环能力需要显式 opcode 和版本化 ABI。
• Commands instead of direct GameObject callbacks：值类型命令将 simulation 与 presentation 分离，便于回放、服务端测试和替换表现层。
• Validate before publish：candidate 完成外部签名/版本检查与内部 ABI 校验后，才能在 tick barrier 发布；失败不会替换 active revision。
• Loss-aware editing：编辑器不能表示的数据必须以占位节点保留，或明确阻止保存；不允许通过重新序列化静默删除未知记录。
• Transactional command output：每个实体在单 tick 内先写入逻辑事务，fault 时只回滚自身副作用，其他实体仍可继续执行。
• Immutable program per world：更新 active program 不会隐式迁移正在执行的 world，迁移策略由上层明确选择 cancel、restart 或 stable-ID migration。

Documentation

• Architecture：程序集依赖、编译过程、ABI、VM 内存模型和本地化边界。
• Runtime Debugging：轨迹、断点、Tick 单步、身份映射和 Zero-GC 容量边界。
• Performance Baseline：EditMode 回归口径、结果、JSON 与复现命令。
• Hot Update Boundary：数据发布事务、YooAsset/HybridCLR 接入点和 production gap。
• Test Results：当前测试快照、套件明细和复现命令。

Roadmap

1. Development Player / IL2CPP / 目标设备 Profiler capture，并建立按平台隔离的 CI performance threshold。
2. GSKL v2 将关键 header 纳入整文件完整性保护，或从 payload 重新推导并核对 stack/instruction budgets。
3. Sub-graph table、call-frame budget、递归检测和跨图版本依赖。
4. 指令级 partial-tick 调试事务、轨迹导出/回放与跨进程远程调试会话。
5. Burst/Jobs/NativeArray runtime backend，同时保持 GSKL 与 command ABI。
6. YooAsset signed manifest、staging、last-known-good、灰度与 kill switch。
7. HybridCLR versioned handler registry、AOT metadata 与 IL2CPP 兼容矩阵。
8. 明确的 cancel/restart 或 stable-ID state migration policy。

License

本仓库自研代码和文档采用 MIT License。Unity Editor、Unity Package Manager 依赖及其商标分别受其原始许可条款约束。