<div align="center">

Ceres

Powerful visual scripting toolkit for Unity.

</div>

Table of Contents

• Install
• Highlights
• Platforms
• Core Concepts
• Quick Start Guide
• Flow Visual Scripting
• ExecutableReflection
• Debugging
• Advanced Features
• Type Preservation
• Code Generation
• Performance
• Documentation
• Implementation
• Articles
• License

📦 Install

Install from UPM

Add following dependencies to manifest.json.

"dependencies": {
    "com.kurisu.chris": "https://github.com/AkiKurisu/Chris.git",
    "com.cysharp.unitask":"https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask"
}

Use git URL to download package by Unity Package Manager https://github.com/AkiKurisu/Ceres.git.

Install from Disk

Clone repo to your project Packages folder.

Use Tools/Ceres/Installer to install dependencies.

✨ Highlights

Powerful visual scripting toolkit that brings the best of both worlds - visual programming and C# code integration.

🚀 Core Features

• 🎯 Generic & Delegate Support - Full support for C# generics and delegates in visual scripting
• 🔗 Graph & C# Integration - Seamless integration between visual graphs and traditional C# code
• 🐛 Editor Debugging - Built-in debugging tools with breakpoints and step-by-step execution
• ⚡ Easy Implementation - Simple setup with minimal configuration required
• 🏃‍♂️ Optimized Runtime Performance - High-performance execution with IL2CPP optimizations
• 📱 IL2CPP Compatible - Fully compatible with IL2CPP builds and recommended for production

🎨 Visual Excellence

• Intuitive Node-Based Editor - Clean, modern interface for creating visual scripts
• Real-time Preview - See your logic flow as you build it
• Professional Workflow - Industry-standard tools and practices

Platforms

Unity 2022.3 LTS or later, compatible with Unity 6.

Core Concepts

Understanding the fundamental concepts of Ceres will help you get started quickly.

Node

CeresNode is the logic and data container that forms the building blocks of your visual scripts.

Port

CeresPort enables you to get data from other nodes. Ceres uses CeresPort<T> to get generic data from other nodes and NodePort to get a NodeReference which can convert to CeresNode at runtime.

Graph

CeresGraph contains everything and acts as a virtual machine that executes your visual scripts.

Data

Ceres serializes node, port and graph to additional data structures: CeresNodeData, CeresPortData and CeresGraphData which contain the actual serialized data and metadata.

Variable

SharedVariable is a data container that can be shared between nodes and graphs. Compared with CeresPort, SharedVariable can be edited outside of the graph and doesn't contain any connection data since it doesn't need to know where the data comes from.

Execution Path

Nodes can be executed in two ways:

Forward: Graph can execute nodes one by one.

Dependency: Graph should execute node's dependencies before executing the node.

As shown in the figure, to execute Log String, we need to first get the variable message. However, since Get message has no outer connection, it has not been executed before. So the graph needs to consider Get message as a dependency and execute it before executing Log String.

Quick Start Guide

Here's a step-by-step example of using Flow to output a "Hello World" message:

1. Create a Flow Object

Create a new C# script MyFlowObject.cs and make it inherit from FlowGraphObject:

using Ceres.Graph.Flow;
using Ceres.Graph.Flow.Annotations;

public class MyFlowObject: FlowGraphObject
{
    [ImplementableEvent]
    private void Start()
    {

    }
}

2. Setup in Scene

Create a new GameObject in the scene and attach the MyFlowObject component to it.

3. Open Flow Graph Editor

Click Open Flow Graph in the Inspector panel to open the Flow Graph Editor.

4. Create Start Event

Right-click the graph and click Create Node/Select Events/Implement Start.

5. Add Log String Node

Click Create Node and search Log String, then connect the white port (exec) to the Start node's output (exec). Fill in "Hello World!" in the In String field of the Log String node.

6. Save and Test

Click the save button in the left upper corner, then play the game. You will see "Hello World!" in the console.

