Synapse

A decision-making framework where actions are evaluated by considerations

👀 Summary

NsSynapse is a Utility AI for Unreal Engine. An actor gets a brain component with a list of actions. Each action has considerations, and each consideration gives a score from 0 to 1. The brain multiplies the scores, picks the action with the highest result, and can run it. You make actions and considerations as Blueprint or C++ child classes.

NsSynapse does not find paths, sense the world, or run animations. The brain does not tick, so your game code decides when the agent thinks. It does not replace a Behavior Tree for long, ordered tasks.

📦 Features

• Brain component: UNsSynapseBrainComponent scores its action list and keeps the best action.
• Actions: Child classes of UNsSynapseAction hold considerations and run ExecuteAction.
• Considerations: Child classes of UNsSynapseConsideration return a raw score from CalculateScore.
• Response curve: Each consideration maps its raw score through Consideration Curve.
• Score compensation: A make-up factor stops one low score from removing an action too early.
• Busy flag: ThinkAndReact does nothing while the brain is busy.
• Blueprint support: All main functions are Blueprint callable, and both events are Blueprint overridable.

⚙️ Requirements

Unreal Engine 5.7+

The module runs on Win64, Mac, and Linux.

🛠️ Installation

1. Clone or download this repository.
2. Copy the NsSynapse folder into the Plugins folder of your project.
3. For C++, add "NsSynapse" to the dependencies of your game module in its Build.cs.
4. Generate the project files and enable the plugin.

🚀 Getting Started

In Blueprint:

1. Make a child Blueprint of NsSynapseConsideration. Override Calculate Score and return a value from 0 to 1.
2. Make a child Blueprint of NsSynapseAction. Override Execute Action. Add the consideration to Considerations.
3. Add the Ns Synapse Brain component to your AI actor.
4. Add the action class to Possible Actions on the component.
5. Call Think And React on the component when the agent must decide, for example from a timer.

In C++:

#include "Classes/NsSynapseBrainComponent.h"
#include "Classes/NsSynapseConsideration.h"

UCLASS()
class ULowHealthConsideration : public UNsSynapseConsideration
{
    GENERATED_BODY()

public:
    virtual float CalculateScore_Implementation(AActor* const InOwner) const override
    {
        const AMyBot* const Bot = Cast<AMyBot>(InOwner);
        return Bot != nullptr ? 1.f - Bot->GetHealthPercent() : 0.f;
    }
};

// In AMyBot: Brain = CreateDefaultSubobject<UNsSynapseBrainComponent>(TEXT("Brain"));
Brain->ThinkAndReact();

🧮 How a Score Is Made

🔧 API

• UNsSynapseBrainComponent – The actor component that scores actions and runs the best one.
• Think() – Scores Possible Actions, stores the best action, and returns it.
• ThinkAndReact() – Calls Think, then calls ExecuteAction on the best action. Does nothing while busy.
• ChooseAction(Actions) – Scores the given action classes and stores the best one.
• ScoreAction(Action) – Returns the combined score of one action.
• GetBestAction() – Returns the action from the last choice.
• SetBusy(bool) / IsBusy() – Set and read the busy flag.
• UNsSynapseAction::ExecuteAction(Actor) – BlueprintNativeEvent. Put the behavior here.
• UNsSynapseConsideration::CalculateScore(Actor) – BlueprintNativeEvent. Return the raw score.

🚧 Limits

• The brain uses the class default object of each action and consideration. All agents share these objects, so they must not hold per-agent data.
• An action with a score of 0 is never chosen. If all actions score 0, the best action is null.
• The plugin does not replicate.
• The plugin has no debug draw, console commands, or log category.

📚 Documentation

Contact

E-mail LinkedIn GitHub Bluesky