Add mod documentation in seven languages

.gitignore

@@ -12,6 +12,7 @@ obj/
 gen/
 obj/
 bin/
+art_sources/
 
 *.tres~
 *.tscn~

docs/en.md

@@ -0,0 +1,64 @@
+# 2D Shell — the frame every 2D game is drawn in
+
+2D Shell is the empty screen that 2D games fill: the picture of the current place, the clock and toolbar at the top, room for panels, and the notifications corner. It shows nothing by itself. Content mods put their own layers into it — the Dialog Engine adds the text box and choices of a visual novel, the RPG mod adds the walkable tile map — so a novel and a tile-map RPG share the same frame, the same toolbar and the same menus.
+
+Every 2D game includes it: Cthangover, My Novel and RPG Plus.
+
+![The same shell in two games: a Cthangover scene with the dialog box and choices, and the RPG Plus village with the tile map; both have the clock at the top left and the toolbar at the top right.](assets/two-games.jpg)
+
+## What you see on screen
+
+![A Cthangover scene: the kitchen background, the clock and a ration counter at the top left, the toolbar at the top right, the choices "Leave" and "Cook", and the text box at the bottom.](assets/novel-scene.jpg)
+
+In this scene, the shell provides:
+
+- **the picture of the place** — the kitchen, with its time-of-day shading and lights (Time Engine);
+- **the top bar** — the clock at the top left, the toolbar at the top right, and in the middle the save indicator and, at night, the portable lamp;
+- **the notifications corner** under the clock;
+- **room for panels** — the bag, map or journal open above the scene.
+
+The text box and the choices come from the Dialog Engine, and the ration counter from Cooking — they are layers that those mods add to the shell.
+
+## Layers, from back to front
+
+```text
+BaseScene
+└── Scene
+    ├── ModFirstPanel        mods' layers behind everything
+    ├── ViewBox              the place: lights, background, foreground, last ground
+    ├── (content layer)      added by a content mod, e.g. the dialog canvas or the RPG world
+    ├── TopView              clock, toolbar, save indicator, lamp
+    ├── ModBeforeUIPanel     toolbar panels: bag, map, journal, menu…
+    ├── NotificationPanel    messages in the top-left corner
+    └── ModLastPanel         overlays above all, e.g. the crafting window
+```
+
+Later layers are drawn over earlier ones.
+
+## For mod authors
+
+**Add a content layer with a scene patch.** A patch is a `.tscn` in your mod's `patches/` folder at the same path as the shell's scene. It instances the shell's scene and adds or changes nodes. The Dialog Engine's patch adds the dialog canvas right after the view box:
+
+```text
+patches/scenes/ui/base_scene.tscn
+```
+
+```text
+[ext_resource type="PackedScene" path="res://mods/shell2d_base/scenes/ui/base_scene.tscn" id="1_target"]
+[ext_resource type="PackedScene" path="res://scenes/ui/dialog_canvas.tscn" id="3_dialog"]
+
+[node name="BaseScene" instance=ExtResource("1_target")]
+
+[node name="DialogCanvas" parent="Scene" index="2" instance=ExtResource("3_dialog")]
+```
+
+The RPG mod adds its `RpgWorldHost` the same way, so a game with both shows the tile map and, over it, dialog lines.
+
+**Add a panel without a patch.** A toolbar panel or an overlay is declared in your manifest's `ui` section with one of the shell's slots: `ModBeforeUIPanel`, `ModLastPanel` or the view box's `Lastground`. See the UI mod's guide for the fields.
+
+**Depend on it.** A mod that needs the 2D frame lists `shell2d_base` in `depends`; the shell itself brings Time Engine and UI.
+
+## If something goes wrong
+
+1. **A black screen with only the toolbar.** No content mod is filling the shell (a Dialog Engine or RPG mod is missing from the game), or the scene has no background.
+2. **A panel appears behind the scene.** Its manifest names a slot that is drawn too early; use `ModBeforeUIPanel` or `ModLastPanel`.

docs/es.md

