Core / traits, size & health

The horse’s body

Speed, max health, jump strength, body size, and the disorders a horse expresses — all of it a pure function of the genotype. This page owns the machinery: the resolver, the baselines, how a gene contributes, the two kinds of lethal, and the server setting that governs them. The genes themselves are one page each.

One walk, one record

HorseTraits.resolve(genotype) walks Genes.codeOrder() once, hands every gene that implements TraitContribution a TraitBuilder, and returns a Traits record.

public record Traits(double speed, double health, double jump, double scale,
                     List<Condition> conditions) {

    Viability viability();              // derived: the worst severity in the list
    Optional<Condition> lethalCondition();
}

Nothing is stored. HorseRecord has no speed or health field any more — the same reasoning that removed its sex field. A stored derived value can only ever go stale against the alleles sitting next to it, and re-resolving on demand means a change to a gene’s weight (or to the server setting below) reaches horses that already exist.

There is deliberately no breed here

resolve takes a genotype, an epigenome and the health switch, and nothing about the horse’s breed. A breed pins one or more body axes to a TargetBand, but that band is read exactly once — by BreedFounder, which writes a point inside it onto a founder’s allele copies as ordinary epigenetic numbers. A Thoroughbred still reliably resolves near ×2 speed where two Swift copies on the plain Gaussian would only reach ×1.2, because its copies genuinely carry those percentages. The height band still exaggerates its above-baseline part (BreedStatCurve.BIG_GAMMA = 3) so a draught breed genuinely towers — real horse heights differ by too little to read (a Percheron founder ends up ×1.0–1.38, a Quarter Horse ×0.96).

Determinism

No Rng, no epigenetics, no entity state. The same genotype always resolves to the same body — on the server, on a reload, and in a unit test. That is the determinism contract applied to the body rather than the coat.

The baselines

A horse carrying nothing but wild types lands on these. They sit a little under vanilla’s midpoints on purpose: the variant alleles are what push a horse up through the vanilla range, so a bred line beats a wild-caught one and there is somewhere to go.

The wild range is measured over 200 000 founder draws. It is deliberately narrower than vanilla’s at both ends: a wild-caught horse should be unremarkable, and both the ceiling and the floor should be things you find by breeding.

How a gene contributes

public interface TraitContribution {
    void contribute(AllelePair pair, Genotype genotype, TraitBuilder out);
}

/** Marker: this contribution is a disorder, and the server setting can suppress it. */
public interface HealthContribution extends TraitContribution { }

A capability a Gene may additionally implement, rather than more methods on Gene that most genes would leave empty. A gene that only does this — every performance, size and health gene — is an allele list, a combination table and one method.

One interface, not four

The roadmap sketched four (StatContribution, BodyContribution, ViabilityRule, ConditionRule). They collapsed into one for two reasons. They all run in the same single walk, so four of them would be four sinks threaded through one loop; and the genes that need any of them mostly need several at once — chondrodysplastic dwarfism is a stat change and a size change and a condition, and splitting that across three interfaces would scatter one gene’s answer over three methods that have to agree.

Viability is not an interface at all. It is derived from the severity of the conditions reported, so a gene can never declare a horse lethal without saying what killed it.

Additive, and therefore order-independent

A contribution is either additive (addSpeed, addHealth, addJump, addScale) or a scale multiplier (multiplyScale). build() applies every addition before every multiplication, and both operations are associative, so the result does not depend on the order genes are visited in — the same argument that keeps the coat’s phase-3 accumulator drift-free. Gene priority still fixes the code order; it deliberately buys nothing here, so nobody is tempted to encode a dependency between two genes as a priority number.

Among the natural loci, multipliers exist for one reason: dwarfism is a proportional change. A pony with chondrodysplasia should end up small twice over, not be dragged to the same absolute height as a draught horse with it. The natural speed, health and jump loci stay purely additive, which keeps a gene’s weight readable as “this allele is worth two hearts” rather than “it depends”.

The four magical body-stat genes — size, speed, health and jump — are the deliberate exception. Each carries a per-copy percentage that has to scale whatever the natural loci settled on, so a magically fast pony is still slower than a magically fast racehorse. They go through multiplyScaleUnclamped and the three siblings beside it (multiplySpeedUnclamped, multiplyHealthUnclamped, multiplyJumpUnclamped), every one applied after all additions and bounded only by the MAGICAL_* guards.

The per-horse twin 2026-09-04

public interface EpigeneticTraitContribution {
    void contribute(AllelePair pair, Genotype genotype, GeneEpigenetics epigenetics, TraitBuilder out);
}

