@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/recipes/asteroid/asteroid.ts

@@ -0,0 +1,336 @@
+// Mineable asteroid — a ~10 m rubble-pile rock for a mining game, in three seeded variants.
+// A signed-distance field meshed by `sdf`: a lumpy ellipsoid (smooth-union lobes), fractal
+// value-noise displacement, impact craters (smooth subtract + raised rims), then vertex colour:
+// carbonaceous dark rock (C-type albedo 0.03–0.09), dust on up-facing slopes, darker crater
+// floors, and nickel-iron ore veins (M-type). Glowing crystal clusters mark the mining points.
+// The bottom is clipped flat at z = 0 so it rests on (or in) the ground. +X front, Z up, metres.
+//
+// Engine contract: `rock` (the collider-friendly mass), `ore_crystals` (glow), interact sockets
+// `mine_point_*` at each crystal cluster, `dust` emitter for mining debris.
+
+import {
+  type Asset,
+  type BuildContext,
+  bakeAo,
+  defineAsset,
+  type Field,
+  hex,
+  lathe,
+  type Mesh,
+  merge,
+  place,
+  sdf,
+  type Vec3,
+  valueNoise,
+} from '@developerz.ai/ts23d';
+
+const ROCK = hex('#3b3632');
+const ROCK_LIGHT = hex('#4f4841');
+const DUST = hex('#6a6157');
+const CRATER = hex('#26221f');
+const ORE = hex('#b78a45');
+const CRYSTAL = hex('#3fe0d0');
+const CRYSTAL_TINT = hex('#1f6f6a');
+
+type V = [number, number, number];
+const step = (a: number, b: number, x: number): number => {
+  const t = Math.max(0, Math.min(1, (x - a) / (b - a)));
+  return t * t * (3 - 2 * t);
+};
+const mix = (a: Vec3, b: Vec3, t: number): Vec3 => [
+  a[0] + (b[0] - a[0]) * t,
+  a[1] + (b[1] - a[1]) * t,
+  a[2] + (b[2] - a[2]) * t,
+];
+const len = (x: number, y: number, z: number): number => Math.sqrt(x * x + y * y + z * z);
+const norm = (v: Vec3): V => {
+  const l = len(v[0], v[1], v[2]) || 1;
+  return [v[0] / l, v[1] / l, v[2] / l];
+};
+const smin = (a: number, b: number, k: number): number => {
+  const h = Math.max(0, Math.min(1, 0.5 + (0.5 * (b - a)) / k));
+  return b + (a - b) * h - k * h * (1 - h);
+};
+const smax = (a: number, b: number, k: number): number => -smin(-a, -b, k);
+const ellipsoid = (p: Vec3, c: Vec3, r: Vec3): number => {
+  const x = (p[0] - c[0]) / r[0];
+  const y = (p[1] - c[1]) / r[1];
+  const z = (p[2] - c[2]) / r[2];
+  const k0 = len(x, y, z);
+  const k1 = len(x / r[0], y / r[1], z / r[2]);
+  return k1 === 0 ? -Math.min(...r) : (k0 * (k0 - 1)) / k1;
+};
+
+interface Crater {
+  readonly centre: V; // sphere centre (cuts the bowl)
+  readonly r: number;
+}
+
+interface Shape {
+  readonly field: Field;
+  readonly craters: readonly Crater[];
+  readonly gradient: (p: Vec3) => V;
+  /** Surface point along a ray from the core (bisection on the field). */
+  readonly surface: (dir: Vec3) => V;
+}
+
+// Below every variant's z radius, so the field always crosses z = 0 and the rock sits clipped flat.
+const CORE: V = [0, 0, 2.2];
+
+/** The rock's field. Every draw comes from forks of `ctx.rng`, identical at every LOD. */
+function shape(ctx: BuildContext, size: V): Shape {
+  const rng = ctx.rng.fork('shape');
+  const big = valueNoise(rng.fork('big'), { scale: 2.8, octaves: 4 });
+  const pits = valueNoise(rng.fork('pits'), { scale: 0.8, octaves: 2 });
+  const lobes = Array.from({ length: 3 }, () => ({
+    c: [rng.range(-2.6, 2.6), rng.range(-1.8, 1.8), CORE[2] + rng.range(-0.6, 1.0)] as V,
+    r: [rng.range(1.8, 2.8), rng.range(1.6, 2.4), rng.range(1.4, 2.2)] as V,
+  }));
+  // Fracture planes: half-spaces that chip flat, angular facets off the lumpy mass.
+  const chips = Array.from({ length: 12 }, () => {
+    const a = rng.range(0, Math.PI * 2);
+    const up = rng.range(-0.2, 0.9);
+    const m = norm([
+      Math.cos(a) * Math.sqrt(1 - up * up),
+      Math.sin(a) * Math.sqrt(1 - up * up),
+      up,
+    ]);
+    const reach = Math.abs(m[0]) * size[0] + Math.abs(m[1]) * size[1] + Math.abs(m[2]) * size[2];
+    return { m, c: reach * rng.range(0.62, 0.8) };
+  });
+  const body = (p: Vec3): number => {
+    let d = ellipsoid(p, CORE, size);
+    for (const l of lobes) d = smin(d, ellipsoid(p, l.c, l.r), 1.0);
+    d += 0.65 * big(p) + 0.12 * pits(p);
+    const x = p[0] - CORE[0];
+    const y = p[1] - CORE[1];
+    const z = p[2] - CORE[2];
+    for (const c of chips)
+      d = smax(d, x * c.m[0] + y * c.m[1] + z * c.m[2] - c.c + 0.08 * pits(p), 0.12);
+    return d;
+  };
+  const gradOf =
+    (f: Field) =>
+    (p: Vec3): V => {
+      const e = 0.05;
+      return norm([
+        f([p[0] + e, p[1], p[2]]) - f([p[0] - e, p[1], p[2]]),
+        f([p[0], p[1] + e, p[2]]) - f([p[0], p[1] - e, p[2]]),
+        f([p[0], p[1], p[2] + e]) - f([p[0], p[1], p[2] - e]),
+      ]);
+    };
+  const surfaceOf =
+    (f: Field) =>
+    (dir: Vec3): V => {
+      const d = norm(dir);
+      let lo = 0;
+      let hi = 9;
+      for (let i = 0; i < 40; i++) {
+        const t = (lo + hi) / 2;
+        if (f([CORE[0] + d[0] * t, CORE[1] + d[1] * t, CORE[2] + d[2] * t]) < 0) lo = t;
+        else hi = t;
+      }
+      return [CORE[0] + d[0] * lo, CORE[1] + d[1] * lo, CORE[2] + d[2] * lo];
+    };
+  const bodySurface = surfaceOf(body);
+  const bodyGrad = gradOf(body);
+  const craters: Crater[] = Array.from({ length: 9 }, (_, i) => {
+    const a = rng.range(0, Math.PI * 2);
+    const up = i < 3 ? rng.range(0.55, 0.95) : rng.range(-0.1, 0.7);
+    const s = bodySurface([
+      Math.cos(a) * Math.sqrt(1 - up * up),
+      Math.sin(a) * Math.sqrt(1 - up * up),
+      up,
+    ]);
+    const n = bodyGrad(s);
+    const r = i < 2 ? rng.range(1.3, 1.9) : rng.range(0.45, 1.0);
+    return {
+      centre: [s[0] + n[0] * r * 0.6, s[1] + n[1] * r * 0.6, s[2] + n[2] * r * 0.6],
+      r,
+    };
+  });
+  const field: Field = (p) => {
+    let d = body(p);
+    for (const c of craters) {
+      // Raised rim: a radial bump that displaces the surface itself (a torus in the tangent
+      // plane floats off convex slopes), then the bowl: a smooth-subtracted sphere.
+      const ds = len(p[0] - c.centre[0], p[1] - c.centre[1], p[2] - c.centre[2]);
+      const u = (ds - c.r * 1.05) / (c.r * 0.28);
+      if (u > -3 && u < 3) d -= c.r * 0.16 * Math.exp(-u * u);
+      d = smax(d, -(ds - c.r), c.r * 0.3);
+    }
+    return d;
+  };
+  return { field, craters, gradient: gradOf(field), surface: surfaceOf(field) };
+}
+
+/** One faceted crystal, base at the origin growing up +Z: hexagonal prism with a pointed tip. */
+const crystal = (r: number, h: number, segments: number): Mesh =>
+  lathe({
+    profile: [
+      [r * 0.7, -0.35],
+      [r, 0],
+      [r * 0.95, h * 0.75],
+      [0, h],
+    ],
+    segments,
+    color: CRYSTAL,
+    creaseDeg: 20,
+  });
+
+function asteroidVariant(
+  name: string,
+  seed: number,
+  size: V,
+  description: string,
+  /** Measured per seed (SDF triangle counts follow the surface area), headroom ≤ 20%. */
+  triangles: readonly [number, number, number],
+): Asset {
+  return defineAsset({
+    name,
+    kind: 'prop',
+    description,
+    tags: ['sci-fi', 'asteroid', 'rock', 'mining', 'sdf'],
+    license: 'CC0-1.0',
+    seed,
+    sources: [
+      'https://www.esa.int/Science_Exploration/Space_Science/Rosetta/Debris_of_the_Solar_System_Asteroids',
+      'https://starlust.org/what-are-the-different-types-of-asteroids',
+    ],
+    budget: { triangles },
+    glow: [{ parts: ['ore_crystals'], color: CRYSTAL, strength: 5 }],
+    build(ctx) {
+      const s = shape(ctx, size);
+      const veins = valueNoise(ctx.rng.fork('veins'), { scale: 1.9, octaves: 2 });
+      const tone = valueNoise(ctx.rng.fork('tone'), { scale: 1.2, octaves: 3 });
+      // Mining points: cluster sites on the upper half, away from the two big craters.
+      const pick = ctx.rng.fork('clusters');
+      const sites = Array.from({ length: 4 }, () => {
+        const a = pick.range(0, Math.PI * 2);
+        const up = pick.range(0.05, 0.75);
+        const p = s.surface([
+          Math.cos(a) * Math.sqrt(1 - up * up),
+          Math.sin(a) * Math.sqrt(1 - up * up),
+          up,
+        ]);
+        return { p, n: s.gradient(p) };
+      });
+      const color = (p: Vec3, n: Vec3): Vec3 => {
+        let near = 99;
+        for (const site of sites)
+          near = Math.min(near, len(p[0] - site.p[0], p[1] - site.p[1], p[2] - site.p[2]));
+        let c = mix(ROCK, ROCK_LIGHT, step(-0.25, 0.35, tone(p)));
+        c = mix(c, DUST, step(0.55, 0.85, n[2]) * 0.8);
+        const vein = 1 - step(0.018, 0.05, Math.abs(veins(p)));
+        c = mix(c, near < 2.4 ? CRYSTAL_TINT : ORE, vein);
+        c = mix(c, CRYSTAL_TINT, (1 - step(0.6, 1.6, near)) * 0.7);
+        for (const cr of s.craters) {
+          const d = len(p[0] - cr.centre[0], p[1] - cr.centre[1], p[2] - cr.centre[2]);
+          c = mix(c, CRATER, (1 - step(cr.r * 0.8, cr.r * 1.2, d)) * 0.85);
+        }
+        return c;
+      };
+      const ext = Math.max(...size) + 3.2;
+      const rock = sdf({
+        field: s.field,
+        bounds: [
+          [-ext, -ext, 0],
+          [ext, ext, CORE[2] + size[2] + 2.2],
+        ],
+        resolution: ctx.pick([0.17, 0.38, 0.95]),
+        color,
+        lipschitz: 2,
+        strip: 'plain',
+      });
+      ctx.part(
+        'rock',
+        ctx.lod < 2
+          ? bakeAo(rock, {
+              samples: ctx.pick([16, 8, 0]),
+              radius: 1.5,
+              strength: 0.55,
+              ground: true,
+            })
+          : rock,
+      );
+
+      // Crystal clusters: 7 / 4 / 1 shards per site, sunk 0.3 m into the rock along its normal.
+      const shards = ctx.pick([11, 5, 1]);
+      const seg = ctx.pick([6, 6, 4]);
+      const grow = ctx.rng.fork('shards');
+      const out: Mesh[] = [];
+      sites.forEach((site, i) => {
+        for (let k = 0; k < shards; k++) {
+          const jitter = k === 0 ? 0 : 0.6;
+          const n = norm([
+            site.n[0] + grow.range(-jitter, jitter),
+            site.n[1] + grow.range(-jitter, jitter),
+            site.n[2] + grow.range(-jitter, jitter) * 0.5,
+          ]);
+          const off: V =
+            k === 0
+              ? [0, 0, 0]
+              : [grow.range(-0.5, 0.5), grow.range(-0.5, 0.5), grow.range(-0.3, 0.3)];
+          const base = s.surface([
+            site.p[0] + off[0] - CORE[0],
+            site.p[1] + off[1] - CORE[1],
+            site.p[2] + off[2] - CORE[2],
+          ]);
+          const r = k === 0 ? 0.3 : grow.range(0.1, 0.22);
+          const h = k === 0 ? 1.9 : grow.range(0.6, 1.4);
+          out.push(
+            place(crystal(r, h, seg), {
+              at: base,
+              yaw: Math.atan2(n[1], n[0]),
+              pitch: Math.acos(Math.max(-1, Math.min(1, n[2]))),
+            }),
+          );
+        }
+        ctx.socket(`mine_point_${i}`, {
+          kind: 'interact',
+          at: [
+            site.p[0] + site.n[0] * 0.8,
+            site.p[1] + site.n[1] * 0.8,
+            site.p[2] + site.n[2] * 0.8,
+          ],
+          dir: [-site.n[0], -site.n[1], -site.n[2]],
+          data: { resource: 'crystal', yield: 120 },
+        });
+      });
+      ctx.part('ore_crystals', merge(out));
+      const top = s.surface([0, 0, 1]);
+      ctx.emitter('dust', {
+        kind: 'dust',
+        at: [top[0], top[1], top[2] + 0.2],
+        rate: 30,
+        life: 2.5,
+        size: [0.2, 1.2],
+        speed: 1.5,
+        spreadDeg: 70,
+        when: 'event',
+      });
+    },
+  });
+}
+
+export const asteroid = asteroidVariant(
+  'asteroid',
+  1,
+  [5.0, 3.8, 3.0],
+  'Mineable ~10 m asteroid: SDF rock with craters, ore veins and glowing crystal clusters',
+  [24000, 5200, 760],
+);
+export const asteroid_b = asteroidVariant(
+  'asteroid_b',
+  2,
+  [4.2, 4.0, 3.3],
+  'Rounder asteroid variant (seed 2) with craters, ore veins and crystal clusters',
+  [21500, 4800, 670],
+);
+export const asteroid_c = asteroidVariant(
+  'asteroid_c',
+  3,
+  [5.6, 3.2, 2.6],
+  'Elongated asteroid shard variant (seed 3) with craters, ore veins and crystal clusters',
+  [24500, 5300, 750],
+);