@@ -0,0 +1,64 @@
+# 2D Shell — el marco donde se dibuja cualquier juego 2D
+
+2D Shell es la pantalla vacía que los juegos 2D rellenan: la imagen del lugar actual, el reloj y la barra de herramientas arriba, espacio para paneles y la esquina de notificaciones. Por sí sola no muestra nada. Los mods de contenido meten en ella sus propias capas: el Dialog Engine añade el cuadro de texto y las opciones de una novela visual, y el mod RPG añade el mapa de tiles transitable, de modo que una novela y un RPG de tiles comparten el mismo marco, la misma barra de herramientas y los mismos menús.
+
+Lo incluye todo juego 2D: Cthangover, My Novel y RPG Plus.
+
+![La misma carcasa en dos juegos: una escena de Cthangover con el cuadro de texto y las opciones, y la aldea de RPG Plus con el mapa de tiles; ambos tienen el reloj arriba a la izquierda y la barra de herramientas arriba a la derecha.](assets/two-games.jpg)
+
+## Lo que ves en pantalla
+
+![Una escena de Cthangover: el fondo de la cocina, el reloj y un contador de raciones arriba a la izquierda, la barra de herramientas arriba a la derecha, las opciones «Leave» y «Cook», y el cuadro de texto abajo.](assets/novel-scene.jpg)
+
+En esta escena, la carcasa aporta:
+
+- **la imagen del lugar** — la cocina, con su sombreado según la hora y sus luces (Time Engine);
+- **la barra superior** — el reloj arriba a la izquierda, la barra de herramientas arriba a la derecha y, en medio, el indicador de guardado y, de noche, la lámpara portátil;
+- **la esquina de notificaciones** bajo el reloj;
+- **espacio para paneles** — la bolsa, el mapa o el diario se abren sobre la escena.
+
+El cuadro de texto y las opciones vienen del Dialog Engine, y el contador de raciones de Cooking: son capas que esos mods añaden a la carcasa.
+
+## Las capas, de atrás hacia delante
+
+```text
+BaseScene
+└── Scene
+    ├── ModFirstPanel        capas de mods por detrás de todo
+    ├── ViewBox              el lugar: luces, fondo, primer plano, Lastground
+    ├── (content layer)      capa de un mod de contenido, p. ej. el lienzo de diálogos o el mundo RPG
+    ├── TopView              reloj, barra de herramientas, indicador de guardado, lámpara
+    ├── ModBeforeUIPanel     paneles de la barra: bolsa, mapa, diario, menú…
+    ├── NotificationPanel    mensajes en la esquina superior izquierda
+    └── ModLastPanel         capas superpuestas sobre todo, p. ej. la ventana de la mesa de trabajo
+```
+
+Las capas posteriores se dibujan sobre las anteriores.
+
+## Para autores de mods
+
+**Añadir una capa de contenido con un parche de escena.** Un parche es un `.tscn` en la carpeta `patches/` de tu mod, en la misma ruta que la escena de la carcasa. Instancia la escena de la carcasa y añade o cambia nodos. El parche del Dialog Engine añade el lienzo de diálogos justo después del visor:
+
+```text
+patches/scenes/ui/base_scene.tscn
+```
+
+```text
+[ext_resource type="PackedScene" path="res://mods/shell2d_base/scenes/ui/base_scene.tscn" id="1_target"]
+[ext_resource type="PackedScene" path="res://scenes/ui/dialog_canvas.tscn" id="3_dialog"]
+
+[node name="BaseScene" instance=ExtResource("1_target")]
+
+[node name="DialogCanvas" parent="Scene" index="2" instance=ExtResource("3_dialog")]
+```
+
+El mod RPG añade su `RpgWorldHost` del mismo modo, así que un juego con ambos muestra el mapa de tiles y, encima, las líneas de diálogo.
+
+**Añadir un panel sin parche.** Un panel de la barra o una capa superpuesta se declara en la sección `ui` del manifiesto con uno de los slots de la carcasa: `ModBeforeUIPanel`, `ModLastPanel` o el `Lastground` del visor. Los campos están en la guía del mod UI.
+
+**Declara la dependencia.** Un mod que necesite el marco 2D lista `shell2d_base` en `depends`; la carcasa de por sí trae Time Engine y UI.
+
+## Si algo falla
+
+1. **Una pantalla negra con solo la barra de herramientas.** Ningún mod de contenido está rellenando la carcasa (falta el Dialog Engine o el mod RPG en el juego), o la escena no tiene fondo.
+2. **Un panel aparece detrás de la escena.** Su manifiesto nombra un slot que se dibuja demasiado pronto; usa `ModBeforeUIPanel` o `ModLastPanel`.

docs/ja.md

