Merge #dev to main

.github/workflows/auto-pr.yml

@@ -37,5 +37,5 @@ jobs:
             gh pr edit "$EXISTING" --body "$(printf 'Daily roll-up of dev → main (auto-generated)\n\n%s commits ahead.\n\nMost recent commits:\n%s' "$AHEAD" "$(git log --oneline origin/main..origin/dev | head -20)")"
           else
             BODY=$(printf 'Daily roll-up of dev → main (auto-generated)\n\n%s commits ahead.\n\nMost recent commits:\n%s' "$AHEAD" "$(git log --oneline origin/main..origin/dev | head -20)")
-            gh pr create --base main --head dev --title "Daily merge: dev → main ($AHEAD commits)" --body "$BODY" --label "auto-pr"
+            gh pr create --base main --head dev --title "Daily merge: dev → main ($AHEAD commits)" --body "$BODY"
           fi

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: ci
 
 on:
   push:
-    branches: [main]
+    branches: [main, dev]
   pull_request:
     branches: [main]
 

eslint.config.mjs

@@ -54,6 +54,15 @@ export default [
       '@typescript-eslint/no-explicit-any': 'off',
       '@typescript-eslint/no-empty-function': 'off',
       '@typescript-eslint/no-misused-promises': 'off',
+      // We deliberately use indexed for-loops in hot paths — for-of on
+      // arrays + typed arrays allocates an iterator on each call. Don't
+      // let the linter rewrite our perf-tuned loops.
+      '@typescript-eslint/prefer-for-of': 'off',
+      // Type-vs-interface stylistic; we use both interchangeably.
+      '@typescript-eslint/consistent-type-definitions': 'off',
+      // Generic-on-constructor stylistic — auto-fix often breaks code
+      // that depends on the variable's declared type.
+      '@typescript-eslint/consistent-generic-constructors': 'off',
     },
   },
   {

package.json

@@ -28,6 +28,7 @@
     "wiki:crawl": "tsx scripts/wiki-crawl.ts",
     "signaling": "tsx signaling/server.ts",
     "bench:mesh": "tsx tests/perf/mesh-bench.ts",
+    "bench:nbt": "tsx tests/perf/nbt-bench.ts",
     "ci": "npm run typecheck && npm run lint && npm run format:check && npm run test",
     "verify:m0": "npm run ci && npm run test:e2e",
     "verify:m1": "npm run ci && npm run bench:mesh && npm run test:e2e",

src/blocks/amethyst.ts

@@ -43,6 +43,20 @@ export function dropsFor(state: AmethystState, hasSilkTouch: boolean): string[]
   ];
 }
 
+// Wiki (minecraft.wiki/w/Amethyst_Cluster#Light): "Small, medium,
+// and large amethyst buds give off a light level of 1, 2 and 4
+// respectively, while amethyst clusters give off a light level of 5."
+// Old code returned 1 for every bud stage, dropping the per-stage
+// glow gradient (the visible cue that a bud is maturing).
 export function lightEmission(state: AmethystState): number {
-  return state.stage === 'cluster' ? 5 : 1;
+  switch (state.stage) {
+    case 'small_bud':
+      return 1;
+    case 'medium_bud':
+      return 2;
+    case 'large_bud':
+      return 4;
+    case 'cluster':
+      return 5;
+  }
 }

src/blocks/amethyst_crystal_growth.test.ts

@@ -25,4 +25,23 @@ describe('amethyst crystal growth', () => {
   it('cluster drops at least 4', () => {
     expect(harvestYield('cluster', 0, false)).toBeGreaterThanOrEqual(4);
   });
+
+  it('Fortune III ore-formula avg ≈ 8.8 (wiki)', () => {
+    let total = 0;
+    const N = 5000;
+    for (let i = 0; i < N; i++) {
+      total += harvestYield('cluster', 3, false, Math.random);
+    }
+    const avg = total / N;
+    // Wiki: average is 4 × 2.2 = 8.8 shards. Allow ±5% tolerance.
+    expect(avg).toBeGreaterThan(8.0);
+    expect(avg).toBeLessThan(9.6);
+  });
+
+  it('Fortune III deterministic boundaries', () => {
+    // rand=0   → roll=-1 → multiplier=1 → 4 shards
+    expect(harvestYield('cluster', 3, false, () => 0)).toBe(4);
+    // rand close to 1 → roll=3 → multiplier=4 → 16 shards
+    expect(harvestYield('cluster', 3, false, () => 0.999)).toBe(16);
+  });
 });

src/blocks/amethyst_crystal_growth.ts

@@ -18,14 +18,31 @@ export function randomTick(stage: AmethystStage, rand: () => number): AmethystSt
   return stage;
 }
 
