# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.parsue.io/aceland-unity-packages/packages/node-framework.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.