docs: add missing error documentation files and improve incomplete existing docs

README.md

@@ -1,18 +1,104 @@
 # Minecraft-Error-Codes
-The pages for errors codes that can be generated by a diagnoser and referenced
+
+Documentation for error codes generated by the [Blockception Minecraft Bedrock Language Server](https://github.com/Blockception/minecraft-bedrock-language-server). When you click on an error code in your IDE, you are directed to the corresponding page in this repository.
+
+## How Error Code URLs Work
+
+String error codes use dots as separators and map directly to file paths in this repository:
+
+```
+behaviorpack.entity.event.missing
+→ behaviorpack/entity/event/missing.md
+```
+
+Numeric error codes link to the [codes/main.md](./codes/main.md) page with a fragment anchor.
+
+## Error Code Naming Convention
+
+Error codes follow the pattern `<category>.<subcategory>.<type>.<detail>`:
+
+- **category** — The top-level area: `behaviorpack`, `resourcepack`, `minecraft`, `general`, `json`, `molang`, `project`, `debugger`
+- **subcategory** — The specific pack section or feature area (e.g., `entity`, `block`, `mcfunction`)
+- **type** — The kind of issue (e.g., `missing`, `invalid`, `deprecated`)
+- **detail** — Optional further specificity (e.g., `components`, `event`)
+
+## Severity Levels
+
+| Severity | Description |
+|---|---|
+| **error** | The content is invalid and will not work correctly in Minecraft |
+| **warning** | The content uses deprecated or discouraged features that may stop working |
+| **info** | Informational notice about the content |
+| **hint** | A suggestion for improvement (e.g., performance optimizations) |
 
 ## Categories
-- [behaviorpack](./behaviorpack/README.md)
-- [codes](./codes/README.md)
-- [debugger](./debugger/README.md)
-- [diagnostics](./diagnostics/README.md)
-- [general](./general/README.md)
-- [json](./json/README.md)
-- [minecraft](./minecraft/README.md)
-- [molang](./molang/README.md)
-- [project](./project/README.md)
-- [resourcepack](./resourcepack/README.md)
+
+- [behaviorpack](./behaviorpack/README.md) — Behavior pack errors (entities, blocks, functions, biomes, etc.)
+- [codes](./codes/main.md) — Numeric diagnostic codes
+- [debugger](./debugger/) — Internal language server diagnostic errors
+- [diagnostics](./diagnostics/) — Diagnostic component errors
+- [general](./general/) — General value type errors (strings, integers, floats, booleans)
+- [json](./json/) — JSON parsing and structure errors
+- [minecraft](./minecraft/) — Minecraft-specific errors (selectors, commands, modes, format versions)
+- [molang](./molang/) — Molang expression errors and optimizations
+- [project](./project/) — Project configuration errors
+- [resourcepack](./resourcepack/README.md) — Resource pack errors (animations, entities, sounds, textures, etc.)
+
+## Common Error Codes Quick Reference
+
+### General
+| Code | Description |
+|---|---|
+| [`general.string.invalid`](./general/string/invalid.md) | Invalid Minecraft string (e.g., unquoted spaces) |
+| [`general.integer.invalid`](./general/integer/invalid.md) | Value is not a valid integer |
+| [`general.integer.minimum`](./general/integer/minimum.md) | Integer below the minimum allowed value |
+| [`general.integer.maximum`](./general/integer/maximum.md) | Integer above the maximum allowed value |
+| [`general.float.invalid`](./general/float/invalid.md) | Value is not a valid float |
+| [`general.boolean.invalid`](./general/boolean/invalid.md) | Value is not a valid boolean |
+
+### JSON
+| Code | Description |
+|---|---|
+| [`json.invalid`](./json/invalid.md) | Invalid JSON structure or syntax |
+
+### Minecraft
+| Code | Description |
+|---|---|
+| [`minecraft.format_version`](./minecraft/format_version.md) | Format version is missing, invalid, or outdated |
+| [`minecraft.selector.invalid`](./minecraft/selector/invalid.md) | Invalid target selector |
+| [`minecraft.commands.<cmd>.syntax`](./minecraft/commands/syntax.md) | Command syntax error |
+| [`minecraft.commands.<cmd>.obsolete`](./minecraft/commands/obsolete.md) | Obsolete command syntax |
+
+### Behavior Pack
+| Code | Description |
+|---|---|
+| [`behaviorpack.mcfunction.empty`](./behaviorpack/mcfunction/empty.md) | Empty mcfunction file |
+| [`behaviorpack.functions.missing`](./behaviorpack/functions/missing.md) | Cannot find function definition |
+| [`behaviorpack.entities.missing`](./behaviorpack/entities/missing.md) | Cannot find entity definition |
+| [`behaviorpack.entity.event.missing`](./behaviorpack/entity/event/missing.md) | Entity event not defined |
+| [`behaviorpack.entity.permutations`](./behaviorpack/entity/permutations.md) | Deprecated entity permutations |
+| [`behaviorpack.entity.aliases`](./behaviorpack/entity/aliases.md) | Deprecated entity aliases |
+| [`behaviorpack.entity.components.deprecated`](./behaviorpack/entity/components/deprecated.md) | Deprecated entity component |
+| [`behaviorpack.block.components.deprecated`](./behaviorpack/block/components/deprecated.md) | Deprecated block component |
+| [`behaviorpack.biome.components.deprecated`](./behaviorpack/biome/components/deprecated.md) | Deprecated biome component |
+
+### Resource Pack
+| Code | Description |
+|---|---|
+| [`resourcepack.animation.missing`](./resourcepack/animation/missing.md) | Cannot find animation definition |
+| [`resourcepack.entities.missing`](./resourcepack/entities/missing.md) | Cannot find resource pack entity definition |
+
+### Molang
+| Code | Description |
+|---|---|
+| [`molang.optimization.constant-folding`](./molang/optimization/constant-folding.md) | Constant expression can be pre-calculated |
+
+### Internal
+| Code | Description |
+|---|---|
+| [`debugger.internal.exception`](./debugger/internal/exception.md) | Internal language server exception |
+| [`project.settings`](./project/settings.md) | Project configuration issue |
 
 ## Documents
-- [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md)
-- [CONTRIBUTING](CONTRIBUTING.md)
+- [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md)
+- [CONTRIBUTING](CONTRIBUTING.md)

behaviorpack/biome/components/climate/particles.md

@@ -0,0 +1,71 @@
+# Biome - Climate - Particles
+
+`behaviorpack.biome.components.climate.particles`
+
+**Severity:** warning
+
+## Description
+
+The particle capability inside the `minecraft:climate` biome component has been moved to `client_biome.json` files. Defining particles in the server-side biome definition no longer has any effect.
+
+## What triggers this error
+
+This warning is triggered when the language server detects a `particles` property inside the `minecraft:climate` component of a behavior pack biome definition. Since Minecraft moved ambient particle effects to client-side biome definitions, this server-side property is no longer processed.
+
+## Example
+
+The following biome definition uses the deprecated climate particles property:
+
+```jsonc
+{
+  "format_version": "1.13.0",
+  "minecraft:biome": {
+    "description": {
+      "identifier": "example:my_biome"
+    },
+    "components": {
+      "minecraft:climate": {
+        "temperature": 0.8,
+        "downfall": 0.4,
+        "particles": [
+          {
+            "id": "minecraft:ambient_block_chance",
+            "chance": 0.01
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## How to fix
+
+Move the particle definition to the client-side `client_biome.json` file. Create or update the corresponding file in your resource pack:
+
+```jsonc
+// resource_pack/biomes_client/example:my_biome.json
+{
+  "format_version": "1.21.0",
+  "minecraft:client_biome": {
+    "description": {
+      "identifier": "example:my_biome"
+    },
+    "components": {
+      "minecraft:ambient_particles": {
+        "particle": {
+          "id": "minecraft:ambient_block_chance",
+          "chance": 0.01
+        }
+      }
+    }
+  }
+}
+```
+
+Remove the `particles` property from the `minecraft:climate` component in your behavior pack biome file.
+
+## Related errors
+
+- [behaviorpack.biome.components.deprecated](../deprecated.md)
+- [behaviorpack.biome.components.pre_1.17_component](../pre_1.17_component.md)

behaviorpack/biome/components/deprecated.md

@@ -0,0 +1,77 @@
+# Biome - Components - Deprecated
+
+`behaviorpack.biome.components.deprecated`
+
+**Severity:** warning
+
+## Description
+
+A deprecated biome component is being used in this biome definition. These components have been removed or replaced in newer versions of Minecraft Bedrock and may not work correctly.
+
+## What triggers this error
+
+This error is triggered when the language server detects a known deprecated biome component. Known deprecated components include:
+
+- `minecraft:surface_parameters` — replaced by `minecraft:surface_builder`
+- `minecraft:frozen_ocean_surface` — replaced by `minecraft:surface_builder`
+- `minecraft:mesa_surface` — replaced by `minecraft:surface_builder`
+- `minecraft:overworld_generation_rules` — superseded by newer world generation APIs
+- `minecraft:climate` (partially deprecated features)
+
+## Example
+
+The following biome definition uses a deprecated surface component:
+
+```jsonc
+{
+  "format_version": "1.13.0",
+  "minecraft:biome": {
+    "description": {
+      "identifier": "example:my_biome"
+    },
+    "components": {
+      "minecraft:surface_parameters": {
+        "top_material": "minecraft:grass",
+        "mid_material": "minecraft:dirt",
+        "sea_floor_material": "minecraft:gravel",
+        "foundation_material": "minecraft:stone",
+        "sea_material": "minecraft:water"
+      }
+    }
+  }
+}
+```
+
+## How to fix
+
+Replace deprecated surface parameter components with `minecraft:surface_builder`:
+
+```jsonc
+{
+  "format_version": "1.21.0",
+  "minecraft:biome": {
+    "description": {
+      "identifier": "example:my_biome"
+    },
+    "components": {
+      "minecraft:surface_builder": {
+        "identifier": "minecraft:default_surface_builder",
+        "top_material": "minecraft:grass",
+        "mid_material": "minecraft:dirt",
+        "sea_floor_material": "minecraft:gravel",
+        "foundation_material": "minecraft:stone",
+        "sea_material": "minecraft:water"
+      }
+    }
+  }
+}
+```
+
+Refer to the [Minecraft Bedrock biome documentation](https://learn.microsoft.com/en-us/minecraft/creator/reference/content/biomereference/) for the current list of supported biome components.
+
+## Related errors
+
+- [behaviorpack.biome.components.climate.particles](climate/particles.md)
+- [behaviorpack.biome.components.pre_1.17_component](pre_1.17_component.md)
+- [behaviorpack.biome.components.replace_biomes.multiple_dimensions](replace_biomes/multiple_dimensions.md)
+- [behaviorpack.block.components.deprecated](../../block/components/deprecated.md)

behaviorpack/biome/components/pre_1.17_component.md

@@ -0,0 +1,50 @@
+# Biome - Pre 1.17 Component
+
+`behaviorpack.biome.components.pre_1.17_component`
+
+**Severity:** warning
+
+## Description
+
+This biome definition uses a component that predates the Caves and Cliffs update (1.17). These pre-1.17 biome components do not work with custom biomes created using behavior packs and will be silently ignored.
+
+## What triggers this error
+
+This warning is triggered when the language server detects biome components that were part of the legacy biome system used before the Caves and Cliffs update. These components were designed for the old world generation pipeline and are incompatible with the custom biome API available to content creators.
+
+Examples of affected components include older overworld generation components that relied on the pre-1.17 world generation system.
+
+## Example
+
+The following biome definition uses a legacy component that is incompatible with custom biomes:
+
+```jsonc
+{
+  "format_version": "1.13.0",
+  "minecraft:biome": {
+    "description": {
+      "identifier": "example:my_biome"
+    },
+    "components": {
+      "minecraft:overworld_generation_rules": {
+        "hills_transformation": "jungle_hills",
+        "shore_transformation": "beach",
+        "generate_for_climates": [
+          ["cold", 1]
+        ]
+      }
+    }
+  }
+}
+```
+
+## How to fix
+
+Remove or replace the pre-1.17 component with a modern equivalent. For world generation, refer to the current Minecraft Bedrock [custom biomes documentation](https://learn.microsoft.com/en-us/minecraft/creator/documents/custombiomes) to understand which components are supported for add-on biomes.
+
+Note that not all biome features available to vanilla Minecraft biomes can be replicated through the custom biome API. Some features are restricted to built-in biomes only.
+
+## Related errors
+
+- [behaviorpack.biome.components.deprecated](deprecated.md)
+- [behaviorpack.biome.components.replace_biomes.multiple_dimensions](replace_biomes/multiple_dimensions.md)