@@ -0,0 +1,64 @@
+# 2D Shell — すべての 2D ゲームを描くための枠
+
+2D Shell は、2D ゲームが中身を満たす空のスクリーンです。現在の場所の絵、上の時計とツールバー、パネルの置き場所、通知の隅から成ります。単独では何も表示しません。コンテンツ MOD がそれぞれのレイヤーを重ねます。Dialog Engine はビジュアルノベルのテキストボックスと選択肢を、RPG MOD は歩き回れるタイルマップを追加します。ノベルもタイルマップの RPG も、同じ枠、同じツールバー、同じメニューを共有するのです。
+
+すべての 2D ゲームがこれを含みます。Cthangover、My Novel、RPG Plus です。
+
+![二つのゲームで同じシェル:テキストボックスと選択肢つきの Cthangover のシーンと、タイルマップつきの RPG Plus の村。どちらも時計が左上、ツールバーが右上にあります。](assets/two-games.jpg)
+
+## 画面に見えるもの
+
+![Cthangover のシーン:台所の背景、左上の時計と配給カウンター、右上のツールバー、選択肢「Leave」「Cook」、下のテキストボックス。](assets/novel-scene.jpg)
+
+このシーンでシェルが担っているのは:
+
+- **場所の絵** — 台所。時刻に応じた色調と照明つき(Time Engine);
+- **上のバー** — 左上の時計、右上のツールバー、中央のセーブインジケーター、夜には携帯ランプ;
+- **通知の隅** — 時計の下;
+- **パネルの空き** — インベントリ、マップ、日誌はシーンの上に開きます。
+
+テキストボックスと選択肢は Dialog Engine から、配給カウンターは Cooking から来ています。どちらも各 MOD がシェルに重ねるレイヤーです。
+
+## レイヤー:後ろから前へ
+
+```text
+BaseScene
+└── Scene
+    ├── ModFirstPanel        すべての後ろに置かれる MOD のレイヤー
+    ├── ViewBox              場所そのもの:照明、背景、前景、Lastground
+    ├── (content layer)      コンテンツ MOD が追加するレイヤー。例:ダイアログのキャンバスや RPG の世界
+    ├── TopView              時計、ツールバー、セーブインジケーター、ランプ
+    ├── ModBeforeUIPanel     ツールバーのパネル:インベントリ、マップ、日誌、メニュー…
+    ├── NotificationPanel    左上隅のメッセージ
+    └── ModLastPanel         すべての上に重なるオーバーレイ。例:作業台のウィンドウ
+```
+
+後のレイヤーほど手前に描かれます。
+
+## MOD 作者向け
+
+**シーンパッチでコンテンツレイヤーを追加する。** パッチとは、MOD の `patches/` フォルダーにシェルのシーンと同じパスで置く `.tscn` のことです。シェルのシーンをインスタンス化し、ノードを追加・変更します。Dialog Engine のパッチは、ダイアログのキャンバスを ViewBox の直後に挿入します:
+
+```text
+patches/scenes/ui/base_scene.tscn
+```
+
+```text
+[ext_resource type="PackedScene" path="res://mods/shell2d_base/scenes/ui/base_scene.tscn" id="1_target"]
+[ext_resource type="PackedScene" path="res://scenes/ui/dialog_canvas.tscn" id="3_dialog"]
+
+[node name="BaseScene" instance=ExtResource("1_target")]
+
+[node name="DialogCanvas" parent="Scene" index="2" instance=ExtResource("3_dialog")]
+```
+
+RPG MOD も同じやり方で `RpgWorldHost` を足します。両方を含むゲームではタイルマップが表示され、その上にセリフが重なります。
+
+**パッチなしでパネルを追加する。** ツールバーのパネルやオーバーレイは、manifest の `ui` セクションでシェルのスロットの一つ(`ModBeforeUIPanel`、`ModLastPanel`、ビューボックスの `Lastground`)を指定して宣言します。フィールドの詳細は UI MOD のガイドを見てください。
+
+**依存関係を宣言する。** 2D の枠を必要とする MOD は `depends` に `shell2d_base` を書きます。シェル自身が Time Engine と UI を連れてきます。
+
+## うまく動かないとき
+
+1. **ツールバーだけの真っ黒な画面。** シェルを満たすコンテンツ MOD がありません(Dialog Engine か RPG MOD がゲームに含まれていない)、またはシーンに背景がありません。
+2. **パネルがシーンの後ろに表示される。** その manifest が、描画が早すぎるスロットを指定しています。`ModBeforeUIPanel` か `ModLastPanel` を使ってください。

