Configuration

AstralRoomEditor has no config.yml — its behavior is entirely driven by three folders of definition files under the plugin's data folder, loaded (and reloaded, atomically per-folder) by AstralRoomEditor#loadConfiguration():

Folder	Loads	Service
`components/`	One `ComponentDefinition` per file (flat, any filename).	`ComponentService`
`layouts/<gamemode>/`	One optional `gamemode.yml` (`GamemodeDefinition`) + one `LayoutDefinition` per other file in the folder.	`LayoutService`
`messages.yml`	`EditorMessages` message enum.	core `loadEnum`

Defaults for all of these are shipped as plugin resources and copied to disk on first run (AstralRoomEditor#saveDefaultDefinitions()), only if the target file doesn't already exist.

Component definitions

Each file in components/ maps to one ComponentDefinition (Configurate @ConfigSerializable, camelCase Java fields → kebab-case YAML keys):

Key	Type	Description
`id`	string	The component's id — how it's referenced from a layout's `components`/`required` lists and from `/re set`.
`primitive`	string	One of `position`, `typed-position`, `cuboid`, `oriented-cuboid`, `orientation` — see Overview: placement primitives. Unknown values make the whole definition invalid and it is skipped.
`requires-id`	boolean	Default `false`. When `true`, placement needs an explicit or auto-generated per-instance id (only meaningful for `typed-position` /cuboid primitives).
`item`	strategy spec	How the hotbar tool item is built.
`render`	strategy spec	How the in-world preview is drawn.

A definition is skipped entirely (with a warning logged) if id, primitive, item, or render is missing, or if primitive, render.type, or item.type names something not registered.

Strategy spec

item and render are both a strategy spec: type selects a registered strategy by name, and every other key under the block is passed through as that strategy's raw options node (no fixed schema — see each strategy's option table below).

item:
  type: simple
  material: BEACON
render:
  type: block-display
  block: BEACON

Built-in item strategies (ComponentService's constructor registers these):

`type`	Options	Behavior
`simple`	`material` (Material name, default `STONE`)	Unbreakable item with a green `"<Display Name> Tool"` name and lore describing the click behavior (single click vs. two-click cuboid, undo hint).

Built-in render strategies: see Overview: component rendering for the full block-display/entity/cuboid-outline option tables.

Shipped component definitions

`id`	`primitive`	`requires-id`	Item	Render
`spawn`	`position`	–	`simple` (`BEACON`)	`block-display` (`BEACON`)
`treasure`	`position`	–	`simple` (`CHEST`)	`block-display` (`CHEST`)
`orientation`	`orientation`	–	`simple` (`COMPASS`)	`block-display` (`OBSERVER`)
`bounding_box`	`cuboid`	–	`simple` (`BLAZE_ROD`)	`cuboid-outline` (`CRIT`)
`damage_zone`	`cuboid`	–	`simple` (`MAGMA_BLOCK`)	`cuboid-outline` (`ANGRY_VILLAGER`)
`door`	`cuboid`	`true`	`simple` (`OAK_DOOR`)	`cuboid-outline` (`HAPPY_VILLAGER`)
`dungeon_door`	`oriented-cuboid`	`true`	`simple` (`IRON_DOOR`)	`cuboid-outline` (`HAPPY_VILLAGER`)
`mob`	`typed-position`	`true`	`simple` (`ZOMBIE_HEAD`)	`entity` (`ZOMBIE`, name `Mob`)
`mini_boss`	`typed-position`	`true`	`simple` (`SKELETON_SKULL`)	`entity` (`ZOMBIE`, name `Mini Boss`, `SCALE` 1.5)
`boss`	`typed-position`	`true`	`simple` (`WITHER_SKELETON_SKULL`)	`entity` (`ZOMBIE`, name `Boss`, `SCALE` 3.0)
`generic`	`typed-position`	`true`	`simple` (`COMMAND_BLOCK`)	`entity` (`ARMOR_STAND`, name `Generic`)
`reward`	`typed-position`	`true`	`simple` (`CHEST`)	`entity` (`ARMOR_STAND`, name `Reward`)

Layout and gamemode definitions

layouts/<gamemode>/ is one folder per gamemode; the folder name is the gamemode id (it is not read from YAML). Inside:

An optional gamemode.yml (GamemodeDefinition) supplies a display name and default save block. If it's absent, the gamemode's name falls back to its id, and its default save dirs become rooms/<gamemode-id> and schematics/<gamemode-id>.
Every other .yml/.yaml file in the folder is one LayoutDefinition — its save block is merged field-by-field with the gamemode's defaults (the layout's own keys win; anything it omits is filled from the gamemode).

