YUNG jigsaws: the start is not counted, priority, depth and bounds rules run

From spec-yungsapi rev 3 §3, §3.1 and §3.2 (impl-questions IQ-2, IQ-3):
- the start piece does not count toward max_count;
- is_priority entries are tried first, in the pool's shuffled order, without
  a weighted draw; min_required_depth skips a pick (no draw) while the parent
  piece is shallower; ignore_bounds places without the free-space test (its
  box is still taken, IQ-12);
- the fallback was already shuffled only when reached.

The port no longer counts these three fields as lost. The layout harness gets
yung-probe and yung-probe2: the spec team's probe pack (built from the oracle
profile) carried as a mod, compared start by start with the oracle's census:
384 of 384 and 32 of 32 starts match.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-25 10:17:21 +01:00
parent 379692f355
commit 3bc38cebb4
3 changed files with 161 additions and 64 deletions
+5 -10
View File
@@ -54,15 +54,9 @@ pub(crate) fn upgrade_pool_element(element: &Value, lost: &mut BTreeMap<String,
if element["element_type"] != ELEMENT {
return false;
}
// spec-yungsapi §3: OPEN-Y5 to OPEN-Y9 and §5.
for field in [
"is_priority",
"min_required_depth",
"ignore_bounds",
"condition",
"enhanced_terrain_adaptation",
"modifiers",
] {
// spec-yungsapi §4 and §5. `name`, `max_count`, `is_priority`,
// `min_required_depth` and `ignore_bounds` are run (§3, §3.2).
for field in ["condition", "enhanced_terrain_adaptation", "modifiers"] {
if active(element, field) {
count(lost, format!("{ELEMENT} {field}"));
}
@@ -95,7 +89,8 @@ mod tests {
let mut lost = BTreeMap::new();
let pile = json!({"element_type": ELEMENT, "name": "loot_pile_0", "max_count": 1,
"enhanced_terrain_adaptation": {"type": NO_ADAPTATION}, "is_priority": false});
"enhanced_terrain_adaptation": {"type": NO_ADAPTATION}, "is_priority": true,
"min_required_depth": 2, "ignore_bounds": true});
assert!(upgrade_pool_element(&pile, &mut lost));
assert!(lost.is_empty());
let gated = json!({"element_type": ELEMENT, "condition": {"type": "yungsapi:not"}});
@@ -120,7 +120,7 @@ impl PoolElement {
Ok(match kind {
"minecraft:empty_pool_element" => Self::Empty,
// YUNG's API's element places what a single element places; its
// `name` and `max_count` are the pool entry's (`Pool::limits`).
// own fields are the pool entry's rules (`Pool::rules`).
"minecraft:single_pool_element"
| "minecraft:legacy_single_pool_element"
| "yungsapi:yung_single_element" => {
@@ -323,9 +323,8 @@ 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)>>,
/// Per entry of `raw`: a YUNG element's rules.
rules: Vec<Rules>,
pub(super) fallback: String,
max_size: OnceLock<i32>,
}
@@ -365,6 +364,37 @@ impl Pool {
})
}
}
/// A `yungsapi:yung_single_element`'s own fields (spec-yungsapi §3, §3.2).
#[derive(Clone, Debug, Default)]
struct Rules {
/// `name` and `max_count`: the most pieces of that name in one start,
/// the start not counted.
limit: Option<(Arc<str>, i32)>,
/// `is_priority`: tried before the pool's other entries, in the
/// shuffled order and without a weighted draw.
priority: bool,
/// `min_required_depth`: the least depth of the parent piece (the start
/// is depth 0).
min_depth: i32,
/// `ignore_bounds`: placed without the free-space test.
ignore_bounds: bool,
}
impl Rules {
fn of(element: &Value) -> Self {
if element["element_type"] != "yungsapi:yung_single_element" {
return Self::default();
}
Self {
limit: element["name"]
.as_str()
.zip(element["max_count"].as_i64())
.map(|(name, max)| (name.into(), max as i32)),
priority: element["is_priority"].as_bool().unwrap_or(false),
min_depth: element["min_required_depth"].as_i64().unwrap_or(0) as i32,
ignore_bounds: element["ignore_bounds"].as_bool().unwrap_or(false),
}
}
}
/// Lazily decoded template pools.
pub struct Pools {
raw: BTreeMap<String, String>,
@@ -393,7 +423,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, mut limits) = (Vec::new(), Vec::new(), Vec::new());
let (mut templates, mut raw, mut rules) = (Vec::new(), Vec::new(), Vec::new());
for entry in value["elements"].as_array()? {
let element =
match PoolElement::decode(&entry["element"], resources, bindings, None) {
@@ -410,22 +440,12 @@ 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,
},
);
rules.push(Rules::of(&entry["element"]));
}
Some(Arc::new(Pool {
templates,
raw,
limits,
rules,
fallback: value["fallback"]
.as_str()
.unwrap_or("minecraft:empty")
@@ -604,9 +624,10 @@ pub trait JigsawContext {
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's API's `yungsapi:yung_jigsaw` (spec-yungsapi §2.1, §3.1, §3.2):
/// pools are drawn by weight from their file entries, without
/// replacement, priority entries first, and an element at its
/// `max_count` or too shallow is skipped.
Yung,
}
@@ -615,14 +636,28 @@ 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.
/// YUNG's: 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: its priority entries in that order, then weighted picks
/// from the others.
Weighted {
pools: Vec<Arc<Pool>>,
current: Option<(Arc<Pool>, Vec<usize>)>,
current: Option<Drawing>,
},
}
/// A YUNG pool being drawn: entries (indices into `raw`) not tried yet.
struct Drawing {
pool: Arc<Pool>,
priority: VecDeque<usize>,
others: Vec<usize>,
}
/// An element to try.
struct Pick {
element: Arc<PoolElement>,
/// Its YUNG name, counted toward `max_count` when it is placed.
name: Option<Arc<str>>,
ignore_bounds: bool,
}
impl Candidates {
fn new(
draws: Draws,
@@ -650,37 +685,62 @@ impl Candidates {
},
}
}
/// The next element to try, with its YUNG name and limit.
/// The next element to try for a jigsaw of a piece at `depth`.
fn next(
&mut self,
counts: &HashMap<Arc<str>, i32>,
depth: i32,
random: &mut impl RandomSource,
) -> Option<(Arc<PoolElement>, Option<Arc<str>>)> {
) -> Option<Pick> {
match self {
Self::Listed(elements) => elements.next().map(|e| (e, None)),
Self::Listed(elements) => elements.next().map(|element| Pick {
element,
name: None,
ignore_bounds: false,
}),
Self::Weighted { pools, current } => loop {
let (pool, order) = match current {
Some((pool, order)) if !order.is_empty() => (pool, order),
let drawing = match current {
Some(d) if !d.priority.is_empty() || !d.others.is_empty() => d,
_ => {
let pool = pools.pop()?;
let mut order: Vec<usize> = (0..pool.raw.len()).collect();
shuffle(&mut order, random);
*current = Some((pool, order));
let (priority, others): (Vec<usize>, _) =
order.into_iter().partition(|&i| pool.rules[i].priority);
*current = Some(Drawing {
pool,
priority: priority.into(),
others,
});
continue;
}
};
let Some(at) = pool.weighted(order, random) else {
order.clear();
continue;
let entry = match drawing.priority.pop_front() {
Some(entry) => entry,
None => {
let Some(at) = drawing.pool.weighted(&drawing.others, random) else {
drawing.others.clear();
continue;
};
drawing.others.remove(at)
}
};
let entry = order.remove(at);
let limit = pool.limits[entry].clone();
if let Some((name, max)) = &limit
// spec-yungsapi §3.1 item 8: an empty element ends the
// jigsaw (the caller's), then `max_count`, then the depth.
let rules = &drawing.pool.rules[entry];
if let Some((name, max)) = &rules.limit
&& counts.get(name).copied().unwrap_or(0) >= *max
{
continue;
}
return Some((pool.raw[entry].0.clone(), limit.map(|(name, _)| name)));
if depth < rules.min_depth {
continue;
}
return Some(Pick {
element: drawing.pool.raw[entry].0.clone(),
name: rules.limit.as_ref().map(|(name, _)| name.clone()),
ignore_bounds: rules.ignore_bounds,
});
},
}
}
@@ -760,10 +820,10 @@ pub fn assemble_drawing(
.unwrap_or_else(|| name.to_owned())
};
let center_pool = pools.get(&alias(config.start_pool), resources, bindings)?;
let (rotation, element, limit) = match draws {
let (rotation, element) = match draws {
Draws::Vanilla => {
let rotation = Rotation::random(random);
(rotation, center_pool.random_template(random), None)
(rotation, center_pool.random_template(random))
}
// The entries shuffled, then the rotation, then a weighted pick in
// the shuffled order.
@@ -772,9 +832,7 @@ pub fn assemble_drawing(
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)
(rotation, center_pool.raw[entry].0.clone())
}
};
if matches!(element.as_ref(), PoolElement::Empty) {
@@ -829,10 +887,10 @@ pub fn assemble_drawing(
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]);
let counts = limit.into_iter().map(|name| (name, 1)).collect();
// The start does not count toward `max_count` (spec-yungsapi §3).
add_children_drawing(
draws,
counts,
HashMap::new(),
config,
context,
pools,
@@ -995,7 +1053,12 @@ impl Placer<'_, '_> {
depth != self.config.max_depth,
random,
);
while let Some((target, name)) = candidates.next(&self.counts, random) {
while let Some(Pick {
element: target,
name,
ignore_bounds,
}) = candidates.next(&self.counts, depth, random)
{
if matches!(target.as_ref(), PoolElement::Empty) {
break;
}
@@ -1057,7 +1120,7 @@ impl Placer<'_, '_> {
let size = (expand_to + 1).max(target_box.max[1] - target_box.min[1]);
target_box.max[1] = target_box.max[1].max(target_box.min[1] + size);
}
if !children_free.borrow().fits(&target_box) {
if !ignore_bounds && !children_free.borrow().fits(&target_box) {
continue;
}
children_free.borrow_mut().removed.push(target_box);
+47 -8
View File
@@ -23,8 +23,16 @@ a fresh work folder, and an overlay of the 26.3 resources adds the carried struc
processor lists, biome tags and templates. The jars are the player's; nothing of them enters the
repository.
usage: test_structure_layout_parity.py [--profile lithostitched|betterdungeons] [--filter REGEX] [--verbose]
The `yung-probe` profiles check YUNG's API's draws with a data pack of the spec team's own (spec-yungsapi
§3, probe experiments e1-e9: fallback, max_count, empty elements, min_required_depth, ignore_bounds,
max_y, is_priority). The pack is carried as one more mod, built at run time from the oracle's profile file
(`.local/structure-oracle/profiles/<profile>.json`), and its starts are read from the oracle's census of
every start (`all_starts`).
usage: test_structure_layout_parity.py [--profile lithostitched|betterdungeons|yung-probe|yung-probe2]
[--filter REGEX] [--verbose]
"""
import base64
import argparse
import gzip
import json
@@ -33,6 +41,7 @@ import re
import shutil
import subprocess
import sys
import zipfile
from pathlib import Path
try:
@@ -49,6 +58,9 @@ PROFILES = {
'betterdungeons': {'side': 'pieces', 'mods': {'yungsapi': 'YungsApi-1.21.1-NeoForge-5.1.9.jar',
'betterdungeons': 'YungsBetterDungeons-1.21.1-NeoForge-5.1.4.jar'},
'carry': ['betterdungeons'], 'structures': r'^betterdungeons:(small|skeleton|zombie)_dungeon$'},
**{name: {'side': 'all_starts', 'mods': {'yungsapi': 'YungsApi-1.21.1-NeoForge-5.1.9.jar'},
'packs': {'probe': name}, 'carry': ['probe'], 'structures': r'^probe:'}
for name in ['yung-probe', 'yung-probe2']},
}
BUNDLES = {'structure': 'structures', 'structure_set': 'structure_sets', 'template_pool': 'template_pools',
'processor_list': 'processor_lists'}
@@ -95,14 +107,29 @@ CENSUS = ['blockstates', 'item_models', 'recipes', 'loot_tables', 'tags', 'world
'textures', 'sounds', 'classes', 'mixin_configs']
def carry(profile, mods, carried):
"""`horizon-port-pack carry` of the profile's mods; the carried mods' data folders."""
def pack_jar(work, mod, profile):
"""The data pack an oracle profile added to its world, as a jar of mod `mod`."""
spec = json.loads((ORACLE / 'profiles' / f'{profile}.json').read_text())
files = {**spec['config_files'], **{path: base64.b64decode(data) for path, data in spec.get('binary_files', {}).items()}}
jar = work / f'{mod}.jar'
with zipfile.ZipFile(jar, 'w') as z:
for path, content in files.items():
parts = Path(path).parts
if parts[:2] == ('world', 'datapacks') and len(parts) > 3:
z.writestr(str(Path(*parts[3:])), content)
return jar
def carry(profile, mods, carried, packs=None):
"""`horizon-port-pack carry` of the profile's mods and packs; the carried mods' data folders."""
work = lab.LOCAL / 'structure-layout' / profile / 'work'
shutil.rmtree(work, ignore_errors=True)
work.mkdir(parents=True)
mods = {key: str(JARS / jar) for key, jar in mods.items()}
mods.update({key: str(pack_jar(work, key, name)) for key, name in (packs or {}).items()})
records = [{'key': key, 'name': key, 'version': '', 'path': jar, 'tier': 'data', 'confidence': 'known',
'class': 'content' if key in carried else 'library', 'source': 'file', 'license': '',
'client': '', 'server': '', 'depends': [], 'layer': 0, 'jar': str(JARS / jar),
'client': '', 'server': '', 'depends': [], 'layer': 0, 'jar': jar,
'info': {'mod_id': key, 'name': key, 'version': '', 'license': '', 'depends': [],
'census': dict.fromkeys(CENSUS, 0)}}
for key, jar in mods.items()]
@@ -188,6 +215,15 @@ def compare(expected, actual):
return None
def census_starts(oracle):
"""The oracle's census of every start (`all_starts`), as `structures` entries with their `all_starts`."""
for chunk in oracle['all_starts']:
for start in chunk['starts']:
if 'children' in start:
yield {'id': start['id'], 'dimension': chunk['dimension'], 'start_chunk': chunk['chunk'],
'all_starts': start['children']}
def main():
parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument('--profile', default='lithostitched', choices=sorted(PROFILES))
@@ -199,20 +235,23 @@ def main():
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['mods'].values() if not (JARS / jar).exists()]
missing = [str(JARS / jar) for jar in profile['mods'].values() if not (JARS / jar).exists()]
missing += [str(ORACLE / 'profiles' / f'{name}.json') for name in profile.get('packs', {}).values()
if not (ORACLE / 'profiles' / f'{name}.json').exists()]
if missing:
print(f'SKIP: mod jars not in {JARS}: {", ".join(missing)}')
print(f'SKIP: not found: {", ".join(missing)}')
return 0
resources = lab.RESOURCES
if profile['carry']:
resources = overlay(args.profile, carry(args.profile, profile['mods'], profile['carry']))
data = carry(args.profile, profile['mods'], profile['carry'], profile.get('packs'))
resources = overlay(args.profile, data)
binary = probe_binary()
matched, known, failed = 0, 0, []
for path in results:
oracle = json.load(gzip.open(path))
seed = oracle['seed']
by_dimension = {}
for start in oracle['structures']:
for start in oracle['structures'] if profile['side'] != 'all_starts' else census_starts(oracle):
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