+// Wiki (minecraft.wiki/w/Amethyst_Cluster): "Amethyst clusters drop
+// 4 amethyst shards when mined with an iron pickaxe or higher (less
+// or none with lower-tier pickaxes / Silk Touch returns the block).
+// Fortune uses the standard discrete-ore formula:
+//   probability of no bonus: 2 / (level + 2)
+//   otherwise: equal chance for any multiplier from 2 to (level + 1)
+// Fortune III gives an average of 8.8 shards per cluster (~2.2× base 4)."
+//
+// Old `base + floor(rand × (1 + fortuneLevel))` yielded 4-7 at
+// Fortune III, averaging ~5.5 — vs wiki ~8.8 (~37% under canon).
+// Now uses the wiki formula via a multiplier roll.
 export function harvestYield(
   stage: AmethystStage,
   fortuneLevel: number,
   silkTouch: boolean,
+  rand: () => number = Math.random,
 ): number {
   if (stage !== 'cluster') return 0;
   if (silkTouch) return 1; // block form
   const base = 4;
-  // Fortune up to +3 extra.
-  return base + Math.floor(Math.random() * (1 + fortuneLevel));
+  if (fortuneLevel <= 0) return base;
+  // Standard ore Fortune formula: rolls = floor(rand × (level + 2)) − 1,
+  // multiplier = max(1, rolls + 1). For Fortune III, multipliers
+  // are uniformly 1, 1, 2, 3, 4 (avg ≈ 2.2).
+  const roll = Math.floor(rand() * (fortuneLevel + 2)) - 1;
+  const multiplier = Math.max(1, roll + 1);
+  return base * multiplier;
 }

src/blocks/anvil_enchant_combine.ts

