Tra cứu API

Mọi thứ công khai, trên một trang, vì bề mặt đủ nhỏ để vừa một trang. Dùng Ctrl+F.

NPCTalkKit

Node bạn thêm vào NPC. extends Node.

Method

play(conversation_id: StringName, params: Dictionary = {}) -> bool
say(content: Variant, params: Dictionary = {}, options: Dictionary = {}) -> bool
advance() -> void
resume() -> void
stop() -> void
is_running() -> bool
is_blocked() -> bool
find_conversation(conversation_id: StringName) -> TalkConversation
list_conversations() -> Array[StringName]
build_context(line: TalkLine = null, conversation: TalkConversation = null) -> TalkContext
static transient_conversation(content: Variant) -> TalkConversation
static default_template() -> TalkBoxTemplate
static substitute(text: String, params: Dictionary) -> String

play() trả về false và không bao giờ ném lỗi khi tên không tồn tại, nội dung không qua được kiểm tra, hoặc một hội thoại đang được đọc dở. Nó được chấp nhận khi đang bị chặn — xem rẽ nhánh.

say() nhận một String, một TalkLine, hoặc một Array trộn hai thứ đó, rồi phát luôn mà không lưu gì vào conversations. Một node không có hội thoại nào vẫn là node hoạt động được.

options nêu những gì bản thân nội dung không nêu: speaker, dialogue_box, placement. Mỗi thứ có thể là resource hoặc id của một resource mà node này đang mang.

$NPCTalkKit.say("Stop!", {}, {"speaker": &"ren", "dialogue_box": &"warning"})
$NPCTalkKit.say("Three days later…", {}, {"speaker": null})   # narrator

Khoá mới là thứ quyết định, không phải giá trị: {"speaker": null} nghĩa là không có ai nói, còn bỏ hẳn khoá đó đi nghĩa là không nói gì và rơi xuống quick_say_speaker. Một giá trị null mang cả hai nghĩa sẽ khiến không thể yêu cầu một người kể chuyện.

Options chỉ chọn. say() không dựng được speaker và không sửa được style của hộp — cần cái chưa có thì tạo nó rồi thêm vào collection của node.

Phân giải

Mọi quy tắc về ai đang nói, hộp trông thế nào và đặt ở đâu đều được quyết định ở đây và không ở đâu khác. Renderer tiêu thụ câu trả lời; nó không tự suy ra.

resolve_speaker(line, conversation = null) -> TalkSpeaker
resolve_dialogue_box(line, conversation = null) -> TalkBoxTemplate
resolve_placement(line, conversation = null) -> TalkAnchor
resolve_typing_speed(line, conversation = null) -> float
resolve_voice(line, conversation = null) -> TalkSpeaker
resolve_dialogue_visual(for_speaker: TalkSpeaker, line: TalkLine = null) -> TalkDialogueVisual
resolve_display_name(for_speaker: TalkSpeaker, line: TalkLine = null) -> String
resolve_follow_target(line: TalkLine = null) -> Node

find_speaker(speaker_id: StringName) -> TalkSpeaker
find_dialogue_box(box_id: StringName) -> TalkBoxTemplate
known_speakers() -> Array[TalkSpeaker]

Bỏ trống conversation là hỏi về cái đang phát.

Hai tầng, và chỉ hai.

ghi đè ở line  →  mặc định của conversation

Câu hỏi	Line nói	Nếu không
Ai đang nói	speaker_mode + speaker	conversation.default_speaker
Hộp nào	line.dialogue_box	conversation.default_dialogue_box
Đặt ở đâu	line.placement	conversation.default_placement
Mặt nào	line.visual_variant	visual mặc định của speaker
Gõ nhanh cỡ nào	line.characters_per_second	typewriter_speed của hộp

Không có tầng fallback nào ở node. Node giữ các collection để chọn ra; nó không nằm dưới conversation để quyết hộ những gì conversation chưa nói. Quick Say Defaults chỉ dành cho say() và không bao giờ chạm vào một conversation đã lưu.

Conversation không có default_dialogue_box sẽ bị validator báo. Runtime vẫn lùi về Classic Panel có sẵn để một conversation làm dở không gây crash — đó là chốt chặn crash, không phải một tầng của mô hình.

