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 風）：部屋、クリックした場所への移動、動詞ベースのインタラクション、会話ツリー、インベントリ、セーブ／ロードが、ドックで生成されるスキャフォールディングによって連携されています

クラシックなポイント＆クリック型アドベンチャーを制作していて、部屋／キャラクター／オブジェクト／会話／インベントリのパイプラインがあらかじめ構築されているものを使いたい場合は、Popochiu を選んでください。ドックで新しいオブジェクトのスキャフォールディングを生成でき、自動読み込みレジストリによって自動補完（R.House、C.Popsy、I.Key、D.PopsyHouseChat）を利用できます。ジャンルがポイント＆クリック型ではない場合や、インタラクションモデルを完全に制御したい場合は、dialogue-system + inventory-system + state-machine を使って手作業で構築してください。Popochiu には Godot 4.6 が必要で、GDScript 専用です（C# API はありません）。

---

2. インストールとプロジェクト設定

1. itch.io または GitHub Releases から Popochiu を入手し、addons/popochiu/ をプロジェクトにコピーします。
2. プロジェクト → プロジェクト設定 → プラグイン で Popochiu を有効にします。Godot の再起動を求められます — プロジェクト → 現在のプロジェクトを再読み込み を選択します。
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. 2 つの関連プラグイン、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. コアコンセプトと1文字のオートロード

ゲームスクリプトは、ほぼすべて短いオートロードシングルトンを介して 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）に対応しており、ドックでオブジェクトを作成するたびに書き換えられます。手動で編集せず、カスタムロジックはオブジェクト自身のスクリプトに記述してください。さらに2つのシングルトンが用意されています。T（PopochiuITransitionLayer、画面遷移 — §4）と Cursor（マウスカーソルの描画）です。

---

4. ルームと移動

ドックの「ルームを作成」ボタンからルームを作成すると、res://game/rooms/<name>/ の下に $Props、$Characters、$Hotspots、$Regions、$WalkableAreas、$Markers の子ノードを含む room_<name>.gd／.tscn が生成されます。ルームには有効なウォーク可能エリアが少なくとも1つ必要です。有効なエリアがないと、クリック時にキャラクターが経路探索できません。

ルームを変更するには 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秒の一時停止。ドットごとに2倍）、その他の文字列は 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)

R.goto_room() は、use_transition := false を指定しない限り、プロジェクトのデフォルトの遷移を自動的に再生します。

---

5. インタラクション

種類	基底クラス	用途
Prop	PopochiuProp (Area2D)	表示・操作可能な背景要素です。スプライト、任意の link_to_item を持ち、ナビゲーションの障害物にもなります
Hotspot	PopochiuHotspot (Area2D)	不可視のインタラクション領域です（独自のスプライトはありません。背景アートの一部などに使います）
Region	PopochiuRegion (Area2D)	入退場時にキャラクターの色やスケールを変更するトリガー領域です。クリックは受け取りません

Props、Hotspots、Characters はすべて 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 は現在のコマンドをスネークケースに変換し、クリックされたオブジェクトに 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 を有効にし、有効化後にプロジェクトを再読み込みする
• ルームを作成する前に、セットアップウィザード（ゲームの種類、解像度、GUIテンプレート）を一度実行する
• すべてのルームに有効な Walkable Area を少なくとも1つ設定する。設定しないと、キャラクターがクリック時に移動できません
• ルーム遷移には 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() には、IDが1つだけの場合も Array を渡す
• コマンドハンドラーには on_<command>()（動詞別）または _on_click() のフォールバックを使用し、パブリックな on_click() ラッパー自体は絶対にオーバーライドしない
• GUIテンプレートは一度選択し、出発点として扱う。後からテンプレートを切り替えると、res://game/gui/ ツリー全体が置き換わります