Troubleshooting
The node is not in the Create New Node dialog
The plugin is not enabled. Project → Project Settings → Plugins → NPC TalkKit. If it is enabled and the node is still missing, the folder is in the wrong place: the path must be exactly res://addons/npc_talkkit/plugin.cfg.
After moving addon files, close and reopen the project. Godot caches global class names and does not always notice.
play() returns false and nothing happens
It returns false — never throws — for three reasons, and each logs a warning telling you which:
| Warning | Cause |
|---|---|
conversation '…' was not found | the name does not match any conversation_id on the node or in the library |
refused invalid conversation | validation failed; the warning carries the report |
is already running a conversation | a conversation is being read — this is deliberate, so a second interact press cannot restart it |
If you are answering a blocking event, play() is allowed — that case is not refused. If it still returns false there, read the validation warning: a branch that fails validation is refused, and the original conversation keeps running.
The speech bubble does not move
A renderer must implement get_box_control(). Anchoring and transitions both act on the control it returns, so a renderer of your own without it looks correct and does nothing.
If you are using the built-in box, check whether a placement is assigned with when_offscreen set to HIDE and the target off screen.
The 3D bubble is in the wrong place, or jumps across the screen
| Symptom | Cause |
|---|---|
| It sits at the character's feet | follow_offset_3d is zero. That is the world-space head offset, in metres — try Vector3(0, 1.9, 0). |
| It drifts off the head as you walk towards them | You used follow_offset (screen space) instead of follow_offset_3d (world space). |
| It flips to the opposite side of the screen | You are on a version before 4.0's behind-camera guard, or your target is behind the camera and when_offscreen is FREE. |
| Nothing shows at all | There is no current Camera3D, or the target is past max_distance. |
My theme is ignored
Assign the theme to the template's theme, not to a renderer scene. When theme is set, the style stops overriding fonts, sizes and colours so your theme wins. Layout settings still apply, because a Theme does not cover them.
If you assigned a theme to a node inside a renderer of your own and it is still ignored, check for theme_override_* on that node — overrides beat a theme.
The text appears all at once
typewriter_speed is 0 on the node, or characters_per_second is set on the line. Both are "characters per second"; zero means show the whole line.
The player stays locked after a conversation
request_player_lock(false) is emitted when a conversation finishes or is stopped. If your handler is connected after play() was called, it misses the first true and the state goes out of step — connect in _ready().
A conversation id is reported as a duplicate
Ids are per node, so two NPCs may each own a greeting — that is a warning, not an error. Errors are only raised when the library declares an id twice, or when one node declares the same id twice, where the second can never play.
Still stuck
Collect this before asking:
print(ProjectSettings.get_setting("application/config/features"))
print(TalkKitConstants.ADDON_VERSION)
print($NPCTalkKit.list_conversations())
print($NPCTalkKit.state)Plus the Godot version and the full text of any warning in the Output panel.