popochiu

Popochiu

相关技能： dialogue-system 用于手工编写对话数据，inventory-system 用于通用库存模式，save-load 用于核心引擎持久化。

插件： Popochiu · 版本 v2.1.1 · Godot 4.6 · MIT · 源码：https://github.com/carenalgas/popochiu · 纯 GDScript（无 C# API — 仅适用于 GDScript 的技能）。

---

1. 何时使用 Popochiu

方案	最适合
手工编写（dialogue-system + inventory-system + state-machine）	自定义类型、严格控制每个系统、不需要编辑器工具
Popochiu	完整的点击式冒险游戏（AGS/PowerQuest 风格）：房间、点击后移动、基于动词的交互、对话树、库存、存档/读档 — 通过停靠面板生成脚手架并将各部分连接起来

如果你正在制作经典的点击式冒险游戏，并希望预先搭建好房间/角色/道具/对话/库存工作流，同时使用可生成新对象的停靠面板，以及提供自动补全的自动加载注册表（R.House、C.Popsy、I.Key、D.PopsyHouseChat），请选择 Popochiu。如果你的游戏类型不是点击式冒险，或者需要完全掌控交互模式，请使用 dialogue-system + inventory-system + state-machine 手工编写。Popochiu 要求使用 Godot 4.6，且仅支持 GDScript（无 C# API）。

---

2. 安装和项目设置

1. 从 itch.io 或 GitHub Releases 获取 Popochiu；将 addons/popochiu/ 复制到项目中。
2. Project → Project Settings → Plugins → 启用 Popochiu。Godot 会提示重启 — 选择 Project → Reload Current Project。
3. 首次运行时，PopochiuResources.init_file_structure() 会生成 res://game/（布局如下）以及 popochiu_data.cfg（用于登记每个房间/角色/物品/对话的 ConfigFile）和 popochiu_globals.gd（空的 Globals 自动加载脚本 — 在此添加自己的状态）。
4. 设置向导会自动弹出（也可通过停靠面板中的“Setup”按钮重新打开）：选择游戏类型（Retro / Pixel Art 或 Modern / Hi-Res — 设置拉伸宽高比和像素艺术纹理过滤；自定义设置表单提供 Custom / Pixel Art / High Resolution）、分辨率和GUI 模板（9 Verb、Sierra 风格的“Action Bar”、Simple Click 或 Custom）。
5. 两个配套插件 PopochiuImporters（Aseprite 导入停靠面板）和 PopochiuGizmo 会与 Popochiu 一起自动启用。

停靠面板生成的布局：

res://game/
  popochiu_globals.gd        # Globals autoload — add vars/on_save/on_load
  popochiu_data.cfg          # registry of rooms/characters/items/dialogs/GUI/setup
  autoloads/{r,c,i,d,a}.gd   # generated — never hand-edit; rewritten per new object
  rooms/<name>/room_<name>.gd (+ .tscn, state script)
  characters/<name>/character_<name>.gd (+ .tscn, state script)
  inventory_items/<name>/inventory_item_<name>.gd (+ .tscn, state script)
  dialogs/<name>/dialog_<name>.gd (+ .tres)
  gui/gui.tscn, gui/gui_commands.gd
  transition_layer/transition_layer.tscn (+ .gd)

---

3. 核心概念与单字母自动加载项

游戏脚本几乎完全通过简短的自动加载单例与 Popochiu 交互（而非 PopochiuUtils 或类名；后两者用于引擎内部代码）：

自动加载项	接口	用途	关键签名
E	Popochiu	核心引擎：队列／过场脚本、保存／加载、摄像机、命令	func queue(instructions: Array, show_gui := true) -> void
R	PopochiuIRoom	房间注册表与导航	func goto_room(script_name := "", use_transition := true, store_state := true, ignore_change := false) -> void
C	PopochiuICharacter	角色注册表（C.player、C.Popsy）	func walk_to_clicked(offset := Vector2.ZERO) -> void
I	PopochiuIInventory	物品栏注册表与当前物品	func set_active_item(item: PopochiuInventoryItem = null) -> void
D	PopochiuIDialog	对话注册表与内联对话	func show_inline_dialog(options: Array) -> PopochiuDialogOption
G	PopochiuIGraphicInterface	GUI 控制：阻止／解除阻止、显示／隐藏、悬停／系统文本	func show_system_text(msg: String) -> void
A	PopochiuIAudio	音频提示注册表（A.sfx_boing）	func is_playing_cue(cue_name: String) -> bool

R／C／I／D 对应的是生成文件（res://game/autoloads/*.gd），每次你在停靠面板中创建对象时都会重写这些文件——不要手动编辑；请将自定义逻辑写在对象自己的脚本中。另外还有两个单例补充了这组接口：T（PopochiuITransitionLayer，屏幕转场 — §4）和 Cursor（鼠标光标渲染）。

---

4. 房间与导航

通过停靠面板中的“Create room”按钮创建房间——该按钮会在 res://game/rooms/<name>/ 下生成 room_<name>.gd／.tscn，并创建子节点 $Props、$Characters、$Hotspots、$Regions、$WalkableAreas、$Markers。房间至少需要一个已启用的 Walkable Area，否则角色将无法根据点击路径移动。

使用 R.goto_room() 切换房间——没有 E.goto_room()；房间导航由 R 负责：