Không có speaker cũng là một câu trả lời hợp lệ. Chữ vẫn gõ, event vẫn bắn; dòng tên và visual chỉ để trống. Đó chính là người kể chuyện, một tấm biển, một thông báo hệ thống.

Thuộc tính

Thuộc tính	Kiểu	Ghi chú
conversations	Array[TalkConversation]	hội thoại của NPC này; để trống vẫn hợp lệ, say() vẫn chạy
speakers	Array[TalkSpeaker]	những speaker node này dùng được — một collection, không phải giá trị mặc định
dialogue_boxes	Array[TalkBoxTemplate]	những hộp node này dùng được
quick_say_speaker	TalkSpeaker	thứ say() lùi về; không bao giờ chạm conversation đã lưu. Nằm dưới Quick Say trong Inspector gọn
quick_say_dialogue_box	TalkBoxTemplate	tương tự, cho hộp
quick_say_placement	TalkAnchor	tương tự, cho vị trí
library	TalkKitDatabase	tuỳ chọn, tìm sau conversations
default_params	Dictionary	ghép dưới params truyền vào play()
conversation_target	Node	mặc định là node cha; chỉ là nguồn toạ độ
box_parent_path	NodePath	nơi hộp được gắn vào
request_lock_on_start	bool	mặc định true
request_face_on_start	bool	mặc định false
request_camera_on_start	bool	mặc định false

state là trạng thái phát, chỉ đọc: enum State { IDLE, OPENING, DISPLAYING, BLOCKED, FINISHING, CANCELLING }. Trong code game nên dùng is_running() và is_blocked().

Hằng số: BOX_SCENE_PATH (scene renderer đi kèm) và DEFAULT_TEMPLATE_PATH (Classic Panel dùng làm phương án chống crash).

Signal

conversation_started(conversation_id: StringName)
line_started(line: TalkLine)
line_finished(line: TalkLine)
event_triggered(event_id: StringName, payload: Variant)
event_blocked(event_id: StringName, payload: Variant)
conversation_finished(conversation_id: StringName)
conversation_cancelled(conversation_id: StringName)
speech_started(line: TalkLine)
speech_progress(normalized_progress: float)
speech_finished(line: TalkLine)
request_player_lock(locked: bool)
request_face_target(target: Node)
request_camera_focus(target: Node)

Ba signal request_* là toàn bộ bề mặt tích hợp. TalkKit hỏi chứ không tự lấy. Bỏ qua hết thì addon vẫn chạy.

Signal mang theo câu đã dựng xong

line_started, line_finished và speech_* đưa cho bạn câu thoại sau khi đã thay — một bản sao, nên nội dung dùng chung không bao giờ bị sửa. line_id được giữ nguyên, nên code đối chiếu theo nó không bị ảnh hưởng.

TalkConversation

Thuộc tính	Kiểu
conversation_id	StringName
lines	Array[TalkLine]
default_speaker	TalkSpeaker — ai nói những câu không nói gì. Để trống nghĩa là không ai, tức một hội thoại người kể chuyện
default_dialogue_box	TalkBoxTemplate — hộp nào vẽ chúng
default_placement	TalkAnchor — chúng hiện ở đâu
event_id, event_payload	phát khi kết thúc, không chặn

is_empty() -> bool
get_line_by_id(line_id: StringName) -> TalkLine
speakers() -> Array[TalkSpeaker]

Chính các giá trị mặc định này là lý do conversation là một resource chứ không phải một mảng trần: một cảnh mà Haru nói mười hai lần trong Classic Panel chỉ khai một lần ở đây, và chỉ câu mà Ren chen ngang mới phải nói gì thêm.

Một hội thoại có thể chứa câu của nhiều speaker. Đó không phải rẽ nhánh — vẫn là một chuỗi thẳng; chỉ cái tên trên hộp là đổi.

TalkLine

