Autogenerate scenario schema doc

swarm-game · Sep 24, 2023 · fc228b5 · fc228b5
1 parent 93bbbe3
commit fc228b5
Show file tree

Hide file tree

Showing 36 changed files with 1,188 additions and 313 deletions.
diff --git a/app/Main.hs b/app/Main.hs
@@ -116,6 +116,7 @@ cliParser =
       , Just Recipes <$ switch (long "recipes" <> help "Generate recipes page (uses data from recipes.yaml)")
       , Just Capabilities <$ switch (long "capabilities" <> help "Generate capabilities page (uses entity map)")
       , Just Commands <$ switch (long "commands" <> help "Generate commands page (uses constInfo, constCaps and inferConst)")
+      , Just Scenario <$ switch (long "scenario" <> help "Generate scenario schema page")
       ]
   seed :: Parser (Maybe Int)
   seed = optional $ option auto (long "seed" <> short 's' <> metavar "INT" <> help "Seed to use for world generation")

diff --git a/data/scenarios/README.md b/data/scenarios/README.md
@@ -58,40 +58,16 @@ your editor to highlight the errors as you are writing.
 
 If you are using Visual Studio Code or VSCodium, you need to have
 the [YAML extension](https://open-vsx.org/extension/redhat/vscode-yaml)
-installed.
-
-To point the editor to the right schema for scenarios in this repository,
-you can use this `settings.json`:
-```JSON
-{
-  "yaml.schemas": {
-    "https://raw.githubusercontent.com/swarm-game/swarm/main/data/schema/scenario.json": [
-      "data/scenarios/*.yaml",
-      "data/scenarios/**/*.yaml"
-    ],
-    "https://raw.githubusercontent.com/swarm-game/swarm/main/data/schema/entities.json": [
-      "data/entities.yaml"
-    ],
-    "https://raw.githubusercontent.com/swarm-game/swarm/main/data/schema/recipes.json": [
-      "data/recipes.yaml"
-    ]
-  }
-}
-```
+installed. The appropriate [`settings.json`](https://github.com/swarm-game/swarm/blob/main/.vscode/settings.json) is already configured for you in the cloned `swarm` repo.
 
 #### CLI
 
 You can also check the files from the command line:
 ```Bash
-# install latest jsonschema executable version (tested with 4.9.1)
-pip install jsonschema
+# install latest check-jsonschema executable version
+pip install check-jsonschema
 # try it on provided scenarios
-yq eval scenarios/creative.yaml -o json | jsonschema data/schema/scenario.json
-# try that it works on empty JSON
-echo {} | jsonschema data/schema/scenario.json
-# {}: 'name' is a required property
-# {}: 'world' is a required property
-# {}: 'robots' is a required property
+scripts/validate-json-schemas.sh
 ```
 
 ### YAML conventions

diff --git a/data/scenarios/doc-fragments/SCHEMA.md b/data/scenarios/doc-fragments/SCHEMA.md
diff --git a/data/scenarios/doc-fragments/base-robot.md b/data/scenarios/doc-fragments/base-robot.md
@@ -0,0 +1,12 @@
+#### Base robot
+
+There must be at most one **base** robot in the world. Since concrete robots can be created
+either via the `loc` attribute or via the map and palette, use the following guide to
+ensure the base robot is the one you intended:
+
+1. Always list the intended **base** as the first robot definition in your scenario.
+2. The first robot with a `loc` attribute will become the base, even if other robots are defined earlier.
+3. Without any located robots, if multiple robots are instantiated on the map from
+   the first robot definition, the first robot in
+   [row-major order](https://en.wikipedia.org/wiki/Row-_and_column-major_order)
+   shall be the base.
diff --git a/data/scenarios/doc-fragments/capabilities.md b/data/scenarios/doc-fragments/capabilities.md
@@ -0,0 +1,8 @@
+#### Capabilities
+
+Each capability enables the evaluation of execution of one or more
+commands or language constructs. Rather than listing all possible
+capabilities here, which would be annoying to keep up-to-date, see the
+(automatically generated) [Commands cheat
+sheet](https://github.com/swarm-game/swarm/wiki/Commands-Cheat-Sheet)
+on the Swarm wiki.
diff --git a/data/scenarios/doc-fragments/cells.md b/data/scenarios/doc-fragments/cells.md
@@ -0,0 +1,23 @@
+#### Cells
+
+Each cell of the world is specified by a list of terrain, optional entity
+and robots present (if any). For example, `[grass]`, `[grass, tree]`,
+or `[grass, null, base]`.
+
+- The first (required) item specifies the terrain.  Currently, valid
+  terrain values are `stone`, `dirt`, `grass`, `ice`, or `blank`.
+- The second item (if present) specifies the name of an entity which
+  should be present in the cell.  This may be a built-in entity, or a
+  custom entity specified in the `entities` section.  `null` may be
+  used to explicitly specify no entity in the cell.
+- The third item and later (if present) specifies the names of the robots
+  which should be present in the cell.  These must be names of robots
+  specified in the `robots` section.  A copy of each robot will be
+  created at each location in the `map` where it is drawn.
+
+  Although multiple robots may be in a single location in general,
+  there is currently no way to specify more than one robot for a
+  cell in the world description.
+
+If a 1-tuple is used, it specifies a terrain value with no entity or
+robot.  A 2-tuple specifies a terrain value and entity, but no robot.
diff --git a/data/scenarios/doc-fragments/entity-properties.md b/data/scenarios/doc-fragments/entity-properties.md
@@ -0,0 +1,19 @@
+#### Entity properties
+
+The properties an entity may possess are listed below.  Each entity
+may possess any number of properties.
+
+- `unwalkable`: robots cannot `move` into a cell containing this
+  entity.  If they try, the `move` command will throw an exception.
+
+- `portable`: robots can pick this up using `grab` or `harvest`.
+  Trying to execute `grab` or `harvest` on an entity that is not
+  `portable` will throw an exception.
+
+- `growable`: when `harvest`ed, the entity will regrow from a seed.
+
+- `infinite`: when `grab`bed or `harvest`ed, the entity will
+  immediately respawn.
+
+- `known`: robots know what this is without having to `scan` it first,
+  hence it does not show up as a question mark.
diff --git a/data/schema/attribute.json b/data/schema/attribute.json
@@ -1,8 +1,8 @@
 {
     "$schema": "http://json-schema.org/draft-07/schema#",
     "$id": "https://raw.githubusercontent.com/swarm-game/swarm/main/data/schema/attribute.json",
-    "title": "Scenario-local attributes",
-    "description": "Local attribute definitions",
+    "title": "Attributes",
+    "description": "Scenario-local attribute definitions",
     "type": "object",
     "additionalProperties": false,
     "properties": {

diff --git a/data/schema/combustion.json b/data/schema/combustion.json
@@ -1,8 +1,8 @@
 {
     "$schema": "http://json-schema.org/draft-07/schema#",
     "$id": "https://raw.githubusercontent.com/swarm-game/swarm/main/data/schema/combustion.json",
-    "title": "Swarm entity combustion",
-    "description": "Properties of combustion",
+    "title": "Combustion",
+    "description": "Properties of entity combustion",
     "type": "object",
     "additionalProperties": false,
     "properties": {
@@ -13,16 +13,8 @@
         },
         "duration": {
             "type": "array",
-            "items": [
-                {
-                    "name": "minimum",
-                    "type": "number"
-                },
-                {
-                    "name": "maximum",
-                    "type": "number"
-                }
-            ],
+            "default": [100, 200],
+            "$ref": "range.json",
             "description": "For combustible entities, a 2-tuple of integers specifying the minimum and maximum amount of time that the combustion shall persist."
         },
         "product": {

diff --git a/data/schema/cosmic-loc.json b/data/schema/cosmic-loc.json
@@ -10,6 +10,6 @@
             "type": "string",
             "description": "Name of subworld"
         },
-        "loc": {"$ref": "./planar-loc.json"}
+        "loc": {"$ref": "planar-loc.json"}
     }
 }
diff --git a/data/schema/display.json b/data/schema/display.json
@@ -1,8 +1,8 @@
 {
     "$schema": "http://json-schema.org/draft-07/schema#",
     "$id": "https://raw.githubusercontent.com/swarm-game/swarm/main/data/schema/display.json",
-    "title": "Swarm entity display",
-    "description": "How to display an entity or robot in the Swarm game",
+    "title": "Display",
+    "description": "Swarm entity display. A display specifies how an entity or a robot (robots are essentially special kinds of entities) is displayed in the world.  It consists of a key-value mapping described by the following table.",
     "type": "object",
     "additionalProperties": false,
     "properties": {
@@ -13,8 +13,7 @@
         },
         "orientationMap": {
             "default": {},
-            "type": "object",
-            "description": "Currently unused"
+            "$ref": "orientation-map.json"
         },
         "curOrientation": {
             "default": null,
@@ -47,12 +46,12 @@
                 "blue",
                 "water"
             ],
-            "description": "The name of the attribute that should be used to style the robot or entity. A list of currently valid attributes can be found at https://github.com/swarm-game/swarm/blob/main/src/Swarm/TUI/Attr.hs."
+            "description": "The name of the attribute that should be used to style the robot or entity. A list of currently valid attributes can be found [here](https://github.com/swarm-game/swarm/blob/main/src/Swarm/TUI/View/Attribute/Attr.hs)."
         },
         "priority": {
             "default": 1,
             "type": "number",
-            "description": "When multiple entities and robots occupy the same cell, the one with the highest priority is drawn. By default, entities have priority 1, and robots have priority 10."
+            "description": "When multiple entities and robots occupy the same cell, the one with the highest priority is drawn. By default, entities have priority `1`, and robots have priority `10`."
         },
         "invisible": {
             "default": false,

diff --git a/data/schema/entities.json b/data/schema/entities.json
@@ -1,110 +1,10 @@
 {
     "$schema": "http://json-schema.org/draft-07/schema#",
     "$id": "https://raw.githubusercontent.com/swarm-game/swarm/main/data/schema/entities.json",
-    "title": "Swarm entities",
+    "title": "Entities",
     "description": "Description of entities in the Swarm game",
     "type": "array",
     "items": {
-        "description": "Description of an entity in the Swarm game",
-        "type": "object",
-        "additionalProperties": false,
-        "properties": {
-            "name": {
-                "type": "string",
-                "description": "The name of the entity. This is what will show up in the inventory and how the entity can be referred to."
-            },
-            "display": {
-                "type": "object",
-                "$ref": "./display.json",
-                "description": "Display information for the entity."
-            },
-            "plural": {
-                "default": "null",
-                "type": "string",
-                "description": "An explicit plural form of the name of the entity. If omitted, standard heuristics will be used for forming the English plural of its name."
-            },
-            "description": {
-                "type": "array",
-                "items": [
-                    {
-                        "type": "string"
-                    }
-                ],
-                "description": "A description of the entity, as a list of paragraphs."
-            },
-            "orientation": {
-                "default": "null",
-                "type": "array",
-                "items": [
-                    {
-                        "name": "X coordinate",
-                        "type": "number"
-                    },
-                    {
-                        "name": "Y coordinate",
-                        "type": "number"
-                    }
-                ],
-                "description": "A 2-tuple of integers specifying an orientation vector for the entity. Currently unused."
-            },
-            "growth": {
-                "default": "null",
-                "type": "array",
-                "items": [
-                    {
-                        "name": "minimum",
-                        "type": "number"
-                    },
-                    {
-                        "name": "maximum",
-                        "type": "number"
-                    }
-                ],
-                "description": "For growable entities, a 2-tuple of integers specifying the minimum and maximum amount of time taken for one growth stage. The actual time for one growth stage will be chosen uniformly at random from this range; it takes two growth stages for an entity to be fully grown."
-            },
-            "combustion": {
-                "type": "object",
-                "$ref": "./combustion.json",
-                "description": "Properties of combustion."
-            },
-            "yields": {
-                "default": "null",
-                "type": "string",
-                "description": "The name of the entity which will be added to a robot's inventory when it executes grab or harvest on this entity. If omitted, the entity will simply yield itself."
-            },
-            "properties": {
-                "default": "[]",
-                "type": "array",
-                "items": [
-                    {
-                        "type": "string",
-                        "examples": [
-                            "unwalkable",
-                            "portable",
-                            "infinite",
-                            "known",
-                            "growable"
-                        ]
-                    }
-                ],
-                "description": "A list of properties of this entity. See Entity properties."
-            },
-            "capabilities": {
-                "default": "[]",
-                "type": "array",
-                "items": [
-                    {
-                        "type": "string"
-                    }
-                ],
-                "description": "A list of capabilities provided by entity, when it is equipped as a device. See Capabilities."
-            }
-        },
-        "required": [
-            "name",
-            "display",
-            "description"
-        ]
+        "$ref": "entity.json"
     }
-
 }