Unity 2020.3 LTS+ · C# SDK

NPC Map Learning System Guide

The complete guide to giving your Unity NPCs real-time environmental awareness, spatial memory, and dynamic dialogue.

1. Overview

In most games, NPCs (Non-Player Characters) operate on pre-written, rigid dialogue lines. No matter what the player asks, the character repeats identical sentences; it has zero awareness of nearby doors, traps, or enemies.

NPC Map Learning System eliminates this limitation. The component scans the game world in real time, cataloging doors, traps, enemies, and chests. This spatial intelligence is conveyed to the player in natural language through an optional local AI (LLM) layer. When AI is not configured, NPCs still learn the map; responses are generated using pre-authored dialogue lines defined directly in the Inspector.

The system is delivered as two lightweight DLL files. Complete setup takes approximately five minutes.

1.1 No-Code Workflow

This system works without writing a single line of C# code. MapElement, NPCMapLearner, NPCPasserbyChat, and NPCRole components are all configured directly through the Unity Inspector. C# scripting is strictly optional for custom gameplay logic, event listening, or adding dynamic objects at runtime.

1.2 Key Features

  • 18 Pre-built Object Types + Custom Categories: Recognizes doors, traps, enemies, chests, keys, puzzles, and more out of the box. Custom types can be added directly in the Unity Inspector without writing any code.
  • 3 Learning Modes: Range mode (scans immediate surroundings), FullMap mode (complete map awareness), and Hybrid mode (blends both).
  • NPC Role Definitions: Guide NPCs share full navigation info, merchants report safe pathways only, and guards report active hazards.
  • Player Mistake Tracker: Counts player mistakes such as stepping on spikes, falling, and deaths; NPCs incorporate these into their greetings.
  • NPCPasserbyChat: NPCs automatically initiate contextual conversations with each other when crossing paths.
  • One-Click Auto-Tagging: The Auto Add tool in the Tools menu assigns MapElement components to all valid scene objects instantly.

2. Requirements

Mandatory

Unity 2020.3 LTS or newer is required. The SDK targets this version and above. There are no additional dependencies; simply importing the DLL files into your project is sufficient.

Optional

LLMUnity Package: Required for NPCs to communicate via local offline AI models (such as Mistral, LLaMA, or Phi).

💡 Note: When AI is not configured, the system remains fully operational. NPCs map the environment and reply using Inspector-defined dialogue lines. NPCPasserbyChat also functions seamlessly without an LLM.

3. Installation

3.1 Delivered Files

Package Layout Directory Structure 
Unity-Package/
└── Plugins/
    ├── NPCMapLearningSystem.dll          (Core SDK)
    └── NPCMapLearningSystemEditor.dll    (Unity Editor SDK)

3.2 Installation Steps

1

Copy the DLL Files

Copy both DLL files into your Unity project's Assets/Plugins/ directory. Create the folder if it does not exist.

2

Verify the Assembly

Once copied, Unity will recompile. Verify that the Tools > NPC Map System menu appears, DLL classes are listed under DLL Info, and MapElement is available when clicking Add Component on any GameObject.

3

(Optional) C# Namespace

If you plan to write custom C# scripts, add using NPCMapLearning; at the top of your script file.

⚠️ Important: Unity automatically discovers and loads assembly files located under Assets/Plugins/. If placed elsewhere, components may trigger 'Missing Script' errors and fail to load.

3.3 Post-Installation Project Structure

Unity Project Hierarchy Assets/Plugins 
YourProjectFolder/
└── Assets/
    └── Plugins/
        ├── NPCMapLearningSystem.dll
        └── NPCMapLearningSystemEditor.dll

4. License Activation

The SDK is license-protected. Editor tools require an active license before they can be used.

4.1 Activation Procedure

1

Sign In to Your Dashboard

Open your Web Dashboard URL in your browser and register or sign in with your email address.

2

Copy Your Auth Token

Navigate to the Unity License System section in your dashboard and copy your Auth Token.

3

Activate in Unity Editor

In Unity, open Tools > NPC Map System > Activate License. Paste your token (or click Paste from Clipboard) and click ACTIVATE LICENSE ('LICENSE ACTIVE' will appear).

4

Verify Status

Open Tools > NPC Map System > Check License Status. It should confirm 'License Active'.

4.2 License Tiers

Tier Device Count Auto MapElement LLM Support
FREE — No No
PRO 1 device Yes Yes
ENTERPRISE Custom Yes Yes

4.3 License Transfer

To move your license to another machine, deactivate it on the current machine first via Tools > NPC Map System > Deactivate License > Confirm. This releases the license slot immediately, allowing instant activation on your new computer.

5. Editor Tools

After installation, the following tools become accessible under Tools > NPC Map System:

🔑 Activate License

Activates the license for this computer. Does not require an active license.

🛡️ Check License Status

Checks whether the license is currently active. Does not require an active license.

⏏️ Deactivate License

Removes the license from this machine and releases the slot. Does not require an active license.

⚡ Auto Add MapElements

Scans all scene GameObjects and assigns MapElement components based on keyword matching. Requires license.

🧪 Test MapElement DLL

Instantiates a test GameObject into the scene to verify DLL assembly loading. Requires license.

🧠 Create MapKnowledgeManager

Adds the central knowledge repository to your scene. Required once per scene. Requires license.

📋 List All MapElements

Prints all scene MapElement components and their categories to the Unity Console. Requires license.

5.1 Automatic MapElement Keyword Mapping

The Auto Add tool parses each GameObject's name and assigns the corresponding type (case-insensitive). Objects that already possess a MapElement component are skipped:

  • "door" or "kapı" → Door
  • "chest" or "sandık" → Item
  • "enemy" or "düşman" → Enemy
  • "trap" or "tuzak" → Trap
  • "button", "lever" or "switch" → Button
  • "tree", "ağaç" or "orman" → Generic
  • "npc" or "character" → Generic
💡 Naming Best Practice: Adhere to clear naming conventions such as Door_Main_Entrance, Enemy_Goblin_01, or Trap_Spikes_Floor. Generic names like GameObject (1) or Cube are not indexed.