Start here

The genetics model

Alleles are objects, not letters in a string. A horse carries one AllelePair per registered Gene, plus an epigenome — a priority and a set of literal numbers riding on each allele copy. Everything below lives in common/genetics/ and imports nothing from Minecraft.

The pieces

The genotype code string

A Genotype is held internally as a map keyed by gene, and serialises to one gene-keyed segment per gene, in Genes.codeOrder(). Each segment is <geneKey>=<a>/<b> — the full Gene.key(), then the two alleles in the gene’s own declaration order; segments joined by -, alleles by /:

horsegenetics.extension=E/e-horsegenetics.agouti=A/a-horsegenetics.silver=z/z-horsegenetics.matp=Cr/N- …

Allele tokens can be any run of characters — Spl, Cr, prl, Mzeb, Blupnk — not single letters. The =, / and - separators (and the gene key, which contains none of them) keep that unambiguous. The forward-looking rule for third-party genes is stricter: alphanumeric tokens, 1–128 characters, wild type named n.

Gene priority and the derived orderings

Every Gene declares an int priority() — a fixed constant of the gene, no default. Genes keeps a single order: every registered gene, built-in and data-driven alike, sorted on (priority, key). The three public views are a result of that one sort, never a source: codeOrder() / all() is the whole list, naturalOrder() is it filtered to isNatural(), magicalOrder() to the magical genes. Ties break alphabetically by key. A data-driven natural gene at priority 45 lands between the built-in MATP (40) and champagne (50) — loaded genes are not appended.

