The coat engine

Body space & regions

Genes do not think in texels. They think in horse body-space and let HorseSkinGeometry translate. That is what lets a coat rule be a smooth function of position and still come out seamless across every body part — no visible join where the neck meets the head, no mismatch where a leg’s front face meets its side.

The coordinate frame

Right-handed, in model units: 1 unit = 1/16 block = TEXELS_PER_UNIT = 2 texels on the SHEET_SIZE = 128px sheet.

There is one absolute scale per mesh (Skin.ADULT, Skin.BABY), with the origins read off the mesh itself — X = 0 is the backmost tail texel, Y = 0 the hoof undersides. So two different parts occupying the same body-space region sample a coat function at the same value, which is exactly why an X-function gradient has no seams.

Parts and faces

Every Part is an axis-aligned box. Each box has six Faces, each looking down one axis and spanned by the other two:

So, concretely:

• “paint the topline black” = the TOP faces (body-space yMax);
• “black up the belly” = BOTTOM faces (yMin);
• “a centreline blaze” = texels with small |z| on the head’s TOP/RIGHT/LEFT faces.

The part list

public enum Part {
    BODY, NECK, HEAD, MUZZLE, MANE, TAIL,
    LEFT_EAR, RIGHT_EAR,
    LEFT_FRONT_LEG, RIGHT_FRONT_LEG, LEFT_HIND_LEG, RIGHT_HIND_LEG;

    public Part mirror();   // LEFT_EAR <-> RIGHT_EAR, etc.
}

The API

The static no-Skin overloads target Skin.ADULT; the Skin-first overloads pick the mesh. It is pure data and arithmetic — keep the geometry tables in sync with HdHorseModel and HdBabyHorseModel.

HorseSkinGeometry.forEachTexel(ctx.skin(), (px, py, part, face, point) -> {
    // point.x() / point.y() / point.z() are body-space model units
    double t = (point.y() - hooves) / drop;
    field.restrictBlack(px, py, (float) (1.0 - t));
});

CoatRegions — the reusable moves

common/coat/pattern/CoatRegions wraps the common cases so a gene never touches a px,py directly. Everything takes a Skin; parts a mesh does not have are silently skipped.

BodyNoise — noise that crosses seams

BodyNoise is deterministic procedural noise sampled in body space — the same (x, y, z) model-unit coordinates every texel already carries.

Sampling in 3D rather than in texture space is the whole point: two texels that sit next to each other on the horse get neighbouring samples even when they live on opposite ends of the sheet (the body’s side face and its top face, say), so a pattern built from these functions crosses part seams without a visible join.

Callers scale their coordinates to choose the cell size. Everything is a pure function of (seed, x, y, z) — no state, no Random — so a coat rebuilt next session comes out identical.

PatchNoise — smooth patch fields for spotting

common/coat/pattern/PatchNoise is what the white-spotting genes (tobiano, frame, KIT sabino) sample for their patches. BodyNoise.value on its own is one lattice cell across the whole horse at the low frequencies a big patch needs, and grids up into visible axis-aligned squares. PatchNoise.field(seed, x, y, z, scale) fixes both: three octaves (detail at more than one scale) and a domain warp (the sample point is pushed around by a second noise field, so the octaves do not line up and the edges wander). z is stretched before sampling, or the two sides of the horse come out mirror-identical. fbm2 is the cheaper two-octave version, for fine speckle (roan, sabino roaning).

HairPattern — the mane and tail painter

common/coat/pattern/HairPattern is to the hair genes what WhitePattern is to the white-marking loci: one shape family, with the difference between two genes being its parameters rather than a second copy of the code. It offers bands (stripes across the hair), centreStripe (a line along it, centred), and the bright-hue draw the per-copy colours come from.

Its one interesting trick is that it works in the part’s own axes rather than the world’s. A mane is a long thin blade and a tail a short fat one, and both are rotated out of the world axes by their rest pose, so neither “bands along X” nor “bands along Y” is right for both. axesBySpan(skin, part) sorts the part’s three axes by the span of its bounds, and the shapes run along the longest and across the second. That is why one painter serves the mane locus, the tail locus and the healer’s stripe, and why it will serve a fourth without changing.

Read by mane colour, tail colour, healer and light’s gold mane.

Three stripe fields, and why they are three

There are three fields in coat/pattern/ that draw bands in body space, and the temptation to collapse them into one is exactly the mistake that produced a zebra with bars up its face and a brindle horse that matched left to right.

BodyStripes — the shared stripe field

Bands that run mostly across the horse (constant body-space X), so a stripe wraps from the barrel’s side over the spine without a seam.

/**
 * @param spacing centre-to-centre distance in body units (the adult barrel is 22 long)
 * @param duty    how much of each period is stripe, (0,1) - 0.5 is equal stripe and gap
 * @param warp    how far, in body units, the noise field may bend a stripe off its plane
 */
public static double coverage(long seed, double x, double y, double z,
                              double spacing, double duty, double warp);

/** Hermite fade from 0 at edge0 to 1 at edge1. */
public static double smoothstep(double edge0, double edge1, double v);

Magic zebra is the first caller. BodyStripes is deliberately generic, and that turned out to be a reason to stop reaching for it rather than a reason to keep doing so. Dun’s leg barring went to CoatRegions.legBar, zebra to ZebraStripes and brindle to BlaschkoStripes, because in each case what the gene actually wanted was a different shape, not the same shape somewhere else — and “where you apply it and what colour you make it” was never the difference between them.

