YUNG's API jigsaw draws: yung_jigsaw structures and yung_single_element read as written

Clean-room, from spec-yungsapi.md §2.1 and §3.1 (no mod source read).
A `yungsapi:yung_jigsaw` structure lays out with the jigsaw assembler and
YUNG's draws: the start pool's file entries shuffled, then the rotation,
then a weighted pick in the shuffled order; each jigsaw's target pool is
drawn by weight from its shuffled entries without replacement, an element
whose `name` already has `max_count` pieces skipped at no other draw.
`yungsapi:yung_single_element` places what a single element places; its
pool entry carries the name and limit.

tools/test_structure_layout_parity.py --profile betterdungeons reads the
mod's own data from its jar into an overlay of the 26.3 resources and
compares the mod world's pieces: 82 of 84 Better Dungeons starts match
piece for piece (60 small, 11 skeleton, 11 zombie dungeons, up to 790
pieces); the other 2 sit in 26.3's sulfur_caves, which 1.21.1 lacks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-25 05:08:43 +01:00
parent 8948bf90c4
commit 41f8cfa3bc
3 changed files with 307 additions and 22 deletions
@@ -122,7 +122,11 @@ impl PoolElement {
};
Ok(match kind {
"minecraft:empty_pool_element" => Self::Empty,
"minecraft:single_pool_element" | "minecraft:legacy_single_pool_element" => {
// YUNG's API's element places what a single element places; its
// `name` and `max_count` are the pool entry's (`Pool::limits`).
"minecraft:single_pool_element"
| "minecraft:legacy_single_pool_element"
| "yungsapi:yung_single_element" => {
let location = value["location"]
.as_str()
.ok_or(DecodeError::Field("location"))?;
@@ -336,6 +340,9 @@ pub struct Pool {
pub(super) templates: Vec<Arc<PoolElement>>,
/// The elements with their weights, in file order (`rawTemplates`).
pub(super) raw: Vec<(Arc<PoolElement>, i32)>,
/// Per entry of `raw`: a YUNG element's `name` and `max_count`, the most
/// pieces of that name in one start.
limits: Vec<Option<(Arc<str>, i32)>>,
pub(super) fallback: String,
max_size: OnceLock<i32>,
}
@@ -354,6 +361,16 @@ impl Pool {
shuffle(&mut copy, random);
copy
}
/// YUNG's API's pick: `nextInt` of the entries' total weight, walked in
/// `order` (indices into `raw`); the entry that takes it below zero.
fn weighted(&self, order: &[usize], random: &mut impl RandomSource) -> Option<usize> {
let total: i32 = order.iter().map(|&i| self.raw[i].1).sum();
let mut pick = random.next_int_bound(total).ok()?;
order.iter().position(|&i| {
pick -= self.raw[i].1;
pick < 0
})
}
pub(super) fn max_size(&self) -> i32 {
*self.max_size.get_or_init(|| {
self.templates
@@ -393,7 +410,7 @@ impl Pools {
}
let pool = self.raw.get(name).and_then(|json| {
let value: Value = serde_json::from_str(json).ok()?;
let (mut templates, mut raw) = (Vec::new(), Vec::new());
let (mut templates, mut raw, mut limits) = (Vec::new(), Vec::new(), Vec::new());
for entry in value["elements"].as_array()? {
let element =
match PoolElement::decode(&entry["element"], resources, bindings, None) {
@@ -410,10 +427,22 @@ impl Pools {
templates.push(element.clone());
}
raw.push((element, weight as i32));
let fields = &entry["element"];
limits.push(
match (fields["name"].as_str(), fields["max_count"].as_i64()) {
(Some(name), Some(max))
if fields["element_type"] == "yungsapi:yung_single_element" =>
{
Some((name.into(), max as i32))
}
_ => None,
},
);
}
Some(Arc::new(Pool {
templates,
raw,
limits,
fallback: value["fallback"]
.as_str()
.unwrap_or("minecraft:empty")
@@ -587,6 +616,93 @@ pub trait JigsawContext {
/// couldStructureExistInColumn over inclusive block Y bounds.
fn column_has_valid_biome(&mut self, x: i32, z: i32, min_y: i32, max_y: i32) -> bool;
}
/// How a jigsaw structure draws its pieces.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Draws {
/// JigsawPlacement's.
Vanilla,
/// YUNG's API's `yungsapi:yung_jigsaw` (spec-yungsapi §2.1, §3.1): pools
/// are drawn by weight from their file entries, without replacement, and
/// an element at its `max_count` is skipped.
Yung,
}
/// The elements a jigsaw tries, in order.
enum Candidates {
/// Vanilla: the target pool's weight-expanded elements, then the
/// fallback's, each shuffled up front.
Listed(std::vec::IntoIter<Arc<PoolElement>>),
/// YUNG's: weighted picks from each pool in turn (the fallback's only
/// once the target's are spent), each pool's entries shuffled when it
/// is reached.
Weighted {
pools: Vec<Arc<Pool>>,
current: Option<(Arc<Pool>, Vec<usize>)>,
},
}
impl Candidates {
fn new(
draws: Draws,
target: &Arc<Pool>,
fallback: &Arc<Pool>,
below_max_depth: bool,
random: &mut impl RandomSource,
) -> Self {
let pools = if below_max_depth {
vec![target.clone(), fallback.clone()]
} else {
vec![fallback.clone()]
};
match draws {
Draws::Vanilla => Self::Listed(
pools
.iter()
.flat_map(|pool| pool.shuffled(random))
.collect::<Vec<_>>()
.into_iter(),
),
Draws::Yung => Self::Weighted {
pools: pools.into_iter().rev().collect(),
current: None,
},
}
}
/// The next element to try, with its YUNG name and limit.
fn next(
&mut self,
counts: &HashMap<Arc<str>, i32>,
random: &mut impl RandomSource,
) -> Option<(Arc<PoolElement>, Option<Arc<str>>)> {
match self {
Self::Listed(elements) => elements.next().map(|e| (e, None)),
Self::Weighted { pools, current } => loop {
let (pool, order) = match current {
Some((pool, order)) if !order.is_empty() => (pool, order),
_ => {
let pool = pools.pop()?;
let mut order: Vec<usize> = (0..pool.raw.len()).collect();
shuffle(&mut order, random);
*current = Some((pool, order));
continue;
}
};
let Some(at) = pool.weighted(order, random) else {
order.clear();
continue;
};
let entry = order.remove(at);
let limit = pool.limits[entry].clone();
if let Some((name, max)) = &limit
&& counts.get(name).copied().unwrap_or(0) >= *max
{
continue;
}
return Some((pool.raw[entry].0.clone(), limit.map(|(name, _)| name)));
},
}
}
}
pub struct JigsawConfig<'a> {
pub start_pool: &'a str,
pub start_jigsaw: Option<&'a str>,
@@ -628,6 +744,30 @@ pub fn assemble(
bindings: &FeatureBlockBindings<'_>,
random: &mut impl RandomSource,
position: [i32; 3],
) -> Option<([i32; 3], Vec<PoolPiece>)> {
assemble_drawing(
Draws::Vanilla,
config,
context,
pools,
resources,
bindings,
random,
position,
)
}
/// [`assemble`] with the given draws.
#[allow(clippy::too_many_arguments)]
pub fn assemble_drawing(
draws: Draws,
config: &JigsawConfig<'_>,
context: &mut impl JigsawContext,
pools: &Pools,
resources: &StructureResources,
bindings: &FeatureBlockBindings<'_>,
random: &mut impl RandomSource,
position: [i32; 3],
) -> Option<([i32; 3], Vec<PoolPiece>)> {
let alias = |name: &str| {
config
@@ -636,9 +776,24 @@ pub fn assemble(
.cloned()
.unwrap_or_else(|| name.to_owned())
};
let rotation = Rotation::random(random);
let center_pool = pools.get(&alias(config.start_pool), resources, bindings)?;
let element = center_pool.random_template(random);
let (rotation, element, limit) = match draws {
Draws::Vanilla => {
let rotation = Rotation::random(random);
(rotation, center_pool.random_template(random), None)
}
// The entries shuffled, then the rotation, then a weighted pick in
// the shuffled order.
Draws::Yung => {
let mut order: Vec<usize> = (0..center_pool.raw.len()).collect();
shuffle(&mut order, random);
let rotation = Rotation::random(random);
let entry = order[center_pool.weighted(&order, random)?];
let (element, _) = &center_pool.raw[entry];
let limit = center_pool.limits[entry].clone().map(|(name, _)| name);
(rotation, element.clone(), limit)
}
};
if matches!(element.as_ref(), PoolElement::Empty) {
return None;
}
@@ -691,7 +846,10 @@ pub fn assemble(
let low_y = (cy - v).max(context.min_y() + config.padding[0]);
let high_y = (cy + v + 1).min(context.max_y() + 1 - config.padding[1]);
let container = BoundingBox::new([cx - h, low_y, cz - h], [cx + h, high_y - 1, cz + h]);
add_children(
let counts = limit.into_iter().map(|name| (name, 1)).collect();
add_children_drawing(
draws,
counts,
config,
context,
pools,
@@ -719,6 +877,32 @@ pub(super) fn add_children(
random: &mut impl RandomSource,
pieces: &mut Vec<PoolPiece>,
container: BoundingBox,
) {
add_children_drawing(
Draws::Vanilla,
HashMap::new(),
config,
context,
pools,
resources,
bindings,
random,
pieces,
container,
);
}
#[allow(clippy::too_many_arguments)]
fn add_children_drawing(
draws: Draws,
counts: HashMap<Arc<str>, i32>,
config: &JigsawConfig<'_>,
context: &mut impl JigsawContext,
pools: &Pools,
resources: &StructureResources,
bindings: &FeatureBlockBindings<'_>,
random: &mut impl RandomSource,
pieces: &mut Vec<PoolPiece>,
container: BoundingBox,
) {
let free = Rc::new(RefCell::new(Free {
container,
@@ -731,6 +915,8 @@ pub(super) fn add_children(
bindings,
pieces,
queue: BTreeMap::new(),
draws,
counts,
};
placer.children(0, free, 0, context, random);
while let Some(state) = placer.next() {
@@ -745,6 +931,9 @@ struct Placer<'a, 'p> {
pieces: &'p mut Vec<PoolPiece>,
/// SequencedPriorityIterator: highest priority first, FIFO within one.
queue: BTreeMap<i32, VecDeque<PieceState>>,
draws: Draws,
/// Pieces placed per YUNG element name.
counts: HashMap<Arc<str>, i32>,
}
impl Placer<'_, '_> {
fn next(&mut self) -> Option<PieceState> {
@@ -816,12 +1005,14 @@ impl Placer<'_, '_> {
} else {
context_free.clone()
};
let mut targets = Vec::new();
if depth != self.config.max_depth {
targets.extend(target_pool.shuffled(random));
}
targets.extend(fallback.shuffled(random));
for target in targets {
let mut candidates = Candidates::new(
self.draws,
&target_pool,
&fallback,
depth != self.config.max_depth,
random,
);
while let Some((target, name)) = candidates.next(&self.counts, random) {
if matches!(target.as_ref(), PoolElement::Empty) {
break;
}
@@ -924,6 +1115,9 @@ impl Placer<'_, '_> {
}],
waterlogging: self.config.waterlogging,
});
if let Some(name) = name {
*self.counts.entry(name).or_default() += 1;
}
if depth < self.config.max_depth {
self.queue
.entry(jigsaw.placement_priority)
@@ -2,7 +2,9 @@
//! references, terrain adaptation and per-chunk piece placement.
use super::{
BoundingBox, StructureResources,
jigsaw::{JigsawConfig, JigsawContext, PlaceFeature, PoolPiece, Pools, Projection, assemble},
jigsaw::{
JigsawConfig, JigsawContext, PlaceFeature, PoolPiece, Pools, Projection, assemble_drawing,
},
legacy::{LegacyPiece, PieceContext},
};
use crate::{
@@ -59,6 +61,8 @@ pub struct JigsawDef {
checks: super::start_checks::StartChecks,
/// Laid out by YUNG's API's assembler (`"horizon:yungsapi"`).
yung: Option<super::yung::Config>,
/// Vanilla's draws, or YUNG's API's for `yungsapi:yung_jigsaw`.
draws: super::jigsaw::Draws,
/// Laid out by Repurposed Structures' and Moog's piece-limited
/// assembler (`"horizon:piece_limited"`).
piece_limited: Option<super::piece_limited::Config>,
@@ -320,8 +324,13 @@ impl StructureRegistry {
.flatten()
.filter_map(|t| Some(t.as_str()?.to_owned())),
);
let draws = match v["type"].as_str() {
Some("yungsapi:yung_jigsaw") => super::jigsaw::Draws::Yung,
_ => super::jigsaw::Draws::Vanilla,
};
let kind = match v["type"].as_str().unwrap_or_default() {
"minecraft:jigsaw" => StructureKind::Jigsaw(JigsawDef {
"minecraft:jigsaw" | "yungsapi:yung_jigsaw" => StructureKind::Jigsaw(JigsawDef {
draws,
start_pool: v["start_pool"].as_str().unwrap_or_default().to_owned(),
start_jigsaw: v["start_jigsaw_name"].as_str().map(str::to_owned),
max_depth: v["size"].as_i64().unwrap_or(0) as i32,
@@ -923,7 +932,8 @@ fn try_generate(
&mut random,
start,
)?,
(None, None) => assemble(
(None, None) => assemble_drawing(
jigsaw.draws,
&config,
context,
&registry.pools,
+89 -8
View File
@@ -17,15 +17,24 @@ The oracle's game is 1.21.1 and Horizon's 26.3. KNOWN lists the starts where 26.
1.21.1, each checked against 26.3 vanilla (VanillaChunkGenerationOracle's `scan`, HORIZON_PIECES=1), whose
pieces equal Horizon's there; they are reported, not failed.
usage: test_structure_layout_parity.py [--profile lithostitched] [--filter REGEX] [--verbose]
Mod profiles compare the mod world's `pieces` instead. Horizon then reads the mod's own data from its jar
(`.local/structure-oracle/jars/`, or HORIZON_STRUCTURE_JARS): an overlay of the 26.3 resources adds the
jar's structures, sets, pools, processor lists, biome tags and templates, as they are written. The mod's
own processors are left out of the overlay's lists: they change blocks, never which pieces are placed.
Block states are upgraded to 26.3's JSON shape, as the port does.
The jars are the player's; nothing of them enters the repository.
usage: test_structure_layout_parity.py [--profile lithostitched|betterdungeons] [--filter REGEX] [--verbose]
"""
import argparse
import gzip
import json
import os
import re
import shutil
import subprocess
import sys
import zipfile
from pathlib import Path
try:
@@ -34,13 +43,26 @@ except ImportError:
import lab
ORACLE = Path(os.environ.get('HORIZON_STRUCTURE_ORACLE', lab.LOCAL / 'structure-oracle'))
JARS = Path(os.environ.get('HORIZON_STRUCTURE_JARS', ORACLE / 'jars'))
# Per profile: which saved pieces are expected, the mod jars whose data Horizon reads, and the structures
# compared (a regex; None: every start that has the pieces).
PROFILES = {
'lithostitched': {'side': 'base_pieces', 'jars': [], 'structures': None},
'betterdungeons': {'side': 'pieces', 'jars': ['YungsApi-1.21.1-NeoForge-5.1.9.jar', 'YungsBetterDungeons-1.21.1-NeoForge-5.1.4.jar'],
'structures': r'^betterdungeons:(small|skeleton|zombie)_dungeon$'},
}
BUNDLES = {'structure': 'structures', 'structure_set': 'structure_sets', 'template_pool': 'template_pools',
'processor_list': 'processor_lists'}
# (profile, seed, structure id, start chunk x, z) -> how 26.3 vanilla differs from 1.21.1 there.
TRIAL_CHAMBERS = '26.3 vanilla lays it out as Horizon does, unlike 1.21.1'
SULFUR_CAVES = "the start is in 26.3's sulfur_caves, a biome the mod's 1.21.1 tag cannot list"
RUINED_PORTAL = "26.3 vanilla's portal is Horizon's; 1.21.1 picked another"
KNOWN = {
('lithostitched', 1234, 'minecraft:village_plains', -24, 47): 'no start in 26.3 vanilla (nor in Horizon)',
('lithostitched', 1234, 'minecraft:ruined_portal', -16, 51): RUINED_PORTAL,
('lithostitched', 42, 'minecraft:ruined_portal', -19, -38): RUINED_PORTAL,
('betterdungeons', 1234, 'betterdungeons:small_dungeon', 162, 10): SULFUR_CAVES,
('betterdungeons', 42, 'betterdungeons:small_dungeon', -29, -28): SULFUR_CAVES,
**{('lithostitched', seed, 'minecraft:trial_chambers', x, z): TRIAL_CHAMBERS
for seed, x, z in [(1234, 13, 21), (2, -28, 13), (2, 11, 16), (2, 146, 44), (42, 17, 7), (42, 38, -25)]},
}
@@ -48,7 +70,7 @@ KNOWN = {
def element(saved):
kind = saved.get('element_type')
if kind in ('minecraft:single_pool_element', 'minecraft:legacy_single_pool_element'):
if kind in ('minecraft:single_pool_element', 'minecraft:legacy_single_pool_element', 'yungsapi:yung_single_element'):
location = saved['location']
return location if ':' in location else 'minecraft:' + location
if kind == 'minecraft:feature_pool_element':
@@ -69,14 +91,66 @@ def expected_piece(saved):
return piece
def upgrade_states(value):
"""1.21.1's block states (`{"Name", "Properties"}`) in 26.3's shape (`{"id", "properties"}`)."""
if isinstance(value, list):
return [upgrade_states(v) for v in value]
if not isinstance(value, dict):
return value
if 'Name' in value and set(value) <= {'Name', 'Properties'}:
return {'id': value['Name'], **({'properties': value['Properties']} if 'Properties' in value else {})}
return {k: upgrade_states(v) for k, v in value.items()}
def overlay(profile, jars):
"""The 26.3 resources plus the jars' structure data, in a folder the probe reads as its resources."""
root = lab.LOCAL / 'structure-layout' / profile
shutil.rmtree(root, ignore_errors=True)
worldgen = root / 'worldgen'
(worldgen / 'structure').mkdir(parents=True)
(root / 'facts.json').symlink_to(lab.RESOURCES / 'facts.json')
source = lab.RESOURCES / 'worldgen'
merged = {name: json.loads((source / f'{name}.json').read_text()) for name in [*BUNDLES.values(), 'biome_tags']}
for entry in source.iterdir():
if entry.name != 'structure' and entry.stem not in merged:
(worldgen / entry.name).symlink_to(entry)
for namespace in (source / 'structure').iterdir():
(worldgen / 'structure' / namespace.name).symlink_to(namespace)
for jar in jars:
with zipfile.ZipFile(JARS / jar) as archive:
for name in archive.namelist():
parts = name.split('/')
if parts[0] != 'data' or len(parts) < 4 or name.endswith('/'):
continue
namespace, kind = parts[1], parts[2]
if kind == 'structure' and name.endswith('.nbt'):
target = worldgen / 'structure' / namespace / '/'.join(parts[3:])
target.parent.mkdir(parents=True, exist_ok=True)
target.write_bytes(archive.read(name))
elif name.endswith('.json') and kind == 'worldgen' and parts[3] in BUNDLES:
value = upgrade_states(json.loads(archive.read(name)))
if parts[3] == 'processor_list':
value['processors'] = [p for p in value['processors'] if p['processor_type'].startswith('minecraft:')]
merged[BUNDLES[parts[3]]][f'{namespace}:' + '/'.join(parts[4:])[:-5]] = json.dumps(value)
elif name.endswith('.json') and parts[2:5] == ['tags', 'worldgen', 'biome']:
tag = f'{namespace}:' + '/'.join(parts[5:])[:-5]
value = json.loads(archive.read(name))
if tag in merged['biome_tags'] and not value.get('replace'):
value['values'] = json.loads(merged['biome_tags'][tag])['values'] + value['values']
merged['biome_tags'][tag] = json.dumps(value)
for name, bundle in merged.items():
(worldgen / f'{name}.json').write_text(json.dumps(bundle))
return root
def probe_binary():
subprocess.run(['cargo', 'build', '--release', '-q', '-p', 'horizon-world', '--example', 'world_probe'], check=True, cwd=lab.ROOT)
name = 'world_probe.exe' if os.name == 'nt' else 'world_probe'
return lab.cargo_target() / 'release/examples' / name
def horizon_starts(binary, seed, dimension, chunks):
result = subprocess.run([str(binary), 'structure_pieces', str(lab.RESOURCES), str(seed), dimension,
def horizon_starts(binary, resources, seed, dimension, chunks):
result = subprocess.run([str(binary), 'structure_pieces', str(resources), str(seed), dimension,
*(f'{x},{z}' for x, z in chunks)], capture_output=True, text=True, cwd=lab.ROOT)
if result.returncode:
raise SystemExit('structure_pieces failed: ' + result.stderr[-2000:])
@@ -107,7 +181,7 @@ def compare(expected, actual):
def main():
parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument('--profile', default='lithostitched')
parser.add_argument('--profile', default='lithostitched', choices=sorted(PROFILES))
parser.add_argument('--filter', default='', help='only structure ids matching this regex')
parser.add_argument('--verbose', action='store_true')
args = parser.parse_args()
@@ -115,6 +189,12 @@ def main():
if not results:
print(f'SKIP: no oracle results in {ORACLE / args.profile} (see this file\'s docstring)')
return 0
profile = PROFILES[args.profile]
missing = [jar for jar in profile['jars'] if not (JARS / jar).exists()]
if missing:
print(f'SKIP: mod jars not in {JARS}: {", ".join(missing)}')
return 0
resources = overlay(args.profile, profile['jars']) if profile['jars'] else lab.RESOURCES
binary = probe_binary()
matched, known, failed = 0, 0, []
for path in results:
@@ -122,15 +202,16 @@ def main():
seed = oracle['seed']
by_dimension = {}
for start in oracle['structures']:
if start.get('base_pieces') is None or not re.search(args.filter, start['id']):
if start.get(profile['side']) is None or not re.search(args.filter, start['id']) \
or not re.search(profile['structures'] or '', start['id']):
continue
by_dimension.setdefault(start['dimension'], []).append(start)
for dimension, starts in by_dimension.items():
chunks = sorted({tuple(s['start_chunk']) for s in starts})
actual = horizon_starts(binary, seed, dimension.removeprefix('minecraft:'), chunks)
actual = horizon_starts(binary, resources, seed, dimension.removeprefix('minecraft:'), chunks)
for start in starts:
key = (start['id'], *start['start_chunk'])
expected = [expected_piece(p) for p in start['base_pieces']]
expected = [expected_piece(p) for p in start[profile['side']]]
got = actual.get(key)
label = f'seed {seed} {start["id"]} chunk {start["start_chunk"]}'
difference = (0, {'start': 'missing in Horizon'}) if got is None else compare(expected, got)