Aetherial Structure Compatibility

Version: 1.0.0g
Minecraft: 1.21.1
Loader: NeoForge 21.1.242+
Java: 21
Author: OurElephant
Contact: slon1k.nash@atomicmail.io

Structure compatibility mod for flying isles type generation. Transfers the start of structures to suitable flying islands

Purpose

Aetherial Structure Compatibility (ASC) adapts normal Minecraft structure generation to worlds made from separated flying islands. In an unmodified structure pipeline, a structure start is chosen from the biome and structure-set rules without knowing whether enough terrain exists below or around the resulting pieces. In an island world this can produce structures in the void, structures split between unrelated islands, unsupported rooms, or underground structures outside the available rock mass.

ASC evaluates nearby island terrain before accepting a structure start. It searches for a suitable island and anchor, validates the generated structure against that island, and either generates the start at the target or translates the completed structure pieces, depending on the selected generation strategy.

ASC changes placement only. It does not add structures, replace structure loot, alter structure-set spacing, or change biome eligibility rules beyond probing valid target positions.

How it works

1. Minecraft requests a structure start in its nominal chunk.
2. ASC identifies the structure and loads its individual profile, falling back to the defaults profile when necessary.
3. Nearby columns are sampled and grouped into flying-island candidates.
4. Candidate anchors are ranked by island size, thickness, free space, and relocation distance.
5. ASC generates or relocates the structure according to generationStrategy.
6. The real structure pieces are checked against one island. Surface structures require terrain under most pieces; underground structures require enough containment or overlap; aquatic structures require appropriate water and floor conditions.
7. If no target passes validation, global.fallback determines whether the structure is skipped or kept at its vanilla position.

The nominal start chunk remains the structure owner. The structure pieces and cached bounding box are updated so placement and /locate structure use the relocated geometry while remaining inside Minecraft's maximum eight-chunk structure-reference distance.

Changes to structure generation

• Structure starts can be moved horizontally and vertically to a validated island anchor.
• regenerate_at_target asks the structure generator to create the start at the target chunk.
• generate_then_translate generates the original start first and then moves all completed pieces as a group.
• auto selects the normal target-generation path, with special translation handling for YUNG's Better Mineshafts and buried treasure.
• Surface structures are validated by their real pieces rather than only by one large bounding rectangle.
• Branching mineshafts are checked piece by piece so empty gaps between tunnels do not count as missing terrain.
• Trial Chambers and other piece-aware underground structures are aligned and validated by actual rooms and corridors.
• Standard vertical support columns can be disabled with verticalSupports. Dedicated YUNG compatibility keeps chains while suppressing unwanted solid support legs.
• Already generated structures are not moved retroactively. Test changes in a new world or unexplored chunks.

Performance

ASC performs additional terrain sampling, island detection, candidate ranking, and structure validation while chunks are generated. This increases CPU work during world generation and may noticeably slow chunk generation, especially when using a large search radius, high sampling limits, or many structure mods.

For large worlds and modpacks, it is recommended to use Chunky to pre-generate the intended world area before normal play. C2ME is also recommended for parallel chunk loading and generation, which can reduce the practical impact of ASC on exploration and server startup. Performance still depends on the world preset, hardware, modpack, and configuration values, so test settings on a backup before generating a production world.

Compatibility

ASC has no required structure-mod dependency. It reads the active dynamic STRUCTURE registry, so standard registry-based structures from mods and datapacks can receive profiles automatically.

The bundled template contains ready-to-edit profiles for:

• Vanilla Minecraft structures;
• YUNG's Better Desert Temples;
• YUNG's Better Dungeons;
• YUNG's Better Nether Fortresses;
• YUNG's Better Jungle Temples;
• YUNG's Better Mineshafts;
• YUNG's Better Ocean Monuments;
• YUNG's Better Strongholds;
• YUNG's Better Witch Huts;
• Integrated Dungeons and Structures (IDAS);
• Integrated Stronghold;
• Integrated Villages;
• Revamped Shipwrecks;
• Supplementaries structures.

Dedicated mixins are included for YUNG's Better Mineshafts and YUNG's Better Dungeons where those mods place support legs directly. These optional adapters do not require the YUNG mods to be installed.

The generation and cache code is designed for parallel world generation, including C2ME. Distant Horizons auxiliary world-generation threads do not run island scanning; the configured fallback is used there to avoid worker-thread chunk-generation stalls.

Configuration location

The configuration file is:

config/aetherial_structure_compat.json

