NullReferenceFix

A small collection of independent Harmony patches, each fixing one specific recurring bug — mostly NullReferenceExceptions that repeat every single frame for the rest of your play session once triggered (spamming the log and wasting CPU), plus the occasional leaked-resource bug that quietly accumulates until it causes lag or a freeze. Every patch targets a different root cause and can trigger (or not) completely independently of the others.

한국어 설명 보기 | English Description

🇰🇷 한국어 (Korean)

개요

NullReferenceFix는 서로 독립적인 여러 개의 작은 Harmony 패치를 모아둔 모드입니다. 대부분은 한 번 터지면 세션이 끝날 때까지 매 프레임 반복해서 터지는 NullReferenceException 버그를 담당하고, 일부는 조용히 누적되다가 렉이나 프리징을 유발하는 리소스 누수를 담당합니다. 패치마다 원인이 다르고, 서로 완전히 독립적으로 발동합니다 — 즉 설치된 다른 모드 구성에 따라 일부 패치는 평생 한 번도 발동하지 않을 수도 있습니다.

현재 5가지 버그를 고칩니다:

1. 바닐라 발헤임 자체 버그 (ZNetScene.RemoveObjects)
2. AzuCraftyBoxes 모드 버그 (제작함 근처 재료 확인)
3. EnemyHud를 건드리는 모드 간 충돌 (EpicMMOSystem 등)
4. 바닐라 발헤임 ZSFX 사운드 오브젝트 누수 (자체 소멸 로직 없음 — 반복 재생 시 렉/프리징 유발)
5. 바닐라 발헤임 TMP 폰트의 비라틴 스크립트(한글/일본어/중국어/아랍어 등) 글리프 누락 경고 (닉네임/길드명 등이 공백으로 표시됨)

회피(무시)가 아니라 청소입니다. 예외를 잡는 패치들은 예외 자체가 처음 한 번은 그대로 발생하고, 이 모드가 그걸 잡아낸 뒤 원인이 된 깨진 상태(딕셔너리/세트의 죽은 항목)를 실제로 지웁니다. 그래서 같은 entry로는 다시 터지지 않습니다 — 단순히 로그만 숨기고 깨진 상태를 계속 방치하는 방식이 아닙니다. ZSFX 패치처럼 예외가 아닌 리소스 누수를 다루는 경우도 근본 원인(자체 소멸 로직 부재)을 직접 채워 넣는 방식이지, 증상만 가리는 임시방편이 아닙니다. 각 패치는 오직 대상 메서드(또는 없으면 아무 일도 하지 않는 선택적 대상)만 건드리며, 다른 모드의 코드를 수정하지는 않습니다.

🏴󠁧󠁢󠁥󠁮󠁧󠁿 English

Overview