docs/ko.md

@@ -0,0 +1,64 @@
+# 2D Shell — 모든 2D 게임이 그려지는 틀
+
+2D Shell은 2D 게임이 채워 넣는 빈 화면입니다. 현재 장소의 그림, 위쪽의 시계와 툴바, 패널이 들어갈 자리, 알림 구석으로 이루어집니다. 스스로는 아무것도 보여 주지 않습니다. 콘텐츠 모드가 각자의 레이어를 얹습니다. Dialog Engine은 비주얼 노벨의 텍스트 상자와 선택지를, RPG 모드는 걸어 다닐 수 있는 타일 맵을 더합니다. 덕분에 노벨 게임과 타일 맵 RPG가 같은 틀, 같은 툴바, 같은 메뉴를 공유합니다.
+
+모든 2D 게임에 들어 있습니다. Cthangover, My Novel, RPG Plus가 그렇습니다.
+
+![두 게임에서 같은 셸: 텍스트 상자와 선택지가 있는 Cthangover 장면, 타일 맵이 있는 RPG Plus 마을. 둘 다 시계는 왼쪽 위, 툴바는 오른쪽 위에 있습니다.](assets/two-games.jpg)
+
+## 화면에 보이는 것들
+
+![Cthangover 장면: 부엌 배경, 왼쪽 위 시계와 배급 카운터, 오른쪽 위 툴바, Leave와 Cook 선택지, 아래 텍스트 상자.](assets/novel-scene.jpg)
+
+이 장면에서 셸이 제공하는 것:
+
+- **장소의 그림** — 부엌. 시간대에 따른 색조와 조명 포함(Time Engine);
+- **위쪽 바** — 왼쪽 위 시계, 오른쪽 위 툴바, 가운데 저장 표시, 밤에는 휴대용 램프;
+- **알림 구석** — 시계 아래;
+- **패널 자리** — 인벤토리, 지도, 일지는 장면 위로 열립니다.
+
+텍스트 상자와 선택지는 Dialog Engine이, 배급 카운터는 Cooking이 가져옵니다. 이것들은 해당 모드들이 셸에 얹는 레이어입니다.
+
+## 레이어: 뒤에서 앞으로
+
+```text
+BaseScene
+└── Scene
+    ├── ModFirstPanel        모든 것 뒤에 깔리는 모드 레이어
+    ├── ViewBox              장면 그 자체: 조명, 배경, 전경, Lastground
+    ├── (content layer)      콘텐츠 모드가 추가하는 레이어. 예: 대화 캔버스나 RPG 세계
+    ├── TopView              시계, 툴바, 저장 표시, 램프
+    ├── ModBeforeUIPanel     툴바 패널: 인벤토리, 지도, 일지, 메뉴…
+    ├── NotificationPanel    왼쪽 위 알림 메시지
+    └── ModLastPanel         모든 것 위에 겹쳐지는 오버레이. 예: 작업대 창
+```
+
+나중 레이어가 먼저 그려진 레이어 위에 놓입니다.
+
+## 모드 제작자를 위해
+
+**장면 패치로 콘텐츠 레이어 추가하기.** 패치는 모드의 `patches/` 폴더에 셸 장면과 같은 경로로 두는 `.tscn`입니다. 셸 장면을 인스턴스화하고 노드를 더하거나 바꿉니다. Dialog Engine의 패치는 대화 캔버스를 ViewBox 바로 뒤에 삽입합니다:
+
+```text
+patches/scenes/ui/base_scene.tscn
+```
+
+```text
+[ext_resource type="PackedScene" path="res://mods/shell2d_base/scenes/ui/base_scene.tscn" id="1_target"]
+[ext_resource type="PackedScene" path="res://scenes/ui/dialog_canvas.tscn" id="3_dialog"]
+
+[node name="BaseScene" instance=ExtResource("1_target")]
+
+[node name="DialogCanvas" parent="Scene" index="2" instance=ExtResource("3_dialog")]
+```
+
+RPG 모드도 같은 방식으로 자기 `RpgWorldHost`를 더합니다. 둘 다 있는 게임에서는 타일 맵 위로 대사가 겹쳐 보입니다.
+
+**패치 없이 패널 추가하기.** 툴바 패널이나 오버레이는 manifest의 `ui` 섹션에 셸 슬롯 하나(`ModBeforeUIPanel`, `ModLastPanel`, 뷰 박스의 `Lastground`)를 지정해 선언합니다. 필드는 UI 모드 가이드를 참고하세요.
+
+**의존성 선언하기.** 2D 틀이 필요한 모드는 `depends`에 `shell2d_base`를 적습니다. 셸 자체가 Time Engine과 UI를 데려옵니다.
+
+## 문제가 생겼을 때
+
+1. **툴바만 있는 검은 화면.** 셸을 채우는 콘텐츠 모드가 없는 것입니다(게임에 Dialog Engine이나 RPG 모드가 없음). 장면에 배경이 없을 수도 있습니다.
+2. **패널이 장면 뒤에 나타난다.** 그 manifest이 너무 일찍 그려지는 슬롯을 지정한 것입니다. `ModBeforeUIPanel`이나 `ModLastPanel`을 쓰세요.

