Updated Docs, and Cortections

2026-08-30 05:50:48 +00:00 · 2026-08-08 00:29:48 -06:00
parent c40e1cf152
commit 506787f51a
70 changed files with 9485 additions and 3050 deletions
@@ -0,0 +1,291 @@
+# 24 - Pack Mods & Snippets
+
+Snippets are active reusable JSON fragments for types annotated `@Snippet`; fields accept either an inline object or a path under `snippet/<type>/`. Iris also loads the legacy `IrisMod` JSON schema from `mods/`, but no engine path applies those injector or replacer fields at runtime.
+
+Related: `05 - Concepts & Pack Layout.md`, `10 - Studio & VSCode Schemas.md`, `11 - Dimensions.md`, `12 - Regions.md`, `13 - Biomes.md`, `14 - Generators & Noise.md`, `20 - Object Placement.md`, `25 - Pack Management.md`.
+
+## Pack mod schema (`IrisMod`, inactive)
+
+Folder: `mods/`. The loader key is the path under `mods/` without `.json`. `IrisData` can parse and expose these registrants to schema and tooling paths, but engine creation and Studio hotload do not consume them. Treat the fields below as an inactive schema, not a supported way to modify a dimension.
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `name` | string | `"A Pack Modification"` | Required human name (min length 2) |
+| `forDimension` | string | `""` | Optional dimension load key; empty = any dimension |
+| `overrideFluidHeight` | int -1..512 | `-1` | `-1` leaves fluid height unchanged |
+| `removeBiomes` | string[] | `[]` | Biome keys to remove |
+| `removeObjects` | string[] | `[]` | Object keys to remove |
+| `removeRegions` | string[] | `[]` | Region keys to remove |
+| `injectRegions` | string[] | `[]` | Region keys to inject into the dimension |
+| `biomeInjectors` | `IrisModBiomeInjector[]` | `[]` | Inject biomes into a region |
+| `biomeReplacers` | `IrisModBiomeReplacer[]` | `[]` | Swap biomes |
+| `objectReplacers` | `IrisModObjectReplacer[]` | `[]` | Swap object keys |
+| `biomeObjectPlacementInjectors` | `IrisModObjectPlacementBiomeInjector[]` | `[]` | Inject object placements into a biome |
+| `regionObjectPlacementInjectors` | `IrisModObjectPlacementRegionInjector[]` | `[]` | Inject object placements into a region |
+| `regionReplacers` | `IrisModRegionReplacer[]` | `[]` | Swap regions |
+| `blockReplacers` | `IrisObjectReplace[]` | `[]` | Block find/replace rules (same shape as object material replacers) |
+| `styleReplacers` | `IrisModNoiseStyleReplacer[]` | `[]` | Replace `NoiseStyle` usages |
+
+### Injector and replacer shapes
+
+**Biome injector** (`@Snippet("biome-injector")`):
+
+```json
+{ "region": "temperate", "inject": ["temperate/meadows"] }
+```
+
+**Biome replacer** (`biome-replacer`):
+
+```json
+{ "find": ["temperate/plains"], "replace": "temperate/lush-plains" }
+```
+
+**Region replacer** (`region-replacer`):
+
+```json
+{ "find": ["temperate"], "replace": "forests" }
+```
+
+**Object replacer** (`object-replacer`):
+
+```json
+{ "find": ["clutter/camp1"], "replace": "clutter/camp3" }
+```
+
+**Object placement biome injector** (`object-placement-biome-injector`):
+
+```json
+{
+  "biome": "temperate/plains",
+  "place": [{ "chance": 0.01, "place": ["clutter/camp1"] }]
+}
+```
+
+**Object placement region injector** (`object-placement-region-injector`): field name is `biome` in code but the registry type is `IrisRegion` (region load key):
+
+```json
+{
+  "biome": "temperate",
+  "place": [{ "chance": 0.01, "place": ["clutter/camp1"] }]
+}
+```
+
+**Noise style replacer** (`noise-style-replacer`):
+
+| Field | Notes |
+|-------|-------|
+| `find` | `NoiseStyle` enum value to match |
+| `replaceTypeOnly` | When true, only swap the style type and keep other style fields |
+| `replace` | Full `IrisGeneratorStyle` replacement |
+
+**Block replacer** (reuses `IrisObjectReplace`, snippet `object-block-replacer`): `find` block list, `replace` palette, optional `exact`, `chance` 0..1.
+
+### Schema example
+
+`mods/example-swap.json`:
+
+```json
+{
+  "name": "Example Temperate Swap",
+  "forDimension": "overworld",
+  "biomeReplacers": [
+    {
+      "find": ["temperate/plains"],
+      "replace": "temperate/meadows"
+    }
+  ],
+  "biomeInjectors": [
+    {
+      "region": "temperate",
+      "inject": ["temperate/shattered-plains"]
+    }
+  ]
+}
+```
+
+The example is parseable as `IrisMod`, but it has no effect on generated terrain. Apply equivalent changes directly to the target dimension, region, biome, generator, or object-placement JSON.
+
+## Snippets
+
+### Mechanism
+
+1. Many nested pack types carry `@Snippet("type-name")`.
+2. Gson type adapters in `IrisData` intercept those types on read.
+3. A field may be either:
+   - an inline JSON object of that type, or
+   - a **string** `"snippet/<type-name>/<path>"` that loads `snippet/<type-name>/<path>.json` from the pack root.
+4. If the string starts with `snippet/` but uses a different type folder, the loader rewrites to the expected `snippet/<type-name>/` prefix for that field.
+5. Missing snippet files log an error and yield null for that value.
+
+Studio schemas (`SchemaBuilder`) expose every snippet as `anyOf` object-or-string and list files under `snippet/<type>/` in the workspace enum.
+
+### Disk layout
+
+```
+pack/
+  snippet/
+    decorator/
+      bush.json
+      dry_grass.json
+      ...
+    style/
+      bedrock.json
+      deepslate.json
+```
+
+Folder is singular `snippet/`, not `snippets/`. Subfolders match the `@Snippet` value exactly.
+
+### Overworld usage
+
+Dimension ores reference style snippets:
+
+```json
+{
+"chanceStyle": "snippet/style/bedrock"
+}
+```
+
+`snippet/style/bedrock.json`:
+
+```json
+{ "style": "STATIC" }
+```
+
+Biome decorators accept snippet strings in arrays:
+
+```json
+{
+"decorators": [
+  "snippet/decorator/wildflowers",
+  "snippet/decorator/bush"
+]
+}
+```
+
+`snippet/decorator/bush.json`:
+
+```json
+{
+  "chance": 0.03,
+  "style": {
+    "style": "CLOVER_HERMITE",
+    "zoom": 0.52,
+    "exponent": 2.5,
+    "axialFracturing": true
+  },
+  "slopeCondition": { "maximumSlope": 5 },
+  "palette": [
+    { "block": "minecraft:bush", "weight": 1 },
+    { "block": "minecraft:air", "weight": 4 }
+  ]
+}
+```
+
+`biomes/dev.json` uses the same pattern for a minimal decorator list.
+
+### `@Snippet` type names (engine/object)
+
+Each value is the folder name under `snippet/` and the string prefix after `snippet/`:
+
+| Snippet value | Class (representative) |
+|---------------|------------------------|
+| `attribute-modifier` | `IrisAttributeModifier` |
+| `axis-rotation` | `IrisAxisRotationClamp` |
+| `biome-injector` | `IrisModBiomeInjector` |
+| `biome-palette` | `IrisBiomePaletteLayer` |
+| `biome-replacer` | `IrisModBiomeReplacer` |
+| `block-drops` | `IrisBlockDrops` |
+| `cave-field-module` | `IrisCaveFieldModule` |
+| `cave-profile` | `IrisCaveProfile` |
+| `color` | `IrisColor` |
+| `command` | `IrisCommand` |
+| `command-registry` | `IrisCommandRegistry` |
+| `coral` | `IrisCoral` |
+| `crystal` | `IrisCrystal` |
+| `custom-biome` | `IrisBiomeCustom` |
+| `custom-biome-particle` | `IrisBiomeCustomParticle` |
+| `custom-biome-spawn` | `IrisBiomeCustomSpawn` |
+| `decorator` | `IrisDecorator` |
+| `deposit` | `IrisDepositGenerator` |
+| `deposit-variant` | `IrisDepositVariant` |
+| `dimension-carving-entry` | `IrisDimensionCarvingEntry` |
+| `dimension-mode` | `IrisDimensionMode` |
+| `duration` | `IrisDuration` |
+| `effect` | `IrisEffect` |
+| `enchantment` | `IrisEnchantment` |
+| `entity-spawn` | `IrisEntitySpawn` |
+| `expression-function` | `IrisExpressionFunction` |
+| `expression-load` | `IrisExpressionLoad` |
+| `floating-child-biome` | `IrisFloatingChildBiomes` |
+| `formation` | `IrisFormation` |
+| `fungus` | `IrisFungus` |
+| `generator` | `IrisNoiseGenerator` |
+| `generator-layer` | `IrisBiomeGeneratorLink` |
+| `image-map` | `IrisImageMap` |
+| `loot` | `IrisLoot` |
+| `loot-registry` | `IrisLootReference` |
+| `noise-style-replacer` | `IrisModNoiseStyleReplacer` |
+| `object-block-replacer` | `IrisObjectReplace` |
+| `object-limit` | `IrisObjectLimit` |
+| `object-loot` | `IrisObjectLoot` |
+| `object-marker` | `IrisObjectMarker` |
+| `object-placement-biome-injector` | `IrisModObjectPlacementBiomeInjector` |
+| `object-placement-region-injector` | `IrisModObjectPlacementRegionInjector` |
+| `object-placer` | `IrisObjectPlacement` |
+| `object-replacer` | `IrisModObjectReplacer` |
+| `object-rotator` | `IrisObjectRotation` |
+| `object-scale` | `IrisObjectScale` |
+| `object-translator` | `IrisObjectTranslate` |
+| `object-vanilla-loot` | `IrisObjectVanillaLoot` |
+| `palette` | `IrisMaterialPalette` |
+| `position-3d` | `IrisPosition` |
+| `potion-effect` | `IrisPotionEffect` |
+| `procedural-objects` | `IrisProceduralObjects` |
+| `procedural-tree` | `IrisProceduralTree` |
+| `range` | `IrisRange` |
+| `rate` | `IrisRate` |
+| `region-replacer` | `IrisModRegionReplacer` |
+| `ruin` | `IrisRuin` |
+| `ruin-decorator` | `IrisRuinDecorator` |
+| `shaped-style` | `IrisShapedGeneratorStyle` |
+| `slope-clip` | `IrisSlopeClip` |
+| `stilt-settings` | `IrisStiltSettings` |
+| `style` | `IrisGeneratorStyle` |
+| `style-range` | `IrisStyledRange` |
+| `time-block` | `IrisTimeBlock` |
+| `tree` | `IrisTree` |
+| `tree-branches` | `IrisTreeBranches` |
+| `tree-canopy` | `IrisTreeCanopy` |
+| `tree-decorator` | `IrisTreeDecorator` |
+| `tree-layer` | `IrisTreeLayer` |
+| `tree-secondary-leaf` | `IrisTreeSecondaryLeaf` |
+| `tree-settings` | `IrisTreeSettings` |
+| `tree-size` | `IrisTreeSize` |
+| `tree-sub-branches` | `IrisTreeSubBranches` |
+| `vacuum-settings` | `IrisVacuumSettings` |
+
+Registrants that are whole files (dimensions, regions, biomes, generators, loot tables, entities, spawners, markers, mods, objects, structures) are not snippet types; only nested field types listed above are.
+
+### Registered schemas without a production authoring path
+
+Schema registration alone does not prove a runtime consumer. The following types are discoverable by loaders or Studio schema generation but are not supported pack features:
+
+| Surface | Current status |
+|---------|----------------|
+| `potion-effect` / `IrisPotionEffect` | Snippet schema exists, but no production field consumes this type; use the potion fields on `IrisEffect` instead |
+| `matter/` resources | A loader exists for Matter binaries, but generation and runtime code do not consume pack `matter/` resources |
+| `IrisObjectPlacement.translateCenter` | Serialized and copied by `toPlacement`, but no placement path reads the value |
+
+The `mods/*.json` family is likewise schema/tooling-only as documented above.
+
+### Authoring snippets
+
+1. Create `snippet/<type>/<name>.json` matching the field type shape.
+2. Reference as `"snippet/<type>/<name>"` (no `.json` suffix in the string).
+3. Prefer snippets for values reused across many biomes (decorators, styles, palettes).
+4. Open studio so VSCode schemas list available snippet paths under `.iris/schema/snippet/`.
+
+## Related commands
+
+- Pack validation: `/iris pack validate` — see `25 - Pack Management.md`, `04 - Commands & Permissions.md`.
+- Studio open/hotload: `10 - Studio & VSCode Schemas.md`.