package/recipes/boulders/README.md

@@ -0,0 +1,28 @@
+# Boulders — a set of four weathered granite/limestone boulders
+
+## Identity
+Generic alpine/glacial erratics for scattering on terrain tiles (see `mountain_range`). What makes
+them read as rock rather than blobs: **a flattened, blocky core** (two or three intersecting or
+smooth-unioned masses, never a sphere), **fractured facets** (a flat cut plane or two), **pitted,
+weathered surface** (fractal value-noise displacement, larger features than the strip texture), a
+**flat bearing face** where it sits on the ground, and **lichen/moss on the upward faces**.
+
+## Specs
+General values cited from prior knowledge, **unsourced / approximate**.
+
+| Quantity | Value | Used as | Source |
+|---|---|---|---|
+| boulder (Udden–Wentworth: > 256 mm) | 0.26 m and up | smallest ~0.6 m | unsourced, approximate (standard grain-size class) |
+| typical field / glacial erratic boulders | 0.5–3 m | 0.6, 1.0, 1.6, 2.4 m long | unsourced, approximate |
+| height / length of resting boulders | ~0.4–0.7 (they settle on a broad face) | 0.45–0.65 | unsourced, approximate |
+| moss / lichen | on the tops and the shaded side, not the bearing face | normal-based tint | observation |
+
+## Photos (by view)
+To be added (no web access in this session).
+
+## Parts the engine needs
+`boulder_0` … `boulder_3`: one static mesh each, base at z = 0 (the flat bearing face), laid out
+along +Y with 0.5 m gaps so the contact sheet shows the set. One shared material.
+
+## Open questions
+Rock type is left to the palette (grey granite here); limestone or sandstone is a colour swap.

