Telepath.Core 0.45.1

Telepath

基于 R3 的 MVVM UI 框架，面向 Godot 4.4+ / .NET 8

Feature

• 平台无关的 Core：Telepath.Core 不依赖 Godot，同一套 ViewModel 可复用到其他 R3 宿主
• 声明式绑定：绑定信息可存在于场景节点的.tscn文件中，由编辑器扩展可视化编辑，无需重新编译即可对绑定进行调整
• 源生成器：使用源生成器减少了大量样板代码
• 内嵌 R3 胶水：帧/时间时钟、Godot 信号转 Observable，无需再装官方 R3.Godot addon

Requirements

• Godot 4.4+（.NET）
• .NET 8 SDK

Installation

NuGet

在宿主工程（Godot.NET.Sdk）里加：

<PackageReference Include="Telepath.Godot" Version="0.45.1" />

或：

dotnet add package Telepath.Godot --version 0.45.1

Telepath.Godot 会带上 Telepath.Core 以及源生成器。

然后按下方 Addon 一节把编辑器插件拷进工程。

From Source

1. Clone 或 submodule 本仓库
2. 在宿主工程（Godot.NET.Sdk）里加两个 ProjectReference：

<ProjectReference Include="path/to/Telepath/src/Telepath.Godot/Telepath.Godot.csproj" />
<ProjectReference Include="path/to/Telepath/src/Telepath.SourceGenerator/Telepath.SourceGenerator.csproj"
                  OutputItemType="Analyzer"
                  ReferenceOutputAssembly="false" />

Telepath.Godot 会附带 Telepath.Core

3. 按下方 Addon 一节把编辑器插件拷进工程。

Addon

无论 NuGet 还是源码引用，都需要把 addon 复制（或符号链接）进宿主工程：

构建 Godot 项目后然后在 项目设置 → 插件 里启用

插件会把 GDScript 外壳 FrameProviderDispatcher.gd 注册成 Autoload，运行时驱动 R3 时钟；导出的工程同样依赖这个 Autoload，请确认 project.godot 里有 [autoload] 条目

注意：

• Windows 上 git 符号链接需要 core.symlinks = true，否则直接复制
• 不要装官方 R3.Godot addon：运行时子集已内嵌（namespace R3），同名类型会冲突
• addon 里的 GDScript 外壳与 Dock 由宿主主程序集编译，不会进入 Telepath.Godot.dll

Quick Start

一个最简单的计数器：ViewModel → View → 场景绑定

1. ViewModel —— 只写字段与方法，生成器产出 R3 属性与命令：

using R3;
using Telepath.Core;

public sealed partial class CounterViewModel : ViewModel
{
    [Bindable]
    private int _count;

    [Command(CanExecute = nameof(CanIncrement))]
    private void OnIncrement() => Count.Value++;

    private Observable<bool> CanIncrement() => Count.Select(c => c < 10);
}

[Bindable] private int _count 生成 BindableReactiveProperty<int> Count；[Command] OnIncrement() 生成 ReactiveCommand IncrementCommand（CanExecute 关联按钮 Disabled），两者都登记进 VM 的 DisposableBag

2. View —— 轻量化对象，标记与通知转发：

using Godot;
using Telepath.Godot;

[TelepathView<CounterViewModel>]
public partial class CounterView : Control
{
    public override partial void _Notification(int what);

    private CounterViewModel CreateViewModel() => new();
}

3. 场景 —— 一个 Label（%CountLabel）和一个 Button（%IncrementButton），使用UI绑定侧栏(在Inspector旁边)，调整绑定关系

场景文件中将会附带这样的 metadata/telepath_bindings

metadata/telepath_bindings = [{
"kind": "Text",
"member": "Count",
"path": "%CountLabel"
}, {
"kind": "Command",
"member": "IncrementCommand",
"path": "%IncrementButton"
}]

运行时，编辑器扩展会解析这些绑定信息，并自动生成对应的代码

Current Supported Bindings

Directory Structure

src/Telepath.Core/             
src/Telepath.Godot/            Godot 层
  Addon/                       
  Editor/                      GDScript 插件
src/Telepath.SourceGenerator/  Roslyn 生成器
samples/Showcase/             演示 Godot 工程（addons/Telepath 为符号链接）
tests/                        单元测试

Showcase

如果你想深入了解，请使用 Godot 打开 samples/Showcase

包含详尽的示例与注释帮你理解这个框架

Build & Test

dotnet build Telepath.sln
dotnet test  Telepath.sln

GitHub Actions 在 PR 和 master 上跑单元测试并验证 NuGet 打包（不编译 Showcase）。发版打 x.y.z tag（不要 v 前缀）并 push。首次 0.45.1 请在 Actions 里对 Release NuGet 手动 Run workflow，填 version 0.45.1。

License

MIT

See LICENSE