From 41f8cfa3bc1f3205fe624a5e162d3a6509fa1b5c Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sun, 25 Oct 2026 05:08:43 +0100 Subject: [PATCH] YUNG's API jigsaw draws: yung_jigsaw structures and yung_single_element read as written MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../src/worldgen/structure/jigsaw.rs | 216 +++++++++++++++++- .../src/worldgen/structure/start.rs | 16 +- tools/test_structure_layout_parity.py | 97 +++++++- 3 files changed, 307 insertions(+), 22 deletions(-) diff --git a/crates/horizon-world/src/worldgen/structure/jigsaw.rs b/crates/horizon-world/src/worldgen/structure/jigsaw.rs index 54ebcdd8b..87a551c05 100644 --- a/crates/horizon-world/src/worldgen/structure/jigsaw.rs +++ b/crates/horizon-world/src/worldgen/structure/jigsaw.rs @@ -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>, /// The elements with their weights, in file order (`rawTemplates`). pub(super) raw: Vec<(Arc, i32)>, + /// Per entry of `raw`: a YUNG element's `name` and `max_count`, the most + /// pieces of that name in one start. + limits: Vec, i32)>>, pub(super) fallback: String, max_size: OnceLock, } @@ -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 { + 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>), + /// 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>, + current: Option<(Arc, Vec)>, + }, +} +impl Candidates { + fn new( + draws: Draws, + target: &Arc, + fallback: &Arc, + 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::>() + .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, i32>, + random: &mut impl RandomSource, + ) -> Option<(Arc, Option>)> { + 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 = (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)> { + 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)> { 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 = (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, _) = ¢er_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, 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, i32>, + config: &JigsawConfig<'_>, + context: &mut impl JigsawContext, + pools: &Pools, + resources: &StructureResources, + bindings: &FeatureBlockBindings<'_>, + random: &mut impl RandomSource, + pieces: &mut Vec, + 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, /// SequencedPriorityIterator: highest priority first, FIFO within one. queue: BTreeMap>, + draws: Draws, + /// Pieces placed per YUNG element name. + counts: HashMap, i32>, } impl Placer<'_, '_> { fn next(&mut self) -> Option { @@ -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) diff --git a/crates/horizon-world/src/worldgen/structure/start.rs b/crates/horizon-world/src/worldgen/structure/start.rs index 70e457b2e..44f4b70f4 100644 --- a/crates/horizon-world/src/worldgen/structure/start.rs +++ b/crates/horizon-world/src/worldgen/structure/start.rs @@ -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, + /// 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, @@ -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, ®istry.pools, diff --git a/tools/test_structure_layout_parity.py b/tools/test_structure_layout_parity.py index 44544f06e..185dde578 100644 --- a/tools/test_structure_layout_parity.py +++ b/tools/test_structure_layout_parity.py @@ -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)