package/recipes/boulders/boulders.ts

@@ -0,0 +1,117 @@
+// Boulders: four weathered rocks meshed from signed-distance fields (surface nets, smooth gradient
+// normals). Each is a blocky core (smooth-unioned ellipsoids and a rounded box), cut by one or two
+// fracture planes, pitted by seeded fractal noise, flattened on its bearing face at z = 0, and
+// tinted with lichen on upward faces. Resolution (cell edge, m) is the LOD knob. Dossier: README.md.
+
+import {
+  type BuildContext,
+  defineAsset,
+  type Field,
+  hex,
+  sd,
+  sdf,
+  type Vec3,
+  valueNoise,
+} from '@developerz.ai/ts23d';
+
+const STONE = hex('#8d8a84');
+const DARK = hex('#5f5c58');
+const LICHEN = hex('#7d8a4e');
+
+/** Length (X), width (Y), height (Z) in metres; `cuts` fracture planes. */
+const ROCKS: readonly { size: Vec3; cuts: number }[] = [
+  { size: [0.6, 0.45, 0.35], cuts: 2 },
+  { size: [1.0, 0.75, 0.6], cuts: 3 },
+  { size: [1.6, 1.1, 0.85], cuts: 2 },
+  { size: [2.4, 1.7, 1.1], cuts: 3 },
+];
+
+/** A plane through `at` with outward normal `n` (unit): negative behind it. */
+const plane =
+  (at: Vec3, n: Vec3): Field =>
+  (p) =>
+    (p[0] - at[0]) * n[0] + (p[1] - at[1]) * n[1] + (p[2] - at[2]) * n[2];
+
+function rock(ctx: BuildContext, i: number, size: Vec3, cuts: number, y: number): void {
+  const rng = ctx.rng.fork(`rock-${i}`);
+  const [l, w, h] = size;
+  const c: Vec3 = [0, y, h * 0.45];
+  // Core: an ellipsoid mass, a rounded block offset inside it, a smaller lobe: blocky, not round.
+  let f: Field = sd.smoothUnion(
+    0.12 * h,
+    sd.ellipsoid(c, [l * 0.5, w * 0.5, h * 0.6]),
+    sd.box(
+      [c[0] + rng.range(-0.1, 0.1) * l, y, c[2] - 0.05 * h],
+      [l * 0.8, w * 0.75, h * 0.9],
+      0.15 * h,
+    ),
+  );
+  f = sd.smoothUnion(
+    0.1 * h,
+    f,
+    sd.ellipsoid(
+      [l * rng.range(0.15, 0.3), y + w * rng.range(-0.2, 0.2), h * 0.6],
+      [l * 0.3, w * 0.35, h * 0.35],
+    ),
+  );
+  // Fracture planes: sliced faces read as split rock.
+  for (let k = 0; k < cuts; k++) {
+    const nx = rng.range(-1, 1);
+    const ny = rng.range(-1, 1);
+    const len = Math.sqrt(nx * nx + ny * ny + 0.09) || 1;
+    const n: Vec3 = [nx / len, ny / len, 0.3 / len];
+    const d = rng.range(0.26, 0.36);
+    f = sd.intersect(f, plane([n[0] * l * d, y + n[1] * w * d, c[2]], n));
+  }
+  const pits = valueNoise(rng.fork('pits'), { scale: Math.max(0.12, l * 0.18), octaves: 4 });
+  const rough = sd.displace(f, pits, 0.08 * h);
+  // Bearing face: cut flat at the ground.
+  const field: Field = (p) => Math.max(rough(p), -p[2]);
+  const pad = 0.15 * l;
+  ctx.part(
+    `boulder_${i}`,
+    sdf({
+      field,
+      bounds: [
+        [-l / 2 - pad, y - w / 2 - pad, 0],
+        [l / 2 + pad, y + w / 2 + pad, h * 1.15],
+      ],
+      resolution: ctx.pick([0.035, 0.08, 0.2]) * Math.max(0.6, l / 1.6),
+      // 'concrete' is the sheet's fractal-noise strip; 'stone' is coursed masonry (walls, not rock).
+      strip: 'concrete',
+      lipschitz: 1.6,
+      color: (p, nrm) => {
+        const up = Math.max(0, nrm[2]);
+        const t = Math.min(1, p[2] / h);
+        const base: Vec3 = [
+          DARK[0] + (STONE[0] - DARK[0]) * t,
+          DARK[1] + (STONE[1] - DARK[1]) * t,
+          DARK[2] + (STONE[2] - DARK[2]) * t,
+        ];
+        const moss = up > 0.75 ? Math.min(1, (up - 0.75) * 4) * 0.8 : 0;
+        return [
+          base[0] + (LICHEN[0] - base[0]) * moss,
+          base[1] + (LICHEN[1] - base[1]) * moss,
+          base[2] + (LICHEN[2] - base[2]) * moss,
+        ];
+      },
+    }),
+  );
+}
+
+export const boulders = defineAsset({
+  name: 'boulders',
+  kind: 'prop',
+  description:
+    'Four weathered boulders (0.6–2.4 m): SDF masses, fracture cuts, noise pitting, lichen.',
+  tags: ['rock', 'boulder', 'nature', 'sdf', 'scatter'],
+  seed: 7,
+  budget: { triangles: [40000, 9000, 2000] },
+  build(ctx) {
+    let y = 0;
+    ROCKS.forEach(({ size, cuts }, i) => {
+      rock(ctx, i, size, cuts, y + size[1] / 2);
+      y += size[1] + 0.5;
+    });
+  },
+});