@@ -9,6 +9,16 @@ export interface Enchantment {
 
 export type EnchantMaxes = Record<string, number>;
 
+// Wiki (minecraft.wiki/w/Enchanting): canonical max levels per
+// enchantment. Old table only listed sword/bow/tool/armor enchants;
+// crossbow (piercing/multishot/quick_charge), trident
+// (loyalty/riptide/channeling/impaling), mace
+// (density/breach/wind_burst), boot (depth_strider/frost_walker/
+// soul_speed/swift_sneak), helmet (aqua_affinity/respiration),
+// armor (thorns), fishing rod (luck_of_the_sea/lure), and the two
+// curses were missing — anvil-combining a Multishot II book on a
+// crossbow silently produced level II (the book's value) instead of
+// capping at I per wiki. Aligned with enchant_max_level_table.ts.
 export const ENCHANT_MAX: EnchantMaxes = {
   sharpness: 5,
   smite: 5,
@@ -31,6 +41,27 @@ export const ENCHANT_MAX: EnchantMaxes = {
   punch: 2,
   flame: 1,
   infinity: 1,
+  multishot: 1,
+  piercing: 4,
+  quick_charge: 3,
+  loyalty: 3,
+  riptide: 3,
+  channeling: 1,
+  impaling: 5,
+  density: 5,
+  breach: 4,
+  wind_burst: 3,
+  thorns: 3,
+  respiration: 3,
+  aqua_affinity: 1,
+  depth_strider: 3,
+  frost_walker: 2,
+  soul_speed: 3,
+  swift_sneak: 3,
+  curse_of_binding: 1,
+  curse_of_vanishing: 1,
+  luck_of_the_sea: 3,
+  lure: 3,
 };
 
 export interface CombineQuery {

src/blocks/anvil_fall.test.ts

@@ -11,26 +11,43 @@ describe('anvil fall', () => {
     expect(anvilFallDamage(10)).toBe(18);
   });
 
-  it('cap at 20 for extreme falls', () => {
-    expect(anvilFallDamage(1000)).toBe(20);
+  it('cap at 40 for extreme falls (wiki)', () => {
+    expect(anvilFallDamage(1000)).toBe(40);
   });
 
   it('tier progresses intact → chipped → damaged → broken', () => {
     const a = makeAnvil();
-    // Force the rng to always trigger degrade.
-    maybeDegrade(a, () => 0.01);
+    // 10-block fall → 50% chance, rng 0.01 always triggers.
+    maybeDegrade(a, 10, () => 0.01);
     expect(a.tier).toBe('chipped');
-    maybeDegrade(a, () => 0.01);
+    maybeDegrade(a, 10, () => 0.01);
     expect(a.tier).toBe('damaged');
-    maybeDegrade(a, () => 0.01);
+    maybeDegrade(a, 10, () => 0.01);
     expect(a.tier).toBe('broken');
-    maybeDegrade(a, () => 0.01);
+    maybeDegrade(a, 10, () => 0.01);
     expect(a.tier).toBe('broken');
   });
 
   it('rng above chance leaves tier', () => {
     const a = makeAnvil();
-    maybeDegrade(a, () => 0.9);
+    // 10-block fall → 50% chance, rng 0.9 stays.
+    maybeDegrade(a, 10, () => 0.9);
     expect(a.tier).toBe('intact');
   });
+
+  it('1-block fall cannot degrade (wiki: only falls > 1 block)', () => {
+    const a = makeAnvil();
+    maybeDegrade(a, 1, () => 0); // rng 0 would always degrade if chance > 0
+    expect(a.tier).toBe('intact');
+  });
+
+  it('degrade chance scales 5% × blocks fallen', () => {
+    const a = makeAnvil();
+    // 4-block fall → 20% chance, rng 0.21 just above → no degrade.
+    maybeDegrade(a, 4, () => 0.21);
+    expect(a.tier).toBe('intact');
+    // rng 0.19 just below → degrade.
+    maybeDegrade(a, 4, () => 0.19);
+    expect(a.tier).toBe('chipped');
+  });
 });

src/blocks/anvil_fall.ts

@@ -1,6 +1,7 @@
 // Falling anvil damage + durability decay. Damage scales with fall
-// distance (capped at 20 HP). Anvil damage state cycles through three
-// tiers (intact / chipped / damaged) and breaks at tier 3.
+// distance (capped at 40 HP per wiki). Anvil damage state cycles
+// through three tiers (intact / chipped / damaged) and breaks at
+// tier 3.
 
 export type AnvilTier = 'intact' | 'chipped' | 'damaged' | 'broken';
 
@@ -12,23 +13,42 @@ export function makeAnvil(): AnvilState {
   return { tier: 'intact' };
 }
 
-// MC formula: anvil damage to entity = max(fallBlocks * 2 - 2, 0), capped 20.
+// Wiki (minecraft.wiki/w/Anvil#Falling_anvils): "The damage amount
+// depends on fall distance: 2 hp per block fallen after the first
+// (e.g., an anvil that falls 4 blocks deals 6 hp damage). The damage
+// is capped at 40 hp, no matter how far the anvil falls." Old cap
+// was 20 — half the wiki value, letting late-game players walk
+// under a 30-block-falling anvil and survive on full diamond armor.
+// Sibling anvil_fall_damage.ts already capped at 40.
+export const ANVIL_DAMAGE_CAP = 40;
 export function anvilFallDamage(fallBlocks: number): number {
-  return Math.min(20, Math.max(0, fallBlocks * 2 - 2));
+  return Math.min(ANVIL_DAMAGE_CAP, Math.max(0, fallBlocks * 2 - 2));
 }
 
-// Per MC, anvil has ~12% chance to degrade per use at a non-zero cost.
-const DEGRADE_CHANCE = 0.12;
+// Wiki (minecraft.wiki/w/Anvil#Falling_anvils): "If it falls from a
+// height greater than one block, the chance of degrading by one stage
+// is 5% × the number of blocks fallen." 12% is the per-USE chance
+// (anvil_damage_chain.ts), not the fall-context chance — old code
+// used 12% regardless of distance, so a 1-block fall could degrade
+// (wiki: cannot) and a 20-block fall had the same odds as a 2-block
+// one (wiki: 100% vs 10%).
+export const FALL_DEGRADE_PER_BLOCK = 0.05;
 const NEXT_TIER: Record<AnvilTier, AnvilTier> = {
   intact: 'chipped',
   chipped: 'damaged',
   damaged: 'broken',
   broken: 'broken',
 };
 
-export function maybeDegrade(state: AnvilState, rng: () => number = Math.random): boolean {
+export function maybeDegrade(
+  state: AnvilState,
+  fallBlocks: number,
+  rng: () => number = Math.random,
+): boolean {
   if (state.tier === 'broken') return false;
-  if (rng() < DEGRADE_CHANCE) {
+  if (fallBlocks <= 1) return false;
+  const chance = Math.min(1, FALL_DEGRADE_PER_BLOCK * fallBlocks);
+  if (rng() < chance) {
     state.tier = NEXT_TIER[state.tier];
     return true;
   }

src/blocks/anvil_fall_damage.test.ts

@@ -4,7 +4,7 @@ import {
   tryDegrade,
   DAMAGE_PER_BLOCK,
   MAX_DAMAGE,
-  DEGRADE_CHANCE,
+  FALL_DEGRADE_PER_BLOCK,
 } from './anvil_fall_damage';
 
 describe('anvil fall', () => {
@@ -17,15 +17,27 @@ describe('anvil fall', () => {
     expect(anvilPassThroughDamage(1000)).toBe(MAX_DAMAGE);
   });
 
-  it('degrades on roll', () => {
-    expect(tryDegrade('webmc:anvil', () => 0)).toBe('webmc:chipped_anvil');
+  it('degrades on roll (10-block fall = 50% chance)', () => {
+    expect(tryDegrade('webmc:anvil', 10, () => 0)).toBe('webmc:chipped_anvil');
   });
 
-  it('no degrade on high roll', () => {
-    expect(tryDegrade('webmc:anvil', () => DEGRADE_CHANCE + 0.01)).toBeNull();
+  it('no degrade on high roll (10-block fall = 50% chance, rng 0.51)', () => {
+    expect(tryDegrade('webmc:anvil', 10, () => 0.51)).toBeNull();
   });
 
-  it('damaged anvil destroys', () => {
-    expect(tryDegrade('webmc:damaged_anvil', () => 0)).toBe('destroyed');
+  it('damaged anvil destroys (10-block fall = 50% chance, rng 0)', () => {
+    expect(tryDegrade('webmc:damaged_anvil', 10, () => 0)).toBe('destroyed');
+  });
+
+  it('1-block fall cannot degrade (wiki: only > 1 block)', () => {
+    expect(tryDegrade('webmc:anvil', 1, () => 0)).toBeNull();
+  });
+
+  it('chance scales 5% × blocks fallen', () => {
+    // 4-block fall → 20% chance, rng 0.21 just above → no degrade.
+    expect(tryDegrade('webmc:anvil', 4, () => 0.21)).toBeNull();
+    // rng 0.19 just below → degrade.
+    expect(tryDegrade('webmc:anvil', 4, () => 0.19)).toBe('webmc:chipped_anvil');
+    expect(FALL_DEGRADE_PER_BLOCK).toBe(0.05);
   });
 });

src/blocks/anvil_fall_damage.ts

@@ -10,7 +10,12 @@ export function anvilPassThroughDamage(fallDistanceBlocks: number): number {
   return Math.min(MAX_DAMAGE, Math.max(0, d));
 }
 
-// On landing, anvil has 12% chance to degrade. Damaged ≤ chipped ≤ normal.
+// Wiki (minecraft.wiki/w/Anvil#Falling_anvils): "If it falls from a
+// height greater than one block, the chance of degrading by one stage
+// is 5% × the number of blocks fallen." 12% is the per-USE chance
+// (anvil_damage_chain.ts); applying it to fall context makes a
+// 1-block drop able to degrade (wiki: cannot) and a 20-block drop
+// no scarier than a 2-block drop (wiki: 100% vs 10%).
 export type AnvilKind = 'webmc:anvil' | 'webmc:chipped_anvil' | 'webmc:damaged_anvil';
 
 const DEGRADE: Record<AnvilKind, AnvilKind | null> = {
@@ -19,10 +24,16 @@ const DEGRADE: Record<AnvilKind, AnvilKind | null> = {
   'webmc:damaged_anvil': null,
 };
 
-export const DEGRADE_CHANCE = 0.12;
+export const FALL_DEGRADE_PER_BLOCK = 0.05;
 
-export function tryDegrade(kind: AnvilKind, rand: () => number): AnvilKind | 'destroyed' | null {
-  if (rand() >= DEGRADE_CHANCE) return null;
+export function tryDegrade(
+  kind: AnvilKind,
+  fallBlocks: number,
+  rand: () => number,
+): AnvilKind | 'destroyed' | null {
+  if (fallBlocks <= 1) return null;
+  const chance = Math.min(1, FALL_DEGRADE_PER_BLOCK * fallBlocks);
+  if (rand() >= chance) return null;
   const next = DEGRADE[kind];
   return next ?? 'destroyed';
 }

src/blocks/anvil_stage_damage.test.ts

@@ -13,13 +13,24 @@ describe('anvil stage damage', () => {
     expect(damageOnUse('anvil', () => 0.99)).toBe('anvil');
   });
 
-  it('fall compounds damage', () => {
-    expect(damageOnFall('anvil', 2)).toBe('damaged_anvil');
-    expect(damageOnFall('anvil', 3)).toBe('destroyed');
+  it('fall advances at most one stage on a lucky roll (wiki)', () => {
+    // Wiki: 5% × blocks chance of single-stage degrade. 10-block drop
+    // → 50% chance. With rng()=0 (always passes) we get exactly one
+    // stage, NOT three.
+    expect(damageOnFall('anvil', 10, () => 0)).toBe('chipped_anvil');
+    expect(damageOnFall('anvil', 3, () => 0)).toBe('chipped_anvil');
+  });
+
+  it('fall ≤1 block never damages', () => {
+    expect(damageOnFall('anvil', 1, () => 0)).toBe('anvil');
+  });
+
+  it('high roll spares the anvil', () => {
+    expect(damageOnFall('anvil', 5, () => 0.99)).toBe('anvil');
   });
 
   it('destroyed stays destroyed', () => {
     expect(damageOnUse('destroyed', () => 0)).toBe('destroyed');
-    expect(damageOnFall('destroyed', 10)).toBe('destroyed');
+    expect(damageOnFall('destroyed', 10, () => 0)).toBe('destroyed');
   });
 });