Flow Visual Scripting

Flow thinks of game logic as an execution chain to let game objects do things in order according to your design. Flow visualizes these executions as nodes so that you can connect them to implement gameplay and functionality.

Events

Each execution chain starts from an event which can contain input data.

You can define events in Flow Graph or C# scripts.

Functions

Functions are components that implement game functions. They complete specified functions by calling the engine or your custom API. Through wiring, you can combine these method calls to complete your creativity.

Container

For any FlowGraph instance, there needs to be a specified Container at runtime. It can be your custom MonoBehaviour (need to implement interface) or inherit from a series of parent classes provided by Ceres.

ExecutableReflection

ExecutableReflection allows you to expose C# methods to Flow graphs, making them available as nodes. There are three main ways to define executable functions:

1. Instance Functions

For instance methods, add ExecutableFunctionAttribute directly to your method:

using Ceres.Graph.Flow.Annotations;
using UnityEngine;

public class MyComponent : MonoBehaviour
{
    [ExecutableFunction]
    public void DoSomething(int arg1, float arg2)
    {
        Debug.Log($"Doing something with {arg1} and {arg2}");
    }
    
    [ExecutableFunction]
    public string GetPlayerName()
    {
        return "Player";
    }
}

2. Static Functions

For static methods, create a partial class that inherits from ExecutableFunctionLibrary and add ExecutableFunctionAttribute:

using Ceres.Graph.Flow;
using Ceres.Graph.Flow.Annotations;
using Ceres.Annotations;
using UnityEngine;

public partial class GameplayFunctionLibrary : ExecutableFunctionLibrary
{
    [ExecutableFunction(IsScriptMethod = true, IsSelfTarget = true)]
    [CeresLabel("Get GameObject Name")]
    public static string Flow_GetGameObjectName(GameObject gameObject)
    {
        return gameObject.name;
    }
    
    [ExecutableFunction(ExecuteInDependency = true)]
    public static float Flow_CalculateDistance(Vector3 pointA, Vector3 pointB)
    {
        return Vector3.Distance(pointA, pointB);
    }
    
    [ExecutableFunction]
    public static Component Flow_FindComponent(
        GameObject target,
        [ResolveReturn] SerializedType<Component> componentType)
    {
        return target.GetComponent(componentType);
    }
}

Important: You must add the partial modifier to let the source generator work. The source generator registers static function pointers to enhance runtime performance instead of using MethodInfo.

3. Always Included Assemblies

Flow automatically includes assemblies matched by Always Included Assembly Wildcards in Project Settings/Ceres/Flow Settings. Methods in these assemblies can be invoked without adding attributes:

public class UtilityClass
{
    public void AutomaticallyIncludedMethod(string message)
    {
        Debug.Log($"Auto-included: {message}");
    }
}

Best Practices and Conventions

1. Unique Method Names: Methods with the same name and parameter count in the same class hierarchy can only have one ExecutableFunctionAttribute.

2. Method Overloads: For methods with the same name but different parameters, use CeresLabelAttribute to distinguish them:

[ExecutableFunction, CeresLabel("Log Message")]
public static void Flow_Log(string message)
{
    Debug.Log(message);
}

[ExecutableFunction, CeresLabel("Log Message with Color")]
public static void Flow_Log(string message, Color color)
{
    Debug.Log($"<color=#{ColorUtility.ToHtmlStringRGB(color)}>{message}</color>");
}

3. Parameter Limits: Keep input parameters ≤ 6 for optimal editor performance. Methods with more parameters use Uber nodes with greater runtime overhead.

4. Generic Methods: Generic methods are not supported with ExecutableFunctionAttribute. Use Generic Nodes instead.

Debugging

Ceres provides powerful debugging capabilities to help you troubleshoot your visual scripts.

Enable Debug Mode

To enable and disable debug mode, click the debug button in the upper right corner. Then, you can click Next Frame to execute t