Thuộc tính	Kiểu	Ghi chú
text	String	rich text, và hỗ trợ
speaker_mode	SpeakerMode	INHERIT, NONE, hoặc SPEAKER
speaker	TalkSpeaker	ai nói câu này, khi mode là SPEAKER
dialogue_box	TalkBoxTemplate	hộp khác cho riêng câu này; để trống thì kế thừa
placement	TalkAnchor	chỗ khác cho riêng câu này; để trống thì kế thừa
event_id, event_payload		báo cho game
event_blocking	bool	dừng lại tới khi game trả lời
line_id	StringName	tuỳ chọn; cho code của bạn và bản địa hoá
speaker_id	StringName	gọi tên một speaker trong kho thay vì trỏ thẳng
display_name_override	String	đổi tên cho riêng câu này — "???" trước lúc lộ diện. Giọng và mặt vẫn là của người đang nói
visual_variant	StringName	chọn một visual có tên của speaker; tên lạ thì lùi về mặc định
characters_per_second	float	0 là kế thừa
voice_clip	AudioStream

enum SpeakerMode { INHERIT, NONE, SPEAKER }

duplicate_line() -> TalkLine
inherits_speaker() -> bool

Ba trạng thái chứ không phải hai, vì "không nói gì và kế thừa" và "nói rằng không ai nói câu này" là hai chỉ thị khác nhau. Một câu người kể chuyện nằm trong hội thoại của Haru là NONE; một câu đơn giản là không quan tâm thì là INHERIT. Một giá trị null không diễn đạt được cả hai.

Line chỉ lưu những gì khác với mặc định của conversation.

TalkBoxTemplate

Toàn bộ những gì làm nên hộp thoại: bộ phận, màu sắc, hiệu ứng. Xem Hộp thoại.

Nhóm	Thuộc tính
Panel	base — một TalkBoxLayer, Base Appearance của Panel
Text	font, text_size, text_color, line_spacing, text_min_size, typewriter_speed
Speaker Name	name_shown, name_placement, name_align, name_offset, name_font, name_size, name_color
Dialogue Visual	visual_shown, visual_size, visual_side, visual_spacing, visual_filter
Tail	tail_shown, tail_look, tail_color, tail_texture, tail_size, tail_overlap
Continue Indicator	continue_shown, continue_look, continue_text, continue_texture, continue_filter, continue_motion
Transitions	open_transition, close_transition, line_transition, transition_duration, transition_curve, transition_easing
Advanced	custom_transition, theme, renderer
Layer	layers — Array[TalkBoxLayer], chỉnh trong màn Layers của workspace

enum VisualSide { LEFT, RIGHT }
enum NamePlacement { INLINE, TOP_EDGE }
enum NameAlign { LEFT, CENTER, RIGHT }
enum TailLook { COLOR, IMAGE }
enum IndicatorLook { GLYPH, IMAGE }
enum IndicatorMotion { NONE, BOUNCE, BLINK }

static default_base() -> TalkBoxLayer   # panel flat cổ điển mà hộp mới bắt đầu từ đó
build_panel_style() -> StyleBox     # Base Appearance, đã áp padding
drawn_panel_style() -> StyleBox     # thứ vẽ Panel, theo scale của nó
style_margins() -> Vector4          # giá trị của "Use style margins"
effective_padding() -> Vector4      # padding thực sự được dùng
is_textured() -> bool               # bất cứ thứ gì không phải flat style
base_draws_in_view() -> bool        # base dạng Image hoặc texture, được vẽ như một layer
image_filter() -> CanvasItem.TextureFilter   # của Panel, ảnh tail và indicator theo nó
panel_color() -> Color              # màu cho tail flat và nút "Sample panel colour"
layers_for(slot: TalkBoxLayer.Slot) -> Array[TalkBoxLayer]
apply_to(box: Control, text: RichTextLabel = null, name_label: Label = null,
         visual: TextureRect = null, indicator: Label = null,
         tail: Polygon2D = null, content: BoxContainer = null,
         indicator_image: TextureRect = null) -> void
transition_for(slot: String) -> TalkTransition   # "open", "close", "line"

Hình thức của Panel là base, một TalkBoxLayer có slot, Position và depth của một layer phủ kín Panel. Nó được chỉnh bằng cùng bộ control Appearance như name box, frame hay bất kỳ layer nào: nhóm Panel hiện các dòng Appearance của base, còn nhóm Speaker Name và Dialogue Visual hiện các dòng của một name box hay frame duy nhất theo đúng cách đó. Khi đã gán theme, các thiết lập font, cỡ chữ và màu nhường chỗ; Panel, padding và layer vẫn áp dụng. text_size bằng 0 nghĩa là kế thừa từ theme thay vì ghi đè. typewriter_speed bằng 0 hiện cả câu cùng lúc — nhịp gõ thuộc về hộp vì nó là một phần cách hộp hành xử: terminal gõ chậm rãi, bong bóng truyện tranh bật ra ngay.

