Update MAPI for Hollow Knight 1.5.12459 (Unity 6)#170
Closed
KunalGehlot wants to merge 1 commit intohk-modding:masterfrom
Closed
Update MAPI for Hollow Knight 1.5.12459 (Unity 6)#170KunalGehlot wants to merge 1 commit intohk-modding:masterfrom
KunalGehlot wants to merge 1 commit intohk-modding:masterfrom
Conversation
Hollow Knight received a major update on Feb 5, 2026 (build 12459) which upgraded the engine to Unity 6 (6000.0.61f1) and introduced significant changes to controller input handling, localization, and scene management. This commit updates the Modding API to compile against and work correctly with the new game binaries. Build system changes (Assembly-CSharp.csproj): - Use FrameworkPathOverride to resolve assemblies from Vanilla/ directory instead of individual HintPath references (required for Unity 6 which ships additional TeamCherry.* and System.* assemblies) - Add System.Memory NuGet package (Unity 6 uses ReadOnlySpan<byte> in Texture2D.LoadImage) - Remove Newtonsoft.Json from dependencies (now shipped with the game) - Remove mscorlib override (no longer needed with Unity 6 runtime) Localization system rewrite: - Delete Patches/Language.cs: The Language class moved from the global namespace to TeamCherry.Localization in HK 1.5. The old MonoMod patch targeting "global::Language.Language" no longer resolves. - Add Language/Language.cs: A backwards-compatible shim in the Language.Language namespace that delegates to TeamCherry.Localization via reflection, with MonoModLinkFrom to redirect existing mod references. This allows mods using Language.Language.Get() to continue working without recompilation. - Update ModHooks.cs LanguageGet to call Language.Language.GetInternal instead of the removed Patches.Language.GetInternal. Mod loading initialization (StartManager.cs): - Move mod loading bootstrap from OnScreenDebugInfo.Awake to StartManager.Awake. The OnScreenDebugInfo component was removed in HK 1.5, so it can no longer serve as the mod loading entry point. - Delete Patches/OnScreenDebugInfo.cs (component no longer exists in game). - Rewrite StartManager.Start to match the new HK 1.5 startup sequence: language verification, PlayerPrefs loading, and scene load state management. - Add deferred Menu_Title scene loading: when mod preloading is active, wait for mods to finish loading before transitioning to Menu_Title instead of using the allowSceneActivation pattern. HeroController patches updated for HK 1.5 game logic: - rb2d.velocity → rb2d.linearVelocity (Unity 6 Rigidbody2D API change) - wallSlideVibrationPlayer.Stop() → vibrationCtrl.StopWallSlide() (HK 1.5 replaced individual vibration players with HeroVibrationController) - Attack(): Add grubberfly beam (charm_35) support for wall slashes, change health check from == to >= for grubberfly beam activation on normal/up/down attacks (matches upstream game logic) - SoulGain(): String literals to nameof() for PlayerData fields - LookForQueueInput(): Remove duplicate CanDash() call - TakeDamage(): Rename flag → carefreeShouldStopDamage for clarity, string literals to nameof(), add explicit returns after death/hazard coroutine starts to match upstream flow control, fix ternary null check on damage angle - OrigDashVector(): Simplify ternary for bump velocity readability InputHandler.OnGUI rewrite: - Replace direct Cursor.visible/Cursor.lockState manipulation with calls to the game's SetCursorVisible() method. This preserves the OnCursorVisibilityChange event and proper cursor lock management through SetCursorEnabled(), fixing controller detection and connection mode switching that was broken by the old approach. GameManager patches: - Import TeamCherry.SharedUtils.Encryption (class moved in HK 1.5) - Add SetPausedState() MonoModIgnore declaration - Rewrite PauseToggleDynamicMenu to match HK 1.5 pause/unpause flow (SetPausedState calls, reordered input prevention, reduced wait times) - SceneManager.UnloadSceneAsync → SceneManager.UnloadScene (API change) SceneManager patches: - Replace DrawBlackBorders() full replacement with OnCameraAspectChanged() hook. HK 1.5 refactored border drawing into the camera aspect change handler with persistent border transforms (borderLeft/Right/Up/Down) instead of instantiating new GameObjects each time. - The ModHooks.OnDrawBlackBorders hook is preserved by collecting the border transforms after orig_OnCameraAspectChanged runs. Other patch updates: - MenuSetting.cs: Add new HK 1.5 settings enum values (SwitchFrameCap, Dithering, Noise, ControllerRumble, HudVisibility, CameraShake, NativeInput, XInput, MFi) - MenuButtonList.cs: Null-conditional on menuButtonLists to prevent NullReferenceException during early UIManager initialization - UIManager.cs: Add ADVANCED_GAMEPAD_MENU and ADVANCED_VIDEO_MENU to MainMenuState enum - TakeDamage.cs: Fix Multiplier ternary to match HK 1.5 operand order - PlayMakerUnity2DProxy.cs: Add explicit this. qualifier - ModHooks.cs: Add bounds checking on version string split to handle version formats with fewer than 4 segments Version: hollowknight.version updated to 1.5.12459 Tested on macOS (Apple M2 Pro) with Unity 6000.0.61f1: - Game launches and reaches title screen - Mod menu appears in Options with working mod list - CompassAlwaysOn and GatheringSwarmAlwaysOn load and function correctly - Controller support works (USB/Bluetooth, vibration, mode switching) - Scene transitions, pause menu, and settings menus all functional - No errors in Player.log or ModLog.txt Builds on work started in PR hk-modding#164 by SFGrenade. Closes hk-modding#169.
Author
|
Feel free to ping me at @zackcodesai on discord server. |
Member
|
practically the same as #164 |
Author
|
I would call that an overstatement, but you're the maintainer... |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Updates the Modding API to work with Hollow Knight build 1.5.12459 (released Feb 5, 2026), which upgraded the game engine to Unity 6 (6000.0.61f1) and made significant changes to controller input, localization, and scene management.
This PR builds on the work started in #164 by @SFGrenade, extending it to the latest public release (12459 vs 12331) and fixing additional issues discovered during testing.
Closes #169.
Changes
Build System (
Assembly-CSharp.csproj)FrameworkPathOverridepointing toVanilla/to resolve all assemblies, replacing individualHintPathreferences. Unity 6 ships additionalTeamCherry.*andSystem.*assemblies that need to be referenced.ReadOnlySpan<byte>inTexture2D.LoadImage.Localization System Rewrite
Patches/Language.cs: TheLanguageclass moved from the global namespace toTeamCherry.Localizationin HK 1.5, breaking the old MonoMod patch target.Language/Language.cs: A backwards-compatible shim that delegates toTeamCherry.Localization.Languagevia reflection, usingMonoModLinkFromto redirect existing mod references. Mods usingLanguage.Language.Get()continue working without recompilation.Mod Loading Bootstrap (
StartManager.cs)OnScreenDebugInfotoStartManager: TheOnScreenDebugInfocomponent was removed in HK 1.5.Start()to match HK 1.5 startup: Language verification,PlayerPrefsloading, scene load state management.Menu_Titleloading: When mod preloading is active, waits for mods to finish before transitioning toMenu_Title.HeroController Patches
rb2d.velocity→rb2d.linearVelocity(Unity 6 API change)wallSlideVibrationPlayer.Stop()→vibrationCtrl.StopWallSlide()(HK 1.5 replaced individual vibration players withHeroVibrationController)== maxHealth→>= maxHealthfor beam activationnameof()forPlayerDatafieldsCanDash()callflag→carefreeShouldStopDamage, string literals →nameof(), added explicitreturnstatements after death/hazard coroutine starts (matching upstream flow)InputHandler.OnGUI
Cursor.visible/Cursor.lockStatemanipulation with calls to the game'sSetCursorVisible()method, preserving theOnCursorVisibilityChangeevent and proper cursor lock management throughSetCursorEnabled(). This fixes controller detection and connection mode switching.GameManager Patches
TeamCherry.SharedUtils.Encryption(moved namespace)PauseToggleDynamicMenufor HK 1.5 pause flow (SetPausedStatecalls, reordered input prevention)SceneManager.UnloadSceneAsync→SceneManager.UnloadSceneSceneManager Patches
DrawBlackBorders()full replacement withOnCameraAspectChanged()hook (HK 1.5 refactored border drawing into the camera aspect handler with persistent transforms)ModHooks.OnDrawBlackBordershook preserved by collecting border transforms afterorig_OnCameraAspectChangedrunsOther Patches
SwitchFrameCap,Dithering,Noise,ControllerRumble,HudVisibility,CameraShake,NativeInput,XInput,MFi)menuButtonListsto preventNullReferenceExceptionduring earlyUIManagerinitializationADVANCED_GAMEPAD_MENUandADVANCED_VIDEO_MENUtoMainMenuStateenumMultiplierternary operand orderthis.qualifierTest Plan
Tested on macOS (Apple M2 Pro) with Unity 6000.0.61f1:
dotnet buildsucceeds with 0 errors