docs/ru.md

@@ -0,0 +1,64 @@
+# 2D Shell — каркас, в котором рисуется каждая 2D-игра
+
+2D Shell — это пустой экран, который 2D-игры наполняют: картинка текущего места, часы и панель инструментов сверху, место под панели и уголок уведомлений. Сам по себе он ничего не показывает. Контентные моды вставляют в него свои слои — Dialog Engine приносит текстовое окно и варианты выбора визуальной новеллы, а мод RPG — тайловую карту, по которой можно ходить, — поэтому новелла и тайловая RPG пользуются одним каркасом, одной панелью инструментов и одними меню.
+
+Он входит в каждую 2D-игру: Cthangover, My Novel и RPG Plus.
+
+![Одна и та же оболочка в двух играх: сцена Cthangover с текстовым окном и вариантами выбора и деревня RPG Plus с тайловой картой; у обеих часы слева вверху и панель инструментов справа вверху.](assets/two-games.jpg)
+
+## Что видно на экране
+
+![Сцена Cthangover: фон кухни, слева вверху часы и счётчик пайков, справа вверху панель инструментов, варианты выбора «Leave» и «Cook», внизу текстовое окно.](assets/novel-scene.jpg)
+
+Вот что даёт оболочка в этой сцене:
+
+- **картинка места** — кухня со своей подсветкой в зависимости от времени суток и огнями (Time Engine);
+- **верхняя полоса** — часы слева вверху, панель инструментов справа вверху, а посередине индикатор сохранения и по ночам переносной фонарь;
+- **уголок уведомлений** под часами;
+- **место для панелей** — сумка, карта или журнал открываются поверх сцены.
+
+Текстовое окно и варианты выбора добавляет Dialog Engine, счётчик пайков — Cooking: это слои, которые эти моды кладут в оболочку.
+
+## Слои: от задних к передним
+
+```text
+BaseScene
+└── Scene
+    ├── ModFirstPanel        слои модов позади всего остального
+    ├── ViewBox              само место: освещение, фон, передний план, Lastground
+    ├── (content layer)      слой контентного мода, например холст диалогов или мир RPG
+    ├── TopView              часы, панель инструментов, индикатор сохранения, фонарь
+    ├── ModBeforeUIPanel     панели инструментов: сумка, карта, журнал, меню…
+    ├── NotificationPanel    сообщения в левом верхнем углу
+    └── ModLastPanel         оверлеи поверх всего, например окно верстака
+```
+
+Поздние слои рисуются поверх ранних.
+
+## Авторам модов
+
+**Добавить слой контента патчем сцены.** Патч — это `.tscn` в папке `patches/` вашего мода по тому же пути, что и сцена оболочки. Он подставляет сцену оболочки и добавляет или меняет узлы. Патч Dialog Engine вставляет холст диалогов сразу после ViewBox:
+
+```text
+patches/scenes/ui/base_scene.tscn
+```
+
+```text
+[ext_resource type="PackedScene" path="res://mods/shell2d_base/scenes/ui/base_scene.tscn" id="1_target"]
+[ext_resource type="PackedScene" path="res://scenes/ui/dialog_canvas.tscn" id="3_dialog"]
+
+[node name="BaseScene" instance=ExtResource("1_target")]
+
+[node name="DialogCanvas" parent="Scene" index="2" instance=ExtResource("3_dialog")]
+```
+
+Мод RPG тем же способом добавляет свой `RpgWorldHost`, поэтому игра с обоими показывает тайловую карту, а поверх неё — реплики диалогов.
+
+**Добавить панель без патча.** Панель инструментов или оверлей объявляется в секции `ui` манифеста с одним из слотов оболочки: `ModBeforeUIPanel`, `ModLastPanel` или `Lastground` у блока просмотра. Поля перечислены в руководстве мода UI.
+
+**Объявите зависимость.** Моду, которому нужен 2D-каркас, следует указать `shell2d_base` в `depends`; сама оболочка приносит с собой Time Engine и UI.
+
+## Если что-то пошло не так
+
+1. **Чёрный экран, на котором есть только панель инструментов.** Оболочку не заполняет ни один контентный мод (в игре нет Dialog Engine или мода RPG), либо у сцены нет фона.
+2. **Панель оказалась позади сцены.** В её манифесте указан слот, который рисуется слишком рано; используйте `ModBeforeUIPanel` или `ModLastPanel`.