Cả hai hộp có sẵn đều chỉ vẽ người đang nói. Hợp đồng renderer mang visible dưới dạng mảng để một hộp giữ cả dàn nhân vật trên màn có thể viết được mà không phải xây lại mô hình speaker — nhưng đó là việc của renderer, ở đây không có gì để cấu hình.

TalkBoxLayer

Một món trang trí trên một phần của hộp: name box, khung portrait, hoa văn góc, dải viền hoặc một lớp nền thêm. Xem Giải phẫu hộp thoại.

enum Slot { PANEL, SPEAKER_NAME, DIALOGUE_VISUAL }
enum Position { FILL, TOP, BOTTOM, LEFT, RIGHT, TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT }
enum Depth { BEHIND, ABOVE }
enum Source { FLAT_STYLE, NINE_SLICE, IMAGE, RESOURCE }
enum Fit { STRETCH, TILE, TILE_FIT, KEEP_SIZE }
enum PaddingMode { STYLE_MARGINS, CUSTOM }

look_properties() -> Array[Dictionary]       # bộ chỉnh Appearance dùng chung
holds_content() -> bool                      # base, name box hoặc frame
style_margins() -> Vector4
effective_padding() -> Vector4
rect_in(slot_rect: Rect2) -> Rect2           # vị trí trên slot của nó
painted_rect_in(slot_rect: Rect2) -> Rect2   # tính cả expand margin của StyleBox
own_size() -> Vector2
draws_texture() -> bool
is_empty() -> bool
is_corner() -> bool
is_edge() -> bool
draw(canvas: CanvasItem, slot_rect: Rect2) -> void
static scaled_style(original: StyleBox, factor: int, smooth := false) -> StyleBox
static is_pixel_filter(texture_filter: CanvasItem.TextureFilter) -> bool

Thuộc tính: name, enabled, slot, position, depth, offset, size, edge_inset, tint, và phần hình thức: visual_source, style, texture, scale, fit, filter, padding_mode, padding. Padding là của riêng layer và không bao giờ được ghi vào StyleBox của nó.

Layer vẽ style (Flat Style, Nine-slice Texture, hoặc một StyleBox resource) hoặc texture (Image, hoặc một Texture2D resource; AtlasTexture chỉ vẽ vùng của nó). Layer ở góc đặt tâm tại điểm góc nên mặc định lòi ra ngoài; layer ở cạnh chạy giữa hai edge_inset. Text, Tail và Continue Indicator không nhận layer.

TalkAnchor

Hộp nằm ở đâu. Xem Anchoring.

enum Mode { SCREEN, NODE_FOLLOW }
enum Spot { TOP_LEFT, TOP, TOP_RIGHT, LEFT, CENTER, RIGHT,
            BOTTOM_LEFT, BOTTOM, BOTTOM_RIGHT, ABSOLUTE }
enum Offscreen { CLAMP, HIDE, FREE }

resolve(box_node: Node, box: Vector2, fallback_target: Node = null) -> TalkAnchorResult
forced_size(view: Vector2) -> Vector2   # kích thước tối thiểu placement này đặt
room(view: Vector2) -> Vector2          # chỗ tối đa trên màn hình, đã trừ lề
stretches(view: Vector2) -> bool        # trải hết chiều ngang màn hình
wants_physics_frame() -> bool

Nhóm	Thuộc tính
Màn hình	screen_spot, screen_margin, screen_position, stretch_horizontal, box_size
Bám node	follow_target, follow_offset, pivot, when_offscreen, viewport_margin
Bám node 3D	follow_offset_3d, max_distance, scale_with_distance, reference_distance, min_scale, max_scale, hide_when_occluded, occlusion_mask

Kế thừa rồi override resolve() để tự cung cấp vị trí — mọi mode có sẵn đều đi qua đúng method đó.

TalkAnchorResult