When the file does not exist, ASC writes the bundled template. After the structure registry becomes available, ASC expands the file with one complete section per registered structure. Internal keys beginning with _ are migration or template markers and are hidden from the in-game structure list.

Global settings

Field	Default	Accepted value	Description
enabled	true	Boolean	Master switch for ASC. When false, vanilla structure generation is used.
searchRadius	128	16–1024 blocks	Maximum radius used to search for island terrain.
maxRelocationChunks	8	1–8 chunks	Maximum horizontal start relocation. Eight is also Minecraft's structure-reference limit.
cacheRadius	128	16–256 blocks	Radius retained by the island analysis cache.
maxAttempts	32	1–256	Maximum candidate generation attempts for a normal structure.
sampleStep	8	2–64 blocks	Spacing of columns during initial island sampling. Smaller values are more accurate and more expensive.
maxSampleColumns	8192	64–16384	Hard cap on columns inspected during initial island analysis.
validationStep	4	2–32 blocks	Column spacing used during detailed placement validation.
maxValidationColumns	4096	32–8192	Hard cap on columns inspected during detailed validation.
verticalConnectionTolerance	16	0–64 blocks	Maximum vertical separation used when grouping sampled regions into one island.
maxAnchorsPerIsland	12	1–32	Maximum candidate anchor points retained for each island.
maxCacheEntries	64	4–2048	Maximum entries in the main island cache.
maxColumnCacheEntries	786432	8192–2097152	Maximum number of sampled world columns retained.
maxColumnCacheMemoryMb	384	32–512 MiB	Approximate memory ceiling for the column cache.
fallback	skip	skip, vanilla	Action when no suitable island is found: skip the start or retain vanilla placement.
logDecisions	false	Boolean	Writes detailed placement decisions and rejection statistics to the log.

Default and per-structure placement fields

The defaults object provides inherited values. A top-level object named with a structure identifier, such as minecraft:village_plains, overrides those values for that structure.

Field	Default	Accepted value	Description
enabled	true	Boolean	Enables ASC processing for this scope or structure.
chanceMultiplier	1.0	0.0–1.0	Probability that ASC processes a non-mandatory structure start.
mode	auto	auto, surface, underground, aquatic	Target environment. auto infers a mode from the structure identifier.
undergroundPlacement	auto	auto, relaxed, contained, mandatory	Underground containment policy. relaxed accepts partial tunnel overlap; contained requires enclosure; mandatory performs a wider required search.
generationStrategy	auto	auto, regenerate_at_target, generate_then_translate	Chooses whether the start is regenerated at the island or generated first and translated.
verticalSupports	false	Boolean	Allows standard vertical support columns beneath pieces. False is safer for floating terrain.
minRadius	10	0–2048 blocks	Minimum horizontal island radius.
minDepth	5	1–384 blocks	Minimum island thickness or usable vertical depth.
minSurfaceArea	160	0–20000000 columns	Minimum usable surface area.
minSolidPercent	0.18	0.0–1.0	Minimum solid-block fraction in the evaluated island volume.
minStonePercent	0.0	0.0–1.0	Minimum stone-like fraction, primarily for underground structures.
minFreeSpace	0.06	0.0–1.0	Minimum free-volume fraction around or inside the target.
minWaterDepth	0	0–384 blocks	Minimum water depth for aquatic placement.
minWaterCoverage	0.0	0.0–1.0	Minimum fraction of the footprint covered by water.
minFootprintCoverage	0.56	0.0–1.0	Minimum fraction of the structure's real piece footprint supported by the chosen island. Effective thresholds may be stricter for surface or piece-aware structures.
maxSurfaceVariation	14	0–128 blocks	Maximum accepted height variation across the placement.
aquaticPlacement	floor	floor, water_surface, preserve	Aligns aquatic structures to the seabed, water surface, or original relative height.
verticalOffset	0	-64–64 blocks	Additional Y offset applied after alignment.
horizontalMargin	2	0–128 blocks	Additional horizontal clearance around the footprint.
verticalMargin	1	0–128 blocks	Additional clearance above and below the structure.
sizeWeight	0.38	Decimal	Contribution of island size to candidate ranking.
distanceWeight	0.12	Decimal	Contribution of relocation distance to candidate ranking.
thicknessWeight	0.32	Decimal	Contribution of island thickness to candidate ranking.
freeSpaceWeight	0.18	Decimal	Contribution of free volume to candidate ranking.

The four ranking weights do not have to total exactly 1.0, but keeping a normalized sum makes their relative influence easier to understand.