Valheim
You are viewing a potentially older version of this package. View Latest Version
Install

Details

Date Uploaded
5 days ago
Downloads
3.2K
Size
163KB
Dependency string
korCaptain-NullReferenceFix-1.0.17
ADDatHost Valheim hosting
30% off!

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 폰트의 비라틴 스크립트(한글/일본어/중국어/아랍어 등) 글리프 누락 경고 (닉네임/길드명 등이 공백으로 표시됨)

📦 필수 모드 (Dependencies)
모드 버전 필수 여부
BepInExPack_Valheim 5.4.2200+ 필수
AzuCraftyBoxes 아무 버전 선택 — 설치되어 있을 때만 해당 패치가 활성화됩니다
EpicMMOSystem 아무 버전 선택 — 설치되어 있지 않아도 다른 두 패치는 정상 작동합니다

이 모드는 어떤 조합으로 설치해도 안전합니다. 위 모드들이 없어도 해당 패치만 조용히 비활성화될 뿐, 나머지 패치는 그대로 작동합니다.


🐛 버그 1 — ZNetScene.RemoveObjects (바닐라 발헤임)

같은 프레임 안에서 어떤 ZNetView의 GameObject가 다른 경로로 먼저 파괴되면, 바닐라 ZNetScene.RemoveObjects가 그 오브젝트를 내부 추적 딕셔너리(m_instances)에서 제거하기도 전에 NullReferenceException을 던집니다. 이 예외 때문에 문제의 entry가 딕셔너리에서 끝내 제거되지 못하고 남아버리고, 그 결과 다음 프레임에도 똑같은 예외가 또 발생 — 이 과정이 세션이 끝날 때까지 매 프레임 무한 반복됩니다.

이건 특정 모드가 만든 버그가 아니라 발헤임 엔진 자체의 오래된 결함입니다. 모드를 하나도 설치하지 않아도 발생할 수 있으며, 몬스터 스폰/디스폰이 잦은 상황(전투, 대규모 소환 등)일수록 더 쉽게 걸립니다.

이 모드가 하는 일: ZNetScene.RemoveObjects에 Harmony Finalizer 패치를 추가해 해당 예외만 정확히 잡아내고, 이미 파괴된(fake-null) ZNetView entry를 m_instances에서 직접 제거합니다.


🐛 버그 2 — AzuCraftyBoxes 제작함 조건 확인

AzuCraftyBoxes는 근처에서 본 모든 제작함을 HashSet<Container>에 정적으로 계속 쌓아둡니다. 상자가 철거될 때는 Container.OnDestroyed 패치로 항목을 지우지만, 일부 파괴 경로(구역/청크 언로드 등)는 이 메서드를 거치지 않고 GameObject를 바로 파괴해버려서, 이미 죽은(fake-null) Container가 세트에 그대로 남습니다. 이후 제작 메뉴가 열려 있는 동안 매 프레임 실행되는 재료 확인 로직이 이 죽은 항목의 GetPrefabName()을 호출하면서 NullReferenceException이 반복 발생합니다 — 제작 메뉴를 닫기 전까지 계속됩니다.

이 모드가 하는 일: AzuCraftyBoxes가 설치되어 있을 때만 활성화되는 패치로, 해당 예외를 잡아내고 파괴된 Container 항목들을 세트에서 직접 제거합니다.


🐛 버그 3 — EnemyHud를 건드리는 모드 간 충돌 (EpicMMOSystem 등)

일부 팩션/마켓플레이스 계열 모드는 자체 EnemyHud.LateUpdate 패치 안에서 EnemyHud.ShowHud를 직접 강제로 재호출해 HUD를 즉시 새로고침하려 합니다. 그런데 이 재호출이 이미 로그아웃했거나 디스폰된 캐릭터를 대상으로 발생하면, 그 캐릭터의 HUD 항목(m_huds)이 아직 정리되지 않은 채 남아있을 수 있고, 이걸 전제로 동작하는 다른 모드의 ShowHud 패치(예: EpicMMOSystem의 PvP 플레이어 이름 색상 표시 패치 DataMonsters.MonsterColorTexts)가 죽은 참조를 건드리면서 NullReferenceException이 반복 발생합니다.

이 모드가 하는 일: EpicMMOSystem이나 특정 모드를 콕 집어 패치하지 않고, 발헤임 기본 EnemyHud.ShowHud에 Finalizer를 걸어서 어떤 모드의 postfix에서 터지든 잡아내고, 문제의 오래된 m_huds 항목과 남은 HUD GameObject를 직접 정리합니다. 그러면 다음 프레임에 정상적인 새 항목이 만들어집니다.


🐛 버그 4 — ZSFX(발헤임 기본 사운드) 오브젝트 누수

