Changelog

Tóm tắt những gì đã đổi và vì sao. CHANGELOG.md trong gói cài đặt mới là bản ghi chính thức và chứa đầy đủ mọi phiên bản.

2.0.0 — hiện tại

Xây lại phần soạn thảo. 1.0.0 sửa speaker là ai; lần này sửa mọi câu trả lời đến từ đâu.

Phân giải sâu bốn tầng — line, participant, conversation, node — và node nằm dưới mọi conversation đã soạn để quyết hộ những gì conversation chưa nói. Một ô trong Inspector có thể trông như đang sống mà chẳng làm gì, và câu hỏi "Ren ở đâu ra?" không có câu trả lời trên bất kỳ màn hình nào.

• Hai tầng, và chỉ hai: ghi đè ở line → mặc định của conversation. Không có tầng fallback nào ở node.
• Node là một thư viện. speakers và dialogue_boxes là collection những gì NPC này dùng được — thứ mà conversation và line chọn ra từ đó.
• Conversation mang các giá trị mặc định: default_speaker, default_dialogue_box, default_placement. Line chỉ lưu phần ngoại lệ.
• TalkLine.speaker_mode — INHERIT, NONE, SPEAKER. Một câu người kể chuyện nằm trong hội thoại của Haru cần NONE; một giá trị null không nói được cả "tôi nhường" lẫn "không ai nói câu này".
• Quick Say Defaults phục vụ say() và không bao giờ chạm tới một conversation đã lưu.
• say() nhận options: say(text, params, {"speaker": &"ren"}). Khoá mới là thứ quyết định — {"speaker": null} là người kể chuyện.
• TalkParticipant biến mất. Thứ nó diễn đạt chính là ghi đè ở line.
• Hộp luôn vừa màn hình: kích thước ép là mức tối thiểu, chữ xuống dòng ở khoảng 440 px trong màn hình, tên dài được rút gọn, phần nhô ra vẫn nằm trong màn hình.
• Thiết lập hiển thị đúng như đã chọn: không còn dính look của hộp trước, không nháy chữ khi chuyển dòng, không nhảy khi dòng gõ xong.
• Preset của riêng bạn: Save as Preset… đưa một hộp vào thư mục preset của project, và + New liệt kê nó trong Your presets.
• Xoá một hộp sẽ liệt kê những chỗ đang dùng và chuyển chúng sang hộp thay thế.
• Ba template, mỗi cái một kiểu box khác nhau: classic_panel, speech_bubble và terminal. visual_novel, soft_light và comic_bubble chỉ là biến thể màu nên đã bị bỏ.
• Manager cho Speakers và Dialogue Boxes sở hữu resource; conversation và line chỉ chọn từ đó.
• Workspace main-screen TalkKit riêng: line text-first, detail theo ngữ cảnh, runtime preview, Undo/Redo native, validation recovery, resource manager, lịch sử Back, bulk edit và responsive navigation.
• Inspector chỉ là entry point gọn, không còn là nested resource editor.
• Preview Script-first: tab Coming soon giới thiệu workflow cho người viết mà chưa tạo ra một source format dở dang.
• Hình thức hộp thoại được xây lại quanh các phần của nó.
  • Panel Appearance: Flat Style, Nine-slice Texture có scale cho pixel art, hoặc bất kỳ StyleBox nào có sẵn.
  • Một padding duy nhất.
  • Visual Layer: name box, khung portrait, hoa văn góc, cạnh và lớp nền thêm, nằm dưới hoặc trên nội dung.
  • Tên trên mép trên; tail và indicator hợp với panel dùng texture.
  • Theme tạo kiểu cho chữ mà không xoá khung.
  • Màn Layers và Anatomy Map tương tác.
• Các demo có trong package. Toàn bộ art của chúng là CC0, nên đi kèm addon được.
• Schema 4.0.

Đã kiểm chứng trên Godot 4.6 stable và 4.7.2 stable.

1.0.0

Xây lại mô hình speaker. Đây là thay đổi phá vỡ tương thích lớn nhất của addon, và không có lớp đệm tương thích nào: sản phẩm chưa đến tay khách hàng nào nên mô hình được thay thẳng.

Trước đây speaker là hai thứ cùng lúc — vừa là danh tính hội thoại, vừa là nhân vật trong game. Nó mang talk_animation và idle_animation, còn node mang animation_player_path, nên phát một câu thoại là điều khiển luôn một sprite trong scene của bạn. Hệ quả: không thể diễn đạt một hội thoại có hai người nói, và một người kể chuyện hay một giọng bộ đàm lại cần tới một nhân vật không hề tồn tại.

