Fill in some undocumented entries (#356)

* Add permutations description * Adjust grammar * Update description of "num_mip_levels" * Update "atlas_tile" and "blend_frames" property Some properties had completely incorrect titles as well, those were fixed in this commit too. * Update JSON UI schema * Update item schema * Update terrain_texture schema * Update animations schema * Update go_home.json * Update textures schemas
2025-06-25 20:35:53 +02:00
parent c5da42a423
commit 4e6f730320
10 changed files with 43 additions and 37 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,14 +3,17 @@
 When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a
 change, creating an issue for a feature request is also acceptable. For smaller fixes, additions, or changes a simple fork and pull request is sufficient.

-Please note we have a [code of conduct](CODE_OF_CONDUCT.md), please follow it in all your interactions with the project.
+Please note: We have a [Code of Conduct](CODE_OF_CONDUCT.md) that should be followed in all interactions with this project.

 ## Titles

-Titles of elements or object in schemas are preferered to be a capitilized version of the name of the object replacing any special character with a space for example. Some are in need
-of version numbering (behaviors) to help with debugging complex schemas
+Titles of elements or objects in schemas should be a capitilized version of the name of the object, replacing any special character with a space for example. Some are in need
+of version numbering (behaviors) to help with debugging complex schemas.

 ## Description

-Descriptions are to be 1:1 with Microsofts original description of said item. If none are provided or the object doesn't exist in official documentation but is a feature, then
-replace the description with `UNDOCUMENTED`. Or fill in a general description that would hold true even if any changes are made to the workings of the item.
+Descriptions are to be 1:1 with Microsoft's original description of said item. If none are provided or the object doesn't exist in official documentation but is a feature, then
+replace the description with `UNDOCUMENTED` or, preferably, fill in a general description that would hold true even if any changes are made to the workings of the item.
+
+When entering descriptions that are not 1:1 with Microsoft's documentation, be sure to follow the
+[Contributor Style Guide](https://learn.microsoft.com/en-us/minecraft/creator/documents/styleguide?view=minecraft-bedrock-stable) provided by Microsoft.
--- a/source/behavior/animations/animations.json
+++ b/source/behavior/animations/animations.json
@@ -61,7 +61,7 @@
  },
  "type": "object",
  "title": "Animation",
-  "description": "Animation for behavior for.",
+  "description": "An animation definition for an entity.",
  "required": ["format_version", "animations"],
  "additionalProperties": false,
  "properties": {
@@ -74,19 +74,19 @@
      "additionalProperties": {
        "title": "Animation",
        "type": "object",
-        "description": "A single animation definition for.",
+        "description": "A single animation definition for an entity.",
        "additionalProperties": false,
        "propertyNames": { "examples": ["animation.example.foo"] },
        "properties": {
          "animation_length": { "type": "number", "description": "The time in seconds this animation will last.", "title": "Animation Length" },
          "loop": {
            "type": "boolean",
-            "description": "Whenever this animation should loop once it reaches the end, will only happen if the animation is still active.",
+            "description": "If set to true, this animation will loop (as long as it remains active).",
            "title": "Loop"
          },
          "timeline": {
            "title": "Timeline",
-            "description": "A timeline specification, property names are timestamps.",
+            "description": "A timeline specification, where property names are timestamps.",
            "type": "object",
            "propertyNames": { "pattern": "^(\\d+\\.\\d+|\\d+)$", "examples": ["0.0", "1.0"] },
            "additionalProperties": {
@@ -98,7 +98,7 @@
          },
          "anim_time_update": {
            "title": "Animation Time Update",
-            "description": "How does time pass when playing the animation. Defaults to `query.anim_time + query.delta_time` which means advance in seconds.",
+            "description": "How time passes when playing the animation. Defaults to `query.anim_time + query.delta_time` which means advance in seconds.",
            "$ref": "../../molang/number.json"
          }
        }
--- a/source/behavior/blocks/format/minecraft.block.json
+++ b/source/behavior/blocks/format/minecraft.block.json
@@ -136,14 +136,15 @@
    "permutations": {
      "type": "array",
      "title": "Permutations",
-      "description": "UNDOCUMENTED.",
+      "description": "An array of different versions of a block, allowing you to specify which components you want the block to have under certain conditions.",
      "$comment": "UNDOCUMENTED",
      "items": {
        "title": "Permutation",
-        "description": "UNDOCUMENTED.",
+        "description": "A permutation of a block, which will be applied given the condition is met.",
        "$comment": "UNDOCUMENTED",
        "type": "object",
        "additionalProperties": false,
+        "required": [ "condition" ],
        "properties": {
          "condition": {
            "title": "Condition",
--- a/source/behavior/entities/format/behaviors/go_home.json
+++ b/source/behavior/entities/format/behaviors/go_home.json
@@ -10,7 +10,7 @@
    "goal_radius": {
      "type": "number",
      "default": 0.5,
-      "description": "Distance in blocks within the mob considers it has reached the goal. This is the `wiggle room` to stop the AI from bouncing back and forth trying to reach a specific spot",
+      "description": "Distance in blocks within the mob considers it has reached the goal. This is the \"wiggle room\" to stop the AI from bouncing back and forth trying to reach a specific spot",
      "title": "Goal Radius"
    },
    "interval": {
--- a/source/behavior/items/format/minecraft.item.json
+++ b/source/behavior/items/format/minecraft.item.json
@@ -3,7 +3,7 @@
  "additionalProperties": false,
  "required": ["description"],
  "type": "object",
-  "description": "UNDOCUMENTED.",
+  "description": "An item definition.",
  "$comment": "UNDOCUMENTED",
  "title": "Item",
  "properties": {
@@ -11,7 +11,7 @@
      "additionalProperties": false,
      "type": "object",
      "title": "Description",
-      "description": "The description for this item",
+      "description": "The description for this item.",
      "$comment": "UNDOCUMENTED",
      "properties": {
        "identifier": {
--- a/source/resource/textures/flipbook_textures.json
+++ b/source/resource/textures/flipbook_textures.json
@@ -12,29 +12,31 @@
    "type": "object",
    "properties": {
      "atlas_index": {
-        "description": "UNDOCUMENTED.",
+        "description": "The index of the texture array inside the definition of that shortname.",
        "$comment": "UNDOCUMENTED",
        "title": "Atlas Index",
        "type": "integer"
      },
      "atlas_tile": {
-        "description": "UNDOCUMENTED.",
+        "description": "The shortname defined in the terrain_texture JSON file.",
+        "markdownDescription": "The shortname defined in the terrain_texture.json file.",
        "$comment": "UNDOCUMENTED",
        "pattern": "^[a-z0-9_:\\-]*$",
-        "title": "Atlas Index",
+        "title": "Atlas Title",
        "type": "string"
      },
      "atlas_tile_variant": {
-        "description": "UNDOCUMENTED.",
+        "description": "The variant of the block's texture array inside the shortname's block variation.",
        "$comment": "UNDOCUMENTED",
-        "title": "Atlas Index",
+        "title": "Atlas Tile Variant",
        "type": "integer"
      },
      "blend_frames": {
-        "description": "UNDOCUMENTED.",
+        "description": "Whether or not Minecraft should interpolate between frames.",
        "$comment": "UNDOCUMENTED",
-        "title": "Atlas Index",
-        "type": "boolean"
+        "title": "Blend Frames",
+        "type": "boolean",
+        "default": true
      },
      "flipbook_texture": {
        "description": "A texture file.",
@@ -44,7 +46,7 @@
      },
      "frames": {
        "title": "Frames",
-        "description": "The collection of frame index to display.",
+        "description": "The order in which frame indices to display. Duplicate frames are allowed.",
        "items": {
          "description": "The index of the frame.",
          "minimum": 0,
@@ -54,10 +56,11 @@
        "type": "array"
      },
      "replicate": {
-        "description": "UNDOCUMENTED.",
+        "description": "Sets the size of pixels.",
        "$comment": "UNDOCUMENTED",
-        "title": "Atlas Index",
-        "type": "integer"
+        "title": "Replicate",
+        "type": "integer",
+        "default": 1
      },
      "ticks_per_frame": {
        "description": "The amount of ticks to wait between frames.",
--- a/source/resource/textures/terrain_texture.json
+++ b/source/resource/textures/terrain_texture.json
@@ -39,7 +39,7 @@
              "items": {
                "type": "object",
                "title": "Variantion",
-                "description": "One of the variantions, specified along with a possible weight.",
+                "description": "One of the variations, specified along with a possible weight.",
                "$comment": "UNDOCUMENTED",
                "required": ["path"],
                "properties": {
@@ -54,22 +54,22 @@
    }
  },
  "properties": {
-    "num_mip_levels": { "type": "integer", "title": "Num Mip Levels", "description": "Sets the number of mipmap levels for better texture quality at varying distances.", "$comment": "UNDOCUMENTED" },
+    "num_mip_levels": { "minimum": 0, "maximum": 4, "default": 4, "type": "integer", "title": "Num Mip Levels", "description": "Sets the number of mipmap levels for reducing texture quality at varying distances. More mipmap levels means reduced texture quality at farther distances.", "$comment": "UNDOCUMENTED" },
    "padding": { "type": "integer", "title": "Padding", "description": "Adds buffer space to prevent textures from bleeding into each other.", "$comment": "UNDOCUMENTED" },
-    "resource_pack_name": { "type": "string", "title": "Resource Pack Name", "description": "UNDOCUMENTED.", "$comment": "UNDOCUMENTED" },
+    "resource_pack_name": { "type": "string", "title": "Resource Pack Name", "description": "The name of your resource pack, which should match the name in this pack's manifest.", "markdownDescription": "The name of your resource pack, which should match the name in `manifest.json`.", "$comment": "UNDOCUMENTED" },
    "texture_data": {
      "type": "object",
      "propertyNames": { "pattern": "^[a-z0-9_:.\\-]*$" },
      "additionalProperties": {
        "type": "object",
        "title": "Texture Data",
-        "description": "UNDOCUMENTED.",
+        "description": "Describes the texture, including properties like the path to the texture.",
        "$comment": "UNDOCUMENTED",
        "properties": {
          "textures": { "oneOf": [{ "$ref": "#/definitions/texture" }, { "type": "array", "items": { "$ref": "#/definitions/texture" } }] }
        }
      },
-      "description": "UNDOCUMENTED.",
+      "description": "A JSON object with shortnames and texture data.",
      "$comment": "UNDOCUMENTED",
      "title": "Texture Data"
    },
--- a/source/resource/ui/elements/properties/bindings.json
+++ b/source/resource/ui/elements/properties/bindings.json
@@ -47,10 +47,11 @@
          },
          "binding_type": {
            "title": "Binding Type",
-            "description": "The type of the binding.",
+            "description": "The type of the binding. The default is global.",
            "anyOf": [
              {
-                "enum": ["collection", "global", "collection_details", "none", "view"]
+                "enum": ["collection", "global", "collection_details", "none", "view"],
+                "default": "global"
              },
              {
                "$ref": "../../general/variable.json"
--- a/source/resource/ui/elements/properties/font_size.json
+++ b/source/resource/ui/elements/properties/font_size.json
@@ -3,7 +3,7 @@
  "description": "The size of the font.",
  "anyOf": [
    {
-      "enum": ["normal"]
+      "enum": [ "small", "normal", "large", "extra_large" ]
    },
    {
      "$ref": "../../general/item_ref.json"
--- a/source/resource/ui/general/size.json
+++ b/source/resource/ui/general/size.json
@@ -34,13 +34,11 @@
      "items": [
        {
          "title": "Width",
-          "type": "string",
          "description": "A variable",
          "$ref": "#/definitions/size_coord"
        },
        {
          "title": "Height",
-          "type": "string",
          "description": "A variable",
          "$ref": "#/definitions/size_coord"
        }