Remote Sky Garden runtime
Once-per-world preparation, extended build height, authored arrival planes and the permanent travel destination.
Remote Sky Garden is prepared in the Overworld before player entry. Its startup service is an internal implementation, not a public API. Gameplay and administrator options are covered by world spawn and world spawn configuration.
What it does
The existing semi-random ground search selects a region. Garden placement inspects generated columns across the footprint and raises the structure above obstructions. All terrain and biomes are eligible; one bounded search permits at most 4 generated-footprint surveys. Preparation preserves terrain, normal lighting, mandatory clearance and border checks. Missing or invalid garden content disables the opening for the current server session and restores ordinary spawn handling. Flat and debug worlds skip preparation.
OverworldHeight extends the Overworld dimension types during terrain registry bootstrap, before any world or chunk is constructed. It reads the active descriptor and bounded manifest headers through the same loader used by placement, then reserves the complete garden span and configured clearance above the preset’s original terrain envelope, with 17 blocks for the strict ceiling check. The result rounds up to a 16-block section and respects Minecraft’s legal height limits. It preserves the configured minimum ceiling, the preset’s greater height, minimum Y and other dimension properties. A terrain envelope ending at Y 1024 with the shipped garden and default clearance gets an exclusive build ceiling of 1488. Noise height and sea level stay unchanged. The ceiling is rebuilt from the original preset on load; extensions do not accumulate.
Runtime model
WorldSpawnSetupMixin wraps MinecraftServer.setupSpawn, which vanilla calls before marking a new world initialized. It selects the ordinary ground spawn, loads the saved world border and attempts garden preparation. SkyGardenStartupMixin runs at the start of MinecraftServer.prepareStartRegion to restore a reservation or attempt optional preparation for an existing world. Missing garden state alone never identifies a fresh world. The server loads the descriptor, validates every native piece, saves the origin and resource digest, then writes terrain, architecture, the arrival marker and the chapter developer layer in order. Explicit air clears prior layers; omitted cells preserve them. Piece decoding is bounded. World writes retain ordinary lighting semantics. A final pass resolves neighbour shapes and schedules fluids after all layers exist.
The marker is consumed after placement and chunks are flushed before readiness is saved. Reopening validates the recorded arrival and uses the ready hub without repasting. Interrupted preparation retries its reservation. A different prototype digest or insufficient height rejects that hub, clears its runtime availability and restores the saved ordinary spawn and marker; old layouts are not migrated. No permanent world opt-out is stored, so startup can retry. Fresh worlds may lower preferred altitude, never mandatory clearance. Preparation is synchronous during loading; full-pack startup cost still needs measurement.
isekaiexpansion_sky_garden stores origin, digest, bounds, arrival and readiness. isekaiexpansion_world_spawn stores the active marker plane. Garden state uses version 2, including the saved ordinary spawn and marker; world-spawn state remains version 1. The hub contributes its exact three-dimensional bounds to protected zones, decoration guards and climate. A separate spawn policy extends hostile natural-spawn exclusion below its horizontal footprint to the world floor; it does not extend building protection or climate to the terrain below. Returning players keep their saved position, and personal respawn points keep precedence.
The travel ledger uses version 1 with a tagged destination: none, sky_garden, anchor or companion. Empty new ledgers default to the hub. Availability and coordinates sync to the owner; destination selection and landing remain server-authoritative. The hub uses no anchor slot and cannot be forgotten. With no prepared hub, the first attuned anchor becomes the destination. Old prototype ledger layouts are rejected.
Contracts
Optional Voxy warmup
spawn.skyGarden.preloadVoxyLod defaults to true. During join warmup, a compatible Voxy client near the prepared garden requests its full saved bounds once per connection. The server selects every intersecting chunk column and vertical section, sends nonempty section palettes and copied block/sky light, and never accepts client-selected coordinates. The client feeds these snapshots to Voxy without installing vanilla client chunks. Voxy World Gen is not required for this transfer.
The optional bridge binds public Voxy members by reflection, checked against the local 0.2.14-alpha source for Minecraft 1.20.1. Missing Voxy, an unavailable renderer or an incompatible binding closes this activity and allows normal joining. It does not introduce a hard mod dependency.
| Bound | Value | Behaviour |
|---|---|---|
| Garden envelope | 2048 chunk columns / 64 vertical sections | Larger envelopes skip prefetch. |
| Outstanding chunk tickets | 4 per transfer / 16 globally | Asynchronous FULL loads; tickets are released after copying or cancellation. |
| Server copy budget | 3 ms per tick globally | Transfers rotate fairly; at most 256 sections are scanned per visit. |
| Packet | 32 sections / 262144 bytes | One page in flight; the next follows client acknowledgement. |
| Client ingestion | 16 sections / 2 ms per tick | Pauses when Voxy has more than 256 queued jobs. |
| Deadlines | 115 seconds client / 2400 ticks (120 seconds) server | The configured warmup deadline or Skip may stop earlier. |
World change, leaving the garden, disconnect, Skip and warmup closure release pending work. Normal completion waits for the Voxy ingestion queue to drain and remain quiet for 750 ms. A timeout or skipped warmup can leave partial scenery; normal Voxy ingestion continues. This prefetch does not override the player’s Voxy render distance or maintain a second terrain cache.
Run gradlew.bat -I tools/gems/verify.gradle checkLaunchContent for the section palette/light round trip. In game, compare a cold Voxy cache with Voxy absent, Voxy World Gen absent, the switch disabled, a remote client and simultaneous joins; inspect the whole garden before the introduction and verify Skip/disconnect releases tickets.
Natural spawn exclusion
SkyGardenSpawnPolicy is an internal, allocation-free position predicate over the cached bounds. All unmanaged natural spawns remain excluded inside the garden. Below it, only entity types in SpawnGroup.MONSTER are excluded, including caves, down to the world’s minimum Y. Horizontal edges are inclusive; outside the footprint and above the garden the rule has no effect. Wildlife, ambient and aquatic groups remain eligible below it.
The boundary binds before placement and on reopening a saved reservation, and clears on server stop. AtelierSpawnHelperMixin rejects ordinary candidates before mob creation, including the data-pack natural-spawn pools. Server-world and chunk-region admission checks reuse LandmarkSpawnPolicy.Source for initialized mobs. Its unmanaged reasons are NATURAL, CHUNK_GENERATION, STRUCTURE, PATROL, REINFORCEMENT and JOCKEY. Commands, spawn eggs, spawners, authored events and existing entities retain their existing behaviour. Queries perform no chunk loading, biome lookups, entity scans or persistent-state reads.
Local climate
The garden’s saved volume carries a fixed climate overlay. SkyGardenClimateAPI under api.world delegates to internal.climate; its read-only contains and biome queries work on server and client world views after boundary installation. Outside the volume, biome returns null and ordinary lookup continues. Queries read an immutable world-owned snapshot without loading chunks or consulting persistent state. The registry biome is isekaiexpansion:remote_sky_garden; it never enters the terrain biome source or rewrites stored chunk palettes.
| Rule | Value | Scope |
|---|---|---|
| Temperature | 0.8 | Minecraft biome temperature, including position queries; altitude does not lower it. |
| Precipitation | None | Rain, snowfall, natural freezing, snow accumulation and rain-dependent lightning selection are excluded inside the saved volume. |
| Grass and foliage | Fixed colours | The garden biome does not use seasonal temperature or tint changes. |
| Existing ordinary ice and snow layers | Thaw on random ticks | Only minecraft:ice and minecraft:snow; packed ice, blue ice and Conquest decorations retain their own behaviour. Requires loaded, ticking chunks and a nonzero random tick speed. |
The boundary installs before first placement and on every ready-world startup. A server-to-client snapshot on joining carries its presence and six integer bounds. The client reapplies it after dimension changes and discards it on disconnect; no client coordinates control server protection. Climate uses the bounds in garden state version 2; no migration reader is supplied.
SkyGardenClimateClientAPI.sheltered is a client/render-thread camera query. Inside the volume, client rain and thunder gradients and lightning flashes return zero, and new weather-category sounds are suppressed. Server weather and time continue unchanged. Precipitation columns overlapping the boundary use the dry biome when viewed from outside; their vertical sampling margin is 10 blocks. Vanilla rain splashes use the same biome overlay. Shader packs or third-party weather systems that bypass these queries need their own integration and an in-game check.
Sodium 0.5.13 has an optional biome-slice adapter because its worker renderer bypasses vanilla biome access. It reads the same world snapshot without allocating a block position per sample. The existing mixin plugin enables this adapter only when Sodium is installed.
Ordered bundle descriptor
The resource is data/isekaiexpansion/spawn/remote_sky_garden.json. Resource priority selects one complete descriptor; layers do not merge across packs. The shipped layers are remote_sky_garden / terrain-v4-fit1, remote_sky_garden_architecture / architecture-v11, remote_sky_garden_arrival / spawn-v1 and remote_sky_garden_story / chapter-v1, all in namespace isekaiexpansion. They contain 281 native pieces and 6017392 listed cells, including clearing air, the marker and chapter developer blocks. Opening chapter owns their personal progression.
| Field | Type | Default | Contract |
|---|---|---|---|
schema | integer | Required | Exactly 1. |
layers | array of objects | Required | 1–8 ordered native bundle references. |
layers[].id | identifier string | Required | Existing bundled manifest ID. |
layers[].revision | string | Required | Existing immutable bundle revision. |
spawnMarker | integer array | Required | Exactly 3 coordinates in the common local frame, inside the combined bounds. |
Unknown descriptor or layer keys, fractional coordinates, missing resources, bad hashes, unknown states and invalid piece data fail preparation. Exactly one world-spawn marker must exist at the declared position. Native bundle schema and limits are documented in Atelier structures.
World spawn marker
isekaiexpansion:world_spawn_point is an operator authoring block. Feet are one block above its position. The shipped marker replaces the pinned gold cell at local (0, -1, 183), producing feet Y 0 before the world-origin offset.
| Field | Type | Default | Contract |
|---|---|---|---|
Radius | NBT int | 10 | Horizontal circular radius, 0–64 blocks. |
Yaw | NBT float | 180 | Finite degrees; the configure command accepts -180–180. Rotation and mirroring transform it. |
FinalState | NBT compound | Gold block | Native block state, restored after consuming the marker. Must be dry, non-air and have no block entity. |
FinalState.Name | NBT string | Required when supplying FinalState | Registered block ID. |
FinalState.Properties | NBT compound of strings | Omitted | Exact valid state properties; see native state validation. |
Missing marker fields use defaults; present fields with wrong types fail. Applying also requires a full safe floor at the centre and clear body space. Unsafe application restores the marker and leaves world spawn unchanged. Runtime arrivals sample only safe cells on the saved plane, favour empty cells, and fail if the plane has no safe stand. They do not use the heightmap, ground-arrival settings or the spawnRadius game rule.
The developer block has no automatic ticker. Hub preparation and manual Atelier postprocessing consume it; a plain template placement must explicitly apply it. Placement journals now use schema 3, with spawn before/after snapshots. Undo restores the prior spawn only if the current spawn still matches this job’s result, preserving later administrator changes. Bundle, draft and natural-landmark schemas remain 2; no old journal reader is retained.
Extending it
A creative operator obtains a marker with /ise dev world_spawn block, sets its plane with /ise dev world_spawn configure <pos> <radius> <yaw>, and consumes it with /ise dev world_spawn apply <pos>. Commands require permission level 2. Author FinalState through typed block-entity NBT when gold is not the desired restored floor. Keep the marker under walkable floor rather than on a roof.
Studio uses distinct physical icons for developer blocks. The garden viewer’s marker and radius overlay read the deployment metadata generated by the companion export tool; they are authoring aids, not extra shipped geometry. Refresh the live block catalogue after installing a build that registers the new block.
Verifying
Run gradlew.bat compileJava, the SpawnAnchorTest, TravelHubTest and SkyGardenClimateTest tests, and gradlew.bat -I tools/atelier/verify.gradle checkSkyGarden. Run SkyGardenSiteTest, SkyGardenSpawnPolicyTest and OverworldHeightTest for terrain-independent placement, existing-world fallback, automatic height, spawn-source and boundary regressions. checkSkyGardenStartup, with atelierMinecraftIntermediary, checks the active bundle envelope, Minecraft dimension codec and remapped startup and spawn-admission hooks. The native check verifies all piece hashes, bounds and counts, typed marker rotation, and the 317 supported clear terrace cells. It does not instantiate Conquest’s runtime collision shapes.
Use a fresh prototype world for acceptance: verify preparation completes before entry, the first arrival faces the sanctuary, simultaneous arrivals spread safely, personal respawn and reconnect positions survive, the hub appears in the ledger, and reopening creates no second island. Test hostile natural attempts on the surface and in caves below the footprint, wildlife below, each footprint edge, above the garden, explicit spawners and commands, and reopening a saved world. Measure startup time and inspect normal lighting and the selected shader. Live Conquest placement, fluid behaviour and shader appearance require this in-game pass.
For climate acceptance, force rain and thunder with cold surrounding terrain. Check water, snow layers, grass and leaf tints, rain sheets, splashes, sounds and flashes inside the garden, just outside every face and over the sea below. Repeat after dimension travel, reconnect and server restart, including two clients on opposite sides of the boundary. checkSkyGardenClimateMixins checks the remapped injection targets against the Minecraft intermediary jar supplied as atelierMinecraftIntermediary and the Sodium runtime jar supplied as atelierSodiumRuntime. checkSkyGardenClimateData decodes the shipped biome with Minecraft’s codec. These checks do not replace this visual pass.