package/recipes/boxcar/README.md

@@ -0,0 +1,53 @@
+# USRA 50-ton single-sheathed boxcar — 1918 (`boxcar`, `boxcar_nw`)
+
+## Identity
+The US Railroad Administration's standard 40 ft single-sheathed boxcar (spec 1001-B, 25,000 built
+from Oct 1918), chosen because it is THE generic American freight car of 1918–1950 and because its
+outside steel framing reads at any distance. `boxcar` is Clinchfield (C.C.& O.) 8024 as built by
+Bettendorf (NARA photo below); `boxcar_nw` is a Norfolk & Western car (same body, other livery).
+
+Signature features: vertical wood sheathing with the steel posts and diagonal braces OUTSIDE it
+(braces lean toward the door), a 6 ft sliding door hung on a bottom track, a low steel roof with a
+wooden running board, grab-iron ladders at diagonally opposite corners, a vertical brake staff with
+a horizontal wheel at roof level on the B end, knuckle couplers, cast-steel side-frame trucks.
+
+## Specs
+| Dimension | Value | Source |
+|---|---|---|
+| inside length | 40 ft 6 in (12.344 m) | B&M RHS ORER table, https://bostonmaine.squarespace.com/box_71000_series (via search summary; page 404s to fetchers) |
+| inside width / height | 8 ft 6 in / 8 ft 7 in (2.591 / 2.616 m) | same |
+| outside (body) length | 41 ft 3 in (12.573 m) | same |
+| extreme width | 9 ft 6 in (2.896 m) | same |
+| extreme height (top of running board over rail) | 13 ft 3 in (4.039 m) | same |
+| length over pulling faces | ≈ 43 ft 9 in (13.34 m): body + 2 × 15 in coupler reach | coupler reach from PRR X29 plan (railroads/tools/procgen recipe wagon_goods_boxcar) |
+| wheel diameter | 33 in (0.838 m), the US freight standard | https://kadee.com/553-ho-scale-andrews-1898-self-centering-trucks-with-33-ribbed-back-wheels-metal-fully-sprung |
+| truck wheelbase | 5 ft 6 in (1.676 m) | Andrews truck, https://www.nasg.org/Gallery/reports/scale/cars/modeltype/StrucksAndrews.php |
+| door opening | ≈ 6 ft (1.83 m) | scaled from the NARA photo against the 41 ft 3 in body |
+| coupler centre over rail | 34½ in (0.876 m), MCB standard | MCB / AAR standard height |
+| truck centres | ≈ 30 ft 9 in (9.37 m) | ESTIMATE, scaled from the NARA photo |
+| gauge | 4 ft 8½ in (1.435 m) | standard gauge |
+
+## Photos (by view)
+| View | URL | Notes |
+|---|---|---|
+| side, 3/4 front | https://commons.wikimedia.org/wiki/File:Military_Administration_-_Transportation_-_Rail_-_Construction_-_50_TON_SINGLE_SHEATHED_BOX_CAR_being_constructed_for_U.S._Railroad_Administration_by_the_Bettendorff_Co.,_Bettendorff,_Iowa_-_NARA_-_45502055.jpg | Clinchfield 8024, Bettendorf 1918: 4 braced panels each side of the door, lettering layout |
+| model reference, all views | https://rapidotrains.com/ho-scale/freight-car/usra-ss-boxcar.html | N&W 42574 livery, ends, roof, brake gear |
+| background | https://en.wikipedia.org/wiki/USRA_standard | spec 1001-B, 25,000 built |
+
+## Parts the engine needs
+`truck_a`, `truck_b` (pivots; engines yaw them on curves) · `axle_a_0` … `axle_b_1` (spin about Y,
+children `*_wheel_l/_r`) · `door_l`, `door_r` (slide one way toward −X, `oneWay`) · `coupler_a`, `coupler_b` (+X / −X).
+
+## Open questions
+- The ORER row (B&M 71000) carries 8 ft 7 in inside height; another page claims 9 ft. The ORER value
+  is used; 13 ft 3 in extreme height is consistent with it.
+- Truck centres are not published in the sources found: 9.37 m is scaled from the photo.
+- Lettering is painted on the boards and post faces; the diagonal braces cross over it (a stroke
+  painted on a brace face jumps sideways in parallax and garbles the word at 3/4 views).
+
+## Materials
+Painted plank sheathing and door (`wood_painted`: car colour over grey wood, worn at board edges and
+ends), silver-grey running board and saddles (`wood_weathered`), painted steel frame, sills and roof
+(`steel_painted`), sand-cast trucks, wheels and bolsters (`iron_cast`), and rusty hardware: grab
+irons, couplers, brake gear (`iron_rust`). The numbers and sources are in
+`docs/architecture/materials.md`.