발헤임의 사운드 재생 컴포넌트 ZSFX는 재생이 끝나도 스스로 소멸하는 로직이 아예 없습니다. ZNetView가 붙어 네트워크로 동기화되는 오브젝트는 자기 생명주기(죽음, 디스폰 등)에 따라 정리되지만, 발헤임 기본 사운드를 로컬에서 즉석으로 재생하는(ZNetScene.GetPrefab + Instantiate) 패턴을 쓰는 모드는 재생이 끝난 뒤에도 아무도 그 오브젝트를 파괴해주지 않아 세션 내내 계속 쌓입니다. 게다가 발헤임 자체의 MonoUpdaters.Update()가 살아있는 ZSFX 전체를 매 프레임 순회하기 때문에, 새어나간 오브젝트 하나하나가 영구적인 프레임당 비용을 추가합니다 — 사운드가 화려한 마법사 계열 스킬/무기 모드를 반복 사용할 때 특히 두드러지며, 플레이 시간이 길어질수록 점점 느려지다 결국 Resources.UnloadUnusedAssets() 시점에 게임이 멈추기도 합니다(리접속하면 씬이 강제로 재로드되어 일시적으로 나아짐). 특정 모드가 아닌 발헤임 엔진 자체의 결함입니다.

이 모드가 하는 일: ZSFX.CustomUpdate에 Postfix 패치를 걸어, 재생이 끝났고·반복재생이 아니고·초기 재생 지연 구간도 지났고·ZNetView가 없는 인스턴스만 자동으로 파괴합니다 — 네트워크로 동기화되는 오브젝트는 절대 건드리지 않습니다.


🐛 버그 5 — TMP 비라틴 스크립트 글리프 누락 경고

발헤임 바닐라·TMP 내장 폰트(예: Valheim-Prstartk, LiberationSans SDF)는 라틴 문자만 커버하고, 한글·일본어·중국어·아랍어·히브리어·태국어 등 비라틴 스크립트 글리프는 자체 글리프 테이블과 폴백 체인에 포함하지 않습니다. 플레이어 닉네임·길드명처럼 사용자가 직접 입력한 비라틴 텍스트가 이런 폰트로 렌더링되는 TMP_Text 오브젝트(예: EpicMMOSystem의 네임플레이트/ 길드명/정보 패널)를 통해 표시될 때마다 "The character with Unicode value ... was not found in the [...] font asset..." 경고가 반복 출력되고, 해당 글자는 공백이나 네모(□)로 대체됩니다. 발헤임은 자체 다국어 로컬라이제이션을 위해 스크립트별 Noto 계열 폰트(NotoSansKR, NotoSansJP, NotoSansSC, NotoSansArabic 등 11개 스크립트 + 이모지)를 이미 게임 파일에 내장하고 있지만, 플레이어가 직접 입력하는 텍스트용 TMP 전역 폴백 목록에는 연결되어 있지 않습니다.

이 모드가 하는 일: 발헤임이 지원하는 각 언어의 폰트를 찾아 세션당 한 번 TMP의 전역 폴백 목록(TMP_Settings.fallbackFontAssets)에 전부 등록합니다. 새 폰트를 번들링하지 않고 발헤임이 이미 갖고 있는 리소스만 사용하며, 어떤 모드가 만든 TMP 텍스트든 상관없이 어떤 언어의 텍스트든 공백/네모 대신 정상적으로 표시되도록 합니다.


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


📥 설치 방법
  1. 권장: r2modman/Thunderstore에서 자동 설치
  2. 수동: NullReferenceFix.dllBepInEx/plugins/ 폴더에 복사

이 버그들은 네트워크로 동기화되지 않는 로컬 상태 문제라서, 서버와 각 클라이언트가 각자 독립적으로 겪을 수 있습니다. 한쪽에만 설치하면 그쪽만 고쳐집니다 — 멀티플레이 환경이라면 서버 + 접속하는 모든 클라이언트에 설치하는 것을 권장합니다.


🏴󠁧󠁢󠁥󠁮󠁧󠁿 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)

📦 Required Mods (Dependencies)
Mod Version Required
BepInExPack_Valheim 5.4.2200+ Required
AzuCraftyBoxes any Optional — that patch only activates if it's installed
EpicMMOSystem any Optional — the other two patches work fine without it

Safe to install in any combination. If a mod above isn't installed, its corresponding patch just stays inactive; the rest still work normally.


🐛 Bug 1 — ZNetScene.RemoveObjects (vanilla Valheim)

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 reach the line that removes the stale entry from its internal tracking dictionary (m_instances). Because that entry never gets removed, the exact same exception fires again on the very next frame — and every frame after that, for the rest of the session.