docs/vi.md

@@ -0,0 +1,64 @@
+# 2D Shell — khung vẽ của mọi game 2D
+
+2D Shell là màn hình trống mà các game 2D lấp đầy: bức tranh về nơi đang đứng, đồng hồ và thanh công cụ ở trên, chỗ cho các bảng điều khiển, và góc thông báo. Tự nó nó không hiện gì cả. Các mod nội dung đặt lớp của mình lên đó — Dialog Engine thêm hộp thoại và các lựa chọn của visual novel, còn mod RPG thêm bản đồ tile đi lại được — nên một game novel và một game tile-map RPG cùng dùng một khung, một thanh công cụ và một bộ menu.
+
+2D Shell có mặt trong mọi game 2D: Cthangover, My Novel và RPG Plus.
+
+![Cùng một lớp vỏ trong hai game: cảnh Cthangover với hộp thoại và các lựa chọn, và làng của RPG Plus với bản đồ tile; cả hai đều có đồng hồ ở góc trên trái và thanh công cụ ở góc trên phải.](assets/two-games.jpg)
+
+## Bạn thấy gì trên màn hình
+
+![Một cảnh Cthangover: nền căn bếp, đồng hồ và bộ đếm khẩu phần trên bên trái, thanh công cụ trên bên phải, hai lựa chọn "Leave" và "Cook", và hộp văn bản ở dưới.](assets/novel-scene.jpg)
+
+Trong cảnh này, lớp vỏ cung cấp:
+
+- **bức tranh nơi chốn** — căn bếp, kèm sắc màu theo giờ và ánh đèn (Time Engine);
+- **thanh trên cùng** — đồng hồ góc trên trái, thanh công cụ góc trên phải, ở giữa là biểu tượng lưu và đèn cầm tay ban đêm;
+- **góc thông báo** dưới đồng hồ;
+- **chỗ cho bảng điều khiển** — túi đồ, bản đồ hay nhật ký mở đè lên cảnh.
+
+Hộp văn bản và các lựa chọn đến từ Dialog Engine, bộ đếm khẩu phần đến từ Cooking — đây là các lớp mà những mod này đặt lên vỏ.
+
+## Các lớp, từ sau ra trước
+
+```text
+BaseScene
+└── Scene
+    ├── ModFirstPanel        các lớp của mod nằm sau tất cả
+    ├── ViewBox              chính là nơi chốn: đèn, nền, tiền cảnh, Lastground
+    ├── (content layer)      lớp do mod nội dung thêm vào, ví dụ canvas hội thoại hay thế giới RPG
+    ├── TopView              đồng hồ, thanh công cụ, biểu tượng lưu, đèn
+    ├── ModBeforeUIPanel     các bảng trên thanh công cụ: túi đồ, bản đồ, nhật ký, menu…
+    ├── NotificationPanel    tin nhắn ở góc trên bên trái
+    └── ModLastPanel         lớp phủ trên cùng tất cả, ví dụ cửa sổ bàn chế tạo
+```
+
+Lớp nào vẽ sau sẽ đè lên lớp vẽ trước.
+
+## Cho tác giả mod
+
+**Thêm lớp nội dung bằng bản vá cảnh.** Bản vá (patch) là một tệp `.tscn` trong thư mục `patches/` của mod bạn, đặt cùng đường dẫn với cảnh của lớp vỏ. Nó khởi tạo cảnh của vỏ rồi thêm hoặc sửa node. Patch của Dialog Engine chèn canvas hội thoại ngay sau ViewBox:
+
+```text
+patches/scenes/ui/base_scene.tscn
+```
+
+```text
+[ext_resource type="PackedScene" path="res://mods/shell2d_base/scenes/ui/base_scene.tscn" id="1_target"]
+[ext_resource type="PackedScene" path="res://scenes/ui/dialog_canvas.tscn" id="3_dialog"]
+
+[node name="BaseScene" instance=ExtResource("1_target")]
+
+[node name="DialogCanvas" parent="Scene" index="2" instance=ExtResource("3_dialog")]
+```
+
+Mod RPG cũng thêm `RpgWorldHost` của mình theo cách đó, nên game có cả hai sẽ hiện bản đồ tile, phía trên là lời thoại.
+
+**Thêm bảng điều khiển không cần patch.** Bảng trên thanh công cụ hay lớp phủ được khai báo trong mục `ui` của manifest với một trong các khe của vỏ: `ModBeforeUIPanel`, `ModLastPanel` hoặc `Lastground` của khung xem. Các trường xem trong hướng dẫn của mod UI.
+
+**Khai báo phụ thuộc.** Mod cần khung 2D hãy liệt kê `shell2d_base` trong `depends`; bản thân lớp vỏ kéo theo Time Engine và UI.
+
+## Khi có trục trặc
+
+1. **Màn hình đen, chỉ còn thanh công cụ.** Không mod nội dung nào đang lấp đầy lớp vỏ (thiếu Dialog Engine hoặc mod RPG trong game), hoặc cảnh không có nền.
+2. **Bảng điều khiển hiện sau cảnh.** Manifest của nó nêu một khe bị vẽ quá sớm; hãy dùng `ModBeforeUIPanel` hoặc `ModLastPanel`.