Bands are a convention: 0–99 natural, 100+ magical — the phase (isNatural()), not the number, splits the two coat passes, and Genes.register only warns when a gene sits outside its band. Within the natural band, low numbers set pigment absolutely, higher numbers dilute (agouti's absolute points must precede PigmentField.dilute). Built-in priorities were chosen to reproduce the pre-rewrite hand-written order, so no coat changed. This is not AlleleEpigenetics.priority, which selects a seed and never an order.

Alleles, combinations and expressions

A gene has any number of alleles. A horse carries two, and order does not matter, so a gene with n alleles has n(n+1)/2 combinations — three for two alleles, six for three, 465 for a thirty-allele KIT. Every combination produces some result, and the gene says which by declaring its distinct results as Expressions and mapping any pair to one of them with expressionOf(AllelePair).

What an expression carries

private final Expression WILD = Expression.wildType("No white markings.");

private final Expression SABINO = Expression.of("sabino1", "Sabino 1")
        .describe("Tall jagged stockings, a splash of white up the belly, ...")
        .varies()
        .restrict((ctx, coat) -> paintSabino(ctx, coat, 1));

private final Expression SABINO_WHITE = Expression.of("sabino-white", "Sabino-white")
        .describe("Ninety per cent white or more, with a few coloured flecks ...")
        .varies()
        .restrict((ctx, coat) -> paintSabino(ctx, coat, 2));

@Override
public Expression expressionOf(AllelePair pair) {
    return switch (pair.count(SB1)) {
        case 2  -> SABINO_WHITE;
        case 1  -> SABINO;
        default -> WILD;
    };
}

A gene may declare more than one wild type when different silent combinations deserve different wording — MATP’s prl/N is a “pearl carrier”, distinct in the gene dictionary from the plain N/N even though the two horses look identical. The catalogue collapses every wild type into one entry, because “changes nothing” is one look.

The genotype-aware question

A handful of genes depend on another gene: agouti paints black points, so it does nothing at all on a chestnut horse. Those override expressionIn(pair, genotype), which defaults to expressionOf(pair) and is what the coat pipeline actually calls. An override may only return one of the gene’s own declared expressions — typically a wild type, meaning “suppressed here”.

A data-driven gene can do this too now. An expression in a gene file may carry a needs block naming another locus and a copy count, and SpecGene implements expressionIn and coatDependsOn off it. That is the whole of the addition: no new concept, just a way to reach the hook the leopard complex has used since long before the file format existed. Accretion is the gene built on it — one locus decides whether there is a pale field and what colour it is, and Accretion Field, which paints nothing at all and which every horse carries, decides whether it takes the topline or the underside.

Founder frequency, per combination

Gene.founderTable(FounderContext) returns a FounderTable: a weight per allele combination, as percentages that should sum to 100. One nextFloat() per gene per founder picks a bucket, drawn in codeOrder(), so a founder’s genotype is reproducible from the RNG stream. Founders only — breeding never consults it.

This replaces the “1 in N per allele” frequency each gene used to hand-roll, for two reasons. It has no meaning past two alleles — “1 in 45 per allele” says nothing about a locus with thirty of them. And it hid the number the author cares about: a per-allele chance only implies a homozygote rate, where a per-combination table lets you set it directly. The two splash loci are the clearest case — a majority of MITF founders carrying one SW1 and none at all homozygous is a shape no allele frequency can produce, because Hardy-Weinberg’s heterozygote share peaks at 50% and always brings homozygotes with it.

The table is sparse: a combination left out simply never turns up in the wild. That is what lets a thirty-allele locus declare the dozen combinations that actually occur instead of all 465. Weights that miss 100 are normalised proportionally with a warning, not an error. FounderTable.hardyWeinberg(variant, baseline, p) is a convenience that computes the three numbers a two-allele author would otherwise work out by hand — it is what the old “1 in N” meant, not a second model.

The multi-allele overload is hardyWeinberg(Map<Allele, Double>, Predicate<AllelePair>), and KIT is why it exists: thirty-six combinations, four of them ruled out, is not a table anyone can hand-write without a typo nobody would ever see. Excluded combinations are dropped and the rest rescaled, which is also the biology — a lethal is absent from the adult population you are observing.

FounderContext carries the part of the genotype already rolled, so a gene’s frequency may depend on what the horse already is (“champagne twice as likely on a chestnut”). Genes roll in codeOrder(), so a gene can only read genes with a lower priority; asking about a later one throws rather than quietly handing back a wild type that would make the bug invisible.

The forty-eight registered genes

The table is in codeOrder() — the one (priority, key) sort every ordering is derived from — so it doubles as the list of the numbers the built-ins occupy. Low numbers set pigment absolutely, higher ones dilute; 80–99 is the non-coat sub-band and 100+ is magical.

Six of them are white-pattern loci, and they are six because real white patterning is six genes. Only alleles at exactly the same locus share a gene here: sabino and the numbered W series are all KIT variants, so they are one gene; splash lives on MITF and PAX3, so it is two; and tobiano (an inversion near KIT, not a KIT variant), roan (region-mapped, causal change unresolved) and frame (EDNRB) each keep their own. That is what lets a horse be tobiano and W20 and splash at two loci — and what stops it being sabino and dominant white at once.

● Brindle is the model’s only sex-linked gene. Its Y is not an allele a horse can express — it is the reserved placeholder a hemizygous stallion’s spare slot holds, meaning “this locus is not on the Y”. That is what lets a genotype stay one two-slotted AllelePair per gene with no structural change, and it is why a stallion carrying brindle displays as X-Brn rather than beside a fake second copy. See its page. ¶ Mane and tail colour are the model’s first genes whose heterozygote paints with two allele copies at once, one colour each, which is why they need CoatBuildContext.epigeneticsForCopy rather than "the copy that expresses". ‡‡ Light is the clearest codominance in the model: three variants, each dominant to the wild type and to none of each other, so a horse shows everything it carries — ten combinations, seven outcomes, and no ordering of three alleles that could describe it. * KIT is the locus that broke the last of the old model. Eight alleles, thirty-six combinations, and four of them homozygotes that are thought nonviable — so canOccur rules them out and the founder table is the survivors, renormalised. It also settles a genotype the old model allowed and biology does not: a horse can be homozygous sabino or dominant white, never both, because they are alleles of one gene competing for two slots. See its page. † O/O is one of the model’s two kinds of lethal. An embryonic lethal is a horse that never existed (canOccur false, no pen, no founder) — KIT’s four W homozygotes, and MET’s met/met. Lethal white is the other kind: the foal is born, so it occurs, it has its own masking all-white outcome and it gets a pen — it is simply never a founder, because a founder is an adult that survived. The death is modelled; see the horse’s body and its page. ¶¶ The leopard complex was the model’s first cross-locus gene, and accretion is the second — the first to do it from a file rather than from Java. LP reads PATN1 and PATN2 in expressionIn to pick one of eight outcomes (leopard, fewspot, spotted blanket, snowcap, semi-leopard, or the plain LP looks). The modifiers paint nothing on their own, so they carry Gene.affectsCoat() false and would be left out of the texture key — LP.coatDependsOn() names them and coatCode() folds their alleles in, but only for a horse that actually has LP. A founder draws a variant PATN copy only if it already rolled LP. See its page. § Dun is the locus with two dominance orders. Dilution reads D > d1 = d2 but marking reads D = d1 > d2, so d1 draws the dorsal stripe without diluting anything — a horse with primitive markings that is not a dun. No single dominance label covers both orders, which is the clearest case yet for the table. See its page. ‡ Sex was the first gene that never paints, and is no longer the only one. Both its outcomes are wild types, so it costs the catalogue nothing and is left out of the texture key; it is registered at priority 1 so a future sex-linked gene can read a sex that is already resolved, and so a foal’s sex is inherited rather than rolled. See its page.

The thirteen that never paint

Every outcome of every gene below is a wild type, which here means “changes nothing about the coat”. So affectsCoat() is false for all of them, they are out of the texture key, and the catalogue collapses each locus to a single entry — thirteen genes for zero catalogue growth, which is the sex locus’s trick reused. What they do instead goes through common/trait/: the machinery is on the horse’s body, and each gene has its own page. Their order among themselves is arbitrary, because none of them can reach another through the coat.

No founder is ever affected. Every health founder table lists only the clear horse and the carrier, because a wild-caught horse is an adult that survived — so the only way to meet a disorder is to breed two carriers. Four colour genes carry one as well: silver Z/Z is MCOA, EDNRB O/O is lethal white, and a homozygote at either splash locus (MITF / PAX3) is deaf — one condition with two causes, de-duplicated by id.

Seal brown has no allele of its own. Neither has blood bay nor liver bay: all four bays are bands of one shade score, which the shade locus, MC1R dosage, ASIP dosage and a per-horse roll add up between them. Agouti declares the four as outcomes and picks between them by reading the rest of the genotype. Cream and pearl are one gene, and so are dominant white and sabino: they are allelic in real horses (MATP and KIT respectively) and are now one locus each, which kills the impossible Cr/Cr-and-prl/prl genotype the old two-gene model allowed. See its page. Dun is the other three-allele locus, and the one that shows why a dominance label could never have worked: see its page.

Sex-linked inheritance

Every gene in the model is autosomal except one. Gene.inheritance() declares AUTOSOMAL (the default), X_LINKED or Y_LINKED, and brindle is the gene that made it worth building: a stallion has one X, so he carries one copy and can never be a carrier, while a mare needs two. That asymmetry produces pedigree shapes no autosomal gene can.

The reserved slot

A genotype stays one AllelePair per gene, two slots, always. A hemizygous horse fills the slot it does not really have with a reserved placeholder allele the gene declares:

That is what keeps the change small. Genotype is untouched, epigenome alignment is untouched (the reserved slot simply carries epigenetics nothing reads), the code string keeps its shape, and parsing needs no special case because the placeholder is a declared allele like any other.

The placeholder must be declared at the end of alleles() that its slot sorts to — Y last on an X-linked gene, X first on a Y-linked one — because AllelePair canonicalises on declaration order. Genes.register refuses a gene that gets this wrong, since the failure otherwise is not an exception but a gene that quietly misbehaves for exactly one sex.

What changes in breeding

• The sire's copy is decided by the foal's own sex rather than drawn. The sex locus is priority 1, so it is always already resolved by the time any other gene is reached. On an X-linked locus the sire gives his X-borne allele to a filly and his Y — nothing — to a colt; Y-linked is the mirror. The dam is unchanged in both.
• The second coin is still flipped and thrown away. Two nextBoolean() per gene is an invariant a great deal leans on — the golden coats, the gamete-bias equivalence test, every claim that adding a gene shifts the stream by a known amount — and a locus that quietly consumed one would make the random stream depend on a foal's sex.
• Gene.sexConsistent drops combinations no horse of either sex could carry, so the catalogue does not enumerate them and the random splice cannot roll them.
• Gene.realAlleles(pair) — two for a diploid horse, one for a hemizygous one, none for a mare at a Y-linked locus — is what a sex-linked gene's expressionOf counts. “Every real copy is Brn” covers recessive in mares and always shows in stallions in one sentence.
• The founder table has to be sex-aware, and a hemizygous one is written out rather than derived from Hardy-Weinberg — Hardy-Weinberg is a statement about diploid loci and this one is not.

On screen a hemizygous copy carries an X- / Y- prefix (X-Brn), unambiguous on sight because - is the gene separator in a code string and can never appear inside an allele token. The code string itself is unaffected.

Epigenetics ride on the allele, not on the horse

A genotype says which alleles a horse carries. It does not say what those particular copies are carrying, and every copy carries two things:

• a priority — an int in [1, Integer.MAX_VALUE], used only for the homozygote tie-break below;
• a set of literal numbers — one per value the gene declares in its epiSchema(): how much white a splash covers, how much bigger a magically large horse is, how far up the legs a bay’s points climb.

So a horse carrying A/a has one set of numbers on its A and another on its a, and a foal that inherits the A inherits that copy’s numbers. Bay point heights run in families rather than being reinvented every generation.

Three kinds of value, because drift cannot treat them alike

Colours are three SCALAR channels (<name>_r / _g / _b) rather than one packed int, so a line’s colour drifts gradually instead of jumping. A founder’s is still rolled bright — hue over the whole circle at a held-up saturation and value — because a magical mane that rolled a muddy olive reads as a bug.

Founder distributions are declared, not flattened

A value names the distribution its founders are rolled from: uniform, a bounded Gaussian, or a power curve. That matters because the genes were deliberately skewed — ednrb’s cover is a power curve so most splash horses carry a little white and a few carry a lot; the magical stat deltas are Gaussian so a single copy is usually subtle. Rolling everything uniformly would have been simpler and would have quietly changed the character of the wild population on every one of them.

Which copy expresses

That is what Epigenome.expressed(gene, genotype) answers, and its values are what CoatBuildContext.epigeneticsFor(geneKey) returns.

The epigenome code string

One <geneKey>=<copy>/<copy> segment per gene that declares a schema, joined by ;. Each copy is p:<priority> followed by that gene’s named values: a plain number, # for a hex noise seed, [a|b|c|d] for a per-leg value.

horsegenetics.body_size=p:1734,delta:0.34215/p:9871,delta:0.31049;horsegenetics.ednrb=p:44,seed:#8f3a21c4b70e1d55,face:0.61,cover:0.4113,…

Two things changed shape here. Genes join with ; rather than -, because values are signed now and a hyphen can no longer double as a delimiter. And the majority of genes write nothing at all — a gene whose behaviour is fixed by its alleles declares an empty schema, which is what keeps the code readable now that each stored gene carries a couple of hundred characters instead of a sixteen-digit seed.

Parsing is tolerant the same way the genotype code is: an unregistered gene’s segment is dropped, and anything the schema declares but the text omits — a gene, or one value inside a gene — is rolled deterministically from the gene key and the value’s name, so every horse in the world agrees on it.

Every value is quantised to what the text can write the moment it is created, so a horse’s numbers in memory are exactly what its code says. That is not tidiness: a value that lost a digit on the way to disk would give a horse a subtly different coat after a reload than before it, and the two would fork the texture cache without ever looking different enough to notice.

Epigenome.fromSeed(long) replays a whole epigenome from a single long — a reproducible test and tooling horse, used by the golden-coat suite, the coat sample sheet and the designer preview. It is not a stand-in for a horse whose epigenome was not stored; FamilyTreeScreen used it that way and drew ancestors that never existed, and that fallback is gone.

Founders roll; foals inherit

• Founder (wild spawn, /summon, a dimension pen horse) — Epigenome.random(rng): an independent priority and an independent roll of every declared value on every copy, deconflicted. Reached through CoatGenerator.generate, which is the founder path, and through BreedFounder for a breed.
• Foal — Genome.breedWith. Every inherited allele brings its parent copy’s priority verbatim and its numbers nudged by drift. A foal must never go through the founder path.

If both copies arrive on the same priority, one extra nextBoolean() bumps the second ±1 (AlleleEpigenetics.deconflict), clamped to [1, MAX] — so a horse never carries a tie. Full inheritance detail is on the breeding page.

What the texture key captures

CoatData.textureKey() is the genotype’s coat code, plus @<fingerprint hex> only when the horse is non-deterministic. Epigenome.visibleFingerprint(genotype) digests only the expressed values of genes that are both visible and non-deterministic, so epigenetics a horse cannot show do not fork the cache. It folds in every stored number rather than a single seed — getting that wrong does not throw, it silently forks the cache or collides two horses onto one texture.

Genotype.coatCode() is the full code minus every gene that can never paint anything — Gene.affectsCoat(), derived as “is any of my outcomes not a wild type?”. Today the sex locus is the only such gene, and leaving it out is what stops a mare and a stallion of the same colour baking two identical textures. It is not a persistence format: it is lossy on purpose and nothing parses it back.

/** Is every gene's contribution identical on every horse with this genotype? */
public boolean isDeterministic();

/** Does any *visible* gene need per-horse randomness? -> bake per horse. */
public boolean hasVisibleNonDeterministic();

Gene.isVisible(pair, genotype) and Gene.isDeterministic(pair, genotype) both see the whole genotype — both derive from expressionIn(pair, genotype), which is how agouti knows it is invisible on a chestnut.

The genotype catalogue

GenotypeCatalog enumerates every visually distinct genotype the registry can produce. Nothing is hard-coded — it falls out of codeOrder(), each gene’s allele list and each gene’s expression table, so registering a gene widens it on its own — the catalogue is built lazily and thrown away whenever the registry changes, which is what makes a drop-in gene show up in the catalogue without anything else being told about it.

Two reductions, both read straight off the expression table with no dominance metadata in the middle: pairs landing on the same expression collapse to one, and a gene on a masks expression keeps exactly one entry — that combination with every other gene at a wild type, which is why a masking combination keeps just one pen instead of hundreds of thousands. Ordering is a mixed-radix odometer whose first gene is the fastest-varying digit, so the catalogue reads

Nothing in the game reads it any more. It used to drive the horse dimension, one pen per entry; that corridor went back to random pens on 2026-09-04, because at two million entries the corridor was longer than the world. The catalogue stays because the tests read it and a punnett display will — the reduction is a statement about the genes, not about the dimension.

Phenotype, coarsely

Genotype.phenotype() gives a coarse CoatPhenotype (CHESTNUT / BLACK / BAY / WHITE; everything else ignored). It is only a family-tree fallback now — foals and adults alike are fully generated through the coat pipeline.

Genes that never paint

Twenty-four of the registry’s forty-eight built-in genes change nothing about a horse’s colour: the sex locus, the six performance and size loci, the seven health loci, the two leopard-complex modifiers (PATN1, PATN2 — read by LP, but never painting themselves), and seven magical genes — milk, verdant, particle, and the four magical body-stat genes (size, speed, health and jump). Every combination they can produce is an Expression marked wildType.

That reads oddly for a gene that can kill a foal, and it is exactly right: wildType means “changes nothing about the coat”. It is the property the coat pipeline asks about, and nothing else. What these genes do instead travels on the trait system — speed, max health, jump strength, body scale, and the disorders a horse expresses.

Three consequences follow, and together they are why the non-painting genes are nearly free:

• Gene.affectsCoat() is false, so they are excluded from Genotype.coatCode(). Two horses that differ only in them share one baked texture.
• GenotypeCatalog.distinctPairsOf collapses every wild type into one group, so each contributes one catalogue entry however many alleles it has — ACAN’s five alleles and fifteen combinations included, and verdant’s four — and particle’s forty, 861 combinations collapsing to one entry — and each leopard-complex modifier’s three combinations collapsing to one. The catalogue stands at 11 098 128 386 distinct coats. The particle locus and the four body-stat genes left it untouched; the two genes that do change the coat — the two-outcome LUT locus and now the leopard complex (coarse expressionOf: wild or varnish-roan) — each doubled it. That tipped GenotypeCatalog.size() past Integer.MAX_VALUE, so it (and get()) are long now; nothing in production indexes the catalogue.
• The raw genotype count is 42 875 903 837 175 872 297 619 456 000 000. All real, all heritable, all distinguishable — just not by colour. (The leopard complex’s three loci, three combinations each, multiplied it by 27.) It is a BigInteger now, and has to be: the particle locus pushed the product past 2⁶³, and the figure this page carried until then — 3 028 898 126 035 238 912 — was a long that had already wrapped. The true count before particle was 94 874 633 669 214 259 200 000.

The magical utility and body-stat genes stretched the phrase further than the health loci did, and it still holds. A lava-bearing horse is emphatically not “the same as an ordinary horse”, and a ten-times giant is the most visible thing on the field — but neither changes a coat pixel, and the coat pipeline is the only thing that asks. The cost is real and is logged as a gap: milk and verdant are invisible until you put a bucket under the horse or watch the floor, where healer deliberately draws a stripe so you can see what it does.

An expression still carries a name and a description when it is a wild type, which is what lets a carrier outcome say something useful (MATP’s pearl-carrier, every health locus’s …-carrier) without pretending to change the coat.