func _on_click() -> void:
    await C.player.walk_to_clicked()
    R.goto_room("Garden")

E.queue() 根据有序指令列表编写过场脚本——可混合使用 Callable（任何操作对应的 queue_* 版本）和普通字符串：

func _on_room_transition_finished() -> void:
    E.queue([
        "Popsy: Finally, some fresh air.",
        C.Popsy.queue_walk_to(Vector2(400, 300)),
        "...",  # 1s pause
        C.Popsy.queue_say("Now, where did I put that key?"),
    ])

queue()／cutscene() 接受的字符串简写："Name: text"（说一句台词）、"Name(emotion): text"、"Name[N]: text"（N 秒后自动继续）、"."／".."／"..."（暂停 0.25 秒／0.5 秒／1 秒，每多一个点时长加倍），其他字符串则通过 G.show_system_text() 显示。E.cutscene() 还可以通过 popochiu-skip 输入操作（默认是 Esc）跳过。

房间转场通过 T 实现（2.1 中新增）——不要使用已弃用的 E.play_transition()／E.queue_play_transition()（这些方法在 2.1.1 中仍然存在，但会打印运行时警告）：

await T.play_transition("fade", 0.5, T.PLAY_MODE.IN_OUT)

除非调用时设置 use_transition := false，否则 R.goto_room() 会自动播放项目的默认转场。

---

5. 交互

类型	基类	用途
道具	PopochiuProp（Area2D）	可见／可交互的场景物件——精灵图、可选的 link_to_item，也可以是导航障碍物
热点	PopochiuHotspot（Area2D）	不可见的交互区域（自身没有精灵图，例如背景图的一部分）
区域	PopochiuRegion（Area2D）	触发区域，在角色进入／离开时为其着色／缩放；不会接收点击

道具、热点和角色都继承自 PopochiuClickable，并共享同一套虚拟生命周期。在生成的脚本中重写这些以下划线开头的方法——引擎会调用公共包装方法（on_click() 等），由它们在内部调用这些方法，因此切勿重写公共包装方法本身：

# prop_key.gd
extends PopochiuProp

func _on_click() -> void:
    await C.player.walk_to_clicked()
    I.Key.add_as_active()

func _on_item_used(item: PopochiuInventoryItem) -> void:
    if item == I.Oil:
        await C.player.say("That should stop it squeaking.")

完整回调集合：_on_room_set、_on_click、_on_double_click、_on_right_click、_on_middle_click、_on_item_used(item)、_on_position_changed、_on_movement_started、_on_movement_ended。

命令式 GUI，简要说明：每个随附的 GUI 模板（9 Verb / Sierra / SimpleClick）都会通过 E.register_command(id, "Display Name", fallback) 注册动词。点击时，Popochiu 会将当前命令转换为 snake_case，并在被点击的对象上查找 on_<command>()（例如 on_look_at()），然后才回退到 _on_click()。完整机制——包括 E.current_command、注册自定义命令，以及你可能在旧教程中看到的已弃用 E.active_command 代码片段——请参阅 references/gui.md。

---

6. 角色与对话基础

从停靠面板创建角色；创建的第一个角色会成为玩家角色。说一句台词，还可以指定可选的情绪：

await C.player.walk_to_clicked()
await C.player.say("What a mess.", "annoyed")

情绪会映射到 voices 和 avatars 导出数组（情绪名称 → 音频提示／GUI 肖像）；say() 会在台词持续期间设置 emotion，随后将其重置为 ""。

从点击处理程序启动指定名称的对话树：

func _on_click() -> void:
    await C.player.face_clicked()
    D.PopsyHouseChat.start()

对话树是 PopochiuDialog 资源，包含分支选项、每个选项的条件和处理程序方法——完整的编写模式（包括仅接受 Array 的 turn_on_options()／turn_off_options() 注意事项）请参阅 references/dialogs.md。

深入了解：references/dialogs.md、references/inventory.md、references/gui.md、references/pipeline.md

---

实现检查清单

• 已在 项目设置 → 插件 中启用 Popochiu；启用后已重新加载项目
• 在编写房间前已运行一次设置向导（Game Type、Resolution、GUI Template）
• 每个房间至少有一个已启用的可行走区域，否则角色不会在点击时寻路
• 房间导航使用 R.goto_room()，而不是不存在的 E.goto_room()
• 过场脚本使用 E.queue([...])／E.cutscene([...])，而不是直接调用 queue_*()（在队列之外调用时，这些方法不会产生任何效果）
• 非 queue_ 操作调用（say()、walk_to() 等）都使用 await，否则它们会并发运行，而非按顺序执行
• 房间转换使用 T.play_transition()，而不是已弃用的 E.play_transition()
• 绝不手动编辑 res://game/autoloads/{r,c,i,d,a}.gd——这些文件会由停靠面板重新生成
• 自定义持久化字段应放在生成的 *_state.gd 资源中（使用 JSON 安全类型；复杂类型则重写 _on_save／_on_load）
• 调用 turn_on_options()／turn_off_options()／turn_off_forever_options() 时传入 Array，即使只有一个 id 也要如此
• 命令处理程序使用 on_<command>()（特定动词）或 _on_click() 回退方法——绝不重写公共 on_click() 包装方法本身
• GUI 模板只选择一次，并将其视为起点——之后切换模板会替换整个 res://game/gui/ 目录树