diff --git a/docs/assets/game-menu.jpg b/docs/assets/game-menu.jpg new file mode 100644 index 0000000..8a8a61a Binary files /dev/null and b/docs/assets/game-menu.jpg differ diff --git a/docs/assets/notification.png b/docs/assets/notification.png new file mode 100644 index 0000000..6b79d43 Binary files /dev/null and b/docs/assets/notification.png differ diff --git a/docs/assets/scene-hud.jpg b/docs/assets/scene-hud.jpg new file mode 100644 index 0000000..d092bd0 Binary files /dev/null and b/docs/assets/scene-hud.jpg differ diff --git a/docs/assets/toolbar.png b/docs/assets/toolbar.png new file mode 100644 index 0000000..9d05d7f Binary files /dev/null and b/docs/assets/toolbar.png differ diff --git a/docs/en.md b/docs/en.md new file mode 100644 index 0000000..e172ab8 --- /dev/null +++ b/docs/en.md @@ -0,0 +1,71 @@ +# UI — the shared interface of every game + +UI is the interface layer that the games share: the toolbar in the top-right corner, the in-game menu, the save indicator, notifications in the top-left corner, the background view and the common look of panels, buttons and lists. It has no story or rules of its own. Almost every other mod builds on it, which is why it is in every game and why so many mods list it as a requirement. + +![A scene in Cthangover at noon: the clock at the top left, the toolbar at the top right, the scene's choices on the right.](assets/scene-hud.jpg) + +## The toolbar + +Each icon opens a panel. The buttons are not fixed: every mod in the game adds its own, so a novel without items has no bag, and a game with the Scenario Studio has one more icon. + +![The Cthangover toolbar: tools, map, bag, characters, recruits, skills, menu (gear) and journal.](assets/toolbar.png) + +In Cthangover, from left to right: + +1. **Tools** — the developer tools menu (only when editors are in the game). +2. **Map** — world map (Map Engine). +3. **Bag** — inventory (Items). +4. **Characters** — party and characters (Characters). +5. **Recruits** — recruited characters (Recruiting). +6. **Skills** — skills (Skills). +7. **Menu** — the in-game menu described below (this mod). +8. **Journal** — quests (Quests). + +Other games show other sets; RPG Plus, for example, adds the **character sheet**. + +## The in-game menu + +The gear icon opens the menu: **Resume**, **Save**, **Load**, **Settings**, **Main menu** and **Exit**. Save is greyed out in scenes that do not allow saving, as in this picture. Load, Save and Settings open the same windows as in the main menu. + +![The in-game menu over a scene: Menu, Resume, Save, Load, Settings, Main menu, Exit.](assets/game-menu.jpg) + +## Notifications + +Short messages appear in the top-left corner: a new journal entry, a hint from the story. Up to four are shown at once, each for about ten seconds; more wait their turn. + +![A notification under the clock: "Look around. Something is lying in the alley." — a hint from Cthangover's prologue.](assets/notification.png) + +## For mod authors + +**Add a toolbar button and its panel** with a `ui` entry in your manifest. This is how Items adds the bag: + +```json +"ui": [ + { + "id": "inventory", + "kind": "panel", + "slot": "ModBeforeUIPanel", + "scene_path": "scenes/ui/inventory_panel.tscn", + "button": { "icon": "bag", "locale": "ui/inventory/title", "index": 20 }, + "priority": 10 + } +] +``` + +- `button.index` orders the icons (map 10, bag 20, characters 30, skills 40, menu 50, journal 60, studio 90); +- `button.icon` is the icon's name, `button.locale` the tooltip's translation key; +- an entry without `button` is a panel or overlay that the game opens itself — Crafting adds its workbench as `"kind": "overlay"` in the `ModLastPanel` slot and opens it from scenarios. + +**Open a panel from a scenario** with the `ui.toggle_panel` action, and **show a notification** with the `notify` command: + +```scenario +notify "The journal has a new entry." +``` + +**Use the common look.** Panels built in code take their frames, labels, chips and buttons from the toolkit (`UiKit`) and its colour and size tokens, so a new panel matches the rest of the game and follows its theme. + +## If something goes wrong + +1. **A toolbar button is missing.** The mod that adds it is not part of this game; check the game's scheme in **Mods & Collections**. +2. **Save is greyed out.** The current scene does not allow saving; move to another place and try again. Authors allow it with `save_allowed: true` in the header of one of the scene's scenarios. +3. **A panel opens but is empty.** The panel's mod has nothing to show yet in this game — for example, no quests have started. diff --git a/docs/es.md b/docs/es.md new file mode 100644 index 0000000..aa2aaca --- /dev/null +++ b/docs/es.md @@ -0,0 +1,71 @@ +# UI — la interfaz común de todos los juegos + +UI es la capa de interfaz que comparten todos los juegos: la barra de herramientas en la esquina superior derecha, el menú del juego, el indicador de guardado, las notificaciones en la esquina superior izquierda, la vista del fondo y el aspecto común de paneles, botones y listas. No tiene historia ni reglas propias. Casi todos los demás mods se construyen sobre ella, y por eso está presente en todos los juegos y tantos mods la declaran como dependencia. + +![Una escena de Cthangover al mediodía: el reloj arriba a la izquierda, la barra de herramientas arriba a la derecha y las opciones de la escena a la derecha.](assets/scene-hud.jpg) + +## La barra de herramientas + +Cada icono abre su panel. Los botones no son fijos: cada mod del juego añade los suyos, así que una novela sin objetos no tiene bolsa, y un juego con Scenario Studio muestra un icono más. + +![La barra de herramientas de Cthangover: herramientas, mapa, bolsa, personajes, reclutas, habilidades, menú (engranaje) y diario.](assets/toolbar.png) + +En Cthangover, de izquierda a derecha: + +1. **Herramientas** — el menú de herramientas de desarrollo (solo cuando hay editores en el juego). +2. **Mapa** — el mapa del mundo (Map Engine). +3. **Bolsa** — el inventario (Items). +4. **Personajes** — el grupo y los personajes (Characters). +5. **Reclutas** — los personajes reclutados (Recruiting). +6. **Habilidades** — las habilidades (Skills). +7. **Menú** — el menú del juego, descrito más abajo (este mod). +8. **Diario** — las misiones (Quests). + +Otros juegos muestran otros conjuntos; RPG Plus, por ejemplo, añade la **hoja de personaje**. + +## El menú del juego + +El icono del engranaje abre el menú: **Continuar**, **Guardar**, **Cargar**, **Ajustes**, **Menú principal** y **Salir**. En las escenas que no permiten guardar, la opción Guardar aparece deshabilitada, como en la imagen. Cargar, Guardar y Ajustes abren las mismas ventanas que en el menú principal. + +![El menú del juego sobre una escena: Menu, Resume, Save, Load, Settings, Main menu, Exit.](assets/game-menu.jpg) + +## Notificaciones + +En la esquina superior izquierda aparecen mensajes breves: una entrada nueva del diario, una pista de la historia. Se ven hasta cuatro a la vez, cada uno unos diez segundos; los demás esperan su turno. + +![Una notificación bajo el reloj: «Mira a tu alrededor. Hay algo tirado en el callejón.» — una pista del prólogo de Cthangover.](assets/notification.png) + +## Para autores de mods + +**Añadir un botón a la barra de herramientas con su panel** se hace con una entrada `ui` en el manifiesto. Así añade Items la bolsa: + +```json +"ui": [ + { + "id": "inventory", + "kind": "panel", + "slot": "ModBeforeUIPanel", + "scene_path": "scenes/ui/inventory_panel.tscn", + "button": { "icon": "bag", "locale": "ui/inventory/title", "index": 20 }, + "priority": 10 + } +] +``` + +- `button.index` ordena los iconos (mapa 10, bolsa 20, personajes 30, habilidades 40, menú 50, diario 60, estudio 90); +- `button.icon` es el nombre del icono y `button.locale`, la clave de traducción del tooltip; +- una entrada sin `button` es un panel o una capa superpuesta que el juego abre por su cuenta: Crafting añade su mesa de trabajo como `"kind": "overlay"` en el slot `ModLastPanel` y la abre desde los escenarios. + +**Abrir un panel desde un escenario** se hace con la acción `ui.toggle_panel`, y **mostrar una notificación**, con el comando `notify`: + +```scenario +notify "Nueva entrada en el diario." +``` + +**Usa el aspecto común.** Los paneles creados en código toman sus marcos, etiquetas, chips y botones del kit de interfaz (`UiKit`) y de sus tokens de color y tamaño, así que un panel nuevo encaja con el resto del juego y sigue su tema. + +## Si algo falla + +1. **Falta un botón en la barra de herramientas.** El mod que lo añade no forma parte de este juego; revisa el esquema del juego en **Mods y colecciones**. +2. **Guardar aparece deshabilitado.** La escena actual no permite guardar; ve a otro sitio e inténtalo de nuevo. Los autores lo permiten con `save_allowed: true` en la cabecera de uno de los escenarios de la escena. +3. **Un panel se abre vacío.** Su mod todavía no tiene nada que mostrar en este juego; por ejemplo, aún no ha empezado ninguna misión. diff --git a/docs/ja.md b/docs/ja.md new file mode 100644 index 0000000..d5cd883 --- /dev/null +++ b/docs/ja.md @@ -0,0 +1,71 @@ +# UI — すべてのゲームで共有されるインターフェース + +UI は全ゲームが共有するインターフェース層です。右上のツールバー、ゲーム内メニュー、セーブインジケーター、左上の通知、背景の表示、そしてパネル・ボタン・リストの共通デザインがここに集まっています。UI 自体は物語もルールも持ちません。ほぼすべての他の MOD が UI の上に成り立っているため、どのゲームにも含まれており、依存関係に挙げる MOD も非常に多くなっています。 + +![Cthangover の正午のシーン:左上に時計、右上にツールバー、右側にシーンの選択肢。](assets/scene-hud.jpg) + +## ツールバー + +アイコンごとにパネルが開きます。ボタンは固定ではなく、ゲームに含まれる各 MOD が自分のボタンを追加します。そのため、アイテムのないノベルにはインベントリのボタンがなく、Scenario Studio を含むゲームではアイコンが一つ増えます。 + +![Cthangover のツールバー:ツール、マップ、インベントリ、キャラクター、勧誘した者たち、スキル、メニュー(歯車)、日誌。](assets/toolbar.png) + +Cthangover では左から順に: + +1. **ツール** — 開発者ツールのメニュー(エディターがゲームに含まれているときだけ)。 +2. **マップ** — ワールドマップ(Map Engine)。 +3. **インベントリ** — 所持品(Items)。 +4. **キャラクター** — パーティとキャラクター(Characters)。 +5. **勧誘した者たち** — 勧誘で仲間にしたキャラクター(Recruiting)。 +6. **スキル** — スキル(Skills)。 +7. **メニュー** — 後述のゲーム内メニュー(この MOD)。 +8. **日誌** — クエスト(Quests)。 + +他のゲームでは並びが異なります。たとえば RPG Plus は**キャラクターシート**を追加します。 + +## ゲーム内メニュー + +歯車のアイコンでメニューが開きます:**再開**、**セーブ**、**ロード**、**設定**、**メインメニュー**、**終了**。セーブが許可されていないシーンでは、画像のように「セーブ」がグレーアウトします。「ロード」「セーブ」「設定」はメインメニューと同じウィンドウを開きます。 + +![シーンの上に開いたゲーム内メニュー:Menu, Resume, Save, Load, Settings, Main menu, Exit。](assets/game-menu.jpg) + +## 通知 + +左上には短いメッセージが表示されます。日誌の新しい記録や、物語からのヒントなどです。同時に最大 4 件まで表示され、それぞれ約 10 秒で消えます。残りは順番を待ちます。 + +![時計の下の通知:「あたりを見渡せ。路地に何か落ちている。」 — Cthangover プロローグのヒント。](assets/notification.png) + +## MOD 作者向け + +**ツールバーボタンとそのパネルを追加する**には、manifest の `ui` エントリーを使います。Items がインベントリを追加しているのがその例です: + +```json +"ui": [ + { + "id": "inventory", + "kind": "panel", + "slot": "ModBeforeUIPanel", + "scene_path": "scenes/ui/inventory_panel.tscn", + "button": { "icon": "bag", "locale": "ui/inventory/title", "index": 20 }, + "priority": 10 + } +] +``` + +- `button.index` がアイコンの順序を決めます(マップ 10、インベントリ 20、キャラクター 30、スキル 40、メニュー 50、日誌 60、スタジオ 90); +- `button.icon` はアイコン名、`button.locale` はツールチップの翻訳キー; +- `button` のないエントリーは、ゲームが自ら開くパネルやオーバーレイです。Crafting は作業台を `"kind": "overlay"` として `ModLastPanel` スロットに登録し、シナリオから開きます。 + +**シナリオからパネルを開く**には `ui.toggle_panel` アクションを、**通知を表示する**には `notify` コマンドを使います: + +```scenario +notify "日誌に新しい記録" +``` + +**共通デザインを使う。** コードで組み立てたパネルは、フレームやラベル、チップ、ボタンを UI キット(`UiKit`)とその色・サイズのトークンから受け取ります。新しいパネルもゲームの見た目に自然になじみ、テーマに従います。 + +## うまく動かないとき + +1. **ツールバーにボタンがない。** そのボタンを追加する MOD がこのゲームに含まれていません。**MOD とコレクション**でゲームの構成を確認してください。 +2. **「セーブ」がグレーアウトしている。** 現在のシーンはセーブを許可していません。別の場所へ移動してからもう一度。作者はシーンのシナリオのいずれかのヘッダーに `save_allowed: true` と書けばセーブを許可できます。 +3. **パネルが開くが中身がない。** その MOD には、このゲームでまだ見せるものがないのです。たとえばクエストがまだ始まっていない、といった具合です。 diff --git a/docs/ko.md b/docs/ko.md new file mode 100644 index 0000000..17c9af1 --- /dev/null +++ b/docs/ko.md @@ -0,0 +1,71 @@ +# UI — 모든 게임이 공유하는 인터페이스 + +UI는 모든 게임이 함께 쓰는 인터페이스 계층입니다. 오른쪽 위의 툴바, 인게임 메뉴, 저장 표시, 왼쪽 위의 알림, 배경 화면, 그리고 패널·버튼·목록의 공통 디자인이 여기에 속합니다. UI 자체에는 이야기도 규칙도 없습니다. 거의 모든 다른 모드가 UI 위에서 만들어지기 때문에 모든 게임에 들어 있고, 수많은 모드가 이를 의존성으로 지정합니다. + +![정오의 Cthangover 장면: 왼쪽 위 시계, 오른쪽 위 툴바, 오른쪽 장면 선택지.](assets/scene-hud.jpg) + +## 툴바 + +아이콘 하나당 패널 하나가 열립니다. 버튼 목록은 고정되어 있지 않습니다. 게임의 각 모드가 자기 버튼을 추가하므로, 아이템이 없는 소설 게임에는 인벤토리 버튼이 없고 Scenario Studio가 포함된 게임에는 아이콘이 하나 더 보입니다. + +![Cthangover 툴바: 도구, 지도, 인벤토리, 캐릭터, 영입자, 스킬, 메뉴(톱니바퀴), 일지.](assets/toolbar.png) + +Cthangover 기준 왼쪽부터: + +1. **도구** — 개발자 도구 메뉴(게임에 편집기가 있을 때만). +2. **지도** — 월드 맵(Map Engine). +3. **인벤토리** — 소지품(Items). +4. **캐릭터** — 파티와 캐릭터(Characters). +5. **영입자** — 영입한 캐릭터(Recruiting). +6. **스킬** — 스킬(Skills). +7. **메뉴** — 아래에서 설명할 인게임 메뉴(이 모드). +8. **일지** — 퀘스트(Quests). + +다른 게임에서는 구성이 다릅니다. 예를 들어 RPG Plus는 **캐릭터 시트**를 추가합니다. + +## 인게임 메뉴 + +톱니바퀴 아이콘을 누르면 메뉴가 열립니다: **계속**, **저장**, **불러오기**, **설정**, **메인 메뉴**, **나가기**. 저장이 허용되지 않는 장면에서는 그림처럼 저장 항목이 회색으로 비활성화됩니다. 불러오기, 저장, 설정은 메인 메뉴와 같은 창을 엽니다. + +![장면 위에 열린 인게임 메뉴: Menu, Resume, Save, Load, Settings, Main menu, Exit.](assets/game-menu.jpg) + +## 알림 + +왼쪽 위에는 짧은 메시지가 나타납니다. 일지에 새 항목이 생겼다거나, 이야기가 힌트를 건네는 식입니다. 한 번에 최대 네 개까지 표시되고 각각 열 초 정도 머문 뒤 사라지며, 나머지는 차례를 기다립니다. + +![시계 아래 알림: "주변을 둘러보자. 골목에 뭔가 놓여 있다." — Cthangover 프롤로그의 힌트.](assets/notification.png) + +## 모드 제작자를 위해 + +**툴바 버튼과 그 패널 추가하기** — manifest에 `ui` 항목을 넣으면 됩니다. Items가 인벤토리를 추가하는 방식이 그 예입니다: + +```json +"ui": [ + { + "id": "inventory", + "kind": "panel", + "slot": "ModBeforeUIPanel", + "scene_path": "scenes/ui/inventory_panel.tscn", + "button": { "icon": "bag", "locale": "ui/inventory/title", "index": 20 }, + "priority": 10 + } +] +``` + +- `button.index`는 아이콘 순서를 정합니다(지도 10, 인벤토리 20, 캐릭터 30, 스킬 40, 메뉴 50, 일지 60, 스튜디오 90); +- `button.icon`은 아이콘 이름, `button.locale`은 툴팁의 번역 키입니다; +- `button` 없는 항목은 게임이 스스로 여는 패널이나 오버레이입니다. Crafting은 작업대를 `"kind": "overlay"`로 `ModLastPanel` 슬롯에 넣고 시나리오에서 엽니다. + +**시나리오에서 패널 열기**는 `ui.toggle_panel` 액션으로, **알림 표시**는 `notify` 명령으로 합니다: + +```scenario +notify "새 일지 항목" +``` + +**공통 디자인 사용하기.** 코드로 만든 패널도 프레임, 라벨, 칩, 버튼을 UI 키트(`UiKit`)와 색·크기 토큰에서 가져옵니다. 새 패널도 게임 전체와 자연스럽게 어울리고 테마를 따릅니다. + +## 문제가 생겼을 때 + +1. **툴바에 버튼이 없다.** 그 버튼을 추가하는 모드가 이 게임에 포함되어 있지 않습니다. **모드와 컬렉션**에서 게임 구성을 확인하세요. +2. **저장이 비활성화되어 있다.** 현재 장면은 저장을 허용하지 않습니다. 다른 곳으로 이동한 뒤 다시 시도하세요. 제작자는 장면 시나리오 중 하나의 헤더에 `save_allowed: true`를 넣어 저장을 허용할 수 있습니다. +3. **패널은 열리지만 비어 있다.** 해당 모드가 이 게임에서 아직 보여 줄 것이 없는 것입니다. 예컨대 퀘스트가 아직 시작되지 않았을 때 그렇습니다. diff --git a/docs/ru.md b/docs/ru.md new file mode 100644 index 0000000..2d74b2e --- /dev/null +++ b/docs/ru.md @@ -0,0 +1,71 @@ +# UI — общий интерфейс всех игр + +UI — общий для всех игр слой интерфейса: панель инструментов в правом верхнем углу, игровое меню, индикатор сохранения, уведомления в левом верхнем углу, просмотр фона и единый вид панелей, кнопок и списков. Собственной истории и правил у него нет. Почти все остальные моды строятся поверх него — поэтому UI есть в каждой игре и значится в зависимостях у огромного числа модов. + +![Сцена в Cthangover в полдень: часы слева вверху, панель инструментов справа вверху, варианты выбора сцены справа.](assets/scene-hud.jpg) + +## Панель инструментов + +Каждая иконка открывает свою панель. Набор кнопок не фиксирован: свой добавляет каждый мод игры, поэтому в новелле без предметов не будет сумки, а в игре со Scenario Studio появится ещё одна иконка. + +![Панель инструментов Cthangover: инструменты, карта, сумка, персонажи, рекруты, навыки, меню (шестерёнка) и журнал.](assets/toolbar.png) + +В Cthangover слева направо: + +1. **Инструменты** — меню инструментов разработчика (только когда в игре есть редакторы). +2. **Карта** — карта мира (Map Engine). +3. **Сумка** — инвентарь (Items). +4. **Персонажи** — отряд и персонажи (Characters). +5. **Рекруты** — завербованные персонажи (Recruiting). +6. **Навыки** — навыки (Skills). +7. **Меню** — игровое меню, о нём ниже (этот мод). +8. **Журнал** — задания (Quests). + +В других играх набор другой: например, RPG Plus добавляет **лист персонажа**. + +## Игровое меню + +Иконка-шестерёнка открывает меню: **Вернуться**, **Сохранить**, **Загрузить**, **Настройки**, **Главное меню** и **Выход**. В сценах, где сохранение запрещено, пункт «Сохранить» неактивен — как на скриншоте. «Загрузить», «Сохранить» и «Настройки» открывают те же окна, что и в главном меню. + +![Игровое меню поверх сцены: Menu, Resume, Save, Load, Settings, Main menu, Exit.](assets/game-menu.jpg) + +## Уведомления + +В левом верхнем углу появляются короткие сообщения: новая запись в журнале, подсказка от сюжета. Одновременно показывается до четырёх, каждое держится на экране около десяти секунд, остальные ждут своей очереди. + +![Уведомление под часами: «Осмотрись. В переулке что-то лежит.» — подсказка из пролога Cthangover.](assets/notification.png) + +## Авторам модов + +**Добавить кнопку на панели инструментов и её панель** можно записью `ui` в манифесте. Так Items добавляет сумку: + +```json +"ui": [ + { + "id": "inventory", + "kind": "panel", + "slot": "ModBeforeUIPanel", + "scene_path": "scenes/ui/inventory_panel.tscn", + "button": { "icon": "bag", "locale": "ui/inventory/title", "index": 20 }, + "priority": 10 + } +] +``` + +- `button.index` задаёт порядок иконок (карта 10, сумка 20, персонажи 30, навыки 40, меню 50, журнал 60, студия 90); +- `button.icon` — имя иконки, `button.locale` — ключ перевода подсказки; +- запись без `button` — панель или оверлей, который игра открывает сама: Crafting добавляет верстак как `"kind": "overlay"` в слот `ModLastPanel` и открывает его из сценариев. + +**Открыть панель из сценария** можно действием `ui.toggle_panel`, а **показать уведомление** — командой `notify`: + +```scenario +notify "Новая запись в журнале." +``` + +**Придерживайтесь общего стиля.** Панели, собранные в коде, берут рамки, надписи, чипы и кнопки из набора виджетов (`UiKit`) и его токенов цвета и размера, поэтому новая панель сразу вписывается в игру и следует её теме. + +## Если что-то пошло не так + +1. **На панели инструментов нет кнопки.** Мод, который её добавляет, не входит в эту игру; проверьте состав игры в разделе **Моды и коллекции**. +2. **«Сохранить» неактивно.** Текущая сцена не разрешает сохранение; перейдите в другое место и попробуйте снова. Авторы разрешают его строкой `save_allowed: true` в заголовке одного из сценариев сцены. +3. **Панель открывается пустой.** Моду панели пока нечего показывать в этой игре — например, задания ещё не начались. diff --git a/docs/vi.md b/docs/vi.md new file mode 100644 index 0000000..13811ed --- /dev/null +++ b/docs/vi.md @@ -0,0 +1,71 @@ +# UI — giao diện chung của mọi game + +UI là lớp giao diện mà mọi game dùng chung: thanh công cụ ở góc trên bên phải, menu trong game, biểu tượng lưu, thông báo ở góc trên bên trái, khung xem nền và diện mạo thống nhất của bảng điều khiển, nút bấm, danh sách. UI không có cốt truyện hay luật chơi riêng. Gần như mọi mod khác đều được xây trên nó, vì thế nó hiện diện trong mọi game và rất nhiều mod liệt kê nó làm phụ thuộc. + +![Một cảnh trong Cthangover lúc buổi trưa: đồng hồ trên bên trái, thanh công cụ trên bên phải, các lựa chọn của cảnh ở bên phải.](assets/scene-hud.jpg) + +## Thanh công cụ + +Mỗi biểu tượng mở một bảng điều khiển. Các nút không cố định: mod nào trong game cũng thêm nút của riêng mình, nên một tiểu thuyết tương tác không có túi đồ, còn game có Scenario Studio thì nhiều thêm một biểu tượng. + +![Thanh công cụ của Cthangover: công cụ, bản đồ, túi đồ, nhân vật, người được chiêu mộ, kỹ năng, menu (bánh răng) và nhật ký.](assets/toolbar.png) + +Trong Cthangover, từ trái sang phải: + +1. **Công cụ** — menu công cụ dành cho nhà phát triển (chỉ khi game có trình soạn thảo). +2. **Bản đồ** — bản đồ thế giới (Map Engine). +3. **Túi đồ** — vật phẩm mang theo (Items). +4. **Nhân vật** — đội và các nhân vật (Characters). +5. **Người được chiêu mộ** — các nhân vật đã chiêu mộ (Recruiting). +6. **Kỹ năng** — kỹ năng (Skills). +7. **Menu** — menu trong game, nói ở dưới (mod này). +8. **Nhật ký** — nhiệm vụ (Quests). + +Các game khác hiển thị bộ nút khác; chẳng hạn RPG Plus thêm **bảng nhân vật**. + +## Menu trong game + +Biểu tượng bánh răng mở menu: **Tiếp tục**, **Lưu**, **Tải**, **Cài đặt**, **Menu chính** và **Thoát**. Ở những cảnh không cho phép lưu, nút Lưu bị mờ đi như trong hình. Tải, Lưu và Cài đặt mở đúng những cửa sổ như ở menu chính. + +![Menu trong game đè lên một cảnh: Menu, Resume, Save, Load, Settings, Main menu, Exit.](assets/game-menu.jpg) + +## Thông báo + +Góc trên bên trái xuất hiện những tin nhắn ngắn: một mục mới trong nhật ký, một gợi ý từ cốt truyện. Cùng lúc hiện tối đa bốn cái, mỗi cái giữ khoảng mười giây; cái khác xếp hàng chờ tới lượt. + +![Thông báo dưới đồng hồ: "Hãy nhìn quanh. Có thứ gì đó nằm trong con hẻm." — một gợi ý từ phần mở đầu của Cthangover.](assets/notification.png) + +## Cho tác giả mod + +**Thêm nút thanh công cụ cùng bảng điều khiển của nó** bằng một mục `ui` trong manifest. Items thêm túi đồ theo cách này: + +```json +"ui": [ + { + "id": "inventory", + "kind": "panel", + "slot": "ModBeforeUIPanel", + "scene_path": "scenes/ui/inventory_panel.tscn", + "button": { "icon": "bag", "locale": "ui/inventory/title", "index": 20 }, + "priority": 10 + } +] +``` + +- `button.index` xếp thứ tự các biểu tượng (bản đồ 10, túi đồ 20, nhân vật 30, kỹ năng 40, menu 50, nhật ký 60, studio 90); +- `button.icon` là tên biểu tượng, `button.locale` là khóa dịch của chú thích; +- mục không có `button` là bảng điều khiển hoặc lớp phủ mà game tự mở — Crafting đặt bàn chế tạo của mình dưới dạng `"kind": "overlay"` ở khe `ModLastPanel` và mở nó từ kịch bản. + +**Mở bảng điều khiển từ kịch bản** bằng hành động `ui.toggle_panel`, còn **hiện thông báo** bằng lệnh `notify`: + +```scenario +notify "Mục nhật ký mới" +``` + +**Dùng diện mạo chung.** Bảng điều khiển viết bằng code lấy khung, nhãn, thẻ và nút từ bộ công cụ giao diện (`UiKit`) cùng các token màu và kích thước, nên bảng mới tự hòa vào tổng thể game và đi theo chủ đề của nó. + +## Khi có trục trặc + +1. **Thiếu nút trên thanh công cụ.** Mod thêm nút đó không nằm trong game này; hãy kiểm tra thành phần của game trong **Mod và bộ sưu tập**. +2. **Nút Lưu bị mờ.** Cảnh hiện tại không cho phép lưu; hãy đến nơi khác rồi thử lại. Tác giả cho phép lưu bằng dòng `save_allowed: true` trong phần đầu một trong các kịch bản của cảnh. +3. **Bảng điều khiển mở ra nhưng trống trơn.** Mod ấy chưa có gì để hiển thị trong game này — ví dụ, chưa có nhiệm vụ nào bắt đầu. diff --git a/docs/zh.md b/docs/zh.md new file mode 100644 index 0000000..efc723a --- /dev/null +++ b/docs/zh.md @@ -0,0 +1,71 @@ +# UI — 所有游戏共用的界面 + +UI 是所有游戏共用的界面层：右上角的工具栏、游戏内菜单、存档指示器、左上角的通知，以及背景画面和面板、按钮、列表的统一外观。它自己没有剧情，也不定规则。几乎所有其他模组都构建在它之上，所以每个游戏里都有它，大量模组也把它列为依赖。 + +![Cthangover 中午时分的一幕：左上角是时钟，右上角是工具栏，右侧是场景选项。](assets/scene-hud.jpg) + +## 工具栏 + +每个图标都会打开一个面板。按钮并非固定不变：游戏中的每个模组都会加上自己的按钮，因此没有物品系统的小说游戏不会有背包，而带 Scenario Studio 的游戏则多出一个图标。 + +![Cthangover 的工具栏：工具、地图、背包、角色、招募者、技能、菜单（齿轮）和日志。](assets/toolbar.png) + +在 Cthangover 中，从左到右依次是： + +1. **工具** — 开发者工具菜单（仅当游戏包含编辑器时出现）。 +2. **地图** — 世界地图（Map Engine）。 +3. **背包** — 物品栏（Items）。 +4. **角色** — 队伍和角色（Characters）。 +5. **招募者** — 已招募的角色（Recruiting）。 +6. **技能** — 技能（Skills）。 +7. **菜单** — 下文介绍的游戏内菜单（本模组）。 +8. **日志** — 任务（Quests）。 + +其他游戏显示的按钮不同：例如 RPG Plus 会多出**角色面板**。 + +## 游戏内菜单 + +齿轮图标打开菜单：**继续**、**保存**、**读取**、**设置**、**主菜单**和**退出**。在不允许存档的场景中，“保存”会变灰，如图所示。“读取”“保存”和“设置”打开的窗口与主菜单中相同。 + +![场景上方的游戏内菜单：Menu, Resume, Save, Load, Settings, Main menu, Exit。](assets/game-menu.jpg) + +## 通知 + +左上角会出现简短消息：日志新增条目、剧情给出的提示等。同屏最多显示四条，每条停留约十秒，其余依次排队。 + +![时钟下方的通知：“看看四周。巷子里躺着什么东西。”——Cthangover 序章中的一条提示。](assets/notification.png) + +## 给模组作者 + +**添加工具栏按钮及其面板**：在 manifest.json 里写一个 `ui` 条目。Items 就是这样添加背包的： + +```json +"ui": [ + { + "id": "inventory", + "kind": "panel", + "slot": "ModBeforeUIPanel", + "scene_path": "scenes/ui/inventory_panel.tscn", + "button": { "icon": "bag", "locale": "ui/inventory/title", "index": 20 }, + "priority": 10 + } +] +``` + +- `button.index` 决定图标顺序（地图 10、背包 20、角色 30、技能 40、菜单 50、日志 60、工作室 90）； +- `button.icon` 是图标名，`button.locale` 是提示文字的翻译键； +- 不带 `button` 的条目是游戏自行打开的面板或覆盖层：Crafting 以 `"kind": "overlay"` 把工作台放进 `ModLastPanel` 槽位，并从剧本中打开它。 + +**从剧本打开面板**用 `ui.toggle_panel` 动作，**显示通知**用 `notify` 命令： + +```scenario +notify "新的日志条目。" +``` + +**使用统一外观。** 用代码构建的面板会从组件库（`UiKit`）及其颜色、尺寸令牌中获取边框、文字、标签和按钮，因此新面板自然融入游戏整体风格并跟随主题变化。 + +## 出现问题时 + +1. **工具栏上少了按钮。** 添加它的模组不属于当前游戏；请在**模组与合集**中查看游戏的构成。 +2. **“保存”是灰色的。** 当前场景不允许存档；换到别的地方再试。作者在场景任一剧本的头部写上 `save_allowed: true` 即可允许存档。 +3. **面板打开了却是空的。** 对应模组在当前游戏中暂时没有内容可显示——例如还没有任务开始。 diff --git a/locale/en.properties b/locale/en.properties new file mode 100644 index 0000000..5d65a5a --- /dev/null +++ b/locale/en.properties @@ -0,0 +1,2 @@ +mod_ui_base_name = UI +mod_ui_base_desc = The interface layer every game shares: the toolbar, the in-game menu, the save indicator, notifications and the common look of panels, buttons and lists. diff --git a/locale/es.properties b/locale/es.properties new file mode 100644 index 0000000..8ea92f0 --- /dev/null +++ b/locale/es.properties @@ -0,0 +1,2 @@ +mod_ui_base_name = UI +mod_ui_base_desc = La capa de interfaz que comparten todos los juegos: la barra de herramientas, el menú del juego, el indicador de guardado, las notificaciones y el aspecto común de paneles, botones y listas. diff --git a/locale/ja.properties b/locale/ja.properties new file mode 100644 index 0000000..ccbbbcd --- /dev/null +++ b/locale/ja.properties @@ -0,0 +1,2 @@ +mod_ui_base_name = UI +mod_ui_base_desc = すべてのゲームで共有される UI レイヤー：ツールバー、ゲーム内メニュー、セーブインジケーター、通知、そしてパネル・ボタン・リストの共通デザイン。 diff --git a/locale/ko.properties b/locale/ko.properties new file mode 100644 index 0000000..90135d4 --- /dev/null +++ b/locale/ko.properties @@ -0,0 +1,2 @@ +mod_ui_base_name = UI +mod_ui_base_desc = 모든 게임이 공유하는 인터페이스 레이어: 툴바, 인게임 메뉴, 저장 표시, 알림, 그리고 패널·버튼·목록의 공통 디자인입니다. diff --git a/locale/ru.properties b/locale/ru.properties new file mode 100644 index 0000000..019918e --- /dev/null +++ b/locale/ru.properties @@ -0,0 +1,2 @@ +mod_ui_base_name = UI +mod_ui_base_desc = Общий для всех игр слой интерфейса: панель инструментов, игровое меню, индикатор сохранения, уведомления и единый вид панелей, кнопок и списков. diff --git a/locale/ui_en.properties b/locale/ui_en.properties index e75ace5..6fbd52d 100644 --- a/locale/ui_en.properties +++ b/locale/ui_en.properties @@ -1,6 +1,4 @@ # --- scenes/battle/winground.tscn --- -mod_ui_base_name = UI -mod_ui_base_desc = Engine UI subsystem: widget toolkit (Widget/ModWidget/lists), ViewBox background viewport, ToolBox toolbar, GameMenu/SaveIcon, notification panels, UiKit design system and DeviceInput. ui/battle/victory = Victory ui/battle/victory/return = Continue ui/battle/victory/loot_title = Loot: @@ -102,6 +100,7 @@ ui/save/game_day = Day {day}, {time} ui/save/party_size = Party: {count} # --- GameMenu --- +menu/title = Menu menu/resume = Resume menu/save = Save menu/load = Load diff --git a/locale/ui_es.properties b/locale/ui_es.properties index 7c2f5f4..02eb876 100644 --- a/locale/ui_es.properties +++ b/locale/ui_es.properties @@ -1,6 +1,4 @@ # --- scenes/battle/winground.tscn --- -mod_ui_base_name = Interfaz -mod_ui_base_desc = Subsistema de interfaz del motor: kit de widgets (Widget/ModWidget/listas), visor de fondos ViewBox, barra de herramientas ToolBox, GameMenu/SaveIcon, paneles de notificaciones, el sistema de diseño UiKit y DeviceInput. ui/battle/victory = Victoria ui/battle/victory/return = Continuar ui/battle/victory/loot_title = Botín: @@ -102,6 +100,7 @@ ui/save/game_day = Día {day}, {time} ui/save/party_size = Grupo: {count} # --- GameMenu --- +menu/title = Menú menu/resume = Continuar menu/save = Guardar menu/load = Cargar diff --git a/locale/ui_ja.properties b/locale/ui_ja.properties index ddfa063..fdae693 100644 --- a/locale/ui_ja.properties +++ b/locale/ui_ja.properties @@ -1,6 +1,4 @@ # --- scenes/battle/winground.tscn --- -mod_ui_base_name = UI -mod_ui_base_desc = エンジンの UI サブシステム：ウィジェットキット（Widget/ModWidget/リスト）、背景ビューポート ViewBox、ツールバー ToolBox、GameMenu/SaveIcon、通知パネル、デザインシステム UiKit、DeviceInput。 ui/battle/victory = 勝利 ui/battle/victory/return = 続ける ui/battle/victory/loot_title = 戦利品： @@ -102,6 +100,7 @@ ui/save/game_day = {day} 日目、{time} ui/save/party_size = パーティ：{count} # --- GameMenu --- +menu/title = メニュー menu/resume = 再開 menu/save = セーブ menu/load = ロード diff --git a/locale/ui_ko.properties b/locale/ui_ko.properties index f5d0586..4184c1a 100644 --- a/locale/ui_ko.properties +++ b/locale/ui_ko.properties @@ -1,6 +1,4 @@ # --- scenes/battle/winground.tscn --- -mod_ui_base_name = UI -mod_ui_base_desc = 엔진 UI 하위 시스템: 위젯 키트(Widget/ModWidget/목록), 배경 뷰포트 ViewBox, 툴바 ToolBox, GameMenu/SaveIcon, 알림 패널, 디자인 시스템 UiKit, DeviceInput. ui/battle/victory = 승리 ui/battle/victory/return = 계속 ui/battle/victory/loot_title = 전리품: @@ -102,6 +100,7 @@ ui/save/game_day = {day}일째, {time} ui/save/party_size = 파티: {count} # --- GameMenu --- +menu/title = 메뉴 menu/resume = 계속 menu/save = 저장 menu/load = 불러오기 diff --git a/locale/ui_ru.properties b/locale/ui_ru.properties index 12997af..a302d5b 100644 --- a/locale/ui_ru.properties +++ b/locale/ui_ru.properties @@ -100,6 +100,7 @@ ui/save/game_day = День {day}, {time} ui/save/party_size = Отряд: {count} # --- GameMenu --- +menu/title = Меню menu/resume = Вернуться menu/save = Сохранить menu/load = Загрузить @@ -258,8 +259,6 @@ ui/journal/entry_of = Запись {0} из {1} ui/journal/finished = Завершено ui/journal/seals = Печати ui/journal/no_entries = Страницы этой записи ещё пусты. Чернила появятся, когда история сдвинется с места. -mod_ui_base_name = Интерфейс -mod_ui_base_desc = Подсистема UI движка: набор виджетов (Widget/ModWidget, списки), ViewBox фона, тулбар ToolBox, GameMenu/SaveIcon, панели уведомлений, дизайн-система UiKit и DeviceInput. Ядро работает с модом через контракты IWidget/IToolbarHost и мосты. tools/unsaved_title = Есть изменения tools/unsaved_text = У вас есть несохранённые изменения. Закрыть без сохранения? diff --git a/locale/ui_vi.properties b/locale/ui_vi.properties index c438cb2..cbb78ad 100644 --- a/locale/ui_vi.properties +++ b/locale/ui_vi.properties @@ -1,6 +1,4 @@ # --- scenes/battle/winground.tscn --- -mod_ui_base_name = Giao diện -mod_ui_base_desc = Hệ thống con giao diện của engine: bộ widget (Widget/ModWidget/danh sách), khung nhìn phông nền ViewBox, thanh công cụ ToolBox, GameMenu/SaveIcon, bảng thông báo, hệ thống thiết kế UiKit và DeviceInput. ui/battle/victory = Chiến thắng ui/battle/victory/return = Tiếp tục ui/battle/victory/loot_title = Chiến lợi phẩm: @@ -102,6 +100,7 @@ ui/save/game_day = Ngày {day}, {time} ui/save/party_size = Tổ đội: {count} # --- GameMenu --- +menu/title = Menu menu/resume = Tiếp tục menu/save = Lưu menu/load = Tải diff --git a/locale/ui_zh.properties b/locale/ui_zh.properties index cb1568b..fc0e202 100644 --- a/locale/ui_zh.properties +++ b/locale/ui_zh.properties @@ -1,6 +1,4 @@ # --- scenes/battle/winground.tscn --- -mod_ui_base_name = 界面 -mod_ui_base_desc = 引擎界面子系统：组件工具包（Widget/ModWidget/列表）、ViewBox 背景视口、ToolBox 工具栏、GameMenu/SaveIcon、通知面板、UiKit 设计系统以及 DeviceInput。 ui/battle/victory = 胜利 ui/battle/victory/return = 继续 ui/battle/victory/loot_title = 战利品： @@ -102,6 +100,7 @@ ui/save/game_day = 第 {day} 天，{time} ui/save/party_size = 队伍：{count} # --- GameMenu --- +menu/title = 菜单 menu/resume = 继续 menu/save = 保存 menu/load = 读取 diff --git a/locale/vi.properties b/locale/vi.properties new file mode 100644 index 0000000..c6f5a16 --- /dev/null +++ b/locale/vi.properties @@ -0,0 +1,2 @@ +mod_ui_base_name = UI +mod_ui_base_desc = Lớp giao diện mà mọi game dùng chung: thanh công cụ, menu trong game, biểu tượng lưu, thông báo và diện mạo thống nhất của bảng điều khiển, nút bấm, danh sách. diff --git a/locale/zh.properties b/locale/zh.properties new file mode 100644 index 0000000..93f1a8a --- /dev/null +++ b/locale/zh.properties @@ -0,0 +1,2 @@ +mod_ui_base_name = UI +mod_ui_base_desc = 所有游戏共用的界面层：工具栏、游戏内菜单、存档指示器、通知，以及面板、按钮和列表的统一外观。 diff --git a/manifest.json b/manifest.json index 36ab7d5..74d66ed 100644 --- a/manifest.json +++ b/manifest.json @@ -3,7 +3,7 @@ "name": "UI", "version": "1.0.0", "author": "ct", - "description": "Engine UI subsystem: widget toolkit (Widget/ModWidget/lists), ViewBox background viewport, ToolBox toolbar, GameMenu/SaveIcon, notification panels, UiKit design system, DeviceInput. Kernel keeps only contracts (IWidget, IDialogBox, IToolbarHost, ISaveIconHost, IBackgroundView, IUiLazyConstruct, MenuRegistry, ToolFactory, NotificationBuffer, SceneEventController, CthangoverTheme/UiTokens boot styling) and drives this mod through those seams.", + "description": "The interface layer every game shares: the toolbar, the in-game menu, the save indicator, notifications and the common look of panels, buttons and lists.", "category": "ui", "depends": [], "sources": [ diff --git a/src/Menu/GameMenu.cs b/src/Menu/GameMenu.cs index 72e05d6..fb1e5f6 100644 --- a/src/Menu/GameMenu.cs +++ b/src/Menu/GameMenu.cs @@ -22,6 +22,7 @@ namespace Cthangover.Mods.Interface.Menu private ISettingsPanel _settingsPanel; private ISaveLoadPanel _saveLoadPanel; private Button _saveBtn; + private Label _title; private readonly Dictionary _btnKeys = new(); /// Wires menu buttons, instantiates the hidden settings and save/load panels from the , and subscribes to language changes. @@ -42,6 +43,7 @@ namespace Cthangover.Mods.Interface.Menu _btnKeys[GetNode