Updated Docs, and Cortections

docs/10 - Studio & VSCode Schemas.md

@@ -0,0 +1,179 @@
+# 10 - Studio & VSCode Schemas
+
+Studio is Iris’s live pack-authoring workflow: open a pack as a transient world, edit JSON under `packs/<key>/`, and hotload changes without a full server restart. VSCode (or IntelliJ) gets JSON Schema bindings generated from the Java models so field names, enums, and pack resource keys autocomplete against the real loaders.
+
+Related: see `04 - Commands & Permissions.md`, `05 - Concepts & Pack Layout.md`, `02 - Getting Started.md`, `25 - Pack Management.md`, `30 - Platform Differences.md`.
+
+## What Studio Is
+
+| Concept | Behavior |
+|---------|----------|
+| Pack workspace | Packs live under the platform data directory folder named `packs` (`StudioSVC.WORKSPACE_NAME`). |
+| Studio world | Opened from a pack dimension key; uses a studio chunk generator with live file watching. |
+| Hotload | On studio worlds only: a low-priority looper polls pack files; when content changes, `EngineHotloader` reloads the pack data and rebuilds engine runtime under a lifecycle lock. |
+| Hotload contract | `IrisDimensionRuntimeContract` refuses hotload if dimension type key, min height, total height, or logical height change. Restart the world after those edits. |
+| Non-studio worlds | No pack file watcher looper; production worlds keep the pack snapshot installed at create/update time. |
+
+Studio settings in `settings.json` → `studio` (`IrisSettings.IrisSettingsStudio`):
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `openVSCode` | `true` | When true and the JVM is not headless, `open` / `vscode` may launch the desktop opener on the pack’s `*.code-workspace` file. |
+| `disableTimeAndWeather` | `true` | Studio world time/weather lock preference. |
+| `entitySpawning` | `true` | Whether studio entity spawning is allowed. |
+| `autoStartDefaultStudio` | `false` | Auto-open default studio on boot when enabled. |
+
+## Commands (Bukkit)
+
+Root: `/iris studio` (aliases `std`, `s`). Implemented by `CommandStudio` + `StudioSVC`.
+
+| Subcommand | Aliases | What it does |
+|------------|---------|--------------|
+| `open <dimension> [seed=1337]` | `o` | Close any open studio, open pack as studio world. Blocks if pack validation has blocking errors. |
+| `close` | `x` | Close the active studio project/world. |
+| `create [name=studio] [template=<dimension>]` | `+` | Create a new pack under `packs/<name>`. Optional template is another pack dimension key; without template, writes the starter skeleton (see below). |
+| `vscode [dimension=default]` | `vsc` | Open the pack’s VSCode workspace (generates it if missing). |
+| `update [dimension=default]` | | Rewrite `<pack>/<name>.code-workspace` and regenerate `.iris/schema/*` mappings. |
+| `version [dimension=default]` | | Print dimension `version` field. |
+| `package [dimension=default] [obfuscate=false] [minify=true]` | `pkg` | Compile pack into a distributable archive. |
+| `importvanilla <dimension> [variants=3] [structures=true]` | `importv`, `iv` | Capture vanilla features/structures into the pack (Bukkit NMS). |
+| `scoreboard` | `board`, `sidebar`, `sb` | Toggle studio debug scoreboard (player, must be in studio world). |
+| `noise [generator=<key>] [seed=12345]` | `nmap` | External noise explorer GUI. |
+| `map [world=<world>]` | `render` | External biome/terrain map GUI for an Iris world. |
+| `regions [radius=500]` | | Sample region rarity over a chunk spiral (player in Iris world). |
+| `loot [fast=false] [add=true]` | | Open a virtual chest with loot tables for the block under the player (studio). |
+| `profile [dimension=default]` | | Write a pack performance profile report. |
+| `spawn` / `summon` | | Spawn a pack entity definition at the player. |
+| `stp` | | Teleport to the active studio world spawn in creative. |
+| `objects` / `find-objects` | | Capture nearby chunk object placement report. |
+
+Permissions and the full `/iris` tree: see `04 - Commands & Permissions.md`.
+
+## Commands (Modded)
+
+`/iris studio` on Fabric/Forge/NeoForge is implemented by `ModdedStudioCommands`. Supported: `create`/`+`, `open`/`o`, `close`/`x`, `tpstudio`/`stp`, `status`, `vscode`/`vsc`, `update`, `version`, `package`/`pkg`, `regions`, `noise`/`nmap`, `map`/`render`.
+
+Bukkit-only (modded replies with a fixed message): `importvanilla`, `loot`, `profile`, `spawn`/`summon`, `objects`/`find-objects`.
+
+## Creating a Pack (Starter Skeleton)
+
+`/iris studio create name=mypack` (no template) writes:
+
+```
+packs/mypack/
+  dimensions/mypack.json
+  regions/starter.json
+  biomes/starter.json
+  generators/flat.json
+  mypack.code-workspace
+```
+
+Starter dimension JSON (from `StudioSVC.createStarterProject`):
+
+```json
+{
+  "name": "mypack",
+  "version": 1,
+  "regions": ["starter"],
+  "logicalHeight": 384,
+  "dimensionHeight": {"min": -64, "max": 320}
+}
+```
+
+Starter region lists the same biome for land/sea/shore. Starter biome uses generator `flat`, layers with `minecraft:grass_block`, and derivatives `minecraft:plains`. Project names must normalize to safe pack folder names; reserved name `studio` is auto-renamed to a free suffix.
+
+With a template: `/iris studio create name=mypack template=overworld` copies that pack tree (after optional download if missing).
+
+## Studio Open Workflow
+
+1. Resolve pack folder `packs/<dimensionKey>/` with a loadable `dimensions/<key>.json`.
+2. Pack validation must not report blocking errors (`PackValidationRegistry`).
+3. Close existing studio if open.
+4. `IrisProject.open` creates a studio world bound to that pack folder (not a permanent production install copy for authoring).
+5. Optional VSCode launch when `studio.openVSCode` is true.
+6. Datapack install may require restart after create; message tells you to re-run `open` after restart when needed.
+
+## Hotload Details
+
+- Watcher runs only when `PlatformChunkGenerator.isStudio()` is true (`BukkitChunkGenerator` looper).
+- On change: load a new `IrisData` from the same folder, reload the dimension key, validate hotload contract, build new engine runtime, retire previous data, refresh workspace/schemas, reload datapacks when a platform world is bound, broadcast client studio-hotload toast on failure/success.
+- Complex-only rebuild (`hotloadComplex`) rebuilds `IrisComplex` without full pack reopen.
+- Failed hotload rolls runtime back when possible and reports the error.
+
+Do not change `dimensionHeight`, `logicalHeight`, or the dimension load/type key mid-session if you need live reload; restart the studio world after those edits.
+
+## VSCode / JSON Schemas
+
+`IrisCodeWorkspace` writes `<pack>/<packName>.code-workspace` with:
+
+| Workspace setting | Value / purpose |
+|-------------------|-----------------|
+| `folders` | `[{ "path": "." }]` — pack root |
+| `workbench.colorTheme` | `Monokai` |
+| `files.autoSave` | `onFocusChange` |
+| `[json]` editor options | bracket indent, smart enter, trim whitespace, string quick suggestions |
+| `json.maxItemsComputed` | `30000` |
+| `json.schemas` | Array of `{ fileMatch, url }` entries |
+
+### Schema generation
+
+`SchemaBuilder` reflects a registrant or snippet class and emits JSON Schema draft-07:
+
+- `$schema`: `http://json-schema.org/draft-07/schema#`
+- `$id`: `https://volmit.com/iris-schema/<classname>.json`
+- Field docs from `@Desc`, ranges from `@MinNumber`/`@MaxNumber`, arrays from `@ArrayType`, required from `@Required`
+- Enumerations for platform registries (blocks, biomes, entities, structures, …) and pack resource lists from `@RegistryListResource` / related annotations
+- Snippet types (classes annotated `@Snippet`) get schemas under `.iris/schema/snippet/<snippet>-schema.json`
+
+`ResourceLoader.buildSchema()` for each loader that `supportsSchemas()`:
+
+| Pack folder pattern | Schema URL (relative to pack) |
+|---------------------|--------------------------------|
+| `/<folder>/**/*.json` (up to 7 depth levels) | `./.iris/schema/<folder>-schema.json` |
+
+Example folders with schemas (from loaders / workspace sample): `dimensions`, `regions`, `biomes`, `generators`, `loot`, `entities`, `spawners`, `structures`, `jigsaw-pieces`, `jigsaw-pools`, `expressions`, `blocks`, and others registered on `IrisData`. Object/image/matter loaders may disable schemas.
+
+Snippet paths: `/snippet/<type>/**/*.json` → `./.iris/schema/snippet/<type>-schema.json`.
+
+IntelliJ: workspace update also merges mappings into `.idea/jsonSchemas.xml` when that project file exists.
+
+### Commands that refresh schemas
+
+| Command | Effect |
+|---------|--------|
+| `/iris studio update dimension=<dim>` | Rewrite workspace + queue schema writes |
+| Studio open / create | Builds workspace config including schemas |
+| Hotload workspace refresh | Platform hook may refresh workspace after successful hotload |
+
+Schema files under `.iris/schema/` are generated artifacts for editors; pack content is the JSON under type folders, not the schema files.
+
+## How To: Edit a Pack in Studio
+
+1. Ensure the pack is under the Iris data `packs/` directory (shipping overworld is typically downloaded as pack key `overworld`).
+2. Run `/iris studio open overworld` (or your pack key). Enter the studio world.
+3. Run `/iris studio vscode dimension=overworld` (or open the pack folder’s `*.code-workspace` in VSCode/Cursor with JSON schema support).
+4. Edit `dimensions/`, `regions/`, `biomes/`, etc. Save. Studio hotloads when the file watcher detects the change.
+5. Use `/iris studio map` or the debug scoreboard to inspect regions/biomes. Use `focus` / `focusRegion` on the dimension JSON for isolation while testing (see `11 - Dimensions.md`).
+6. `/iris studio close` when finished. Promote pack changes into production worlds with pack install / world update flows (`06 - Worlds & Lifecycle.md`, `25 - Pack Management.md`).
+
+## Studio Dimension Modes (author testing)
+
+Dimension field `studioMode` (`StudioMode` enum) can force special studio generators:
+
+| Value | Effect |
+|-------|--------|
+| `NORMAL` | Default generation |
+| `BIOME_BUFFET_1x1` … `BIOME_BUFFET_36x36` | Biome buffet grid of given cell size |
+| `REGION_BUFFET` | Region buffet |
+| `OBJECT_BUFFET` | Object studio generator |
+
+These are dimension JSON fields for studio testing, not production world modes (production engine mode is `mode.type`; see `11 - Dimensions.md`).
+
+## Platform Notes
+
+| Platform | Studio |
+|----------|--------|
+| Paper/Purpur/Folia (Bukkit plugin) | Full `CommandStudio` + file-watch hotload on studio worlds |
+| Fabric / Forge / NeoForge | Studio open/create/workspace/package; subset of tooling; no Bukkit-only importers/GUIs that need Bukkit inventory |
+
+Pack JSON contracts are shared across platforms. Schemas are built from the same core models.