docs/zh.md

@@ -0,0 +1,64 @@
+# 2D Shell — 每一款 2D 游戏都在其中绘制的框架
+
+2D Shell 是一块空白的屏幕，等 2D 游戏来填充：当前地点的画面、顶部的时钟和工具栏、面板的容身之处，以及通知一角。它自己什么都不显示。内容模组把自己的图层放进这里——Dialog Engine 加上视觉小说的文本框和选项，RPG 模组加上可行走的图块地图——因此小说游戏和图块 RPG 共用同一个框架、同一条工具栏和同一套菜单。
+
+每款 2D 游戏都包含它：Cthangover、My Novel 和 RPG Plus。
+
+![同一个外壳出现在两款游戏中：带文本框和选项的 Cthangover 场景，带图块地图的 RPG Plus 村庄；两者的时钟都在左上角，工具栏都在右上角。](assets/two-games.jpg)
+
+## 屏幕上看到的东西
+
+![一幕 Cthangover 场景：厨房背景，左上角是时钟和口粮计数器，右上角是工具栏，选项为“Leave”和“Cook”，底部是文本框。](assets/novel-scene.jpg)
+
+在这一幕中，外壳提供了：
+
+- **地点的画面** — 厨房，带有随时间变化的色调和灯光（Time Engine）；
+- **顶栏** — 左上角时钟、右上角工具栏，中间是存档指示器，夜间还有便携提灯；
+- **通知一角** — 时钟下方；
+- **面板空间** — 背包、地图或日志会叠在场景上方打开。
+
+文本框和选项来自 Dialog Engine，口粮计数器来自 Cooking——它们都是这些模组加到外壳上的图层。
+
+## 图层：从后到前
+
+```text
+BaseScene
+└── Scene
+    ├── ModFirstPanel        各模组垫在最后面的图层
+    ├── ViewBox              场景本身：灯光、背景、前景、Lastground
+    ├── (content layer)      内容模组添加的图层，例如对话框画布或 RPG 世界
+    ├── TopView              时钟、工具栏、存档指示器、提灯
+    ├── ModBeforeUIPanel     工具栏面板：背包、地图、日志、菜单…
+    ├── NotificationPanel    左上角的消息
+    └── ModLastPanel         盖在一切之上的覆盖层，例如工作台窗口
+```
+
+靠后的图层绘制在靠前图层之上。
+
+## 给模组作者
+
+**用场景补丁添加内容图层。** 补丁是放在你模组 `patches/` 文件夹里的一个 `.tscn`，路径与外壳场景相同。它实例化外壳场景并增加或修改节点。Dialog Engine 的补丁就是把对话框画布插到 ViewBox 之后：
+
+```text
+patches/scenes/ui/base_scene.tscn
+```
+
+```text
+[ext_resource type="PackedScene" path="res://mods/shell2d_base/scenes/ui/base_scene.tscn" id="1_target"]
+[ext_resource type="PackedScene" path="res://scenes/ui/dialog_canvas.tscn" id="3_dialog"]
+
+[node name="BaseScene" instance=ExtResource("1_target")]
+
+[node name="DialogCanvas" parent="Scene" index="2" instance=ExtResource("3_dialog")]
+```
+
+RPG 模组用同样的方式添加自己的 `RpgWorldHost`，因此两者齐全的游戏会显示图块地图，其上再叠加对话文本。
+
+**不用补丁添加面板。** 工具栏面板或覆盖层在 manifest 的 `ui` 一节中声明，并使用外壳的某个槽位：`ModBeforeUIPanel`、`ModLastPanel`，或视图框的 `Lastground`。字段说明见 UI 模组的指南。
+
+**声明依赖。** 需要 2D 框架的模组应在 `depends` 中列出 `shell2d_base`；外壳本身会带上 Time Engine 和 UI。
+
+## 出现问题时
+
+1. **黑屏，只有工具栏。** 没有内容模组填充外壳（游戏缺少 Dialog Engine 或 RPG 模组），或者场景没有背景。
+2. **面板出现在场景后面。** 它的 manifest 用了绘制过早的槽位；改用 `ModBeforeUIPanel` 或 `ModLastPanel`。

