How to Add AI NPC Dialogue in Godot 4

Godot developers searching for AI NPCs mostly find tutorials that send text to a chatbot API through HTTPRequest and print the answer. That's a start. This guide goes further with the Neocortex Godot SDK: a character with a personality and a voice, who listens to the player, shows emotion on every line and triggers gameplay, wired up in GDScript.

What you need

• Godot 4.7 or later (version 0.2.0 of the SDK, in beta)
• A free Neocortex account

Step 1: design the character

In the Neocortex dashboard, create a character: a personality, a knowledge base with your world's lore, a voice, and Action nodes for what it can do, such as GIVE_ITEM. Talk to it in the browser until it sounds right; in-editor testing is free on every plan.

Step 2: add the addon

Download the latest neocortex-godot-sdk zip from the SDK's GitHub releases and unzip it into your project, which adds addons/neocortex-godot-sdk. Then open Project > Project Settings > Plugins and enable Neocortex.

For voice, also turn on Project Settings > Audio > Driver > Enable Input. Godot doesn't record from the microphone without it.

Step 3: add your API key

The Neocortex dock appears next to the Inspector. Paste your API key and press Save. It's stored in addons/neocortex-godot-sdk/neocortex_settings.tres, so add that file to .gitignore, and remember an exported game carries the key (more on that below).

Step 4: add the character

The fastest way is Project > Tools > Neocortex > Complete Voice Chat (or Complete Text Chat). It builds a chat UI with a NeocortexSmartAgent, an audio player, a microphone and a chat panel. Pick your character in the agent's Character Id dropdown, or select the node and press Use next to the character in the dock.

Run the scene and say hello. The character answers in its own voice, and the chat panel shows both sides of the conversation.

Step 5: connect the character to your game

The NeocortexSmartAgent emits a signal for each part of a reply, and register_action connects actions to your code:

extends Node3D

@onready var agent: NeocortexSmartAgent = $Blacksmith/NeocortexSmartAgent
@onready var anim: AnimationPlayer = $Blacksmith/AnimationPlayer
@onready var subtitle: Label3D = $Blacksmith/Subtitle

func _ready() -> void:
	agent.chat_line_started.connect(func(line: NeocortexChatLine): subtitle.text = line.text)
	agent.emotion_changed.connect(func(emotion): anim.play(NeocortexEnums.emotion_to_string(emotion)))
	agent.request_failed.connect(func(error: String): push_warning(error))
	agent.register_action("GIVE_ITEM", _give_item)  # authored on the character's Action node

func ask(player_line: String) -> void:
	agent.text_to_audio(player_line)

func _give_item(action: NeocortexChatAction):
	if player_has_paid():  # your own game code
		inventory.give(action.target_id)
	return get_tree().create_timer(0.5).timeout  # the next action waits for this signal

player_has_paid and inventory stand in for your own systems: the character asks, your game decides. Other settings on the agent:

• Chat Lines Mode: PER_LINE_AUDIO speaks each line as it comes (the default), SINGLE_AUDIO speaks the reply as one clip, TEXT shows lines without voice, OFF gives you the raw reply.
• Action Trigger: run actions when the reply arrives, when speech starts, or after the line is spoken.
• Audio Player: an AudioStreamPlayer, AudioStreamPlayer2D or AudioStreamPlayer3D, so a 3D character's voice comes from where it stands.

Voice input and lip sync

• Microphone: a NeocortexAudioReceiver next to or under the agent records the player, with voice detection by default (Amplitude Threshold 0.1, Max Wait Time one second). For push-to-talk, call set_push_to_talk(true) and start_microphone() / stop_microphone() from your input. transcription_received gives you what the player said.
• Lip sync: add a NeocortexFaceAnimator and point it at the character's meshes. It moves the mouth from the spoken text on ARKit-named blend shapes.
• Android: the receiver asks for microphone permission on start. On iOS, set the permission text in the export preset.

Let the character see the scene

Add NeocortexInteractable nodes to things the character should know about: the anvil, the door, the sword on the wall. Each gets an id and optional properties like state: closed. Set the agent's Body to the character's 3D node, and every message includes the nearest interactables (10 by default, within an optional Perception Radius), so actions can target them by id. See how to make AI NPCs act on what they say for the design side.

The samples

The addon includes a sample launcher with seven scenes: text chat, audio chat, actions, interactables, group chat, usage gating and a quiz show. Group chat puts up to six characters in one conversation (Pro and Team plans), and the quiz host needs the Team plan.

Common problems

• The microphone records nothing. Turn on Audio > Driver > Enable Input in Project Settings and restart the editor.
• 401 errors. The key isn't saved. Open the Neocortex dock and press Save.
• Your key ships in the export. Any key in a build can be extracted. Create a separate API key for each release, set per-player and per-character usage limits on it in the dashboard (enforced on our servers), and deactivate it if it leaks. The usage gating sample shows how to check limits in game.
• A request fails mid-game. The request_error signal tells you why, so you can fall back to authored lines instead of going silent.

Without an SDK

If you'd rather call a model yourself, Godot's HTTPRequest node can talk to any HTTP API. Our guide to running a local LLM in Godot 4 shows the code, and what you'd still need to build for voice, emotions and actions.

Next steps

For the design side, read how to give NPCs unique personalities and how to give AI NPCs memory of the player. Every tutorial is in the guide to building AI NPCs, and the Godot integration page has the requirements in one place.

Frequently Asked Questions