/** The trait-side twin of CoatBuildContext's two epigenetics accessors. */
public interface GeneEpigenetics {
    Rng expressed();        // one locus, one result - almost everything
    Rng copy(int slot);     // a CODOMINANT gene, where both copies contribute
}

The plain interface is a pure function of the genotype, and for every natural gene that is exactly right: p/p is one particular pony and always the same one. It cannot express the four magical body-stat genes at all, because the point of them is that two horses can both be “big” (or fast, or hardy, or springy) and one of them be twice the other — which needs a number that varies between horses carrying identical alleles.

Two accessors, because a codominant gene needs both copies. expressed() answers "what does this horse show at this locus", which is right wherever one locus produces one result. The four magical body-stat genes cannot use it: their two alleles each contribute a percentage and they add, so asking for the expressed copy would count one allele twice and the other not at all. That is the same split mane colour needed on the coat side.

HorseTraits.resolve gained an epigenome parameter to feed it, and HorseRecord.traits() / HorseRecords.traitsOf now pass the record’s own. Asking a bare genotype (resolve(genotype)) still works and is still the right call for a question about a genotype rather than a horse — a punnett display, a wiki table, a test — and answers with the midpoint of what the genotype can produce, via MidpointRng. It is not random and is not pretending to be; inventing an epigenome there would answer about a horse nobody owns.

Scale has two stages, and only one is clamped

MIN_SCALE / MAX_SCALE (0.45 – 1.75) exist so that no amount of stacking the real size loci and the dwarfisms can produce a horse that is not a horse. A magical gene is allowed to produce exactly that, so multiplyScaleUnclamped applies after that clamp and is bounded only by MAGICAL_MIN_SCALE / MAGICAL_MAX_SCALE (0.1 – 10) — a limit on absurdity rather than a limit on size, and the exact counterpart of the coat’s uncapped phase-3 accumulator.

The two stages compose the way you would want: the natural loci settle the horse’s own size first and the magic multiplies whatever that turned out to be, so a magically enormous pony is still smaller than a magically enormous draught horse.

Speed, health and jump work the same way, minus the natural clamp they never had: multiplySpeedUnclamped / multiplyHealthUnclamped / multiplyJumpUnclamped take the additive result and scale it, bounded only by MAGICAL_MIN_FACTOR / MAGICAL_MAX_FACTOR (0.1 – 10). The MIN_HEALTH floor is still applied last, so no combination of Frail and a disorder can resolve a horse to zero hearts.

The non-coat genes cost the coat nothing

All thirteen of them paint nothing — as do seven magical genes (milk, verdant, particle and the four body-stat genes), on the same terms: every combination is an expression marked wildType. That is not a loophole, it is what wildType means — changes nothing about the coat. Three things follow, and together they are why thirteen new genes were nearly free:

• Gene.affectsCoat() is false, so they are excluded from Genotype.coatCode() and two horses that differ only in them share one baked texture.
• GenotypeCatalog.distinctPairsOf collapses every wild type into one group, so each locus contributes one catalogue entry however many alleles it has. Adding all thirteen left the catalogue of distinct coats exactly where it was — the number itself has moved since, but only ever because a gene that does paint was added.
• The raw genotype count multiplied by 5 314 410. Those are all real, heritable, distinguishable horses — they just are not distinguishable by colour. Current figures are on the genetics model, which is the one place they are kept.

Conditions

A Condition is a named disorder, declared by a gene as a constant next to the expression that produces it. It carries the same two pieces of prose an expression does — a short name and a sentence — because the surfaces that show it are the same surfaces that show an expression, and a player who has just lost a foal deserves to be told which disorder took it.

The mechanical effect is not on the condition. A gene applies its own stat changes through TraitBuilder in the same breath as it reports the condition; the record is the label plus the one bit the breeding and death code switches on. Keeping them apart is what lets two genes cause “dwarfism” with different numbers without either pretending to be the other.

Deafness and MCOA cost nothing that exists

A deaf horse and a horse with malformed eyes are both real and both worth telling the player about, and the mod has no hearing or vision for a horse to lose. So deafness is INFORMATIONAL — reported, no cost — while MCOA is priced the way every sub-lethal disorder here is priced, in hearts. Both are honest; neither pretends to a system the mod does not have.

The two shapes a disorder comes in

Sixteen health loci ship, and they divide into two classes that behave differently enough to be separate base classes.