locale/en.properties

@@ -1,2 +1,2 @@
 mod_shell2d_base_name = 2D Shell
-mod_shell2d_base_desc = 2D presentation platform: base shell scene with the view box, toolbar, panel slots and notifications. Parent for all 2D mods; content mods fill the shell through scene patches.
+mod_shell2d_base_desc = The frame every 2D game is drawn in: the background view box, the toolbar, panel slots and notifications that content mods fill.

locale/es.properties

@@ -0,0 +1,2 @@
+mod_shell2d_base_name = Carcasa 2D
+mod_shell2d_base_desc = El marco donde se dibuja cualquier juego 2D: el visor de fondos, la barra de herramientas, los slots para paneles y las notificaciones que rellenan los mods de contenido.

locale/ja.properties

@@ -0,0 +1,2 @@
+mod_shell2d_base_name = 2D シェル
+mod_shell2d_base_desc = あらゆる 2D ゲームが描かれる土台:背景ビューボックス、ツールバー、パネルスロット、通知。コンテンツ MOD がここに中身を重ねます。

locale/ko.properties

@@ -0,0 +1,2 @@
+mod_shell2d_base_name = 2D 셸
+mod_shell2d_base_desc = 모든 2D 게임이 그려지는 틀: 배경 뷰 박스, 툴바, 패널 슬롯, 알림. 콘텐츠 모드가 여기를 채웁니다.

locale/ru.properties

@@ -1,2 +1,2 @@
 mod_shell2d_base_name = 2D-оболочка
-mod_shell2d_base_desc = Базовая 2D-платформа: сцена-оболочка с ViewBox, тулбаром, слотами панелей и уведомлениями. Родитель для всех 2D-модов; контент-моды наполняют оболочку через патчи сцен.
+mod_shell2d_base_desc = Каркас, в котором рисуется каждая 2D-игра: блок просмотра фона, панель инструментов, слоты панелей и уведомления, которые заполняют контентные моды.

locale/vi.properties

@@ -0,0 +1,2 @@
+mod_shell2d_base_name = Vỏ 2D
+mod_shell2d_base_desc = Khung nơi mọi game 2D được vẽ lên: khung xem nền, thanh công cụ, các khe bảng điều khiển và thông báo — mod nội dung sẽ lấp đầy chúng.

locale/zh.properties

@@ -0,0 +1,2 @@
+mod_shell2d_base_name = 2D 外壳
+mod_shell2d_base_desc = 每一款 2D 游戏都在其中绘制的框架：背景视口、工具栏、面板槽位和通知，由内容模组填充。

manifest.json

@@ -3,7 +3,7 @@
   "name": "2D Shell",
   "version": "1.0.0",
   "author": "ct",
-  "description": "2D presentation platform: base shell scene with the view box, toolbar, panel slots and notifications. Parent for all 2D mods; content mods fill the shell through scene patches.",
+  "description": "The frame every 2D game is drawn in: the background view box, the toolbar, panel slots and notifications that content mods fill.",
   "category": "engine, library",
   "depends": ["time_base>=1", "ui_base>=1"],
   "ui": []