monarch-screen-setup

Monarch を使った画面とポップアップの整理

前提条件：Monarch の依存関係を確認する

このスキルのガイダンスを適用する前に、プロジェクトで実際に Monarch が使用されていることを必ず確認してください。プロジェクトのルートにある game.project ファイルで、britzl/monarch を含む依存関係の URL を確認します（例：dependencies#N = https://github.com/britzl/monarch/archive/...）。または、プロジェクトツリーに monarch/monarch.lua ファイルが存在するか確認してください。

game.project に Monarch の依存関係がなく、ローカルの monarch/monarch.lua モジュールも見つからない場合は、このスキルを適用しないでください。プロジェクトでは Monarch が使用されていないようであることをユーザーに伝え、使用を希望する場合は game.project に依存関係を追加するよう提案してください：

[project]
dependencies#N = https://github.com/britzl/monarch/archive/refs/tags/5.2.0.zip

---

このスキルでは、Monarch ライブラリを使用する Defold プロジェクトで、画面（collectionproxy 経由）とポップアップ（collectionfactory 経由）を作成、管理する際の規約について説明します。

命名規則

• 画面とポップアップの名前には、すべて snake_case を使用します。
• Monarch は単一の共有レジストリ（monarch.lua の screens テーブル）に名前を登録するため、画面とポップアップの名前はプロジェクト全体で必ず一意にしてください。ID が重複するとアサーションエラーが発生します。
• ポップアップ名には、画面名（例：main_menu、gameplay）と衝突しないよう、異なるプレフィックスを付けることを推奨します（例：settings_popup、reward_popup）。

ディレクトリ構成

project/
├── main/
│   ├── main.collection          -- bootstrap collection (set in game.project [bootstrap])
│   └── main.script              -- main controller script: waits for registration, shows first screen
├── screens/
│   └── <screen_name>/
│       ├── <screen_name>.collection   -- IMPORTANT: collection name MUST be unique (see below)
│       ├── <screen_name>.gui
│       └── <screen_name>.gui_script
├── popups/
│   └── <popup_name>/
│       ├── <popup_name>.collection
│       ├── <popup_name>.gui
│       └── <popup_name>.gui_script

画面の作成（collectionproxy）

画面とは、collectionproxy を介して読み込まれる全画面表示のビューです。同時にアクティブにする画面は 1 つだけにしてください。画面を切り替える際は、複数の画面がスタックされないよう、常に { clear = true } を使用してください。

画面に必要なファイル（例：gameplay）

1. screens/gameplay/gameplay.collection

• コレクションの name プロパティは、プロジェクト全体で必ず一意にしてください（Defold は、読み込まれたワールド内での URL アドレス指定に使用します）。
• カメラコンポーネントを含むゲームオブジェクトを配置します。

name: "gameplay"
scale_along_z: 0
embedded_instances {
  id: "camera"
  data: "embedded_components {\n"
  "  id: \"camera\"\n"
  "  type: \"camera\"\n"
  "  data: \"aspect_ratio: 1.0\\n"
  "fov: 0.7854\\n"
  "near_z: -1.0\\n"
  "far_z: 1.0\\n"
  "orthographic_projection: 1\\n"
  "orthographic_mode: ORTHO_MODE_AUTO_COVER\\n"
  "\"\n"
  "}\n"
  ""
}

main.collection への画面の登録

main.collection で、画面ごとに次の要素を持つゲームオブジェクト（例：ID が gameplay）を作成します。

1. /monarch/screen_proxy.script を参照する screen_proxy コンポーネント。プロパティは次のとおりです。
   • screen_id = gameplay（ハッシュ。monarch.show() で使用する ID と一致させる必要があります）
   • popup = false
   • popup_on_popup = false
2. /screens/gameplay/gameplay.collection を指定する、collectionproxy 型の埋め込みコンポーネント。

screen_proxy.script は init() で monarch.register_proxy() を呼び出し、画面を自動的に登録します。

画面の表示（単一画面スタックのパターン）

スタックを既存のインスタンスまでクリアしてから置き換え、スタック内に画面が常に 1 つだけ存在するようにするため、画面を表示する際は必ず { clear = true } を使用してください。

monarch.show("gameplay", { clear = true })

画面に対して clear = true を指定せずに monarch.show("gameplay") を呼び出さないでください。画面がスタックに追加され、複数の画面が積み重なった分かりにくい状態になります。

画面間を移動するには、次のようにします。