HYPP is also the first locus that is both kinds of thing at once — a survivable heart reducer on one copy and a lethal on two — which is what made a second base class worth writing rather than bending the first.

Why the reference’s percentages are not the numbers

The disorder table this layer is built from gives each condition a health %, a speed % and a jump %. None of the shipped genes uses them as arithmetic, and that is deliberate: read literally against the 22-health baseline, HYPP’s “30% health” would make an affected but living horse worse than several of this mod’s outright lethals, which is plainly not what the table means.

So every locus is calibrated against the disorders that already ship — a survivable disorder costs 3 to 8 hearts’ worth, a lethal 11 to 18 — and the reference is used for the ordering of the disorders against each other. If the severity model on roadmap §3 ever lands, it does not get to inherit those percentages either.

The two kinds of lethal

Lethal at conception — no foal

The Mendelian draw happens exactly as it always does. Genotype.breedWith knows nothing about viability and was not touched. HorseBreedingHandler.applyBredFoal then reads the genotype it just drew, and returns false; the caller cancels the BabyEntitySpawnEvent. So the odds are the ordinary one-in-four for two carriers, the draw stays a pure function of the two parents and the RNG, and the check is one branch in one place.

Lethal at birth — born, then lost

The foal is born: it gets a name, a record and a place in the family tree, and then dies over about four seconds. LethalFoalHandler does it, and it stores nothing — being lethal is a property of the genotype, so it re-reads it each second. A foal that logs out mid-death still dies on the way back in.

• It has to out-damage the healing. Gated healing regenerates a hurt horse by 1 (or 2 in a herd) every 30 ticks. The damage is a fraction of the foal’s own max health (28%, floor 2) applied once a second, so it beats that comfortably at any health value and a player cannot save a foal by standing it next to a hay bale.
• Foals only. An adult is never killed by this. The only ways to get an adult with a lethal genotype are the custom spawn egg and a hand-written /summon, and both are debug tools for looking at a coat — and lethal white is exactly the coat people want to look at.
• Not in the horse dimension. Its pens are there to be looked at, not survived — and lethal white is exactly the coat people go there to look at.
• The damage source is horsegenetics:genetic_defect, a real datapack damage type, so the death message reads as a genetic defect rather than an unexplained death.

The server settings

ServerConfig, and server-side for the same reason both times: whether a foal dies has to be one answer for everyone, and so does how big a horse is, because size moves the hitbox.

Mechanically, OFF is HorseTraits.resolve(genotype, /*healthGenetics=*/false), which skips every gene marked HealthContribution. The performance and size loci are not health genetics and keep working in all three modes. A gene may paint a coat and be a health contribution — overo lethal white is a white pattern and a foal lethal at once — and only the trait half is ever gated; the coat never is.

body.size — may the size loci resize the horse?

A boolean, true by default. The size loci resolve a body scale and HorseRecords.applyTraitsToEntity writes it to Attributes.SCALE; setting this false writes a flat 1.0 there instead. That is the whole mechanism — one expression, in the one place listed in the table below.

Nothing else is gated. The size genes are registered, drawn from the same founder tables and inherited identically; Traits.scale() still resolves to what the alleles say, so the info screen, the inspect paper and the breeding debug line all keep reporting the real number. Only the entity is held at 1.0. The one other route to SCALE — an effects attribute verb naming scale — answers to the same setting, and GeneAbilityHandler.clearAttributes takes a standing modifier back off rather than leaving it frozen on the horse.

Like health.mode, a change reaches horses already in the world when they next load: each horse re-resolves its body once per level load, from the entity tick.

Reaching the game

HorseRecords.applyTraitsToEntity writes four attributes, and is called on every horse join as well as at birth. Vanilla has just randomised this horse’s speed, health and jump; this is where that gets overwritten with what its alleles actually say.

What this is not

• No environmental noise. The roadmap left room for the random roll to survive as jitter on top of the genetic value. It did not: two horses with the same genotype are the same horse, full stop. Epigenetic variation (which would be inherited with the allele and still deterministic) is the obvious place to reopen this if the numbers ever feel too tidy.
• No per-part scaling. Friesian dwarfism should shorten the limbs and leave the head; SCALE is one number for the whole entity. See the roadmap.
• No naked-foal coat. ST14’s hairless foal is reported, not drawn — phase 1 can only remove pigment, and a de-pigmented mane is a white mane.
• No gait. DMRT3 needs animation work and is still on the backlog.
• No CSNB. It rides on LP/LP, and the leopard complex is not built.
• No group traits. TraitRule — two genes that only together trigger an outcome — is still the roadmap.