visible, position, scale, size, focus, has_focus. focus là điểm đang bám, tính theo toạ độ màn hình — đó là cách bong bóng chĩa đuôi về đúng chỗ; has_focus cho biết có điểm đó hay không. size bằng 0 trên trục nào anchor để hộp tự lấy kích thước tự nhiên. TalkAnchorResult.hidden() trả về kết quả có visible = false.

TalkTransition

enum Kind { NONE, FADE, SLIDE, SCALE_POP }

static builtin(of_kind: Kind, seconds := 0.18) -> TalkTransition
is_instant() -> bool
play_in(box: Node) -> void    # await it
play_out(box: Node) -> void   # await it
rest_state() -> Dictionary    # {alpha, offset, scale} khi hiện hẳn
away_state() -> Dictionary    # tương tự, khi ẩn hẳn, theo kind này

Thuộc tính: kind, duration, curve, easing, slide_offset, scale_from.

Transition không bao giờ ghi thẳng lên hộp — anchor ghi lại vị trí và tỉ lệ mỗi khung hình — nên nó animate transition_alpha, transition_offset và transition_scale trên renderer, rồi renderer gộp chúng vào kết quả của anchor. Cần thứ khác thì kế thừa và override play_in / play_out.

TalkBoxRenderer

Lối thoát nâng cao, cho hộp mà thiết lập của template không mô tả nổi. extends CanvasLayer. Override những cái này:

get_text_label() -> RichTextLabel   # một câu thoại là rich text
get_name_label() -> Label
get_visual_rect() -> TextureRect
get_continue_label() -> Label
get_continue_image() -> TextureRect    # indicator dạng ảnh, hoặc null
get_continue_indicator() -> Control    # chỉ hiện khi người chơi có thể đi tiếp
get_tail() -> Polygon2D
get_content_container() -> BoxContainer
get_box_control() -> Control     # bắt buộc, cho anchoring và transition

Và được cho sẵn những cái này:

setup(context: TalkContext) -> void
show_line(line: TalkLine) -> void
finish_line() -> void
close() -> void
open() -> void
reopen() -> void
is_typing() -> bool
request_advance() -> void
apply_template() -> void
apply_layers() -> void
apply_anchor() -> void
can_advance() -> bool
get_slot_control(slot: TalkBoxLayer.Slot) -> Control
exposed_slots() -> Array[TalkBoxLayer.Slot]   # layer ở slot khác bị bỏ qua
layer_view(layer: TalkBoxLayer) -> Control
layer_rect(layer: TalkBoxLayer) -> Rect2
slot_rects() -> Dictionary      # từng phần, cho Anatomy Map
layer_bleed() -> Vector4        # layer lòi ra ngoài hộp bao xa
name_width() -> float           # độ rộng của tên khi hiện đầy đủ
const WRAP_WIDTH := 440.0       # nơi chữ xuống dòng khi không có gì đặt chiều rộng
freeze() -> void
effective_template() -> TalkBoxTemplate
effective_anchor() -> TalkAnchor
visible_length() -> int      # số ký tự cần hiện, không tính thẻ
visible_text() -> String     # chữ đúng như người chơi đọc

enum Phase { HIDDEN, OPENING, SHOWN, CHANGING, CLOSING }

signal advance_requested
signal finished                 # câu hiện tại đã gõ xong
signal closed                   # transition đóng đã xong; hộp sắp được giải phóng
signal speech_started(line: TalkLine)
signal speech_progress(line: TalkLine, normalized_progress: float)
signal speech_finished(line: TalkLine)

Trạng thái renderer giữ: context, current_line, last_anchor ( TalkAnchorResult gần nhất), phase, và các kênh transition transition_alpha, transition_offset, transition_scale.

Renderer tiêu thụ trạng thái đã phân giải. Nó không được tự suy ra ai đang nói, dùng hộp nào hay gõ nhanh cỡ nào — resolver đã ghép ngoại lệ ở line với mặc định conversation rồi trao nguyên vẹn qua TalkContext.

Export sẵn: default_anchor — vị trí riêng của renderer.

TalkSpeaker

Ai đang nói: danh tính, trông thế nào trong hộp, nghe ra sao.

