Skip to content

Commit 256c404

Browse files
BAKAOLCBAKAOLC
committed
feat(NodeAttachments): enhance node attachment functionality and documentation
- Added new method `EnsureReadyNodeAttachments` to ensure all registered ready-time node attachments are applied for a given parent node. - Updated `ModNodeAttachmentRegistry` to include `EnsureReadyAttachments` for applying registered attachments. - Enhanced documentation across various classes and methods to improve clarity, including translations for key comments. - Refactored node attachment attributes to provide clearer metadata and options for managing child nodes during the ready lifecycle.
1 parent f2e3068 commit 256c404

8 files changed

Lines changed: 98 additions & 1 deletion

‎Interop/AutoRegistration/RegistrationAttributes.NodeAttachments.cs‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,105 +4,124 @@ namespace STS2RitsuLib.Interop.AutoRegistration
44
{
55
/// <summary>
66
/// Base metadata for declarative ready-time node attachments.
7+
/// 声明式 ready 阶段节点挂载的基础元数据。
78
/// </summary>
89
public abstract class RegisterNodeAttachmentAttributeBase(Type parentType, string localId)
910
: AutoRegistrationAttribute
1011
{
1112
/// <summary>
1213
/// Parent node type whose ready lifecycle receives the child.
14+
/// ready 生命周期会接收子节点的父节点类型。
1315
/// </summary>
1416
public Type ParentType { get; } = parentType;
1517

1618
/// <summary>
1719
/// Local, mod-scoped attachment id.
20+
/// mod 作用域内的本地挂载 id。
1821
/// </summary>
1922
public string LocalId { get; } = localId;
2023

2124
/// <summary>
2225
/// Direct child name assigned to the attached node.
26+
/// 分配给挂载节点的直接子节点名称。
2327
/// </summary>
2428
public string? NodeName { get; set; }
2529

2630
/// <summary>
2731
/// Sets <c>UniqueNameInOwner</c> and assigns the parent as owner after add.
32+
/// 设置 <c>UniqueNameInOwner</c>，并在加入后将父节点设为 owner。
2833
/// </summary>
2934
public bool UniqueNameInOwner { get; set; }
3035

3136
/// <summary>
3237
/// Applies the registration to derived parent node types.
38+
/// 将注册应用到派生父节点类型。
3339
/// </summary>
3440
public bool IncludeDerivedParentTypes { get; set; } = true;
3541

3642
/// <summary>
3743
/// Existing-child duplicate policy.
44+
/// 已有子节点的重复处理策略。
3845
/// </summary>
3946
public NodeAttachmentDuplicatePolicy DuplicatePolicy { get; set; } =
4047
NodeAttachmentDuplicatePolicy.AllowDuplicateName;
4148

4249
/// <summary>
4350
/// Node add mode.
51+
/// 节点加入模式。
4452
/// </summary>
4553
public NodeAttachmentAddMode AddMode { get; set; } = NodeAttachmentAddMode.AddChildSafely;
4654

4755
/// <summary>
4856
/// Setup timing for <see cref="INodeAttachmentSetup" />.
57+
/// <see cref="INodeAttachmentSetup" /> 的 setup 时机。
4958
/// </summary>
5059
public NodeAttachmentSetupTiming SetupTiming { get; set; } = NodeAttachmentSetupTiming.BeforeAdd;
5160

5261
/// <summary>
5362
/// Optional final direct-child index.
63+
/// 可选最终直接子节点索引。
5464
/// </summary>
5565
public int ChildIndex { get; set; } = -1;
5666

5767
/// <summary>
5868
/// Optional sibling name to insert before.
69+
/// 可选：插入到该同级节点名称之前。
5970
/// </summary>
6071
public string? InsertBeforeName { get; set; }
6172

6273
/// <summary>
6374
/// Optional sibling name to insert after.
75+
/// 可选：插入到该同级节点名称之后。
6476
/// </summary>
6577
public string? InsertAfterName { get; set; }
6678

6779
/// <summary>
6880
/// Queues a replaced existing node for freeing.
81+
/// 对被替换的已有节点调用 QueueFree。
6982
/// </summary>
7083
public bool QueueFreeReplacedNode { get; set; } = true;
7184
}
7285

7386
/// <summary>
7487
/// Declaratively registers a factory-created ready-time node attachment.
88+
/// 声明式注册由工厂创建的 ready 阶段节点挂载。
7589
/// </summary>
7690
[AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = false)]
7791
public sealed class RegisterNodeAttachmentAttribute(Type parentType, string localId)
7892
: RegisterNodeAttachmentAttributeBase(parentType, localId)
7993
{
8094
/// <summary>
8195
/// Optional child node type. When omitted, the annotated type must be the child node type.
96+
/// 可选子节点类型。省略时，标注类型本身必须是子节点类型。
8297
/// </summary>
8398
public Type? NodeType { get; set; }
8499
}
85100