This is vanilla engine behavior, not something any particular mod causes. It can happen with zero mods installed; busier games (more monster spawns/despawns, heavy combat) simply hit the underlying race condition more often.

What this patch does: adds a Harmony Finalizer to ZNetScene.RemoveObjects that catches only that specific exception and removes the already-destroyed (stale) ZNetView entry from m_instances directly.


🐛 Bug 2 — AzuCraftyBoxes nearby-container check

AzuCraftyBoxes keeps a static HashSet<Container> of every crafting container it has ever seen nearby. Container.OnDestroyed is patched to remove an entry when a box is demolished, but some destroy paths (e.g. a zone/chunk unload) destroy the GameObject without going through that method, leaving a Unity-destroyed (fake-null) Container sitting in the set. The next recipe check that walks nearby containers calls GetPrefabName() on the dead entry and throws NullReferenceException — every frame the crafting menu stays open.

What this patch does: only activates when AzuCraftyBoxes is installed; catches that exception and removes the destroyed Container entries from the set directly.


🐛 Bug 3 — Mod conflicts touching EnemyHud (EpicMMOSystem, etc.)

Some factions/marketplace-style mods call EnemyHud.ShowHud directly from their own EnemyHud.LateUpdate patch to force an immediate HUD refresh. If that re-entrant call targets a Character that already logged out or despawned, its HUD entry (m_huds) can still be sitting around uncleaned, and another mod's ShowHud patch that assumes a live entry — e.g. EpicMMOSystem's PvP player name-color patch, DataMonsters.MonsterColorTexts — dereferences the dead reference and throws NullReferenceException repeatedly.

What this patch does: instead of targeting EpicMMOSystem or any specific mod, it patches vanilla EnemyHud.ShowHud itself with a Finalizer, so it catches the exception no matter which installed mod's postfix throws it, then clears the stale m_huds entry (and its leftover HUD GameObject) so the next call rebuilds a clean one.


🐛 Bug 4 — Leaked ZSFX (vanilla Valheim sound) objects

Valheim's sound-playback component, ZSFX, has no self-destruct logic at all once it finishes playing. Objects tracked by a ZNetView get cleaned up as part of their own lifecycle (death, despawn, etc.), but any mod that instantiates a vanilla sound effect locally (e.g. ZNetScene.GetPrefab + Instantiate to play a one-off sound) leaves nothing to ever destroy it — it just sits there for the rest of the session. Worse, Valheim's own MonoUpdaters.Update() iterates the entire live ZSFX list every single frame, so each leaked instance adds a permanent per-frame cost — most noticeable with sound-heavy Mage-class skill/weapon mods that cast repeatedly, causing progressively worse lag that can eventually freeze the game during Resources.UnloadUnusedAssets() (relogging force-reloads the scene and temporarily fixes it). This is vanilla engine behavior, not something any particular mod causes.

What this patch does: adds a Postfix to 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.


🐛 Bug 5 — Missing non-Latin script glyph warnings in TMP text

Vanilla/TMP-bundled fonts (e.g. Valheim-Prstartk, LiberationSans SDF) only cover Latin glyphs — Korean, Japanese, Chinese, Arabic, Hebrew, Thai, and other non-Latin scripts aren't in their own glyph table or fallback chain. Whenever player-authored non-Latin text — a nickname or guild name, for example — is rendered through a TMP_Text object using one of these fonts (e.g. EpicMMOSystem's nameplate/guild-name/info-panel objects), Unity logs a repeating "The character with Unicode value ... was not found in the [...] font asset..." warning and replaces the character with a blank space or a missing-glyph box (□). Valheim already ships a Noto-family font asset for every non-Latin script its own localization supports (NotoSansKR, NotoSansJP, NotoSansSC, NotoSansArabic, and 7 more, plus an emoji set) in its own game files, but none of them are wired into TMP's fallback list for arbitrary player-authored text.

What this patch does: finds each of Valheim's bundled per-language fonts and registers all of them into TMP's global fallback list (TMP_Settings.fallbackFontAssets) once per session. No new font is bundled — it reuses resources Valheim already ships — and it fixes rendering for any mod's TMP text in any of those languages, not just Korean and not just one specific mod's.


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.


📥 Installation
  1. Recommended: Install via r2modman/Thunderstore
  2. Manual: Copy NullReferenceFix.dll into BepInEx/plugins/

These bugs are local state, not something synced over the network — the server and each client can hit them independently. Installing on only one side only fixes that side. In multiplayer, install it on the server and every connected client to be safe.


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

🌳 CaptainSkillTree

👹 MonsterModifiers

🎵 CaptainAudio


📝 Credits / 크레딧

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

💬 Support / 지원


📜 License / 라이선스

Developer - KorCaptain


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

Thunderstore development is made possible with ads. Please consider making an exception to your adblock.