HollowKnight.GodhomeWinLossTracker

A mod for the game Hollow Knight.

The mod's goal is to improve Godhome boss fight training experience by stats tracking and data analysis.

How to reach out?

If you have any questions, suggestions or bugs, please feel free to reach out.

Either create an issue here in github.com, or join discord server: https://discord.gg/vqKTF26VGX

Features and screenshots

All in Godhome (both Hall of Gods and pantheons):

• Stats tracking happens automatically during boss fights.

  • Win/loss stats

  • Hit stats

  • Phase stats

• Localized stats display are available in "Challenge" menu.

  

• Data analysis can be done by exporting stats into google spreadsheets.

  • Win/loss analyzer

    

    

  • Hit analyzer

  • Phase analyzer (for AbsRad)

Other features:

• In-game notifications

• Mod menu

• Auto-screenshot on hits

---

Stats tracking

The mod automatically tracks your boss fights' win/loss and hit stats.

Win/loss records (one line of record per boss fight):

• Timestamp (of the record)
• Sequence name (HoG, P1, P2, P3, P4, P5)
• Boss name
• Scene name (some boss has different arenas for Attuned vs. Ascneded+)
• Wins (0 or 1)
• Losses (0 or 1)
• Heals
• Heal amount
• Hits (the number of hits your hero took)
• Hit amount (the amount of masks your hero lost)
• Boss HP (0~1, the amount of remaining HP the boss has at the end of the fight)
• Fight length (in milliseconds, from entering to leaving boss scene)
• Boss phase (0..6, the maximum boss phase achieved in the fight, 0 being no phase info)
• See example records

Hit records (one line of record per hit the hero took):

• Timestamp
• Sequence name
• Boss name
• Scene name
• Hero status (standing/walking, airborne, dashing, etc)
• Hero position in scene
• Hero health before took hit (in number of masks)
• Damage amount (of the hit)
• Damage source (e.g. for AbsRad, this can be "Orb", "Face Swords", etc)
• Damage source detail (the actual name of the damage source used in game code)
• Boss HP (0~1, at the time of the hit)
• Boss state (the action the boss was performing at the time of the hit; can usually tell what attack the boss was using)
• Boss position in scene
• Time into fight (in milliseconds, from entering boss scene to the time of the hit)
• See example records
• Boss phase (0..6, the boss phase in which the hero took the hit)

Phase records (one line of record per phase the boss fight enters)

• Timestamp
• Sequence name
• Boss name
• Scene name
• Phase (1..6)
• Heals
• Heal amount
• Hits
• Hit amount
• Time spent in phase (in milliseconds, from entering the phase to leaving the phase)

Localized stats display

In Hall of Gods, different boss variants (dream version or different forms) are tracked separately. For the same boss variant/form, if it has different arenas for Attuned and Ascended/Radiant, they are tracked separately, too. Stats are displayed in the "Challenge" menu.

In pantheons, the number of runs, your PB (personal best, i.e. how far you go in a pantheon) and the bosses that gave you the most difficulty are tracked and displayed in the "Challenge" menu.

Data analysis

Step 1: Export stats

In the mod's menu (see below), either choose Auto export stats or Export stats now.

Step 2: Find the export

All stats can be found in the GodhomeWinLossTracker subfolder in the game's save folder.

• On a PC: "%AppData%/../LocalLow/Team Cherry/Hollow Knight/GodhomeWinLossTracker"

The exported files are:

• Win/loss stats: Export.WinLoss.Save1.txt ~ Export.WinLoss.Save4.txt
• Hit stats: Export.Hit.Save1.txt ~ Export.Hit.Save4.txt

Step 3: Clone data analysis sheet

Example data analysis sheets are available:

• Win/loss analyzer
• Hit analyzer

Step 4: Import exported files into data analysis sheets

In google spreadsheet, you can do "(switch to first tab in sheet -> File -> Import -> Upload -> (choose/drag your exported file) -> Replacec current sheet -> Import data".

Step 5: View pre-configured analysis

In google spreadsheet, switch to any tab that has a "👁" symbol in their name to see pre-configured analysis.

In-game notifications

Whenever the mod detects a boss fight's win/loss event, it shows a small notification at the bottom left corner of the game to indicate that the result has been recorded.

You can turn this notification on/off in the mod's menu. See more details below.

Mod menu

You can find the mod's menu by pausing the game -> "Options" -> "Mods" -> "GodhomeWinLossTracker".

• Show stats in challenge menus: Display stats (mentioned above) in "Challenge" menus in Hall of Gods and pantheons. "On" by default. Turn this off will return to the normal "Challenge" menus.

• Notify win/loss: Display an in-game notification whenever the mod detects the result of boss fights. "On" by default. This helps you to confirm that the detections are working properly. Turn this off to prevent the notifications from showing up.

• Notify exports: Display an in-game notification whenever stats have been exported. "Off" by default. Turn this on will you to confirm the filename and the successfulness of expoerts.

• Export stats now: While playing (i.e. when a game save is loaded), this will write stats into Export.WinLoss.SaveX.txt and Export.Hit.SaveX.txt in TSV format. They each contain win/loss and hit records. The exported files can then be imported into spreadsheet apps for data analysis (see examples above).

• Auto export stats: This makes the mod export every time the game is being saved. This helps if you plan to constantly pull stats into data analysis.

Auto-screenshot on hits

The mod can automatically take screenshots when the hero takes a hit. This feature can be turned on/off in the mod menu. The filters, however, need to be manually configured in the mod's global settings file.

Where to find the mod's global settings file: The file can be found in the game's save folder, named "GodhomeWinLossTracker.GlobalSettings.json":

• On a PC: "%AppData%/../LocalLow/Team Cherry/Hollow Knight/GodhomeWinLossTracker.GlobalSettings.json"

How to config: Learning from examples is the fastest: screenshot all hits, screenshot AbsRad's beam hits, disable screenshots.

If you want to customize your own config:

• "AutoScreenCapture" should be a boolean value (true or false).
• "AutoScreenCaptureConfigs" should be an array, containing zero or more config objects, which have the following fields.
  • All config objects work as disjunction filters (OR). When hero is hit, the mod will take one screenshot if the situation matches any of the config objects.
  • All fields within one config object work as conjunction filters (AND). For the situation to match a config object, the situation need to satisfy all of the specified fields.
  • Fields:
    • Only "Trigger" is required. All others are optional and be specified to scope down when to take screenshots.
    • "Trigger" should always be 0, which means "hits". This field exists for future extensibility.
    • "SequenceName" should be one of "HoG", "P1" to "P5".
    • "SceneName" should be one of the boss scene names in Godhome (the ones starting with "GG_").
    • "DamageSource" should be one of the damage sources that show up in your hit records. If you don't know what this is, don't add this field or leave it to be null.
    • "BossPhase" is only useful for AbsRad. Value can be from 1 to 6. 0 means "all boss phases".