NPC MEMORY SYSTEMDOCUMENTATION
← Asset
ESEN
Unity 2021.3+
OFFICIAL GUIDE

Give your NPCs memory, relationships and personality.

A modular social brain for Unity NPCs: decaying memories, multi-axis relationships, factions, gossip, complete saving and plug-and-play components with no code required.

Start installationBrowse the APIBuy on Unity Asset Store ↗
Engine
Unity 2021.3 LTS+
Rendering
Built-in
Dependencies
None
01 A living social system: every action creates memories and changes how each NPC relates to the player.
01

GETTING STARTED

Installation & demo scene

1

Import the package

Import NPC Memory & Relationship System and wait for Unity to compile.

2

Open Setup Wizard

Go to Tools → NPC Memory System → Setup Wizard and select Create Complete Demo Scene.

3

Press Play

Move with WASD, approach an NPC and press E. Try actions and watch dialogue and relationships evolve.

WASDMove player
EInteract with NPC
MouseSelect actions
02 The wizard creates ground, lighting, camera, player, four NPCs, dialogue, waypoints and all required ScriptableObjects.
02

ARCHITECTURE

Core components

Add the core components to any GameObject to turn it into an NPC with a social brain.

NPC Identity

Add Component → NPC Memory System → NPC Identity

NPC ID
Stable identifier used by memories, relationships and saving.
Display Name
Name shown in UI and dialogue.

NPC Brain

Add Component → NPC Memory System → NPC Brain

Relationship Config
Axes and relationship-state thresholds.
Memory Decay Config
Controls how quickly memories fade.
Impact Database
Maps memory tags to relationship effects.

NPC Registry

Automatic singleton

Global registry
Find registered NPCs by ID from any script.
Editor-safe
Prevents singleton recreation while leaving Play Mode.

NPC Memory API

AIVA.NPCMemorySystem.NPCMemoryAPI

Convenience API
Add memories and query NPC relationships without direct references.
No dependencies
Available from any script.
03

MEMORY

Memory system

NPCs store tagged memories with a source, strength and timestamp. Important recent memories carry more weight; decay removes memories once they become insignificant.

MemoryStore

AddMemory()
Add a tagged memory with source and strength.
GetMemories()
Return active memories.
HasMemory(tag)
Check for a specific tag.

Memory Decay Config

Decay Rate
Strength lost per second.
Min Strength
Removal threshold.

Memory Impact Database

Impact rules
Map tags to relationship-axis changes.
Example
PLAYER_HELPED_ME → Trust +15, Friendship +10.
// Add a memory to an NPC
NPCMemoryAPI.AddMemory("Guard_A", "PLAYER_HELPED_ME", "Player");

// Check whether the NPC remembers it
bool remembers = NPCMemoryAPI.GetNPC("Guard_A")
    .MemoryStore.HasMemory("PLAYER_HELPED_ME");
PLAYER_HELPED_MERaises Trust and Friendship.
PLAYER_THREATENED_MERaises Fear and lowers Trust.
PLAYER_STOLE_FROM_MELowers Trust and Friendship.
PLAYER_GIFTED_MERaises Friendship.
PLAYER_ATTACKED_MERaises Fear and lowers other axes.
PLAYER_SAVED_MEStrong Trust and Respect increase.
04

RELATIONSHIPS

Multi-axis relationships

Friendship, Trust, Respect, Fear and Romance evolve independently. Their combination determines the overall state: Hostile, Unfriendly, Neutral, Friendly or Trusted.

AXISRANGEPURPOSE
Friendship-100 to 100General affection.
Trust-100 to 100Willingness to trade or share information.
Respect-100 to 100Admiration and compliance.
Fear0 to 100Can make an NPC flee or submit.
Romance0 to 100Optional romantic affinity.
string state = NPCMemoryAPI.GetRelationshipState("Guard_A", "Player");
float trust = NPCMemoryAPI.GetRelationshipValue("Guard_A", "Player", "Trust");
REL Friendship, trust, fear and gossip evolve independently across the cast.
05

FACTIONS

Factions & reputation

Assign NPCs to factions and propagate the consequences of player actions across entire groups.

Faction Database

  • Define faction ID, name and description.
  • Set default inter-faction standings.
  • Assign factions through NPCIdentity.

Faction Manager

  • Tracks player reputation with every faction.
  • Propagates changes across group members.
  • Raises OnFactionReputationChanged.
