Special Balls

In short

A pitch has two special-ball slots: the park’s ball (PitchData.effect) and the pitcher’s own ball (bossEffect). Each is rolled on its own seeded stream and they stack, so special balls never change which pitches you get. All flight changes live in PitchData, or the speed in PitcherAI. Everything that reads the ball sees the same thing. For the batter, a special ball mostly changes when and where to swing; only $$$ changes the reward. Harder difficulties multiply every chance.

How it works

The roll

1. PitcherAI.CreatePitch picks the pitch as normal (see Pitching), leaning on the pitch types the special balls ride on.
2. Roll walks a BallModifier list. The first modifier that applies to this pitch type and wins its roll gives the effect: ballRng.Value < chance x ballChanceScale. A modifier with an alternate gives that instead half the time (The Gale: Headwind or Tailwind).
3. The pitcher’s list (PitcherDefinition.balls) rolls first, then the park’s (BallparkDefinition.balls). Both use ballRng, a separate SeededRandom derived from the round seed with stream 0x0BA11. See Daily Seed and Leaderboard.
4. ballChanceScale comes from the run’s difficulty.

The effect that sets the ball’s colour, glow, sound and pill is Primary: the pitcher’s if any, else the park’s.

The effects

Effect	Label	What it does to the batter’s job
Money	$$$	Normal flight. A home run off it pays +3 bonus coins (”$BALL!+3COINS",orthe"$ +3 COINS” chip on the counter).
SuperFast	Super Fast	Thrown at x1.15 speed: less time to react. Same plate location.
AntiGravity	Anti-Gravity	The drop turns into a rise (a curveball curves up), and the loop sags first. Still crosses where aimed.
Ghost	Ghost	Fades to 12% opacity mid-flight and back in before the plate. The trail stops while it is fainter than 50%. Its shadow never fades: the tell.
Sticky	Sticky	Quick out of the hand, then drags at 45% pace through the last 40% of the flight. Arrives on time.
Wiffle	Wiffle	Drifts up to 0.6 m sideways, then swerves hard back to cross where aimed. The side looks random per pitch.
Headwind	Headwind	Normal pace until 70% of the flight, then 0.45x to the plate. Arrives on time.
Tailwind	Tailwind	Normal pace until 70%, then 1.9x. Arrives on time.

Sticky, Headwind and Tailwind use LateSpeedProgress(t, at, lateSpeed): pace 1 / (at + (1 - at) x lateSpeed) before at, then lateSpeed times that, so the ball reaches the plate exactly on schedule. Because the arrival time is unchanged, the swing timing that would be right for a normal pitch is still right; what changes is how the ball looks on the way in.

Telling one is coming

• BallEffectLook: the ball takes the effect’s colour (70% toward it), glows with a point light already in the pitcher’s hand during the windup, and leaves a 1.8x wider trail. A ghost fades the model (an alpha copy), dims the glow and stops the trail. Fully solid again once the pitch is decided.
• GameAudio plays a special-ball cue at the windup, pitched per effect (Wiffle highest, Sticky lowest).
• The HUD pitch chip names both slots, e.g. “WIFFLE GHOST FASTBALL 88 MPH”, in the primary effect’s chip colour. The play card does too.
• The ballpark card describes each with BallModifier.Describe(), e.g. “Anti-Gravity balls: Curveballs, Sinkers (1 in 3)” or “Headwind / Tailwind balls: any pitch (1 in 8)“. A boss’s own balls show under the matchup as “HIS OWN: …“.

Who throws what

From DefaultContent. Parks: Sandlot Field $$$ on any pitch (1 in 6); Windy City Yard Super Fast fastballs and sliders (1 in 3); Moon Stadium Anti-Gravity curveballs, sinkers and changeups (1 in 3); Midnight Yard Ghost on any pitch (1 in 12); Farmyard Sticky changeups, curveballs and knuckleballs (1 in 3). Bosses: Backyard Benny Wiffle (1 in 4); The Gale Headwind / Tailwind (1 in 8). The Phantom’s decoys are a pitcher trick, not an effect. See Pitchers and Bosses.

Numbers

What	Value	Where to tune
Default chance	0.33	BallModifier.chance
Super Fast speed	x1.15	BallEffects.SuperFastSpeed
$$$ home run coins	3	BallEffects.MoneyBallCoins
Ghost fade (share of flight)	out 0.2 to 0.38, faintest 0.12 opacity until 0.62, back in by 0.82	GhostFadeOut, GhostFaintFrom, GhostFaintest, GhostFaintTo, GhostFadeIn
Sticky slows at / to	0.6 of flight / 0.45 pace	StickyAt, StickyDrag
Wiffle	drifts until 0.65 of the flight, swerve 0.6 m	WiffleAt, WiffleSwerve
Headwind / Tailwind	from 0.7 of the flight, 0.45x / 1.9x	GustAt, HeadwindSpeed, TailwindSpeed
Alternate effect	50% when set	BallModifier.alternate, PitcherAI.Roll
Chance multiplier by difficulty	x1 Normal, x1.5 Medium, x2 Hard	Difficulties.BallChance
Ball tint strength	0.7	BallEffectLook.TintStrength
Special trail width	x1.8	BallEffectLook.TrailWidth
Trail stops below opacity	0.5	BallEffectLook.TrailBelow
Random stream id	0x0BA11	PitcherAI.BallStream

In the code

File	What it does
Assets/_Project/Scripts/Data/BallEffect.cs	BallEffect enum, BallModifier (AppliesTo, Describe, alternate), BallEffects (tuning, Label, Tint, StickyProgress, LateSpeedProgress)
Assets/_Project/Scripts/Pitching/PitchData.cs	Has, Primary, PositionAt (pace, Wiffle), Break (Anti-Gravity), OpacityAt (Ghost)
Assets/_Project/Scripts/Pitching/PitcherAI.cs	Roll for both slots, Super Fast speed
Assets/_Project/Scripts/Batting/BallEffectLook.cs	Colour, glow, wide trail, ghost fade (also on decoys)
Assets/_Project/Scripts/Batting/AtBatController.cs	DressBall, $$$ coins in ResolvePlay
Assets/_Project/Editor/BallEffectTest.cs	Self-test: every flight, stacking slots, Wiffle, gusts arrive on time, decoys, arcs, favoured pitches, descriptions

Run the test from Tools > Home Run Derby > Run Ball Effect Test. See Editor Tools and Tests.

Gotchas

• Up to two effects per pitch (one per slot). Within one slot, list order decides which rolls first. The same effect in both slots reads once on the chip.
• An empty pitchIds list means every pitch type.
• The batting cage uses ballChanceScale 1 (the RoundContext default), so it throws the park’s balls at Normal odds.
• Dev menu can force a special ball on every pitch (PitcherAI.DevForcedEffect), in the park slot only. See Dev Menu and Shortcuts.
• The Swing Log records only the park slot (effect) in special_ball.
• The README credits the windup cue to BallEffectLook; the sound is actually played by Audio/GameAudio.
• Not built yet: Heavy, Ice and Fire balls (README roadmap; they need their maps). Farmer Fitz and The Alien have no own ball yet (code comments: “still to be decided”).

Related

• Pitching: the pitch the effect rides on
• Pitchers and Bosses: bosses’ own balls and decoys
• Ballparks: each park’s special ball
• Batting Feedback: the pitch chip and cue before the swing
• Difficulty: chance multiplier
• Add a Special Ball: how to add a new effect
• Seeds and Determinism: why the separate stream matters