> For the complete documentation index, see [llms.txt](https://docs.parsue.io/aceland-unity-packages/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parsue.io/aceland-unity-packages/packages/node-framework.md).

# Node Framework

### In One Line

Node Forest: Because trees shouldn't limit your imagination!

### Overview

The Node Framework is a powerful, type-safe system for creating and managing hierarchical relationships in your Unity projects. It provides an intuitive way to build parent-child relationships between objects while maintaining strong typing and safe runtime operations.

### Package Info

<table data-header-hidden><thead><tr><th width="174"></th><th></th></tr></thead><tbody><tr><td>display name</td><td>AceLand Node Framework</td></tr><tr><td>package name</td><td><pre><code>com.aceland.nodeframework
</code></pre></td></tr><tr><td>latest version</td><td>2.2.1</td></tr><tr><td>namespace</td><td><pre><code>AceLand.NodeFramework
AceLand.NodeFramework.Mono
</code></pre></td></tr><tr><td>git repository</td><td><a href="https://github.com/parsue/com.aceland.nodeframework.git">https://github.com/parsue/com.aceland.nodeframework.git</a></td></tr><tr><td>dependencies</td><td><pre><code>com.aceland.disposable: 1.0.0
com.aceland.optional: 1.0.0
com.aceland.projectsetting: 1.0.0
com.aceland.taskutils: 1.2.1
</code></pre></td></tr></tbody></table>

### Key Features

* **Type-Safe Hierarchy**: Build and manage parent-child relationships with compile-time type checking
* **Fluent Builder Pattern**: Easy-to-read node construction using builder syntax
* **Automatic Memory Management**: Built-in disposal system for clean resource management
* **Rich Navigation APIs**: Extensive methods for traversing and manipulating node hierarchies
* **Async Support**: Built-in async operations for safe node access
* **Flexible Node Identification**: Automatic GUID generation with optional custom IDs

***

### Why Use It

Traditional node systems often constrain you to a single-root tree structure. Our Node Framework breaks free from these limitations, offering a "Node Forest" approach that perfectly aligns with Unity's GameObject-Component architecture.

#### Global Accessibility

The framework automatically registers all nodes upon creation, enabling powerful node access:

* Access any node globally using ID and type
* Navigate nodes through relationships within the same tree
* No manual registration or reference management needed

While you have the freedom to structure nodes as needed, we recommend maintaining logical tree structures for better organization and maintainability. For GameObject-specific implementation, see the "[Mono Node Framework](/aceland-unity-packages/packages/node-framework/mono-node.md)" page.

#### Key Benefits:

* **Flexible Structure**: Build nodes without root constraints
* **Freedom to Design**: Create individual node trees or complex node networks
* **Unity-Friendly**: Seamlessly integrates with GameObject hierarchy
* **Auto-Registration**: Nodes self-register on creation for immediate availability
* **Extensible Design**: Easy to extend and customize for your specific needs

***

### Creating Nodes

```csharp
// Define your node type
public class MyNode : Node<MyNode> { }

// Create a node using the builder pattern
INode<MyNode> yourNode = Node<MyNode>.Builder()
    .WithId("customId")  // Optional: Provide custom ID
    .Build();
```

### Managing Relationships

```csharp
// Create parent and child nodes
INode<MyNode> parent = Node<MyNode>.Builder().Build();
INode<MyNode> child = Node<MyNode>.Builder()
    .WithParent(parent)  // Set parent during construction
    .Build();

// Or manage relationships after creation
yourNode.SetParent(parent);
yourNode.AddChild(child);
```

### Navigating the Hierarchy

```csharp
// Access relationships
INode parentNode = yourNode.Parent();
INode rootNode = yourNode.Root();
IEnumerable<INode> children = yourNode.Children();

// Type-safe navigation
MyNode typedParent = yourNode.Parent<MyNode>();
IEnumerable<MyNode> typedChildren = yourNode.Children<MyNode>();

// Find specific children
MyNode firstChild = yourNode.Child<MyNode>();
MyNode namedChild = yourNode.Child<MyNode>("specificId");
IEnumerable<MyNode> allChildren = yourNode.ChildrenInAllLevel<MyNode>();
```

### Node Access

```csharp
// Safely wait for node availability
MyNode node = await Node<MyNode>.GetAsync();
MyNode specificNode = await Node<MyNode>.GetAsync("specificId");

// Get an available node instant
MyNode node = Node<MyNode>.Get();
MyNode specificNode = Node<MyNode>.Get("specificId");
```

***

### Important Notes

* Nodes are automatically registered in a type-based registry
* Each node has a unique ID (auto-generated if not specified)
* Nodes implement IDisposable for proper cleanup
* Async operations have configurable timeouts