Add mod documentation in seven languages
This commit is contained in:
cthangover committed
1 parent
e4666ea420
commit
a11af1f342
18 files changed
+687
-8
No files matched your search
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 66 KiB |
+97
@@ -0,0 +1,97 @@
|
||||
# Schemas — descriptions of actions, commands and data fields
|
||||
|
||||
Schemas is a library: it lets every mod describe, as data, what its scenario actions take, what its DSL commands look like and which fields its kinds of data have. From one such description the tools build forms, pickers and checks, so an author fills in a form instead of remembering parameter names, and a mistake is reported before the game is run.
|
||||
|
||||
This mod has no window of its own. What you see of it is shown by other tools:
|
||||
|
||||
- **Schema Tools** — the command palette and the Data Editor window;
|
||||
- **Validator** — unknown or missing parameters and broken references in its report;
|
||||
- the **items and characters editors** — fields that other mods add to items and characters.
|
||||
|
||||
## From a description to a form and a check
|
||||
|
||||
```text
|
||||
items_base/schemas/items_base.json the description, next to the action's code
|
||||
│
|
||||
▼
|
||||
schema catalog (all mods, in load order)
|
||||
│
|
||||
├──► form in the command palette one field per parameter
|
||||
├──► scenario line action item.remove id=… count=…
|
||||
└──► checker same verdict in the palette and in the validator
|
||||
```
|
||||
|
||||
Items Engine describes its action `item.remove` like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"Id": "item.remove",
|
||||
"Name": "items/schema/remove",
|
||||
"Description": "items/schema/remove_desc",
|
||||
"Category": "items",
|
||||
"Params": [
|
||||
{ "Key": "id", "Type": "ref", "Kind": "item", "Required": true, "Name": "items/schema/field/item" },
|
||||
{ "Key": "count", "Type": "int", "Default": "1", "Name": "items/schema/field/count" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The command palette of RPG Plus shows it as a form: **Item** is a list of the game's items (type `ref`, kind `item`), **Count** is a number with 1 already filled in. Until an item is chosen, the checker says what is missing:
|
||||
|
||||
|
||||
|
||||
Stats Engine's `stat.archetype` has no required parameter, so the same empty form is accepted:
|
||||
|
||||
|
||||
|
||||
Every action and command the loaded mods describe appears in the palette's list, grouped by category; the footer counts them:
|
||||
|
||||
|
||||
|
||||
## Schema files
|
||||
|
||||
A mod ships `schemas/<mod>.json` with up to three lists:
|
||||
|
||||
- `Actions` — scenario actions (`action <id> key=value …`): their parameters;
|
||||
- `Commands` — DSL commands such as `check` or `select`: positional values and named parameters;
|
||||
- `Kinds` — kinds of data (`item`, `character`, `shop`…): the fields of their entities, the folder for new files and the pattern of a new id.
|
||||
|
||||
Names and descriptions are translation keys in the mod's own locale, so the forms speak every language of the game.
|
||||
|
||||
Field types: `text`, `locale` (a text in every language), `int`, `number`, `bool`, `choice` (with `Options`), `ref` and `ref_list` (ids of a kind), `who`, `picture`, `formula`, `condition`, `scene`, `flag`, `label`, `list` (a list of objects with fields of their own), `values`, `map`, `json`. An unknown type is edited as text.
|
||||
|
||||
## Several mods describe one kind
|
||||
|
||||
Files are read in mod load order:
|
||||
|
||||
- an action or a command described again is **replaced whole** by the later mod;
|
||||
- a kind is **merged field by field**: a field with the same key is replaced, new fields are added.
|
||||
|
||||
So Equipment adds its fields to Items Engine's `item` without touching that file:
|
||||
|
||||
```json
|
||||
{ "Kind": "item",
|
||||
"Fields": [
|
||||
{ "Key": "Equip", "Type": "text", "Name": "equipment/schema/field/equip" },
|
||||
{ "Key": "Archetypes", "Type": "ref_list", "Kind": "archetype", "Name": "equipment/schema/field/archetypes" }
|
||||
] }
|
||||
```
|
||||
|
||||
Every field remembers which mod described it ("Described by the mod items_base" in the palette). A broken schema file is reported and skipped; the other files still count.
|
||||
|
||||
The rule is that each mod describes its own actions, commands and kinds, next to their code. A mod may describe another mod's action to correct it, and then wins by load order.
|
||||
|
||||
## What the checker reports
|
||||
|
||||
- **needs a parameter** — a required parameter is missing (error);
|
||||
- **has no parameter** — the line names a parameter the description does not know (warning);
|
||||
- **bad value** — not a whole number, not a number, not one of the choices (error, or a warning for yes/no and choices);
|
||||
- **unknown reference** — the id names an item, character or other entity that no loaded mod defines (error).
|
||||
|
||||
The validator reports the same things as `SCHEMA_MISSING_PARAM`, `SCHEMA_UNKNOWN_PARAM`, `SCHEMA_BAD_VALUE` and `SCHEMA_UNKNOWN_REF`. The checker only knows what the descriptions say: a line it accepts can still do something unexpected in the game.
|
||||
|
||||
## If something goes wrong
|
||||
|
||||
1. **An action is missing from the palette.** No loaded mod describes it; the action still works in scenarios.
|
||||
2. **A field shows as a plain text box.** Its type is unknown, or the field has no description at all (the Data Editor then shows it under other fields as JSON).
|
||||
3. **A form ignores your schema.** A mod later in the load order describes the same action and replaced yours.
|
||||
+97
@@ -0,0 +1,97 @@
|
||||
# Schemas — descripciones de acciones, comandos y campos de datos
|
||||
|
||||
Schemas es una biblioteca: permite a cada mod describir, como datos, qué aceptan sus acciones de escenario, cómo son sus comandos DSL y qué campos tienen sus tipos de datos. A partir de esa descripción, las herramientas construyen formularios, selectores y comprobaciones, de modo que el autor rellena un formulario en lugar de memorizar nombres de parámetros, y un error se detecta antes de ejecutar el juego.
|
||||
|
||||
Este mod no tiene ventana propia. Lo que de él se ve lo muestran otras herramientas:
|
||||
|
||||
- **Schema Tools** — la paleta de comandos y la ventana Editor de datos;
|
||||
- **Validator** — parámetros desconocidos o ausentes y referencias rotas en su informe;
|
||||
- los **editores de objetos y personajes** — los campos que otros mods añaden a objetos y personajes.
|
||||
|
||||
## De la descripción al formulario y a la comprobación
|
||||
|
||||
```text
|
||||
items_base/schemas/items_base.json la descripción, junto al código de la acción
|
||||
│
|
||||
▼
|
||||
catálogo de esquemas (todos los mods, en orden de carga)
|
||||
│
|
||||
├──► formulario en la paleta un campo por parámetro
|
||||
├──► línea de escenario action item.remove id=… count=…
|
||||
└──► comprobación el mismo veredicto en la paleta y en el validador
|
||||
```
|
||||
|
||||
Items Engine describe su acción `item.remove` así:
|
||||
|
||||
```json
|
||||
{
|
||||
"Id": "item.remove",
|
||||
"Name": "items/schema/remove",
|
||||
"Description": "items/schema/remove_desc",
|
||||
"Category": "items",
|
||||
"Params": [
|
||||
{ "Key": "id", "Type": "ref", "Kind": "item", "Required": true, "Name": "items/schema/field/item" },
|
||||
{ "Key": "count", "Type": "int", "Default": "1", "Name": "items/schema/field/count" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
La paleta de comandos de RPG Plus lo muestra como formulario: **Item** es una lista de los objetos del juego (tipo `ref`, entidad `item`), **Count** es un número con el 1 ya rellenado. Mientras no se elija un objeto, la comprobación dice qué falta:
|
||||
|
||||
|
||||
|
||||
El `stat.archetype` de Stats Engine no tiene parámetro obligatorio, así que el mismo formulario vacío se acepta:
|
||||
|
||||
|
||||
|
||||
Cada acción y comando que describen los mods cargados aparece en la lista de la paleta, agrupado por categorías; el pie los cuenta:
|
||||
|
||||
|
||||
|
||||
## Archivos de esquemas
|
||||
|
||||
Un mod incluye `schemas/<mod>.json` con hasta tres listas:
|
||||
|
||||
- `Actions` — acciones de escenario (`action <id> key=value …`): sus parámetros;
|
||||
- `Commands` — comandos DSL como `check` o `select`: valores posicionales y parámetros con nombre;
|
||||
- `Kinds` — tipos de datos (`item`, `character`, `shop`…): los campos de sus entidades, la carpeta para archivos nuevos y el patrón de un id nuevo.
|
||||
|
||||
Los nombres y las descripciones son claves de traducción de la localización del propio mod, así que los formularios hablan todos los idiomas del juego.
|
||||
|
||||
Tipos de campo: `text`, `locale` (un texto en todos los idiomas), `int`, `number`, `bool`, `choice` (con `Options`), `ref` y `ref_list` (ids de un tipo), `who`, `picture`, `formula`, `condition`, `scene`, `flag`, `label`, `list` (una lista de objetos con campos propios), `values`, `map`, `json`. Un tipo desconocido se edita como texto.
|
||||
|
||||
## Varios mods describen un mismo tipo
|
||||
|
||||
Los archivos se leen en el orden de carga de los mods:
|
||||
|
||||
- una acción o un comando descritos de nuevo se **sustituyen enteros** por el mod posterior;
|
||||
- un tipo se **fusiona campo a campo**: el campo con la misma clave se sustituye y los campos nuevos se añaden.
|
||||
|
||||
Así Equipment añade sus campos al `item` de Items Engine sin tocar ese archivo:
|
||||
|
||||
```json
|
||||
{ "Kind": "item",
|
||||
"Fields": [
|
||||
{ "Key": "Equip", "Type": "text", "Name": "equipment/schema/field/equip" },
|
||||
{ "Key": "Archetypes", "Type": "ref_list", "Kind": "archetype", "Name": "equipment/schema/field/archetypes" }
|
||||
] }
|
||||
```
|
||||
|
||||
Cada campo recuerda qué mod lo describió («Descrito por el mod items_base» en la paleta). Un archivo de esquema roto se informa y se salta; los demás archivos siguen contando.
|
||||
|
||||
La regla es que cada mod describa sus propias acciones, comandos y tipos, junto a su código. Un mod puede describir la acción de otro para corregirla, y entonces gana el orden de carga.
|
||||
|
||||
## Qué informa la comprobación
|
||||
|
||||
- **falta un parámetro** — ausenta un parámetro obligatorio (error);
|
||||
- **no existe el parámetro** — la línea nombra un parámetro que la descripción no conoce (aviso);
|
||||
- **valor incorrecto** — no es un número entero, no es un número, no está entre las opciones (error, o aviso para sí/no y opciones);
|
||||
- **referencia desconocida** — el id nombra un objeto, personaje u otra entidad que ningún mod cargado define (error).
|
||||
|
||||
El validador informa de lo mismo como `SCHEMA_MISSING_PARAM`, `SCHEMA_UNKNOWN_PARAM`, `SCHEMA_BAD_VALUE` y `SCHEMA_UNKNOWN_REF`. La comprobación solo sabe lo que dicen las descripciones: una línea que acepta todavía puede hacer algo inesperado en el juego.
|
||||
|
||||
## Si algo sale mal
|
||||
|
||||
1. **Una acción no aparece en la paleta.** Ningún mod cargado la describe; la acción sigue funcionando en los escenarios.
|
||||
2. **Un campo se muestra como caja de texto sencilla.** Su tipo es desconocido, o el campo no tiene descripción alguna (el Editor de datos lo muestra entonces entre otros campos, como JSON).
|
||||
3. **Un formulario ignora tu esquema.** Un mod más tarde en el orden de carga describió la misma acción y sustituyó la tuya.
|
||||
+97
@@ -0,0 +1,97 @@
|
||||
# Schemas — 行動・コマンド・データフィールドの記述
|
||||
|
||||
Schemas はライブラリです。どの MOD も、自分のシナリオ行動が何を受け取り、自分の DSL コマンドがどんな形で、自分のデータの種類にどのフィールドがあるのかを、データとして記述できます。ツールはその記述からフォーム、ピッカー、検査を組み立てるので、作者はパラメーター名を覚える代わりにフォームを埋めるだけで済み、誤りはゲームを実行する前に分かります。
|
||||
|
||||
この MOD には独自のウィンドウはありません。見える部分は、ほかのツールが表示します:
|
||||
|
||||
- **Schema Tools** — コマンドパレットと「データエディター」ウィンドウ；
|
||||
- **Validator** — 不明・不足のパラメーターと壊れた参照を報告書に載せる；
|
||||
- **アイテム・キャラクターエディター** — 他の MOD がアイテムやキャラクターに足すフィールド。
|
||||
|
||||
## 記述からフォームと検査へ
|
||||
|
||||
```text
|
||||
items_base/schemas/items_base.json 記述。行動のコードのそばに置く
|
||||
│
|
||||
▼
|
||||
スキーマカタログ（全 MOD、読み込み順）
|
||||
│
|
||||
├──► コマンドパレットのフォーム パラメーターごとに一つのフィールド
|
||||
├──► シナリオの行 action item.remove id=… count=…
|
||||
└──► チェッカー パレットでもバリデーターでも同じ判定
|
||||
```
|
||||
|
||||
Items Engine は自分の行動 `item.remove` を次のように記述します:
|
||||
|
||||
```json
|
||||
{
|
||||
"Id": "item.remove",
|
||||
"Name": "items/schema/remove",
|
||||
"Description": "items/schema/remove_desc",
|
||||
"Category": "items",
|
||||
"Params": [
|
||||
{ "Key": "id", "Type": "ref", "Kind": "item", "Required": true, "Name": "items/schema/field/item" },
|
||||
{ "Key": "count", "Type": "int", "Default": "1", "Name": "items/schema/field/count" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
RPG Plus のコマンドパレットはこれをフォームとして示します: **Item** はゲームのアイテムの一覧（型 `ref`、種類 `item`）、**Count** は 1 が入力済みの数値。アイテムを選ぶまで、チェッカーは何が足りないかを教えます:
|
||||
|
||||
|
||||
|
||||
Stats Engine の `stat.archetype` には必須パラメーターがないので、同じ空のフォームでも受け付けられます:
|
||||
|
||||
|
||||
|
||||
読み込まれた MOD が記述した行動とコマンドはすべて、カテゴリーごとにまとまってパレットの一覧に現れます。フッターが数を数えます:
|
||||
|
||||
|
||||
|
||||
## スキーマファイル
|
||||
|
||||
MOD は `schemas/<mod>.json` に、最大三つのリストを同梱します:
|
||||
|
||||
- `Actions` — シナリオの行動（`action <id> key=value …`）: そのパラメーター；
|
||||
- `Commands` — `check` や `select` などの DSL コマンド: 位置パラメーターと名前付きパラメーター；
|
||||
- `Kinds` — データの種類（`item`、`character`、`shop`…）: そのエンティティのフィールド、新規ファイルのフォルダー、新しい id のパターン。
|
||||
|
||||
名前と説明は MOD 自身のローカライズにある翻訳キーなので、フォームはゲームのすべての言語で語ります。
|
||||
|
||||
フィールドの型: `text`、`locale`（全言語のテキスト）、`int`、`number`、`bool`、`choice`（`Options` 付き）、`ref` と `ref_list`（種類の id）、`who`、`picture`、`formula`、`condition`、`scene`、`flag`、`label`、`list`（各自のフィールドを持つオブジェクトのリスト）、`values`、`map`、`json`。不明な型はテキストとして編集されます。
|
||||
|
||||
## 複数の MOD が一つの種類を記述する
|
||||
|
||||
ファイルは MOD の読み込み順に読まれます:
|
||||
|
||||
- 行動やコマンドを再度記述すると、後の MOD が**丸ごと置き換えます**；
|
||||
- 種類は**フィールドごとに統合**されます: 同じキーのフィールドは置き換わり、新しいフィールドは足されます。
|
||||
|
||||
たとえば Equipment は、Items Engine の `item` に自分のフィールドを、そのファイルには触れずに足します:
|
||||
|
||||
```json
|
||||
{ "Kind": "item",
|
||||
"Fields": [
|
||||
{ "Key": "Equip", "Type": "text", "Name": "equipment/schema/field/equip" },
|
||||
{ "Key": "Archetypes", "Type": "ref_list", "Kind": "archetype", "Name": "equipment/schema/field/archetypes" }
|
||||
] }
|
||||
```
|
||||
|
||||
どのフィールドも、どの MOD が記述したかを覚えています（パレットの「MOD items_base が記述」）。壊れたスキーマファイルは報告されて読み飛ばされ、ほかのファイルは引き続き数に入ります。
|
||||
|
||||
ルールは、各 MOD が自分の行動・コマンド・種類を、そのコードのそばに記述する、というものです。他の MOD の行動を直すために記述することもでき、その場合は読み込み順が勝ちます。
|
||||
|
||||
## チェッカーが報告すること
|
||||
|
||||
- **パラメーターが必要** — 必須パラメーターがない（エラー）；
|
||||
- **パラメーターが存在しない** — 行が、記述にないパラメーターを名指している（警告）；
|
||||
- **値が不正** — 整数でない、数値でない、選択肢にない（エラー。はい/いいえと選択肢は警告）；
|
||||
- **不明な参照** — id が、読み込まれたどの MOD も定義しないアイテムやキャラクターなどのエンティティを名指している（エラー）。
|
||||
|
||||
バリデーターは同じものを `SCHEMA_MISSING_PARAM`、`SCHEMA_UNKNOWN_PARAM`、`SCHEMA_BAD_VALUE`、`SCHEMA_UNKNOWN_REF` として報告します。チェッカーは記述に書かれたことしか知りません: 受け入れた行でも、ゲームの中では思いがけないことをするかもしれません。
|
||||
|
||||
## うまくいかないとき
|
||||
|
||||
1. **行動がパレットにない。** 読み込まれたどの MOD も記述していません。それでも行動はシナリオの中で機能します。
|
||||
2. **フィールドがただのテキストボックスになる。** 型が不明か、フィールドの記述がまったくありません（データエディターはそれを他のフィールドとして JSON で示します）。
|
||||
3. **フォームがあなたのスキーマを無視する。** 読み込み順で後の MOD が同じ行動を記述し、置き換えました。
|
||||
+97
@@ -0,0 +1,97 @@
|
||||
# Schemas — 행동, 명령, 데이터 필드의 설명
|
||||
|
||||
Schemas는 라이브러리입니다. 어떤 모드든 자신의 시나리오 행동이 무엇을 받는지, DSL 명령이 어떤 모양인지, 데이터 종류마다 어떤 필드가 있는지를 데이터로 설명할 수 있게 해 줍니다. 도구는 이 설명으로 양식, 선택기, 검사를 만들므로, 작성자는 매개변수 이름을 외우는 대신 양식을 채우고, 실수는 게임을 실행하기 전에 잡힙니다.
|
||||
|
||||
이 모드에는 자체 창이 없습니다. 눈에 보이는 부분은 다른 도구가 보여 줍니다:
|
||||
|
||||
- **Schema Tools** — 명령 팔레트와 '데이터 에디터' 창;
|
||||
- **Validator** — 보고서의 알 수 없거나 빠진 매개변수, 깨진 참조;
|
||||
- **아이템·캐릭터 에디터** — 다른 모드가 아이템과 캐릭터에 더하는 필드.
|
||||
|
||||
## 설명에서 양식과 검사로
|
||||
|
||||
```text
|
||||
items_base/schemas/items_base.json 설명. 행동 코드 바로 옆에 둠
|
||||
│
|
||||
▼
|
||||
스키마 카탈로그 (모든 모드, 로드 순서)
|
||||
│
|
||||
├──► 명령 팔레트의 양식 매개변수마다 필드 하나
|
||||
├──► 시나리오 줄 action item.remove id=… count=…
|
||||
└──► 검사기 팔레트에서도 검증기에서도 같은 판정
|
||||
```
|
||||
|
||||
Items Engine은 자신의 행동 `item.remove`을 이렇게 설명합니다:
|
||||
|
||||
```json
|
||||
{
|
||||
"Id": "item.remove",
|
||||
"Name": "items/schema/remove",
|
||||
"Description": "items/schema/remove_desc",
|
||||
"Category": "items",
|
||||
"Params": [
|
||||
{ "Key": "id", "Type": "ref", "Kind": "item", "Required": true, "Name": "items/schema/field/item" },
|
||||
{ "Key": "count", "Type": "int", "Default": "1", "Name": "items/schema/field/count" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
RPG Plus의 명령 팔레트는 이것을 양식으로 보여 줍니다: **Item**은 게임 아이템의 목록(유형 `ref`, 종류 `item`), **Count**는 1이 채워진 숫자입니다. 아이템을 고르기 전까지 검사기는 무엇이 빠졌는지 알려 줍니다:
|
||||
|
||||
|
||||
|
||||
Stats Engine의 `stat.archetype`에는 필수 매개변수가 없으므로 같은 빈 양식도 받아들여집니다:
|
||||
|
||||
|
||||
|
||||
불러온 모드가 설명한 모든 행동과 명령이 팔레트 목록에 카테고리별로 나타나고, 바닥글이 개수를 세어 줍니다:
|
||||
|
||||
|
||||
|
||||
## 스키마 파일
|
||||
|
||||
모드는 `schemas/<mod>.json`에 최대 세 개의 목록을 담습니다:
|
||||
|
||||
- `Actions` — 시나리오 행동(`action <id> key=value …`): 그 매개변수;
|
||||
- `Commands` — `check`나 `select` 같은 DSL 명령: 위치 값과 이름 있는 매개변수;
|
||||
- `Kinds` — 데이터 종류(`item`, `character`, `shop`…): 그 엔티티의 필드, 새 파일의 폴더, 새 id의 패턴.
|
||||
|
||||
이름과 설명은 모드 자체 로컬라이즈의 번역 키이므로, 양식은 게임의 모든 언어로 말합니다.
|
||||
|
||||
필드 유형: `text`, `locale`(모든 언어의 텍스트), `int`, `number`, `bool`, `choice`(`Options`와 함께), `ref`와 `ref_list`(한 종류의 id), `who`, `picture`, `formula`, `condition`, `scene`, `flag`, `label`, `list`(자체 필드를 가진 객체의 목록), `values`, `map`, `json`. 알 수 없는 유형은 텍스트로 편집됩니다.
|
||||
|
||||
## 여러 모드가 한 종류를 설명할 때
|
||||
|
||||
파일은 모드 로드 순서대로 읽힙니다:
|
||||
|
||||
- 행동이나 명령이 다시 설명되면 나중 모드가 **통째로 대체**합니다;
|
||||
- 종류는 **필드별로 합쳐집니다**: 같은 키의 필드는 대체되고, 새 필드는 더해집니다.
|
||||
|
||||
그래서 Equipment는 Items Engine의 `item`에 자신의 필드를, 그 파일을 건드리지 않고 더합니다:
|
||||
|
||||
```json
|
||||
{ "Kind": "item",
|
||||
"Fields": [
|
||||
{ "Key": "Equip", "Type": "text", "Name": "equipment/schema/field/equip" },
|
||||
{ "Key": "Archetypes", "Type": "ref_list", "Kind": "archetype", "Name": "equipment/schema/field/archetypes" }
|
||||
] }
|
||||
```
|
||||
|
||||
모든 필드는 어느 모드가 설명했는지 기억합니다(팔레트의 "모드 items_base가 설명함"). 깨진 스키마 파일은 보고되고 건너뛰며, 나머지 파일은 계속 효력을 가집니다.
|
||||
|
||||
규칙은 각 모드가 자신의 행동, 명령, 종류를 그 코드 옆에 설명하는 것입니다. 다른 모드의 행동을 고치기 위해 설명할 수도 있고, 그때는 로드 순서가 이깁니다.
|
||||
|
||||
## 검사기가 보고하는 것
|
||||
|
||||
- **매개변수 필요** — 필수 매개변수가 없음(오류);
|
||||
- **알 수 없는 매개변수** — 줄이 설명에 없는 매개변수를 이름으로 지목함(경고);
|
||||
- **잘못된 값** — 정수가 아님, 숫자가 아님, 선택지에 없음(오류. 예/아니오와 선택지는 경고);
|
||||
- **알 수 없는 참조** — id가 불러온 어느 모드도 정의하지 않는 아이템, 캐릭터 따위의 엔티티를 가리킴(오류).
|
||||
|
||||
검증기는 같은 내용을 `SCHEMA_MISSING_PARAM`, `SCHEMA_UNKNOWN_PARAM`, `SCHEMA_BAD_VALUE`, `SCHEMA_UNKNOWN_REF`로 보고합니다. 검사기는 설명에 쓰인 것만 압니다: 받아들인 줄이라도 게임 안에서는 뜻밖의 일을 할 수 있습니다.
|
||||
|
||||
## 문제가 생겼을 때
|
||||
|
||||
1. **행동이 팔레트에 없습니다.** 불러온 모드 중 아무도 설명하지 않았습니다. 그래도 행동은 시나리오 안에서 작동합니다.
|
||||
2. **필드가 평범한 텍스트 상자로 보입니다.** 유형을 알 수 없거나 필드 설명이 아예 없습니다(이때 데이터 에디터는 그것을 다른 필드 아래 JSON으로 보여 줍니다).
|
||||
3. **양식이 당신의 스키마를 무시합니다.** 로드 순서에서 뒤인 모드가 같은 행동을 설명해 당신 것을 대체했습니다.
|
||||
+97
@@ -0,0 +1,97 @@
|
||||
# Schemas — описания действий, команд и полей данных
|
||||
|
||||
Schemas — это библиотека: она позволяет каждому моду описать в виде данных, что принимают его сценарные действия, как выглядят его команды DSL и какие поля есть у его видов данных. Из такого описания инструменты собирают формы, списки выбора и проверки, так что автор заполняет форму вместо того, чтобы держать в голове имена параметров, а ошибка находится ещё до запуска игры.
|
||||
|
||||
У мода нет своего окна. Всё, что из него видно, показывают другие инструменты:
|
||||
|
||||
- **Schema Tools** — палитра команд и окно «Редактор данных»;
|
||||
- **Validator** — неизвестные или недостающие параметры и битые ссылки в своём отчёте;
|
||||
- **редакторы предметов и персонажей** — поля, которые другие моды добавляют к предметам и персонажам.
|
||||
|
||||
## От описания к форме и проверке
|
||||
|
||||
```text
|
||||
items_base/schemas/items_base.json описание — рядом с кодом действия
|
||||
│
|
||||
▼
|
||||
каталог схем (все моды, по порядку загрузки)
|
||||
│
|
||||
├──► форма в палитре команд по полю на каждый параметр
|
||||
├──► строка сценария action item.remove id=… count=…
|
||||
└──► проверка тот же вердикт в палитре и у валидатора
|
||||
```
|
||||
|
||||
Items Engine описывает своё действие `item.remove` так:
|
||||
|
||||
```json
|
||||
{
|
||||
"Id": "item.remove",
|
||||
"Name": "items/schema/remove",
|
||||
"Description": "items/schema/remove_desc",
|
||||
"Category": "items",
|
||||
"Params": [
|
||||
{ "Key": "id", "Type": "ref", "Kind": "item", "Required": true, "Name": "items/schema/field/item" },
|
||||
{ "Key": "count", "Type": "int", "Default": "1", "Name": "items/schema/field/count" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Палитра команд RPG Plus показывает его как форму: **Item** — список предметов игры (тип `ref`, вид `item`), **Count** — число, в котором уже подставлена 1. Пока предмет не выбран, проверка сообщает, чего не хватает:
|
||||
|
||||
|
||||
|
||||
У `stat.archetype` из Stats Engine обязательных параметров нет, поэтому та же пустая форма считается верной:
|
||||
|
||||
|
||||
|
||||
Каждое действие и команда, описанные загруженными модами, попадают в список палитры, сгруппированный по категориям; в подвале — счётчик:
|
||||
|
||||
|
||||
|
||||
## Файлы схем
|
||||
|
||||
Мод кладёт в `schemas/<mod>.json` до трёх списков:
|
||||
|
||||
- `Actions` — сценарные действия (`action <id> key=value …`): их параметры;
|
||||
- `Commands` — команды DSL вроде `check` или `select`: позиционные значения и именованные параметры;
|
||||
- `Kinds` — виды данных (`item`, `character`, `shop`…): поля их сущностей, папка для новых файлов и шаблон нового id.
|
||||
|
||||
Имена и описания — ключи перевода в собственной локализации мода, поэтому формы говорят на всех языках игры.
|
||||
|
||||
Типы полей: `text`, `locale` (текст на всех языках), `int`, `number`, `bool`, `choice` (с `Options`), `ref` и `ref_list` (идентификаторы вида), `who`, `picture`, `formula`, `condition`, `scene`, `flag`, `label`, `list` (список объектов со своими полями), `values`, `map`, `json`. Неизвестный тип правится как текст.
|
||||
|
||||
## Несколько модов описывают один вид
|
||||
|
||||
Файлы читаются в порядке загрузки модов:
|
||||
|
||||
- действие или команда, описанные заново, **целиком заменяются** более поздним модом;
|
||||
- вид **сливается по полям**: поле с тем же ключом заменяется, новые поля добавляются.
|
||||
|
||||
Так Equipment добавляет свои поля к `item` из Items Engine, не трогая чужой файл:
|
||||
|
||||
```json
|
||||
{ "Kind": "item",
|
||||
"Fields": [
|
||||
{ "Key": "Equip", "Type": "text", "Name": "equipment/schema/field/equip" },
|
||||
{ "Key": "Archetypes", "Type": "ref_list", "Kind": "archetype", "Name": "equipment/schema/field/archetypes" }
|
||||
] }
|
||||
```
|
||||
|
||||
Каждое поле помнит, какой мод его описал («Описано модом items_base» в палитре). Битый файл схемы сообщается в отчёт и пропускается; остальные файлы продолжают работать.
|
||||
|
||||
Правило простое: каждый мод описывает свои действия, команды и виды — рядом с их кодом. Описать чужое действие можно, чтобы его поправить, — и тогда побеждает порядок загрузки.
|
||||
|
||||
## О чём сообщает проверка
|
||||
|
||||
- **нужен параметр** — отсутствует обязательный параметр (ошибка);
|
||||
- **неизвестный параметр** — в строке назван параметр, которого описание не знает (предупреждение);
|
||||
- **плохое значение** — не целое число, не число, не из списка вариантов (ошибка, а для да/нет и вариантов — предупреждение);
|
||||
- **неизвестная ссылка** — идентификатор называет предмет, персонажа или другую сущность, которую не определяет ни один загруженный мод (ошибка).
|
||||
|
||||
Валидатор сообщает то же самое как `SCHEMA_MISSING_PARAM`, `SCHEMA_UNKNOWN_PARAM`, `SCHEMA_BAD_VALUE` и `SCHEMA_UNKNOWN_REF`. Проверка знает только то, что сказано в описаниях: строка, которую она приняла, всё равно может сделать в игре нечто неожиданное.
|
||||
|
||||
## Если что-то пошло не так
|
||||
|
||||
1. **Действия нет в палитре.** Ни один загруженный мод его не описал; в сценариях действие всё равно работает.
|
||||
2. **Поле выглядит как обычное текстовое поле.** Его тип неизвестен или поля вообще нет в описании (тогда «Редактор данных» показывает его среди прочих полей как JSON).
|
||||
3. **Форма игнорирует вашу схему.** Мод, стоящий позже по порядку загрузки, описал то же действие и заменил ваше.
|
||||
+97
@@ -0,0 +1,97 @@
|
||||
# Schemas — mô tả hành động, lệnh và trường dữ liệu
|
||||
|
||||
Schemas là một thư viện: nó cho phép mọi mod mô tả, dưới dạng dữ liệu, hành động kịch bản của mình nhận những gì, lệnh DSL của mình có dạng thế nào và các loại dữ liệu của mình có những trường nào. Từ một mô tả như vậy, các công cụ dựng biểu mẫu, bộ chọn và phép kiểm tra, nên tác giả chỉ cần điền biểu mẫu thay vì nhớ tên tham số, và lỗi được báo trước khi chạy game.
|
||||
|
||||
Mod này không có cửa sổ riêng. Phần bạn thấy được do các công cụ khác hiển thị:
|
||||
|
||||
- **Schema Tools** — bảng lệnh và cửa sổ Trình sửa dữ liệu;
|
||||
- **Validator** — tham số lạ hoặc thiếu, tham chiếu hỏng trong báo cáo của nó;
|
||||
- các **trình sửa vật phẩm và nhân vật** — những trường mà mod khác thêm vào vật phẩm và nhân vật.
|
||||
|
||||
## Từ mô tả đến biểu mẫu và phép kiểm tra
|
||||
|
||||
```text
|
||||
items_base/schemas/items_base.json mô tả, đặt cạnh mã của hành động
|
||||
│
|
||||
▼
|
||||
danh mục lược đồ (mọi mod, theo thứ tự tải)
|
||||
│
|
||||
├──► biểu mẫu trong bảng lệnh mỗi tham số một trường
|
||||
├──► dòng kịch bản action item.remove id=… count=…
|
||||
└──► bộ kiểm tra cùng một kết luận trong bảng lệnh và trình kiểm tra
|
||||
```
|
||||
|
||||
Items Engine mô tả hành động `item.remove` của mình thế này:
|
||||
|
||||
```json
|
||||
{
|
||||
"Id": "item.remove",
|
||||
"Name": "items/schema/remove",
|
||||
"Description": "items/schema/remove_desc",
|
||||
"Category": "items",
|
||||
"Params": [
|
||||
{ "Key": "id", "Type": "ref", "Kind": "item", "Required": true, "Name": "items/schema/field/item" },
|
||||
{ "Key": "count", "Type": "int", "Default": "1", "Name": "items/schema/field/count" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Bảng lệnh của RPG Plus hiển thị nó như một biểu mẫu: **Item** là danh sách vật phẩm của game (kiểu `ref`, loại `item`), **Count** là một số đã điền sẵn 1. Cho đến khi chọn một vật phẩm, bộ kiểm tra sẽ cho biết thiếu gì:
|
||||
|
||||
|
||||
|
||||
`stat.archetype` của Stats Engine không có tham số bắt buộc nên cùng một biểu mẫu trống vẫn được chấp nhận:
|
||||
|
||||
|
||||
|
||||
Mọi hành động và lệnh mà các mod đã tải mô tả đều xuất hiện trong danh sách của bảng lệnh, nhóm theo loại; chân bảng đếm chúng:
|
||||
|
||||
|
||||
|
||||
## Tệp lược đồ
|
||||
|
||||
Mod kèm `schemas/<mod>.json` với tối đa ba danh sách:
|
||||
|
||||
- `Actions` — hành động kịch bản (`action <id> key=value …`): các tham số của chúng;
|
||||
- `Commands` — các lệnh DSL như `check` hay `select`: giá trị vị trí và tham số đặt tên;
|
||||
- `Kinds` — các loại dữ liệu (`item`, `character`, `shop`…): trường của thực thể, thư mục cho tệp mới và mẫu của id mới.
|
||||
|
||||
Tên và mô tả là khóa dịch trong bản địa hóa của chính mod đó, nên biểu mẫu nói được mọi ngôn ngữ của game.
|
||||
|
||||
Các kiểu trường: `text`, `locale` (một văn bản cho mọi ngôn ngữ), `int`, `number`, `bool`, `choice` (kèm `Options`), `ref` và `ref_list` (id của một loại), `who`, `picture`, `formula`, `condition`, `scene`, `flag`, `label`, `list` (danh sách các đối tượng có trường riêng), `values`, `map`, `json`. Kiểu lạ được sửa như văn bản.
|
||||
|
||||
## Nhiều mod mô tả một loại
|
||||
|
||||
Tệp được đọc theo thứ tự tải mod:
|
||||
|
||||
- hành động hay lệnh được mô tả lại sẽ bị mod sau **thay thế toàn bộ**;
|
||||
- loại thì được **gộp theo từng trường**: trường cùng khóa bị thay, trường mới được thêm.
|
||||
|
||||
Nhờ vậy Equipment thêm trường của mình vào `item` của Items Engine mà không đụng tới tệp đó:
|
||||
|
||||
```json
|
||||
{ "Kind": "item",
|
||||
"Fields": [
|
||||
{ "Key": "Equip", "Type": "text", "Name": "equipment/schema/field/equip" },
|
||||
{ "Key": "Archetypes", "Type": "ref_list", "Kind": "archetype", "Name": "equipment/schema/field/archetypes" }
|
||||
] }
|
||||
```
|
||||
|
||||
Mỗi trường đều nhớ mod nào đã mô tả nó ("Mod items_base mô tả" trong bảng lệnh). Tệp lược đồ hỏng được báo cáo và bỏ qua; các tệp khác vẫn được tính.
|
||||
|
||||
Nguyên tắc là mỗi mod mô tả hành động, lệnh và loại của chính mình, cạnh mã của chúng. Một mod có thể mô tả hành động của mod khác để sửa nó, và khi đó thứ tự tải quyết định.
|
||||
|
||||
## Bộ kiểm tra báo cáo gì
|
||||
|
||||
- **cần một tham số** — thiếu tham số bắt buộc (lỗi);
|
||||
- **không có tham số này** — dòng nêu một tham số mà mô tả không biết (cảnh báo);
|
||||
- **giá trị sai** — không phải số nguyên, không phải số, không nằm trong các lựa chọn (lỗi, hoặc cảnh báo với có/không và các lựa chọn);
|
||||
- **tham chiếu lạ** — id gọi tới một vật phẩm, nhân vật hay thực thể khác mà không mod nào đã tải định nghĩa (lỗi).
|
||||
|
||||
Trình kiểm tra báo những điều tương tự dưới mã `SCHEMA_MISSING_PARAM`, `SCHEMA_UNKNOWN_PARAM`, `SCHEMA_BAD_VALUE` và `SCHEMA_UNKNOWN_REF`. Bộ kiểm tra chỉ biết những gì mô tả nói: một dòng nó chấp nhận vẫn có thể làm điều bất ngờ trong game.
|
||||
|
||||
## Khi có trục trặc
|
||||
|
||||
1. **Hành động không có trong bảng lệnh.** Không mod nào đã tải mô tả nó; hành động vẫn chạy trong kịch bản.
|
||||
2. **Một trường hiện thành ô văn bản thường.** Kiểu của nó lạ, hoặc trường không có mô tả nào (Trình sửa dữ liệu khi đó hiện nó trong phần trường khác, dưới dạng JSON).
|
||||
3. **Biểu mẫu bỏ qua lược đồ của bạn.** Một mod đứng sau trong thứ tự tải đã mô tả cùng hành động và thay thế mô tả của bạn.
|
||||
+97
@@ -0,0 +1,97 @@
|
||||
# Schemas — 动作、命令与数据字段的描述
|
||||
|
||||
Schemas 是一个程序库：它让每个模组都能用数据来描述自己的剧本动作接受什么参数、DSL 命令长什么样、各类数据有哪些字段。工具根据这些描述构建表单、选择器和校验，作者只需填表单而不用背参数名，错误在运行游戏之前就会被指出来。
|
||||
|
||||
这个模组没有自己的窗口。你能看到的部分都由其他工具呈现：
|
||||
|
||||
- **Schema Tools** —— 命令面板和「数据编辑器」窗口；
|
||||
- **Validator** —— 在报告中指出未知或缺失的参数、断裂的引用；
|
||||
- **物品与角色编辑器** —— 其他模组加到物品和角色上的字段。
|
||||
|
||||
## 从描述到表单与校验
|
||||
|
||||
```text
|
||||
items_base/schemas/items_base.json 描述文件，就放在动作代码旁边
|
||||
│
|
||||
▼
|
||||
模式目录（所有模组，按加载顺序）
|
||||
│
|
||||
├──► 命令面板中的表单 每个参数一个字段
|
||||
├──► 剧本行 action item.remove id=… count=…
|
||||
└──► 检查器 在面板和验证器中给出同样的结论
|
||||
```
|
||||
|
||||
Items Engine 这样描述自己的动作 `item.remove`：
|
||||
|
||||
```json
|
||||
{
|
||||
"Id": "item.remove",
|
||||
"Name": "items/schema/remove",
|
||||
"Description": "items/schema/remove_desc",
|
||||
"Category": "items",
|
||||
"Params": [
|
||||
{ "Key": "id", "Type": "ref", "Kind": "item", "Required": true, "Name": "items/schema/field/item" },
|
||||
{ "Key": "count", "Type": "int", "Default": "1", "Name": "items/schema/field/count" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
RPG Plus 的命令面板把它显示为表单：**Item** 是游戏物品的列表（`ref` 类型，指向 `item` 实体），**Count** 是已填好 1 的数字。在选定物品之前，检查器会说明缺了什么：
|
||||
|
||||
|
||||
|
||||
Stats Engine 的 `stat.archetype` 没有必填参数，所以同样的空表单也能通过：
|
||||
|
||||
|
||||
|
||||
已加载模组描述的每个动作和命令都会出现在面板列表中，按类别分组；底部给出统计：
|
||||
|
||||
|
||||
|
||||
## 模式文件
|
||||
|
||||
模组附带 `schemas/<mod>.json`，其中最多有三份列表：
|
||||
|
||||
- `Actions` —— 剧本动作（`action <id> key=value …`）：它们的参数；
|
||||
- `Commands` —— `check`、`select` 之类的 DSL 命令：位置参数和命名参数；
|
||||
- `Kinds` —— 数据类型（`item`、`character`、`shop`…）：其实体的字段、新文件的目录和新 id 的命名规则。
|
||||
|
||||
名称和描述是模组自己本地化里的翻译键，所以表单会说游戏里的每种语言。
|
||||
|
||||
字段类型：`text`、`locale`（每种语言一段文本）、`int`、`number`、`bool`、`choice`（带 `Options`）、`ref` 和 `ref_list`（某类型的 id）、`who`、`picture`、`formula`、`condition`、`scene`、`flag`、`label`、`list`（由带各自字段的对象组成的列表）、`values`、`map`、`json`。未知类型按文本编辑。
|
||||
|
||||
## 多个模组描述同一个类型
|
||||
|
||||
文件按模组加载顺序读取：
|
||||
|
||||
- 再次描述的动作或命令会被后面的模组**整体替换**；
|
||||
- 类型则**按字段合并**：键相同的字段被替换，新字段被添加。
|
||||
|
||||
于是 Equipment 给 Items Engine 的 `item` 加了自己的字段，而不用碰那个文件：
|
||||
|
||||
```json
|
||||
{ "Kind": "item",
|
||||
"Fields": [
|
||||
{ "Key": "Equip", "Type": "text", "Name": "equipment/schema/field/equip" },
|
||||
{ "Key": "Archetypes", "Type": "ref_list", "Kind": "archetype", "Name": "equipment/schema/field/archetypes" }
|
||||
] }
|
||||
```
|
||||
|
||||
每个字段都记得是哪个模组描述了它（面板中的「由模组 items_base 描述」）。有问题的模式文件会被报告并跳过；其余文件照常生效。
|
||||
|
||||
规则是：每个模组在自己的代码旁描述自己的动作、命令和类型。模组也可以描述别的模组的动作来纠正它——这时加载顺序靠后者获胜。
|
||||
|
||||
## 检查器报告什么
|
||||
|
||||
- **缺少参数** —— 缺了必填参数（错误）；
|
||||
- **参数不存在** —— 行里写了描述中不认识的参数（警告）；
|
||||
- **值不对** —— 不是整数、不是数字、不在可选值里（错误；对是否值和选项则是警告）；
|
||||
- **引用不存在** —— id 指向的物品、角色或其他实体没有任何已加载模组定义（错误）。
|
||||
|
||||
验证器把同样的问题报告为 `SCHEMA_MISSING_PARAM`、`SCHEMA_UNKNOWN_PARAM`、`SCHEMA_BAD_VALUE` 和 `SCHEMA_UNKNOWN_REF`。检查器只知道描述里写的内容：它放过的行仍可能在游戏里做出意料之外的事。
|
||||
|
||||
## 出问题了怎么办
|
||||
|
||||
1. **动作不在面板里。** 没有任何已加载模组描述它；它在剧本里仍然可用。
|
||||
2. **字段显示为普通文本框。** 它的类型未知，或者根本没有描述（这时「数据编辑器」会把它作为 JSON 放在其他字段里）。
|
||||
3. **表单不理会你的模式。** 加载顺序靠后的模组描述了同一个动作，替换了你的。
|
||||
Reference in new issue
Block a user