• TalkCharacterProfile → TalkSpeaker. Danh tính, hình nhân vật và giọng nói. Không NodePath, không animation, không tham chiếu nào tới thế giới game.
• TalkDialogueVisual là mới — một texture hoặc SpriteFrames kèm các biến thể có tên, độc lập với node nhưng vẫn dùng lại được chính asset của game.
• TalkParticipant là mới — một speaker tham gia một hội thoại như thế nào: hộp, chỗ đứng, vị trí. Tuỳ chọn; speaker không có entry thì chạy với giá trị mặc định.
• Nhiều người nói trong một hội thoại. Mỗi câu tự nêu ai nói nó; không phải khai báo dàn nhân vật, không có chế độ nào phải bật. Xem Người nói.
• Không có speaker cũng là trạng thái hợp lệ — tấm biển, người kể chuyện, thông báo hệ thống.
• TalkKit không còn điều khiển animation nào. Mọi hook animation thế giới đã bị gỡ; game muốn có thì tự phát.
• Rich text trong cả hội thoại soạn sẵn lẫn say(), hiện ra theo ký tự đã phân tích nên không bao giờ lộ thẻ. Label nội dung giờ là RichTextLabel.
• say() nhận String, TalkLine, TalkConversation, hoặc mảng trộn các thứ đó, chạy qua đúng đường ống của play(). Node không có hội thoại nào được lưu vẫn là node hoạt động được.
• Một hệ phân giải duy nhất nằm trên node; renderer tiêu thụ trạng thái đã phân giải chứ không tự đặt ra thứ tự ưu tiên.
• TalkLine.speaker_name → display_name_override, giờ chỉ đổi tên — mặt và giọng vẫn là của người đang nói.
• TalkConversation.npc_id → default_speaker, và giờ nó thắng speaker của node.
• portrait_* → visual_* trên hộp; voice_enabled chuyển về speaker.
• Schema 3.0. Tài liệu 2.0 bị từ chối chứ không đọc dở.

Đã kiểm chứng trên Godot 4.6 stable và 4.7.2 stable.

0.3.0

Node-first. Hội thoại được soạn trên node, trong Inspector. Database giờ là kho dùng chung tuỳ chọn.

• NPCTalkKit thay cho TalkKitComponent.
• dialogues: Array[TalkConversation] trên node; database đổi tên thành library.
• play(name, params);
• Thứ tự tra: dialogues của node trước, rồi tới library.
• Blocking event — TalkLine.event_blocking, trạng thái BLOCKED, signal event_blocked, và resume() / is_blocked().
• Tham số trong text — điền lúc play(), gộp đè lên default_params. Line gốc được sao chép, không bị sửa.
• TalkLine.speaker_name và characters_per_second theo từng line.
• TalkConversation.event_id / event_payload, nổ khi kết thúc.
• Thứ tự người nói: library → profile của node → speaker_name → ẩn dòng tên.
• MISSING_NPC_REFERENCE không còn được phát — speaker_id rỗng là hợp lệ.
• TalkKitSceneCollector, cùng Promote to Library và Validate scene trong Inspector.
• Demo dựng lại trên nội dung inline: 20 file .tres hội thoại còn 10 asset dùng chung.

Đã kiểm chứng trên Godot 4.7.2 stable.

0.2.0

Hình hài công khai đầu tiên của addon, theo hướng database-first.

Runtime

• NPCTalkKit với vòng đời hội thoại đầy đủ và mười bốn signal.
• Quyết định kiểu hiển thị theo từng line: override của line → conversation → profile → bottom_box.
• Hook animation qua AnimationPlayer hoặc AnimatedSprite, bỏ qua êm khi thiếu.
• Tiếng blip với dải cao độ, giới hạn tần suất và bỏ qua dấu câu; voice_clip tuỳ chọn theo từng line.
• TalkInteractionArea2D làm trigger theo khoảng cách, tuỳ chọn.

Kiểu hiển thị

• Bottom Box và Speech Bubble.
• Hợp đồng kiểu tùy chỉnh gồm bốn method, cộng với TalkPresentationBase.
• portrait_texture_filter và portrait_size trên TalkPresentationProfile cho chân dung pixel art.

Nội dung

• TalkKitDatabase, TalkCharacterProfile, TalkConversation, TalkLine, TalkPresentationProfile dưới dạng resource thuần.
• Kiểm tra dữ liệu xác định với mã lỗi ổn định.
• Xuất và nhập JSON ở schema_version "1.0", với chế độ safe / preview / overwrite.

Editor

• Dock TalkKit: CRUD, sắp xếp lại, kiểm tra khi lưu, xem trước dạng văn bản.
• Ô xem trước trạng thái trong Inspector, vẽ hộp thoại thật lên workspace 2D, đóng băng ở IDLE, OPENING, DISPLAYING, FINISHING hoặc CANCELLING, mà không lưu gì vào scene.

Đã kiểm chứng trên Godot 4.6 stable và 4.7.2 stable. Tương thích →

Cách đánh phiên bản

TalkKitConstants mang hai phiên bản tách biệt:

Hằng số	Ý nghĩa
ADDON_VERSION	Bản phát hành của addon.
SCHEMA_VERSION	Định dạng tài liệu JSON. Hiện là "1.0", độc lập với phiên bản addon.