86101
/// <summary>
87102
/// Declaratively registers a ready-time node attachment instantiated directly from a scene path.
103+
/// 声明式注册直接从 scene 路径实例化的 ready 阶段节点挂载。
88104
/// </summary>
89105
[AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = false)]
90106
public sealed class RegisterNodeAttachmentFromSceneAttribute(Type parentType, string localId, string scenePath)
91107
: RegisterNodeAttachmentAttributeBase(parentType, localId)
92108
{
93109
/// <summary>
94110
/// Expected child node type. When omitted, the annotated type must be the child node type.
111+
/// 期望的子节点类型。省略时，标注类型本身必须是子节点类型。
95112
/// </summary>
96113
public Type? NodeType { get; set; }
97114

98115
/// <summary>
99116
/// Godot scene path to instantiate.
117+
/// 要实例化的 Godot scene 路径。
100118
/// </summary>
101119
public string ScenePath { get; } = scenePath;
102120
}
103121

104122
/// <summary>
105123
/// Declaratively registers a ready-time node attachment created from a scene converted by RitsuLib node factories.
124+
/// 声明式注册由 RitsuLib 节点工厂转换 scene 后创建的 ready 阶段节点挂载。
106125
/// </summary>
107126
[AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = false)]
108127
public sealed class RegisterNodeAttachmentFromConvertedSceneAttribute(
@@ -113,11 +132,13 @@ public sealed class RegisterNodeAttachmentFromConvertedSceneAttribute(
113132
{
114133
/// <summary>
115134
/// Expected child node type. When omitted, the annotated type must be the child node type.
135+
/// 期望的子节点类型。省略时，标注类型本身必须是子节点类型。
116136
/// </summary>
117137
public Type? NodeType { get; set; }
118138

119139
/// <summary>
120140
/// Godot scene path loaded and converted through RitsuLib node factories.
141+
/// 通过 RitsuLib 节点工厂加载并转换的 Godot scene 路径。
121142
/// </summary>
122143
public string ScenePath { get; } = scenePath;
123144
}

‎RitsuLibFramework.cs‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -506,12 +506,22 @@ public static ModContentRegistry GetContentRegistry(string modId)
506506

507507
/// <summary>
508508
/// Returns the ready-time Godot node attachment registry for <paramref name="modId" />.
509+
/// 返回 <paramref name="modId" /> 的 ready 阶段 Godot 节点挂载注册表。
509510
/// </summary>
510511
public static ModNodeAttachmentRegistry GetNodeAttachmentRegistry(string modId)
511512
{
512513
return ModNodeAttachmentRegistry.For(modId);
513514
}
514515

516+
/// <summary>
517+
/// Ensures all ready-time node attachments registered for <paramref name="parent" /> have been applied.
518+
/// 确保已应用为 <paramref name="parent" /> 注册的所有 ready 阶段节点挂载项。
519+
/// </summary>
520+
public static void EnsureReadyNodeAttachments(Node parent)
521+
{
522+
ModNodeAttachmentRegistry.EnsureReadyAttachments(parent);
523+
}
524+
515525
/// <summary>
516526
/// Returns the keyword registry for <paramref name="modId" />.
517527
/// 返回 <paramref name="modId" /> 的关键字注册表。

‎Scaffolding/Godot/NodeAttachments/INodeAttachmentFactory.cs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,22 +4,26 @@ namespace STS2RitsuLib.Scaffolding.Godot.NodeAttachments
44
{
55
/// <summary>
66
/// Attribute auto-registration factory hook for ready-time node attachments.
7+
/// ready 阶段节点挂载的 attribute 自动注册工厂钩子。
78
/// </summary>
89
public interface INodeAttachmentFactory
910
{
1011
/// <summary>
1112
/// Creates the child node for <paramref name="parent" />.
13+
/// 为 <paramref name="parent" /> 创建子节点。
1214
/// </summary>
1315
Node CreateNode(Node parent);
1416
}
1517

1618
/// <summary>
1719
/// Attribute auto-registration setup hook for ready-time node attachments.
20+
/// ready 阶段节点挂载的 attribute 自动注册 setup 钩子。
1821
/// </summary>
1922
public interface INodeAttachmentSetup
2023
{
2124
/// <summary>
2225
/// Runs attachment setup for <paramref name="node" /> and its <paramref name="parent" />.
26+
/// 为 <paramref name="node" /> 及其 <paramref name="parent" /> 运行挂载 setup。
2327
/// </summary>
2428
void Setup(Node parent, Node node);
2529
}

‎Scaffolding/Godot/NodeAttachments/ModNodeAttachmentRegistry.cs‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ namespace STS2RitsuLib.Scaffolding.Godot.NodeAttachments
55
{
66
/// <summary>
77
/// Per-mod registration surface for attaching child nodes when a Godot parent becomes ready.
8+
/// 当 Godot 父节点进入 ready 时挂载子节点的逐 mod 注册入口。
89
/// </summary>
910
public sealed class ModNodeAttachmentRegistry
1011
{
@@ -26,6 +27,7 @@ private ModNodeAttachmentRegistry(string modId)
2627

2728
/// <summary>
2829
/// Returns the singleton registry for <paramref name="modId" />.
30+
/// 返回 <paramref name="modId" /> 对应的单例注册表。
2931
/// </summary>
3032
public static ModNodeAttachmentRegistry For(string modId)
3133
{
@@ -44,6 +46,7 @@ public static ModNodeAttachmentRegistry For(string modId)
4446

4547
/// <summary>
4648
/// Registers a factory-created child for <typeparamref name="TParent" /> ready events.
49+
/// 为 <typeparamref name="TParent" /> 的 ready 事件注册由工厂创建的子节点。
4750
/// </summary>
4851
public NodeAttachmentDefinition RegisterReadyChild<TParent, TNode>(
4952
string localId,
@@ -57,6 +60,7 @@ public NodeAttachmentDefinition RegisterReadyChild<TParent, TNode>(
5760

5861
/// <summary>
5962
/// Registers a factory-created child with setup for <typeparamref name="TParent" /> ready events.
63+
/// 为 <typeparamref name="TParent" /> 的 ready 事件注册带 setup 的工厂创建子节点。
6064
/// </summary>
6165
public NodeAttachmentDefinition RegisterReadyChild<TParent, TNode>(
6266
string localId,
@@ -78,6 +82,7 @@ public NodeAttachmentDefinition RegisterReadyChild<TParent, TNode>(
7882

7983
/// <summary>
8084
/// Registers a child instantiated directly from a <see cref="PackedScene" /> path.
85+
/// 注册直接从 <see cref="PackedScene" /> 路径实例化的子节点。
8186
/// </summary>
8287
public NodeAttachmentDefinition RegisterReadyChildFromScene<TParent, TNode>(
8388
string localId,
@@ -100,6 +105,8 @@ public NodeAttachmentDefinition RegisterReadyChildFromScene<TParent, TNode>(
100105
/// <summary>
101106
/// Registers a child created from a scene converted by
102107
/// <see cref="RitsuGodotNodeFactories.CreateFromScenePath{TNode}(string)" />.
108+
/// 注册由 <see cref="RitsuGodotNodeFactories.CreateFromScenePath{TNode}(string)" />
109+
/// 转换 scene 后创建的子节点。
103110
/// </summary>
104111
public NodeAttachmentDefinition RegisterReadyChildFromConvertedScene<TParent, TNode>(
105112
string localId,
@@ -121,6 +128,7 @@ public NodeAttachmentDefinition RegisterReadyChildFromConvertedScene<TParent, TN
121128

122129
/// <summary>
123130
/// Reads an attached node by this registry's local id without creating it.
131+
/// 通过该注册表的本地 id 读取已挂载节点，不会创建节点。
124132
/// </summary>
125133
public bool TryGetAttached<TParent, TNode>(TParent parent, string localId, out TNode node)
126134
where TParent : Node
@@ -132,6 +140,7 @@ public bool TryGetAttached<TParent, TNode>(TParent parent, string localId, out T
132140

133141
/// <summary>
134142
/// Reads an attached node by fully qualified attachment id without creating it.
143+
/// 通过完整限定挂载 id 读取已挂载节点，不会创建节点。
135144
/// </summary>
136145
public static bool TryGetAttachedById<TParent, TNode>(TParent parent, string id, out TNode node)
137146
where TParent : Node
@@ -140,8 +149,19 @@ public static bool TryGetAttachedById<TParent, TNode>(TParent parent, string id,
140149
return NodeAttachmentRuntime.TryGetAttached(parent, id, out node);
141150
}
142151

152+
/// <summary>
153+
/// Ensures all ready-time attachments registered for <paramref name="parent" /> have been applied.
154+
/// 确保已应用为 <paramref name="parent" /> 注册的所有 ready 阶段挂载项。
155+
/// </summary>
156+
public static void EnsureReadyAttachments(Node parent)
157+
{
158+
ArgumentNullException.ThrowIfNull(parent);
159+
NodeAttachmentRuntime.AttachReadyChildren(parent);
160+
}
161+
143162
/// <summary>
144163
/// Returns every registered node attachment for diagnostics and audit UIs.
164+
/// 返回所有已注册节点挂载项，供诊断和审计 UI 使用。
145165
/// </summary>
146166
public static NodeAttachmentDefinition[] GetDefinitionsSnapshot()
147167
{
@@ -157,6 +177,7 @@ public static NodeAttachmentDefinition[] GetDefinitionsSnapshot()
157177

158178
/// <summary>
159179
/// Builds the stable public id for a mod-scoped node attachment.
180+
/// 构建 mod 作用域节点挂载项的稳定公开 id。
160181
/// </summary>
161182
public static string GetQualifiedNodeAttachmentId(string modId, string localId)
162183
{

‎Scaffolding/Godot/NodeAttachments/NodeAttachmentDefinition.cs‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ namespace STS2RitsuLib.Scaffolding.Godot.NodeAttachments
44
{
55
/// <summary>
66
/// Immutable audit record for a ready-time node attachment registration.
7+
/// ready 阶段节点挂载注册的不可变审计记录。
78
/// </summary>
89
public sealed class NodeAttachmentDefinition
910
{
@@ -35,56 +36,67 @@ internal NodeAttachmentDefinition(
3536

3637
/// <summary>
3738
/// Mod id that owns this attachment.
39+
/// 拥有该挂载项的 mod id。
3840
/// </summary>
3941
public string ModId { get; }
4042

4143
/// <summary>
4244
/// Fully qualified attachment id.
45+
/// 完整限定的挂载 id。
4346
/// </summary>
4447
public string Id { get; }
4548

4649
/// <summary>
4750
/// Local id supplied by the owning mod.
51+
/// 拥有方 mod 提供的本地 id。
4852
/// </summary>
4953
public string LocalId { get; }
5054

5155
/// <summary>
5256
/// Parent node type whose ready lifecycle installs this attachment.
57+
/// ready 生命周期会安装该挂载项的父节点类型。
5358
/// </summary>
5459
public Type ParentType { get; }
5560

5661
/// <summary>
5762
/// Expected attached child node type.
63+
/// 期望的被挂载子节点类型。
5864
/// </summary>
5965
public Type NodeType { get; }
6066

6167
/// <summary>
6268
/// Options captured at registration time.
69+
/// 注册时捕获的选项。
6370
/// </summary>
6471
public NodeAttachmentOptions Options { get; }
6572

6673
/// <summary>
6774
/// Creation source label such as factory, scene, or converted-scene.
75+
/// 创建来源标签，例如 factory、scene 或 converted-scene。
6876
/// </summary>
6977
public string SourceKind { get; }
7078

7179
/// <summary>
7280
/// Scene path used by scene-backed registrations, if any.
81+
/// scene-backed 注册使用的 scene 路径（如果有）。
7382
/// </summary>
7483
public string? ScenePath { get; }
7584

7685
/// <summary>
7786
/// Stable ordering among attachments on the same parent.
87+
/// 同一父节点上各挂载项的稳定顺序。
7888
/// </summary>
7989
public int Order => Options.Order;
8090

8191
/// <summary>
8292
/// Optional direct-child name assigned to the attached node.
93+
/// 分配给挂载节点的可选直接子节点名称。
8394
/// </summary>
8495
public string? Name => Options.Name;
8596

8697
/// <summary>
8798
/// Setup delegate adapted to untyped Node parameters for diagnostics.
99+
/// 适配为非泛型 Node 参数、用于诊断的 setup 委托。
88100
/// </summary>
89101
public Action<Node, Node>? Setup { get; }
90102

0 commit comments

Comments
 (0)