Speaker là một danh tính hội thoại, không phải nhân vật trong game. Nó không mang NodePath, không AnimationPlayer, không sprite thế giới, và TalkKit không bao giờ ánh xạ nó sang một node trong scene của bạn — nên người kể chuyện, giọng bộ đàm, tấm biển, hay một nhân vật đang đứng ở màn chưa load đều là speaker bình thường.

Nhóm	Thuộc tính	Kiểu
Danh tính	speaker_id	StringName — chỉ cần khi tra kho hoặc JSON
	display_name	String — để trống thì ẩn dòng tên
Hình nhân vật	visual	TalkDialogueVisual
	variants	Dictionary[StringName, TalkDialogueVisual]
Giọng	voice_enabled	bool
	voice_blip	AudioStream
	voice_blip_interval	float
	voice_pitch_min, voice_pitch_max	float — ngẫu nhiên hoá cho mỗi tiếng blip

normalized_pitch_range() -> Vector2
resolve_visual(variant: StringName = &"") -> TalkDialogueVisual

Muốn nhân vật trong thế giới cử động lúc nói thì game của bạn tự làm:

$NPCTalkKit.play(&"greeting")
$AnimationPlayer.play("talk")

TalkDialogueVisual

Speaker trông thế nào bên trong hộp thoại.

Thuộc tính	Kiểu	Ghi chú
texture	Texture2D	ảnh tĩnh — chân dung, hoặc nửa người
sprite_frames	SpriteFrames	hình động; bị bỏ qua khi đã có texture
animation	StringName	lấy animation nào trong bộ frame đó
flip_h	bool	cho asset vẽ quay mặt hướng ngược lại

is_empty() -> bool
frame_texture(elapsed := 0.0) -> Texture2D

Tách khỏi node không đồng nghĩa với tách khỏi asset. Trỏ cái này vào đúng bộ SpriteFrames mà người chơi đang dùng chính là cách để biến người chơi thành speaker:

Player trong game            TalkSpeaker "Player"
└─ AnimatedSprite2D          └─ visual
   └─ player_frames.tres        └─ sprite_frames = player_frames.tres

TalkKit không bao giờ đi tìm $Player/AnimatedSprite2D và không sao chép trạng thái chạy của nó.

TalkRenderParticipant

Một speaker đúng như hộp cần vẽ, mọi quy tắc đã được áp dụng xong. extends RefCounted.

Thuộc tính	Kiểu
speaker	TalkSpeaker — có thể null
display_name	String — sau khi áp display_name_override
visual	TalkDialogueVisual — sau khi chọn variant của câu
active	bool — đây có phải người nói của câu đang hiện không

TalkInteractionArea2D / TalkInteractionArea3D

Bộ kích hoạt theo khoảng cách, tuỳ chọn. extends Area2D / Area3D.

Thuộc tính	Kiểu
talkkit_component	NPCTalkKit
conversation_id	StringName
input_action	StringName, mặc định ui_accept
accepted_body_group	StringName, mặc định player

Signal: availability_changed(available: bool).

Không bắt buộc — gọi play() từ code tương tác sẵn có của bạn mới là cách tích hợp được khuyến nghị.

TalkKitDatabase

Tuỳ chọn. Xem Kho dùng chung. Export speakers và conversations, cùng:

list_speakers() -> Array[StringName]
get_speaker(speaker_id: StringName) -> TalkSpeaker
upsert_speaker(entry: TalkSpeaker, overwrite := false) -> bool
list_conversations() -> Array[StringName]
get_conversation(conversation_id: StringName) -> TalkConversation
create_conversation(data: Dictionary) -> TalkConversation
update_conversation(conversation_id: StringName, data: Dictionary) -> bool
delete_conversation(conversation_id: StringName) -> bool

validate_speaker(speaker_id: StringName) -> TalkValidationReport
validate_conversation(conversation_id: StringName) -> TalkValidationReport
validate_renderer(scene: PackedScene) -> TalkValidationReport
validate_all() -> TalkValidationReport

export_speaker_json(speaker_id: StringName) -> String
export_conversation_json(conversation_id: StringName) -> String
import_speaker_json(json_text: String, mode := "safe") -> TalkValidationReport
import_conversation_json(json_text: String, mode := "safe") -> TalkValidationReport

mode khi import là "safe" (từ chối thay id đã có), "overwrite", hoặc "preview" (parse và kiểm tra, không đổi gì). Resource parse được nằm ở value của report.

