Swing Log

In short

Every pitch you see (swing, whiff or take) is appended as one line to swings.csv. It is for tuning the batting numbers (Batting/HitTables) from real play; testers can send the file in. It is local only. Nothing is uploaded. Co-op pitches you only watch are not logged.

How it works

1. GameRoot adds a SwingLog component at boot.
2. It listens to GameEvents.PlayEnded (one per pitch, after the result is known). See Game Events.
3. It skips the line when the game isn’t ready, the report has no swing, or the at-bat is spectating.
4. It appends the line to Application.persistentDataPath/swings.csv. A new file gets the header first.
5. A write error logs one warning (“Swing log: couldn’t write …”) and never stops the game.

Where the file is. Application.persistentDataPath with company DefaultCompany and product RoguelikeHomeRunDerby (ProjectSettings). On Windows that is normally %USERPROFILE%\AppData\LocalLow\DefaultCompany\RoguelikeHomeRunDerby\swings.csv. The Dev menu’s PROGRESS page shows “SWING LOG (n pitches this session)”, the full path, and an OPEN THE LOG’S FOLDER button. See Dev Menu and Shortcuts.

Columns

Column	Meaning
time	Local time, yyyy-MM-dd HH:mm:ss
mode	cage, coop, daily or run
park	Ballpark id
difficulty	The run’s difficulty (empty in the cage)
inning	Inning number
batter	Batter id (e.g. slugger = Baked Bean)
pitch, pitch_mph	Pitch type id and shown speed
in_zone	1 if the pitch was in the strike zone
special_ball	The map’s ball effect (PitchData.effect; the boss slot is not logged)
outcome	Take, Whiff or Contact
timing_ms	Contact: from the bat face angle, spray / 45 x 60 ms (- = early). Whiff: real ms between the barrel crossing the aim point and the pitch arriving. Empty on a take
contact_offset_cm	Where on the bat, from the sweet spot (+ = toward the tip)
zone, grade, green	Sour / Nice / Perfect, WEAK…PERFECT, 1 / 0
aim_x, aim_y	Held direction at contact (-1 left / +1 right; +1 W / -1 S)
spray_deg, launch_deg, exit_mph, curve	The hit (curve in m/s^2, + = toward right field)
result	home_run, foul, out, whiff, called_strike or ball
distance_ft	Carry distance (contact only)

Contact-only columns are empty for takes and whiffs. Commas inside values become spaces. Numbers use the invariant culture (a dot for decimals).

How to read it

Open it in a spreadsheet. Useful cuts:

• Grade spread: count grade per player. Many WEAK means the aim helper isn’t being read well.
• Aim error: contact_offset_cm against zone. A lean to + means players hit off the tip; - means jammed.
• Timing error: timing_ms for whiffs (real time) and contacts (direction-based) by pitch and special_ball.
• Held aim use: how often aim_y is 1 (W) and its home run rate per park.
• Home run rate: result = home_run over contacts, compare with the balance-sim figures in HitTables.

Numbers

What	Value	Where to tune
File name	swings.csv	SwingLog.FileName
Contact timing scale	45 degrees of spray = 60 ms	SwingResolver.FromContact (timingOffset)

In the code

File	What it does
Assets/_Project/Scripts/Batting/SwingLog.cs	OnPlayEnded, Line, FilePath, LoggedThisSession
Assets/_Project/Scripts/Batting/SwingResult.cs	contactOffset (added for the log), timingOffset, Grade
Assets/_Project/Scripts/Core/GameRoot.cs	Adds the component
Assets/_Project/Scripts/UI/DevMenu.cs	PROGRESS page: count and folder button

Gotchas

• The file only grows. There is no rotation or size cap; delete it by hand to start over.
• timing_ms means two different things: a real time for whiffs, a direction converted to ms for contacts. Do not mix them in one average.
• Forced Dev menu hits (insta-home-run bat, TEST HITS) are logged too, as normal lines.
• ball / called_strike come from in_zone; a foul is foul whatever the count.
• The under value (ball above or below the bat’s axis) is not logged.

Related

• Batting Explained: what the columns measure
• Batting Feedback: what the player was shown for the same swing
• Save System: save.json and run.json live in the same folder
• Editor Tools and Tests: BattingModelTest