What it is still exactly right for is the data-driven STRIPES mask, where a gene author has no Java and wants parallel bands with a chevron: one field, four numbers, no geometry knowledge required. That is now its only caller.

The vanilla model underneath

Every number in HorseSkinGeometry is read off HdHorseModel / HdBabyHorseModel, which are in turn structural copies of vanilla’s AbstractEquineModel.createBodyMesh. So there are two coordinate systems in play, and it is worth being explicit about both — most confusion about this engine is really confusion about which one a number is written in.

Minecraft model space

The convention vanilla’s mesh builders use, and the one the tables below are in. Units are model units, 16 to a block — the same unit body space uses.

A cube is declared as a pivot (PartPose.offset) plus an addBox(originX, originY, originZ, width, height, depth) whose origin is the box’s minimum corner relative to that pivot. PartPose.offsetAndRotation additionally gives a part a rest rotation about its pivot; on the horse only the neck group and the tail have one, both a pitch of π/6.

…and the flip into body space

Body space is model space turned the right way up and measured from the horse rather than from an arbitrary pivot. Both axes that reverse do so about the mesh’s own maxima, so the origins land on real anatomy:

bodyX =  modelMax.z - mz;   // 0 at the backmost tail texel, + toward the nose
bodyY =  modelMax.y - my;   // 0 at the hoof undersides,     + up
bodyZ = -mx;                // 0 on the centre plane,        + to the horse's right

Two axes swap and all three negate, so the map is orientation-preserving — a face wound outward in model space is still wound outward in body space, which is what lets the gene creator’s 3D preview build its mesh straight out of these tables.

The adult parts, as 26.1.2 declares them

Pivot and origin in model space; texOffs in vanilla’s 64-space (the HD sheet lands each at 2×). Parts listed as children carry the neck group’s π/6 pitch.

The hierarchy those poses imply:

root
├─ body
│  └─ tail                     pose (0, -5, 2), pitch π/6
├─ head_parts   (the NECK)     pivot (0, 4, -12), pitch π/6
│  ├─ head
│  │  ├─ left_ear
│  │  └─ right_ear
│  ├─ mane
│  └─ upper_mouth  (the MUZZLE)
├─ left_front_leg              ├─ right_front_leg
└─ left_hind_leg               └─ right_hind_leg

Note that the neck group is a child of the root, not of the body: it shares no transform with the barrel, which is why a horse can drop its head to graze without the torso following. The four legs are likewise siblings, each swinging about its own pivot.

Asking a part what shape it is

The AABB approximation above is fine for looking a texel up and wrong for saying “along this part”. On the six pitched parts — neck, head, muzzle, mane, ears, tail — a band on body Y is a horizontal slice, so a stripe meant for the crest comes out as a collar wrapping the throat as well. Eleven gene files used to work around that with a sawtooth longer than the horse, tilted by hand to tan(60°), which is the neck’s own long axis written out as two constants in files this class had never heard of (gap 103).

HorseSkinGeometry.local(skin, part, point) is the replacement: the inverse of posed’s frame change, returning the point as three fractions along the edges of the part’s actual cuboid. Each fraction is named for the body axis it pairs with and runs the same way, so "axis": "X" still means “toward the nose” in spirit — on the neck it is across the part’s depth, low at the crest (the face the mane box sits on) and high at the throat, while "axis": "Y" runs along the neck’s length and a band there is a collar square to the neck. It is what space: "local" reads on AXIS, WAVES and RAMP.

Two properties are worth knowing and are both pinned by PartLocalFrameTest. On an unpitched part the box is its own AABB, so local and part-space normalisation agree to the bit — there is never a reason to think about which to use on a leg. And the fractions run outside 0..1 on a pitched part, because the texel grid is the bounding box and its corners sit off the ends of the real cuboid: on the adult neck local X spans −0.72 to 1.72. Nothing clamps them, which is why a band meaning “everything from the crest to here” starts at -1.0.

The texture is an atlas, not a wrap

Every cuboid gets six independently UV-mapped faces packed onto the sheet; there is no continuous unwrap of a horse-shaped mesh anywhere. That is exactly what makes forEachTexel necessary — two texels that are neighbours on the horse are routinely nowhere near each other on the sheet, so a coat rule written in texture space would seam at every box edge, and one written in body space cannot.

Vanilla points all four legs at one patch (the left pair additionally .mirror()ed) and both ears at another. HdHorseModel gives each its own patch in what was empty space on the vanilla layout, which is what lets this mod paint four legs and two ears independently — a horse with one white sock is not expressible on the vanilla sheet at all.

The HD models the geometry describes

HdHorseModel and HdBabyHorseModel are 128px, per-part UV, structural copies of vanilla’s meshes with every cube at texScale = 0.5 and the layer baked at 128×128 — so the effective texture size stays 64 and every normalized UV is identical to vanilla. The 2× sheet just gives each face twice the texels.

GeneticHorseRenderer deliberately does not add vanilla’s HorseMarkingLayer: that layer paints horse_markings_white.png over the whole texture, so any horse that rolled Markings.WHITE rendered as a flat white horse on top of a correct generated coat. All white markings here come from the splash genes, inside the coat texture.