TalkValidator / TalkKitSceneCollector / TalkKitSerializer

TalkValidator.validate_conversation(conversation, speakers = []) -> TalkValidationReport
TalkValidator.validate_against_collection(conversation, available_speakers, available_boxes) -> TalkValidationReport
TalkValidator.validate_speaker(speaker, require_id := false) -> TalkValidationReport
TalkValidator.validate_renderer(scene: PackedScene) -> TalkValidationReport
TalkValidator.validate_all(speakers, conversations) -> TalkValidationReport

TalkKitSceneCollector.collect(root: Node, library = null) -> Collected
TalkKitSceneCollector.validate(root: Node, library = null) -> TalkValidationReport

TalkKitSerializer.export_conversation_json(conversation) -> String
TalkKitSerializer.export_speaker_json(speaker) -> String
TalkKitSerializer.parse_conversation_json(json_text, speakers = []) -> TalkValidationReport
TalkKitSerializer.parse_speaker_json(json_text) -> TalkValidationReport
TalkKitSerializer.conversation_to_dictionary(conversation) -> Dictionary
TalkKitSerializer.conversation_from_dictionary(data, speakers = []) -> TalkConversation
TalkKitSerializer.speaker_to_dictionary(speaker) -> Dictionary
TalkKitSerializer.speaker_from_dictionary(data) -> TalkSpeaker

Tất cả đều nhận mảng thường chứ không nhận database, nên nội dung nhúng là công dân hạng nhất. validate_against_collection báo những line trỏ tới speaker hoặc hộp mà node không mang — vẫn hợp lệ, nhưng không hiện trong dropdown nào. Các hàm parse_* của serializer không bao giờ đụng tới kho; resource parse được là value của report. import_conversation_json và import_speaker_json của database là bản lưu kết quả vào kho.

TalkValidationReport

var issues: Array[TalkValidationIssue]
var intended_changes: Array[Dictionary]
var value: Variant          # thứ một lần parse tạo ra, nếu có

is_valid() -> bool          # không có lỗi; cảnh báo thì được
error_count() -> int
warning_count() -> int
add(code: StringName, severity: StringName, message: String, context := {}) -> void
add_issue(issue: TalkValidationIssue) -> void
merge(other: TalkValidationReport) -> void
to_dictionary(include_issues := true) -> Dictionary

TalkValidationIssue

code, severity (&"error" hoặc &"warning"), message, và vị trí: speaker_id, conversation_id, line_id, line_index (-1 nếu không thuộc line nào), field. TalkValidationIssue.create(code, severity, message, context) tạo một issue; to_dictionary() chuyển nó thành dictionary.

TalkKitConstants

SCHEMA_VERSION ("4.0"), định dạng ghi vào JSON khi export; ADDON_VERSION ("2.0.0"), trùng với phiên bản trong plugin.cfg và hiện ở footer của workspace; DOCS_URL và SUPPORT_URL, hai link Docs và Support ở footer.

TalkContext

Được đưa vào setup() của renderer. Mọi thứ hộp cần để vẽ một câu, đã phân giải sẵn — renderer không tự chạy chuỗi suy luận nào.

Thuộc tính	Kiểu	Ghi chú
component	NPCTalkKit
target	Node	thứ mà anchor bám theo; chỉ là nguồn toạ độ
conversation	TalkConversation
anchor	TalkAnchor	null thì lùi về anchor riêng của renderer
template	TalkBoxTemplate	hộp mà câu này phân giải ra
typewriter_speed	float	ký tự mỗi giây; 0 hiện cả câu cùng lúc
active	TalkRenderParticipant	ai đang nói; null nếu là người kể chuyện
visible	Array[TalkRenderParticipant]	tất cả những ai hộp cần giữ trên màn

display_name() -> String                       # "" thì ẩn dòng tên
visual_texture(elapsed := 0.0) -> Texture2D    # null thì không vẽ
voice_speaker() -> TalkSpeaker                 # null là im lặng

Cả hai hộp có sẵn chỉ vẽ active, nên hôm nay visible nhiều nhất chứa một phần tử. Nó là mảng vì một renderer giữ cả dàn nhân vật là chuyện của renderer — không phải tính năng authoring, và không có gì để cấu hình.