ModVersionGuard 및 런타임 안정성 (MC 26.2)
이 문서는 Minecraft 26.2 버전의 Item Clumps에 대한 무의존 런타임 클래스로더 검사, 버전 보호 아키텍처 및 바이트코드 안전 메커니즘에 대해 다룹니다.
📊 기능 정보 상자
| 속성 | 값 |
|---|---|
| 시스템 이름 | Knot 클래스로더 버전 가드 |
| 대상 클래스 | net.instantgratification.item_clumps.util.ModVersionGuard |
| 검증 대상 클래스 | net.minecraft.world.entity.item.ItemEntity |
| 라이브러리 검증 | net.dasik.social.api.config.ConfigHelper (DasikLibrary $\ge 1.7.4$ 필요) |
| 보안 목적 | 호환되지 않는 Minecraft 버전 실행 시 월드 손상 방지 |
🛡️ Knot 클래스로더 아키텍처
Fabric Loader 환경에서는 모드 클래스가 여러 클래스로더(Knot ClassLoader 대 시스템 클래스로더)로 분리되어 로드됩니다. 현재 스레드 컨텍스트를 거치지 않는 일반 Class.forName(name) 호출은 실패할 수 있습니다.
Item Clumps는 2단계의 안전한 클래스로더 조회를 구현합니다:
┌───────────────────────────────────┐
│ ModVersionGuard.checkClass Invoked│
└─────────────────┬─────────────────┘
│
▼
┌───────────────────────────────────┐
│ Query Knot Thread Context Loader │
│ Thread.currentThread() │
│ .getContextClassLoader() │
└─────────────────┬─────────────────┘
│
┌────────────────┴────────────────┐
│ (Success) │ (ClassNotFoundException)
▼ ▼
┌───────────────────────────┐ ┌───────────────────────────┐
│ Game Continues Execution │ │ Fallback to Current Loader│
│ Safe Runtime Verified │ │ ModVersionGuard.class │
└───────────────────────────┘ │ .getClassLoader() │
└─────────────┬─────────────┘
│
┌────────────────┴────────────────┐
│ (Success) │ (ClassNotFoundException)
▼ ▼
┌───────────────────────────┐ ┌───────────────────────────┐
│ Game Continues Execution │ │ Throw Descriptive Warning │
│ Safe Runtime Verified │ │ Halt Corrupted World Load │
└───────────────────────────┘ └───────────────────────────┘💻 실제 Java 소스 코드 구현
Minecraft 26.2의 ModVersionGuard.java 출처:
java
// Copyright (C) 2026 Dasik (Rifaditya) | GNU GPLv3
package net.instantgratification.item_clumps.util;
public final class ModVersionGuard {
private ModVersionGuard() {}
public static void checkClass(String modName, String requiredClassName) {
ClassLoader contextLoader = Thread.currentThread().getContextClassLoader();
ClassLoader currentLoader = ModVersionGuard.class.getClassLoader();
try {
if (contextLoader != null) {
Class.forName(requiredClassName, false, contextLoader);
} else {
Class.forName(requiredClassName, false, currentLoader);
}
} catch (ClassNotFoundException e) {
try {
Class.forName(requiredClassName, false, currentLoader);
} catch (ClassNotFoundException e2) {
throw new RuntimeException("\n" +
"=====================================================================\n" +
" [PRE-RELEASE / VERSION GUARD WARNING] " + modName + "\n" +
"---------------------------------------------------------------------\n" +
" CRITICAL: Incompatible Minecraft Game Runtime or Missing Class!\n" +
" Required Class : " + requiredClassName + "\n" +
" Status : UNRESOLVED AT RUNTIME\n\n" +
" Safety Protection:\n" +
" Execution halted to prevent unreleased/incompatible build deployment\n" +
" or broken world state save corruption.\n\n" +
" Troubleshooting Steps:\n" +
" 1. Verify target Minecraft version (26.2+ release drop).\n" +
" 2. Ensure all required dependencies (Fabric API, DasikLibrary) are loaded.\n" +
" 3. Build/Download a verified matching release JAR from Modrinth/CurseForge.\n" +
"=====================================================================");
}
}
}
}