Skip to content

Commit 7a54c1e

Browse files
Kryptos-FRKryptos-FR
authored
docs: add quantum contributor documentation (#3136)
* docs: add graph-model.md for Quantum contributor docs * docs: add asset-graph.md for Quantum contributor docs * docs: add property-grid.md for Quantum contributor docs * docs: add README.md, completing Quantum contributor docs * chore: move contributors docs * docs: unwrap quantum markdown
1 parent 63dc265 commit 7a54c1e

4 files changed

Lines changed: 472 additions & 0 deletions

File tree

‎docs/quantum/README.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Quantum — Overview
2+
3+
Quantum is Stride's graph-based introspection framework. It wraps any .NET object hierarchy into a typed node graph, and that graph is the single source of truth for three things: **property grid display**, **undo/redo**, and **asset override tracking** (the "bold = overridden" behaviour in prefab/archetype workflows).
4+
5+
## Layers
6+
7+
```mermaid
8+
flowchart TD
9+
A["Stride.Core.Quantum<br/>sources/presentation/Stride.Core.Quantum/<br/>Live node graph over .NET objects"]
10+
B["Stride.Core.Assets.Quantum<br/>sources/assets/Stride.Core.Assets.Quantum/<br/>Override tracking, base-asset linking"]
11+
C["Stride.Core.Presentation.Quantum<br/>sources/presentation/Stride.Core.Presentation.Quantum/<br/>INodePresenter — property grid view model"]
12+
D["Stride.Core.Assets.Editor<br/>sources/editor/Stride.Core.Assets.Editor/Quantum/<br/>IAssetNodePresenter, AssetNodePresenterUpdaterBase"]
13+
E["Stride.Assets.Presentation<br/>sources/editor/Stride.Assets.Presentation/NodePresenters/<br/>Concrete updaters per asset type"]
14+
15+
A --> B
16+
B --> C
17+
C --> D
18+
D --> E
19+
```
20+
21+
## Data Flow
22+
23+
1. **Asset opens** — `AssetPropertyGraph` (created via `AssetQuantumRegistry.ConstructPropertyGraph` with the session's `AssetPropertyGraphContainer`) calls `GetOrCreateNode(asset)` on the underlying `NodeContainer` to build the core graph.
24+
2. **Override semantics** — `AssetPropertyGraph` links each node to its counterpart in the base asset graph (if any) and marks inherited vs. overridden values.
25+
3. **Presenter tree** — `AssetNodePresenterFactory` walks the node graph and creates one `IAssetNodePresenter` per node.
26+
4. **Updaters run** — all registered `INodePresenterUpdater` implementations get `UpdateNode()` called per node, then `FinalizeTree()` called once for the full tree.
27+
5. **Property grid binds** — the WPF property grid binds to the presenter tree: `DisplayName` → label, `Value/UpdateValue` → input control, `IsVisible/IsReadOnly` → visibility and editability, `AttachedProperties` → input constraints.
28+
29+
## When You Need Quantum
30+
31+
> **Decision tree:**
32+
>
33+
> - Adding a new asset type with default property grid display?
34+
> → **No Quantum code needed.** `[DataMember]` and `[Display]` attributes on the asset class
35+
> are sufficient. See [asset-system/README.md](../asset-system/README.md).
36+
>
37+
> - Customising visibility, display names, numeric constraints, or computed properties
38+
> for a new or existing asset?
39+
> → **Write an `INodePresenterUpdater`.** See [property-grid.md](property-grid.md).
40+
>
41+
> - Asset class holds members that are references to other content objects (Prefabs, Textures)?
42+
> → **Write an `AssetPropertyGraphDefinition`.** See [asset-graph.md](asset-graph.md).
43+
>
44+
> - Custom override or inheritance behaviour (rare — scenes and prefabs already cover this)?
45+
> → **Subclass `AssetPropertyGraph`.** See [asset-graph.md](asset-graph.md).
46+
47+
## Spoke Files
48+
49+
| File | Covers |
50+
|---|---|
51+
| [graph-model.md](graph-model.md) | `IGraphNode`, `IObjectNode`, `IMemberNode`, `NodeContainer`, mutations, change listeners |
52+
| [asset-graph.md](asset-graph.md) | `AssetPropertyGraph`, override model, `AssetPropertyGraphDefinition`, `AssetQuantumRegistry` |
53+
| [property-grid.md](property-grid.md) | `INodePresenter`, `IAssetNodePresenter`, updater pipeline, `INodePresenterUpdater` cookbook |

‎docs/quantum/asset-graph.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Asset Property Graph
2+
3+
## Role
4+
5+
`Stride.Core.Assets.Quantum` wraps the core Quantum graph with asset-specific semantics: override tracking, base-asset linking, and archetype/prefab inheritance. When a derived prefab overrides a value from its base, the graph records that override and can reset it. This is the layer that makes "this property is bold because it's overridden" possible in GameStudio.
6+
7+
## `IAssetNode` Extensions
8+
9+
`IAssetNode` extends `IGraphNode` with asset-aware members:
10+
11+
| Member | Type | Purpose |
12+
|---|---|---|
13+
| `PropertyGraph` | `AssetPropertyGraph` | The graph that owns this node |
14+
| `BaseNode` | `IGraphNode` | The corresponding node in the base asset, or `null` if none |
15+
| `OverrideChanging` | event | Raised before override state changes |
16+
| `OverrideChanged` | event | Raised after override state changes |
17+
| `ResetOverrideRecursively()` | method | Resets this node and all descendants to inherited values |
18+
| `SetContent(key, node)` | method | Attaches an auxiliary node (used internally) |
19+
| `GetContent(key)` | method | Retrieves an attached auxiliary node |
20+
21+
`IAssetMemberNode` (extends `IAssetNode`, `IMemberNode`) and `IAssetObjectNode` (extends `IAssetNode`, `IObjectNode`) are the concrete asset-aware node types. `IAssetObjectNode` adds per-item override tracking for collections (`IsItemInherited`, `IsItemOverridden`, `OverrideItem`, etc.).
22+
23+
## Override Model
24+
25+
A property in a derived asset is in one of three states:
26+
27+
| State | Meaning | GameStudio visual |
28+
|---|---|---|
29+
| **Inherited** | Value comes from the base asset; any change to the base propagates here | Normal weight, italic |
30+
| **Overridden** | Value was explicitly set on this derived asset, shadowing the base | Bold |
31+
| **No base** | Asset has no base (or this property has no base equivalent) | Normal weight |
32+
33+
**`ResetOverride()`** is a method on `IAssetNodePresenter` (the presenter layer — see `property-grid.md`), not on `IAssetNode` directly. Calling it restores the overridden value to its inherited state, and the graph then re-propagates the base value. The underlying graph node's `ResetOverrideRecursively()` handles the recursive reset; the presenter method is the entry point from the UI.
34+
35+
When a composite node (an object with children) is reset, all descendant nodes are also reset recursively.
36+
37+
> [!NOTE] Just adding a new asset type
38+
> If your asset has no base/derived relationship and you are not implementing archetypes or prefab composition, the override model is invisible to you. `IsInherited` will always be `false` and `HasBase` will always be `false`. You do not need to understand this layer to add a new asset type.
39+
40+
## `AssetPropertyGraph`
41+
42+
`AssetPropertyGraph` wraps a `NodeContainer` and adds override semantics on top:
43+
44+
- Created via `AssetQuantumRegistry.ConstructPropertyGraph(container, assetItem, logger)` where `container` is an `AssetPropertyGraphContainer` (not a raw `NodeContainer`) — this is obtained from the editor session; do not instantiate it manually
45+
- Tied to the editor session — created when an asset is opened, disposed when closed
46+
- Links each node to its counterpart in the base asset graph (if the asset has an archetype)
47+
- Propagates base values to all inherited nodes on load
48+
49+
You rarely interact with `AssetPropertyGraph` directly. The presenter layer reads from it via `IAssetNodePresenter.Asset` and `IAssetNodePresenter.HasBase`.
50+
51+
## `AssetPropertyGraphDefinition`
52+
53+
`AssetPropertyGraphDefinition` tells the graph which member values are **object references** (shared identities, loaded separately by `ContentManager`) vs **inline data** (copied into the asset).
54+
55+
Provide one only when your asset type holds references to other content objects. If you don't, the default definition treats all values as inline — which is correct for most new asset types.
56+
57+
```csharp
58+
// sources/engine/Stride.Assets/YourFeature/YourAssetPropertyGraphDefinition.cs
59+
using Stride.Core.Assets.Quantum;
60+
using Stride.Core.Quantum;
61+
62+
namespace Stride.Assets.YourFeature;
63+
64+
[AssetPropertyGraphDefinition(typeof(YourAsset))]
65+
public class YourAssetPropertyGraphDefinition : AssetPropertyGraphDefinition
66+
{
67+
// Return true when the value stored in 'member' is an object reference
68+
// (i.e. a handle to a separately-loaded content object, not an inline copy).
69+
public override bool IsMemberTargetObjectReference(IMemberNode member, object? value)
70+
{
71+
// Example: treat any Prefab member as an object reference
72+
if (value is Prefab)
73+
return true;
74+
75+
return base.IsMemberTargetObjectReference(member, value);
76+
}
77+
78+
// Return true when a collection item is an object reference.
79+
public override bool IsTargetItemObjectReference(IObjectNode collection, NodeIndex itemIndex, object? value)
80+
{
81+
// Example: treat items in PrefabCollection as object references
82+
if (collection.Descriptor.ElementType == typeof(Prefab))
83+
return true;
84+
85+
return base.IsTargetItemObjectReference(collection, itemIndex, value);
86+
}
87+
}
88+
```
89+
90+
The `[AssetPropertyGraphDefinition(typeof(YourAsset))]` attribute is discovered automatically when the assembly is registered. No manual registration is needed beyond `AssetQuantumRegistry.RegisterAssembly()` in `Module.cs`.
91+
92+
> [!NOTE] Just adding a new asset type
93+
> If all your asset's properties are plain data values (numbers, strings, lists of structs), you do not need an `AssetPropertyGraphDefinition`. Only provide one when your asset class has members that hold references to other content objects (Prefabs, Textures, Materials, etc.) that should remain as references rather than be embedded inline.
94+
95+
## `AssetQuantumRegistry`
96+
97+
| Method | When to call |
98+
|---|---|
99+
| `AssetQuantumRegistry.RegisterAssembly(assembly)` | From `Module.cs` — call once per assembly containing asset graph types |
100+
| `AssetQuantumRegistry.ConstructPropertyGraph(AssetPropertyGraphContainer, AssetItem, ILogger?)` | Called internally by the editor session; do not call manually |
101+
| `AssetQuantumRegistry.GetDefinition(assetType)` | Called internally; do not call manually |
102+
103+
`RegisterAssembly` scans the assembly for `AssetPropertyGraph` subclasses (decorated with `[AssetPropertyGraph(typeof(T))]`) and `AssetPropertyGraphDefinition` subclasses (decorated with `[AssetPropertyGraphDefinition(typeof(T))]`) and registers them.
104+
105+
In `Module.cs` for an assembly that contains both asset classes and graph types:
106+
```csharp
107+
[ModuleInitializer]
108+
public static void Initialize()
109+
{
110+
// AssemblyRegistry.Register is required for assemblies that contain Asset subclasses.
111+
// If the assembly only contains graph types (no Asset subclasses), omit this line.
112+
AssemblyRegistry.Register(typeof(Module).Assembly, AssemblyCommonCategories.Assets);
113+
AssetQuantumRegistry.RegisterAssembly(typeof(Module).Assembly);
114+
}
115+
```
116+
117+
## Assembly Placement
118+
119+
`Stride.Core.Assets.Quantum` — `sources/assets/Stride.Core.Assets.Quantum/`
120+
121+
Concrete `AssetPropertyGraphDefinition` subclasses for engine assets live alongside their asset classes (e.g. `sources/engine/Stride.Assets/`).

‎docs/quantum/graph-model.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Graph Model
2+
3+
## Role
4+
5+
`Stride.Core.Quantum` builds a live, typed graph over any .NET object hierarchy. Every property and collection item becomes a node. All reads and writes go through the graph, which ensures change notifications fire and undo/redo integrations receive every mutation. This is the foundation layer — it knows nothing about assets, editors, or UI.
6+
7+
## Node Types
8+
9+
| Type | What it represents | Key members |
10+
|---|---|---|
11+
| `IGraphNode` | Base interface for all nodes | `Guid`, `Type`, `Descriptor`, `IsReference`, `Retrieve()`, `Retrieve(NodeIndex)` |
12+
| `IObjectNode : IGraphNode` | An object with named members and/or collection items | `Members`, `Indices`, `IsEnumerable`, `this[string name]`, `Update(object?, NodeIndex)`, `Add()`, `Remove()` |
13+
| `IMemberNode : IGraphNode` | A single named property — child of an `IObjectNode` | `Name`, `Parent`, `Target`, `MemberDescriptor`, `Update(object?)` |
14+
15+
`IObjectNode` is the node for the object itself. `IMemberNode` is the node for each of its properties. Accessing `myObjectNode["MyProperty"]` returns the `IMemberNode` for `MyProperty`. Accessing `memberNode.Target` returns the `IObjectNode` for the referenced object when `IsReference` is true.
16+
17+
## `NodeContainer`
18+
19+
`NodeContainer` is the factory and owner of all nodes. Call `GetOrCreateNode(object)` to enter the graph for any object:
20+
21+
```csharp
22+
var container = new NodeContainer();
23+
IObjectNode rootNode = container.GetOrCreateNode(myAsset);
24+
```
25+
26+
Nodes are keyed by object identity (via `ConditionalWeakTable`). Calling `GetOrCreateNode` on the same object twice returns the same node. Call `GetNode` (non-creating variant) when you only want to look up an existing node.
27+
28+
**Reference vs. value nodes:** When a member holds a reference to another object, `IMemberNode.IsReference` is `true` and `IMemberNode.Target` returns the `IObjectNode` for that object (creating it if needed). When a member holds a value type or a primitive, `IsReference` is `false` and the value is stored inline.
29+
30+
## Mutations
31+
32+
Never set properties on the underlying object directly while the graph is active — change notifications will not fire. Always mutate through the node:
33+
34+
```csharp
35+
// Update a member value
36+
IMemberNode member = rootNode["MyProperty"];
37+
member.Update(newValue);
38+
39+
// Update a collection item
40+
// IMemberNode.Target is non-null when IsReference is true (i.e. the member holds a reference-type collection like List<T>)
41+
IMemberNode listMember = rootNode["MyList"];
42+
IObjectNode list = listMember.Target!; // valid when listMember.IsReference == true
43+
list.Update(newItem, new NodeIndex(0)); // replace item at index 0
44+
45+
// Add to a collection
46+
list.Add(newItem);
47+
list.Add(newItem, new NodeIndex(2)); // insert at index 2
48+
49+
// Remove from a collection
50+
list.Remove(existingItem, new NodeIndex(0));
51+
```
52+
53+
## Observing Changes
54+
55+
`GraphNodeChangeListener` subscribes to all nodes reachable from a root and surfaces four events:
56+
57+
```csharp
58+
var listener = new GraphNodeChangeListener(rootNode);
59+
60+
listener.ValueChanging += (sender, e) => { /* MemberNodeChangeEventArgs: e.Member, e.OldValue, e.NewValue */ };
61+
listener.ValueChanged += (sender, e) => { /* MemberNodeChangeEventArgs: e.Member, e.OldValue, e.NewValue */ };
62+
listener.ItemChanging += (sender, e) => { /* ItemChangeEventArgs: e.Collection, e.Index, e.OldValue, e.NewValue */ };
63+
listener.ItemChanged += (sender, e) => { /* ItemChangeEventArgs: e.Collection, e.Index, e.OldValue, e.NewValue */ };
64+
65+
listener.Initialize(); // walk the graph after subscribing
66+
67+
// Dispose to unsubscribe from all nodes
68+
listener.Dispose();
69+
```
70+
71+
`GraphNodeChangeListener` accepts any `IGraphNode` as its root — not just `IObjectNode`. You can start the listener from a member node if needed.
72+
73+
Call `Initialize()` after subscribing to events — it walks the graph and registers all reachable nodes. Always `Dispose()` the listener when done; failing to do so leaks node subscriptions.
74+
75+
## `NodeIndex`
76+
77+
`NodeIndex` is a `readonly struct`. It cannot be `null`; use `NodeIndex.Empty` as the "no index" sentinel.
78+
79+
`NodeIndex` addresses items in collection nodes:
80+
81+
```csharp
82+
NodeIndex.Empty // non-collection members (the "no index" sentinel)
83+
new NodeIndex(0) // list item at position 0
84+
new NodeIndex("key") // dictionary item with key "key"
85+
```
86+
87+
```csharp
88+
NodeIndex idx = new NodeIndex(2);
89+
idx.IsEmpty // false
90+
idx.IsInt // true
91+
idx.Int // 2
92+
```
93+
94+
## Assembly Placement
95+
96+
`Stride.Core.Quantum` — `sources/presentation/Stride.Core.Quantum/`

0 commit comments

Comments
 (0)