float rep = FactionManager.Instance.GetReputation("Player", "Guards");
FactionManager.Instance.ModifyReputation("Player", "Guards", -20f);
06

SOCIAL

Gossip & rumors

NPCs share memories as rumors. Range, interval, maximum hops and distortion are configurable, allowing information to spread naturally through a social network.

1

Witness

NPC A observes an event and creates a memory.

2

Share

NPC A meets NPC B and passes the rumor.

3

React

NPC B receives it and changes their relationship.

07

INTERACTION

NPC Reactor

A plug-and-play bridge between relationship state and gameplay. Configure dialogue for every state and player actions directly in the Inspector.

03 Color-coded dialogue and configurable actions in a purpose-built Inspector.

State dialogue

Unique text for Hostile, Unfriendly, Neutral, Friendly and Trusted states.

Player actions

Each action has a label, memory tag and cooldown. Trigger quests, prices, doors and game logic through UnityEvents.

08

VISUAL

Visual integration

NPC World UI

Floating name, relationship bar and state label.

NPC State Feedback

Material tint, particle burst and scale punch on state changes.

NPC State Audio & Animation

Enter/loop audio and Animator triggers or booleans per state.

NPC Memory Trigger

Create memories from colliders, code or Inspector events.

04 World-space identity and relationship feedback above NPCs.
09

MOVEMENT

Patrol & movement

Waypoint movement with Loop, PingPong and Random modes. Configure speed, turn rate, arrival distance and wait time; patrol can pause automatically during interaction.

InspectorAdd Component → NPC Memory System → NPC Patrol
10

PERSISTENCE

Save system

Save and restore all NPC memories, relationship axes, faction reputation and current states.

Built-in file saving

NPCSaveSystem.Instance.SaveToFile();
NPCSaveSystem.Instance.LoadFromFile();

Uses JSON in Application.persistentDataPath.

Custom provider

Implement ISaveProvider for cloud saves, encryption or your existing save framework.

11

DEVELOPMENT

Events & API

Use global static events for decoupled systems and per-NPC UnityEvents for Inspector-driven integration.

AddMemory(npcId, tag, source)Add a memory to an NPC.GetRelationshipState(npcId, targetId)Return Hostile, Unfriendly, Neutral, Friendly or Trusted.GetRelationshipValue(npcId, targetId, axis)Return one relationship-axis value.GetNPC(npcId)Return the registered NPCBrain.
NPCEvents.OnMemoryAdded += args => Debug.Log(args.Memory.Tag);
NPCEvents.OnRelationshipStateChanged += args => Debug.Log(args.NewState);
NPCEvents.OnRumorReceived += args => Debug.Log(args.ReceiverId);
NPCEvents.OnFactionReputationChanged += args => Debug.Log(args.NewValue);
12

EDITOR

Editor tools

Inspect and author the system visually with dedicated windows and custom Inspectors.

05 Quick access to every authoring and debugging tool.
DB

Memory Debugger

Live view of memory tags, sources, strength and remaining lifetime.

GR

Relationship Graph

Node visualization of NPC connections, axes and states.

WZ

Setup Wizard

Create the demo, default ScriptableObjects and wiring in one click.

13

ARCHITECTURE

Project structure

Runtime/Core/NPCBrain, NPCIdentity, NPCRegistry, NPCMemoryAPI
Runtime/Memory/MemoryStore, MemoryDecayConfig, MemoryImpactDatabase
Runtime/Relationships/RelationshipData, RelationshipConfig, RelationshipManager
Runtime/Factions/Faction, FactionDatabase, FactionManager
Runtime/Rumors/GossipConfig, GossipSystem
Runtime/SaveSystem/NPCSaveSystem, ISaveProvider
Runtime/Integration/Reactor, World UI, Patrol, Feedback, Audio and Triggers
Editor/Custom Inspectors, debugger, graph and wizard
Demo/Complete scene with four NPCs
14

SUPPORT

Troubleshooting

“No script asset for MemoryImpactDatabase”

Ensure MemoryImpactDatabase.cs is a standalone file whose name matches the ScriptableObject class.

NPCs do not appear

Use the Setup Wizard. It creates editable scene objects before Play Mode.

The camera does not follow the player

Assign the DemoCamera target or tag the player GameObject as “Player”.

Dialogue does not react to relationships

Verify NPCBrain configs, Reactor dialogue for each state and matching rules in MemoryImpactDatabase.

Particles or tint do not activate

NPCStateFeedback needs a Renderer with an assignable material.