Puzzles Lib — Minecraft Java Edition 1.21.1

Puzzles Lib는 개발자 Fuzs가 제작한 마인크래프트 모드용 기본 기술 라이브러리입니다. 이 모드는 새로운 블록, 아이템, 몹, 게임플레이 메커니즘을 게임 세계에 직접 추가하지 않습니다. 주요 기능은 공통 프로그래밍 인터페이스(API)를 제공하는 것으로, 이를 통해 다른 모드들이 Forge, Fabric, NeoForge의 고유 코드를 추상화하여 서로 다른 로더에서 동일하게 안정적으로 작동할 수 있게 합니다. Puzzles Lib 모드는 오로지 연관된 애드온의 작동을 보장하기 위해서만 설치해야 합니다.

의존 모드 생태계

이 라이브러리는 30개가 넘는 다양한 프로젝트를 실행하기 위한 필수 요구사항입니다. 이벤트 처리, 모델 렌더링, 클라이언트와 서버 간 데이터 동기화를 위한 공통 코드를 담고 있습니다.

이 프레임워크를 사용하는 가장 인기 있는 마인크래프트 기술 모드:

• 인터페이스 및 블록 변경: Easy Magic, Easy Anvils, Visual Workbench. 라이브러리는 이러한 블록을 닫은 후에도 인벤토리 내 아이템을 보존하고, 블록 텍스처에 직접 전리품을 시각화하는 역할을 담당합니다.

• 마법 및 거래 확장: Enchanting Infuser, Trading Post, Universal Enchants. Puzzles Lib는 이 모드들이 바닐라 난수 생성기 및 주민 거래 생성 알고리즘과 상호작용하는 로직을 제공합니다.

• 클라이언트 확장: 나침반, 시계 및 기타 정보 애드온으로, API가 FPS 저하 없이 화면에 데이터를 출력하는 작업을 처리합니다.

Fuzs 모드 설정

설정 형식의 통일은 이 라이브러리의 핵심 과제입니다. 개발자는 Fabric용 JSON과 Forge용 TOML을 각각 지원하는 대신 단일 표준을 도입했습니다.

Puzzles Lib는 이에 의존하는 모든 모드가 .toml 형식을 사용하도록 강제로 전환합니다. 라이브러리 자체도 config 폴더에 puzzleslib-client.toml이라는 자체 설정 파일을 가지고 있습니다.

checkIncompatibleMods

enableOptifineWarning

forceResourcePacks

실행 문제 해결 및 충돌

Puzzles Lib는 크로스플랫폼이기 때문에 클라이언트 빌드 중 오류가 자주 발생합니다. 로그 분석 결과 이 라이브러리와 관련하여 게임 크래시(crash)가 발생하는 세 가지 주요 원인이 드러났습니다.

Fabric용 설정 포트 부재

초기화 단계에서 게임이 즉시 종료되는 오류입니다. Fabric은 Forge의 설정 시스템(TOML 형식)을 기본적으로 지원하지 않기 때문에 Puzzles Lib가 설정 파일을 읽을 수 없습니다. 이 문제를 해결하려면 보조 모드인 Forge Config API Port를 mods 폴더에 설치해야 합니다.

로더 버전 비호환

플레이어들은 Forge용 Puzzles Lib의 .jar 파일을 Fabric 빌드에 복사하거나 그 반대로 하는 경우가 많습니다. CurseForge와 Modrinth 플랫폼의 파일에는 해당 태그(이름에 fabric, forge, neoforge)가 붙어 있습니다. 다른 로더용 파일을 실행하면 반드시 Mod resolution failed 또는 java.lang.NoClassDefFoundError 오류가 발생합니다.

서버 태그 비동기화

라이브러리가 서버에는 설치되어 있지만 클라이언트에는 없거나(또는 버전이 다른 경우), 플레이어는 접속을 시도할 때 Connection closed - mismatched mod channel list 오류를 받게 됩니다. Puzzles Lib는 양쪽 모두에 동일한 버전의 파일을 설치해야 합니다.

호환성

• 필수 의존성: Fabric/Quilt에서 플레이하려면 Fabric API와 Forge Config API Port가 필수적입니다. Forge/NeoForge의 경우 추가 파일을 다운로드할 필요가 없습니다 — 클래스가 로더에 내장되어 있습니다.

• 비호환성: OptiFine과의 통합은 렌더링 파이프라인 충돌로 인해 불안정하게 작동합니다. 개발자는 대안으로 Sodium 또는 Embeddium 사용을 권장합니다.

결론

Puzzles Lib는 개발을 최적화하고 모든 최신 로더에서 방대한 모드 목록을 동시에 업데이트할 수 있게 해주는 순수 기술 도구입니다. Architectury API와 같은 대규모 프레임워크와 비교하면, 이 모드는 특정 목적에 집중되어 있으며 오로지 한 제작자의 생태계만을 지원합니다. 한계는 Fabric 플레이어에게 다소 과도한 의존성 구조로, 이들은 서드파티 설정 포트를 추가로 다운로드해야 합니다. 이 모드는 Fuzs의 도구를 사용하여 기술 또는 RPG 모드팩을 구성하는 모든 사람에게 필수입니다.