NullReferenceFix is a collection of independent, small Harmony patches. Most fix a specific bug where a NullReferenceException, once triggered, repeats every single frame for the rest of the session; a few fix a leaked-resource bug that quietly accumulates until it causes lag or a freeze. Every patch has a different root cause and triggers (or doesn't) completely independently — depending on your mod list, some patches may never activate at all.

It currently fixes 5 bugs:

1. A vanilla Valheim engine bug (ZNetScene.RemoveObjects)
2. An AzuCraftyBoxes mod bug (nearby-container requirement check)
3. A mod-conflict bug involving EnemyHud (EpicMMOSystem and similar mods)
4. A vanilla Valheim ZSFX sound object leak (no self-destruct logic — causes lag/freezes on repeated playback)
5. Missing non-Latin script glyphs (Korean, Japanese, Chinese, Arabic, etc.) in vanilla Valheim TMP fonts (nicknames/guild names render as blank spaces)

Cleanup, not evasion. For the exception-catching patches, the exception itself still fires once — this mod catches that one occurrence and then actually deletes the broken state (the dead dictionary/set entry) that caused it. The same entry can't throw again. It's not just hiding the log while leaving the broken state in place. The ZSFX patch applies the same philosophy to a resource leak instead of an exception: it fills in the missing self-destruct logic at its actual root cause, rather than papering over the symptom. Each patch only touches its own target method (or, if that target isn't present, does nothing at all) — no other mod's code is modified.

🎮 My Other Mods / 함께 즐기면 더 좋은 모드

🌳 CaptainSkillTree

👹 MonsterModifiers

🎵 CaptainAudio

📝 Credits / 크레딧

• Developer / 개발자: KorCaptain
• Framework / 프레임워크: BepInEx, Harmony

💬 Support / 지원

• Discord: KorCaptainSkillTree_MOD_Server - https://discord.gg/W26PTxYhug
• Ko-fi: https://ko-fi.com/korcaptain
• E-mail: [email protected]
• Issues: Report bugs and suggestions on Discord
• 문제 보고: Discord에서 버그 및 제안사항 보고

📜 License / 라이선스

Developer - KorCaptain

Enjoy a quieter log file! / 조용해진 로그를 즐기세요!

Changelog

한국어 보기 | English Version

English

2026-08-17 (v1.0.16)

• Replaced the polling coroutine (retried every 2s, up to 30 times) from the fix below with an event-driven one: Plugin.Awake() now subscribes once to Application.logMessageReceived, and font registration only runs when TMP actually logs a missing-glyph warning. Since that warning re-fires every time the same text re-renders, reacting to it is self-retrying without a separate timer, and outside of a session where it never happens, this does no background work at all. The handler unsubscribes itself once every target font is registered.

2026-08-17 (v1.0.15)

• Extended the previous Korean-only TMP fallback fix (below) to every non-Latin script Valheim itself ships a font for: Arabic, Armenian, Bengali, Devanagari, Georgian, Hebrew, Japanese, Korean, Malayalam, Simplified Chinese, Thai, plus Noto's emoji set. TMPKoreanFallbackFontRegistrar → TMPLocalizationFallbackFontRegistrar; the single-font lookup became a multi-font one that registers every bundled Noto font it can find into TMP's global fallback list, so any of those scripts render instead of showing blank spaces or missing-glyph boxes — not just Korean.

2026-08-17 (v1.0.14)

• Found & cleaned up: vanilla/TMP-bundled fonts (Valheim-Prstartk, LiberationSans SDF) lack Hangul glyphs, so player-authored or mod-added Korean text rendered through TMP_Text objects using them — most visibly EpicMMOSystem's nameplate/guild-name/info-panel text — showed up as blank spaces or missing-glyph boxes with repeating "character ... was not found in the [...] font asset..." warnings. Registers Valheim's own bundled NotoSansKR-Regular SDF font (already shipped for the game's Korean localization) into TMP's global fallback list once per session, via a short polling coroutine started from Plugin.Awake() rather than a Harmony hook on LoadFontAsset (a live session logged 500+ of these warnings with that hook never firing at all, proving it isn't actually invoked during normal play) — no new font bundled, fixes Korean rendering for any mod's TMP text regardless of which font it's assigned.

2026-08-16 (v1.0.9)

• Found & cleaned up: a vanilla engine gap in ZSFX (Valheim's sound-playback component) with no self-destruct logic at all. Once a ZSFX-carrying vanilla SFX prefab finishes playing, nothing ever destroys it if it isn't tracked by a ZNetView — a pattern many mods hit when they instantiate a vanilla sound effect locally (e.g. ZNetScene.GetPrefab + Instantiate to play a one-off sound), most visibly with sound-heavy Mage-class skill/weapon mods repeatedly casting effects. Worse, MonoUpdaters.Update() iterates the entire static ZSFX.Instances list every frame, so each leaked instance adds a permanent per-frame cost — explaining a progressive slowdown that eventually freezes the game during Resources.UnloadUnusedAssets() (temporarily "fixed" by relogging, which force-reloads the scene). Not caused by any specific mod; it's an engine-level defect. Added a Postfix patch on ZSFX.CustomUpdate that destroys an instance only once it has finished playing, isn't looping, is past its initial play-delay window, and has no ZNetView — never touching anything that could be network-synced.

1.0.7 - 1.0.8

• Found & cleaned up: a recurring TextMeshPro warning ("The LiberationSans SDF Font Asset was not found. There is no Font Asset assigned to <name>."), most visibly on EpicMMOSystem's mmoname/guildname player nameplate text objects. Some mods create TMP text objects without ever assigning a font asset; TMP's own fallback tries to load a "LiberationSans SDF" resource that Valheim's build doesn't ship, fails, and logs the warning every time that text object re-initializes (e.g. each OnEnable). Rather than special-casing those two object names, this patches TextMeshProUGUI.LoadFontAsset/TextMeshPro.LoadFontAsset directly (the actual root cause, shared by any unfonted TMP text in the game) with a Prefix that assigns an already-loaded, valid TMP font asset before the vanilla check runs, so the normal code path executes instead of the warn-and-bail one.

1.0.6

• Found & cleaned up: a conflict between EpicMMOSystem (WackyMole.EpicMMOSystem) and factions/marketplace-style mods. EpicMMOSystem's DataMonsters.MonsterColorTexts patch (player PvP name coloring) was throwing a repeating NullReferenceException every frame when a separate factions/marketplace-style mod force-called EnemyHud.ShowHud directly from its own EnemyHud.LateUpdate patch, targeting a Character whose HUD entry should already have been torn down (logged out / despawned). Instead of targeting EpicMMOSystem or any specific mod, this patches vanilla EnemyHud.ShowHud itself with a Finalizer so it catches the exception no matter which installed mod's postfix throws it, and directly cleans up the stale m_huds entry (and its leftover HUD GameObject) so the next call rebuilds a clean one.

1.0.4 - 1.0.5

• Found & cleaned up: a bug in AzuCraftyBoxes (Azumatt.AzuCraftyBoxes). AzuCraftyBoxes keeps a static HashSet<Container> of every crafting container it has ever seen nearby, but some destroy paths (e.g. a zone/chunk unload) destroy the GameObject without going through Container.OnDestroyed, leaving a Unity-destroyed (fake-null) Container sitting in the set. The recipe check that runs every frame while the crafting menu is open then dereferenced that dead entry, throwing NullReferenceException repeatedly. Added a patch (only active when AzuCraftyBoxes is installed) that catches the exception and directly removes the destroyed Container entries from the set.

1.0.3 (Hotfix)

• Fixed: the plugin DLL was accidentally missing from the previous releases (1.0.1, 1.0.2), so the mod did not work at all. This release restores the DLL.

1.0.1

• Found & cleaned up: a vanilla Valheim engine bug (initial release). If a ZNetView's GameObject is destroyed by something else in the same frame that vanilla ZNetScene.RemoveObjects tries to clean it up, the method throws a NullReferenceException before it can remove the stale entry from its internal tracking dictionary (m_instances) — so the same exception then repeats every frame for the rest of the session. Not caused by any specific mod; it's an engine-level defect. Added a Finalizer patch on ZNetScene.RemoveObjects that catches the exception and directly removes the already-destroyed (stale) ZNetView entry from m_instances.

🇰🇷 한국어 (Korean)

2026-08-17 (v1.0.16)

• 아래 수정에 쓰였던 폴링 코루틴(2초 간격, 최대 30회 재시도)을 이벤트 반응형으로 교체: Plugin.Awake()가 Application.logMessageReceived를 한 번만 구독해두고, TMP가 실제로 글리프 누락 경고를 로그로 찍을 때만 폰트 등록을 시도합니다. 이 경고는 같은 텍스트가 다시 그려질 때마다 반복해서 찍히므로 별도 타이머 없이 자연스럽게 재시도되고, 경고가 한 번도 안 뜨는 세션에서는 아무 백그라운드 작업도 하지 않습니다. 타겟 폰트를 전부 등록하면 핸들러가 스스로 구독을 해제합니다.

2026-08-17 (v1.0.15)

• 이전에 한국어 전용이었던 TMP 폴백 수정(아래)을, 발헤임이 자체적으로 폰트를 내장한 모든 비라틴 스크립트로 확장: 아랍어·아르메니아어·벵골어·데바나가리(힌디)·조지아어·히브리어·일본어·한국어·말라얄람어·중국어(간체)·태국어 + 이모지. TMPKoreanFallbackFontRegistrar → TMPLocalizationFallbackFontRegistrar로 이름 변경했고, 단일 폰트 탐색이었던 로직을 다중 폰트 탐색으로 바꿔 발헤임에 내장된 Noto 계열 폰트를 찾는 대로 전부 TMP 전역 폴백 목록에 등록하도록 했습니다 — 한글뿐 아니라 해당 스크립트 전부가 공백/네모 대신 정상 표시됩니다.

2026-08-17 (v1.0.14)

• 바닐라·TMP 내장 폰트(Valheim-Prstartk, LiberationSans SDF)에 한글 글리프가 없어, 이런 폰트를 쓰는 TMP_Text 오브젝트(EpicMMOSystem의 네임플레이트/길드명/정보 패널 텍스트에서 가장 두드러짐)를 통해 표시되는 플레이어·모드 텍스트가 공백 또는 네모(□)로 나오고 "character ... was not found in the [...] font asset..." 경고가 반복되던 문제 발견 및 정리. 발헤임이 자체 한국어 로컬라이제이션용으로 이미 내장한 NotoSansKR-Regular SDF 폰트를 세션당 한 번 TMP 전역 폴백 목록에 등록하도록 했는데, 처음엔 LoadFontAsset에 거는 Harmony 훅으로 구현했다가 실제 플레이 세션에서 이 훅이 500회 넘게 경고가 발생하는 동안 단 한 번도 호출되지 않는 것을 로그로 확인 — 정상 플레이 중에는 아예 호출되지 않는 메서드였음이 드러나, Plugin.Awake()에서 시작하는 짧은 폴링 코루틴 방식으로 교체함. 새 폰트 번들링 없이, 어떤 모드의 TMP 텍스트든 할당된 폰트와 무관하게 한글이 정상 표시되도록 정리.

2026-08-16 (v1.0.9)

• ZSFX(발헤임 기본 사운드 재생 컴포넌트)에 자체 소멸 로직이 아예 없는 바닐라 엔진 빈틈 발견 및 정리: ZSFX가 붙은 발헤임 기본 SFX 프리팹은 재생이 끝나도 ZNetView로 추적되지 않는 한 아무도 파괴해주지 않습니다 — 발헤임 기본 사운드를 로컬로 즉석 재생하는(ZNetScene.GetPrefab + Instantiate) 패턴을 쓰는 모드에서 흔히 발생하며, 사운드가 화려한 마법사 계열 스킬/무기 모드를 반복 사용할 때 특히 두드러집니다. 더 나아가 MonoUpdaters.Update()가 매 프레임 static ZSFX.Instances 리스트 전체를 순회하기 때문에, 새어나간 인스턴스 하나하나가 영구적인 프레임당 비용을 추가해 — 플레이 시간이 길어질수록 점점 느려지다 결국 Resources.UnloadUnusedAssets() 시점에 게임이 멈추는 증상으로 이어집니다(리접속으로 씬이 강제 재로드되면 일시적으로 해결됨). 특정 모드가 아닌 엔진 자체의 결함입니다. ZSFX.CustomUpdate에 Postfix 패치를 추가해, 재생이 끝났고·반복재생이 아니고·초기 재생 지연 구간도 지났고·ZNetView가 없는 인스턴스만 파괴하도록 했습니다 — 네트워크 동기화 대상은 절대 건드리지 않습니다.

1.0.7 - 1.0.8

• 반복되는 TextMeshPro 경고("The LiberationSans SDF Font Asset was not found. There is no Font Asset assigned to <이름>.") 발견 및 정리: EpicMMOSystem의 플레이어 네임플레이트 mmoname/guildname 텍스트 오브젝트에서 가장 두드러지게 나타났습니다. 일부 모드가 폰트를 전혀 할당하지 않은 채 TMP 텍스트 오브젝트를 생성하면, TMP의 기본 폴백 로직이 발헤임 빌드에는 없는 "LiberationSans SDF" 리소스를 로드하려다 실패하고, 그 텍스트 오브젝트가 재초기화될 때마다(예: 매 OnEnable) 같은 경고를 반복 출력합니다. 해당 오브젝트 이름을 콕 집어 처리하는 대신, 실제 근본 원인인 TextMeshProUGUI.LoadFontAsset/TextMeshPro.LoadFontAsset(게임 내 폰트 미할당 TMP 텍스트 전체에 공통되는 지점)을 직접 패치했습니다. 바닐라 체크가 실행되기 전에 이미 로드되어 있는 유효한 TMP 폰트 애셋을 미리 할당하는 Prefix를 추가해, 경고 후 중단되는 경로 대신 정상 코드 경로를 타도록 했습니다.

1.0.6

• EpicMMOSystem(WackyMole.EpicMMOSystem) ↔ 팩션/마켓플레이스 계열 모드 충돌 발견 및 정리: EpicMMOSystem의 DataMonsters.MonsterColorTexts(플레이어 PvP 이름 색상 표시) 패치가, 팩션/마켓플레이스 계열의 다른 모드가 EnemyHud.LateUpdate 패치 안에서 EnemyHud.ShowHud를 직접 강제 재호출할 때 이미 정리됐어야 할(로그아웃/디스폰된) 캐릭터의 남은 HUD 항목을 참조하면서 매 프레임 NullReferenceException을 반복 발생시키던 문제를 발견했습니다. EpicMMOSystem이나 특정 모드를 콕 집어 패치하는 대신 발헤임 기본 EnemyHud.ShowHud에 Finalizer를 걸어, 어떤 모드의 postfix에서 터지든 잡아내고 원인이 된 오래된 m_huds 항목(과 남은 HUD GameObject)을 직접 정리해서 다음 프레임에 정상적으로 새로 만들어지도록 청소 처리했습니다.

1.0.4 - 1.0.5

• AzuCraftyBoxes(Azumatt.AzuCraftyBoxes) 모드 문제 발견 및 정리: AzuCraftyBoxes가 근처에서 본 모든 제작함을 정적 HashSet<Container>에 계속 쌓아두는데, 구역/청크 언로드 등 일부 파괴 경로가 Container.OnDestroyed 정리 로직을 거치지 않고 GameObject를 바로 파괴해버려서 이미 죽은(fake-null) Container가 세트에 남아있는 것을 발견했습니다. 제작 메뉴가 열려 있는 동안 매 프레임 실행되는 재료 확인 로직이 이 죽은 항목을 건드리며 NullReferenceException을 반복 발생시켰습니다. AzuCraftyBoxes가 설치된 경우에만 활성화되는 패치를 추가해 해당 예외를 잡아내고, 파괴된 Container 항목들을 세트에서 직접 제거해 정리했습니다.

1.0.3 (긴급 패치 / Hotfix)

• 이전 배포(1.0.1, 1.0.2)에서 실수로 플러그인 DLL이 패키지에서 누락되어 모드가 전혀 동작하지 않던 문제를 수정했습니다.

1.0.1

• 바닐라 발헤임 엔진 문제 발견 및 정리 (최초 배포): 같은 프레임 안에서 어떤 ZNetView의 GameObject가 다른 경로로 먼저 파괴되면, 바닐라 ZNetScene.RemoveObjects가 그 오브젝트를 내부 추적 딕셔너리(m_instances)에서 제거하기도 전에 NullReferenceException을 던지고, 그 결과 문제의 entry가 끝내 제거되지 못한 채 남아 다음 프레임에도 똑같은 예외가 세션이 끝날 때까지 무한 반복되는 것을 발견했습니다. 특정 모드가 아닌 발헤임 엔진 자체의 결함입니다. ZNetScene.RemoveObjects에 Finalizer 패치를 추가해 해당 예외를 잡아내고, 이미 파괴된(fake-null) ZNetView entry를 m_instances에서 직접 제거해 정리했습니다.