`GamemodeDefinition`

Key	Type	Description
`name`	string	Display name for the gamemode. Defaults to the folder name if omitted/absent.
`save`	save settings	Defaults inherited by every layout in this folder.

# layouts/tower/gamemode.yml
name: "Tower"
save:
  schematic-format: sponge_v3
  rooms-dir: rooms/tower
  schematic-dir: schematics/tower

`LayoutDefinition`

Key	Type	Description
`id`	string	The layout's id within its gamemode — passed as `<layout>` to `/re create` and `/re load`. Layout ids are namespaced per gamemode; the same id can exist in two different gamemodes.
`components`	list\<string\>	Component ids the layout permits placing; drives which hotbar tools are given on session start.
`required`	list\<string\>	Component types that must be present (by type, not by session key) before `/re save` will succeed. `RoomEditSession#validate()` diffs these against the placed components' types.
`save`	save settings	Overrides the gamemode's defaults field-by-field.

A layout definition is skipped if id or save is missing/null, if save.serializer doesn't name a registered BlueprintSerializer, or if save.schematic-format isn't one of sponge_v3, sponge_v2, mcedit (case-insensitive).

# layouts/tower/boss.yml
id: boss
components:
  - generic
  - spawn
  - mob
  - reward
  - boss
  - bounding_box
  - door
  - damage_zone
required:
  - bounding_box

Save settings

Key	Type	Default	Description
`schematic-format`	string	`sponge_v3`	One of `sponge_v3`, `sponge_v2`, `mcedit`. Selects both the WorldEdit `BuiltInClipboardFormat` used to write the schematic and its file extension (`mcedit` → `.schematic`, otherwise `.schem`).
`rooms-dir`	string	`rooms`	Folder (relative to the data folder) the blueprint YAML is written into.
`schematic-dir`	string	`schematics`	Folder (relative to the data folder) the `.schem`/`.schematic` file is written into.
`filename`	string	`"{name}"`	Blueprint YAML filename (`.yml` appended). Supports `{name}`, `{layout}`, `{gamemode}` substitution.
`exclude-components`	list\<string\>	`[]`	Component session keys dropped from the persisted blueprint on save (still used live, e.g. for the bounds cuboid).
`serializer`	string	`default`	Registered `BlueprintSerializer` name used to write the blueprint YAML. Only `default` (`DefaultBlueprintSerializer`) ships.
`bounds-component`	string	`bounding_box`	Session key of the `CuboidComponent` whose region is exported as the schematic and used to make every other component's position relative on save.

Shipped gamemodes and layouts

Gamemode	Layouts	Required components
`tower`	`lobby`, `monsters`, `mini_boss`, `boss`, `shop`	`bounding_box`
`dungeons`	`spawn`, `corridor`, `mob_room`, `boss_room`, `treasure_room`	`bounding_box` plus a layout-specific component (`spawn`/`dungeon_door`/`mob`/`boss`/`treasure`)

Room blueprints

A saved room is a RoomBlueprint — name, gamemode, layout, the relative schematicPath to its .schem, and a components map keyed by session key (component id, or <componentId>_<n> for id-requiring components). Unlike the definition files above, RoomBlueprint and the RoomComponent impls have no @Setting annotations, so their multi-word fields serialize as raw camelCase, not kebab-case (schematicPath, typeId — not schematic-path/type-id). It's written under <rooms-dir>/<filename>.yml by the layout's serializer:

name: north-tower-01
gamemode: tower
layout: boss
schematicPath: schematics/tower/north-tower-01.schem
components:
  bounding_box:
    component-type: cuboid
    min: [0, 0, 0]
    max: [12, 8, 12]
  spawn:
    component-type: position
    position: [6, 1, 6]
    yaw: 0.0
    pitch: 0.0
  boss_0:
    component-type: typed-position
    position: [6, 1, 10]
    yaw: 180.0
    pitch: 0.0
    typeId: boss_0

RoomComponentTypeSerializer writes the component-type discriminator (its own explicit node("component-type") key, unrelated to the field-naming point above) so the loader can pick the right RoomComponent implementation from RoomEditorRegistries.primitives() when reading it back. Blueprint positions are stored relative to the bounds component's lower-north-east corner — BlueprintService loads every rooms/**/*.yml (recursively, so nested per-gamemode folders work) on startup/reload, and SessionService#load offsets a blueprint's components to the loading player's current location before opening a new session with them.

Last modified: 25 July 2026