-- from main_menu to gameplay:
monarch.show("gameplay", { clear = true })

-- from gameplay to main_menu:
monarch.show("main_menu", { clear = true })

画面間の移動に monarch.back() を使用しないでください。back() はポップアップを閉じるためのものです。

ポップアップの作成（collectionfactory）

ポップアップは、背後の画面を一時停止させたり暗くしたりするオーバーレイです。ポップアップは collectionfactory 経由で作成するため、複数のポップアップインスタンスを同時に表示できます（ポップアップの上に別のポップアップを表示できます）。

ポップアップに必要なファイル（例：settings_popup）

1. popups/settings_popup/settings_popup.collection

• 参照された GUI コンポーネントを含むゲームオブジェクトを配置します。

name: "settings_popup"
scale_along_z: 0
embedded_instances {
  id: "go"
  data: "components {\n"
  "  id: \"gui\"\n"
  "  component: \"/popups/settings_popup/settings_popup.gui\"\n"
  "}\n"
  ""
}

2. popups/settings_popup/settings_popup.gui

• ポップアップの UI ノードを含む標準的な Defold GUI ファイルです。

3. popups/settings_popup/settings_popup.gui_script

• ポップアップ自身を閉じるには、monarch.back() を呼び出します。

local monarch = require("monarch.monarch")

function init(self)
end

function final(self)
end

function on_message(self, message_id, message, sender)
end

function on_input(self, action_id, action)
    if action_id == hash("touch") and action.pressed then
        -- example: close popup on a button press
        -- (check node picking for your close button here)
        monarch.back()
    end
end

main.collectionでポップアップを登録する

main.collectionで、ポップアップごとに次のオブジェクトを作成します（例：IDがsettings_popup）。

1. /monarch/screen_factory.scriptを参照するコンポーネントscreen_factory。プロパティは次のとおりです。
   • screen_id = settings_popup（ハッシュ）
   • popup = true
   • popup_on_popup = true（このポップアップが別のポップアップの上に表示される場合はtrueに設定します）
   • screen_factory = コレクションファクトリーコンポーネントのURL（手順2を参照）
2. /popups/settings_popup/settings_popup.collectionを参照する、タイプがcollectionfactoryの埋め込みコンポーネントcollectionfactory。

screen_factory.scriptはinit()でmonarch.register_factory()を呼び出し、ポップアップを自動的に登録します。

ポップアップの表示と閉じ方

-- Open a popup (it stacks on top of the current screen):
monarch.show("settings_popup")

-- Open a popup on top of another popup (requires popup_on_popup = true):
monarch.show("confirm_popup")

-- Close the topmost popup:
monarch.back()

ポップアップのタイムステップ動作

画面の上にポップアップを表示すると、Monarchは下にある画面のプロキシに timestep_below_popupを自動的に設定します。デフォルト値は1（通常速度）です。ポップアップの下にある画面を一時停止するには、画面のscreen_proxy.scriptのプロパティで0に設定します。

• timestep_below_popup = 0

すべての画面が登録されてから開始する

main.scriptのinit()からmonarch.show()を直接呼び出さないでください。その時点では、ほかのスクリプトのinit()がまだ実行されておらず、画面も登録されていません。これによりアサーションエラーが発生します。

解決策は、init()から自身にメッセージを送信することです。メッセージが処理される頃には、コレクション内のすべてのinit()関数の実行が完了し、すべての画面とポップアップが登録されています。

例：main/main.script

local monarch = require("monarch.monarch")

function init(self)
    msg.post(".", "acquire_input_focus")
    msg.post("#", "start")
end

function on_message(self, message_id, message, sender)
    if message_id == hash("start") then
        monarch.show("main_menu", { clear = true })
    end
end

クイックリファレンス

操作	コード
画面を表示する（スタックをクリア）	monarch.show("screen_name", { clear = true })
ポップアップを表示する	monarch.show("popup_name")
最前面のポップアップを閉じる	monarch.back()
画面が登録されているか確認する	monarch.screen_exists("screen_name")
処理中（遷移中）か確認する	monarch.is_busy()
画面データを取得する	monarch.data("screen_name")
画面にデータを渡す	monarch.show("screen_name", { clear = true }, { key = "value" })
ポップアップにデータを渡す	monarch.show("popup_name", nil, { key = "value" })
ポップアップかどうかを確認する	monarch.is_popup("popup_name")
現在の最前面の画面を取得する	monarch.top()