Puzzles Lib — Minecraft Java Edition 1.21.1

Puzzles Libは、開発者Fuzsが制作したMinecraft Mod向けの基盤となる技術ライブラリです。新しいブロック、アイテム、モブ、ゲームプレイの仕組みをゲーム世界に直接追加することはありません。その主な役割は、共通のプログラミングインターフェース（API）を提供することにあり、これによりForge、Fabric、NeoForge固有のコードを抽象化し、他のModがさまざまなローダー上で同じように安定して動作できるようにします。Puzzles Lib本体のダウンロードは、関連するアドオンの動作を保証するためだけに必要です。

依存Modのエコシステム

このライブラリは、30を超えるさまざまなプロジェクトを起動するための必須要件です。イベント処理、モデルのレンダリング、クライアントとサーバー間のデータ同期のための共通コードを含んでいます。

このフレームワークを利用している、Minecraftで最も人気の技術系Mod:

• インターフェースとブロックの変更: Easy Magic、Easy Anvils、Visual Workbench。ライブラリは、これらのブロックを閉じた後もインベントリ内のアイテムを保持すること、そして戦利品をブロックのテクスチャ上に直接表示することを担います。

• 魔法・取引系の拡張: Enchanting Infuser、Trading Post、Universal Enchants。Puzzles Libは、これらのModがバニラの乱数生成器や村人の取引生成アルゴリズムとやり取りするためのロジックを提供します。

• クライアント側の拡張: コンパス、時計、その他の情報表示系アドオンなど。ここではAPIが、FPSを落とすことなく画面へのデータ出力を処理します。

Fuzs製Modの設定

設定フォーマットの統一は、このライブラリの中心的な課題です。FabricにJSON、ForgeにTOMLをそれぞれサポートする代わりに、開発者は単一の標準を導入しました。

Puzzles Libは、依存するすべてのModを強制的に.toml形式の使用へと切り替えます。ライブラリ自体も、configフォルダ内にpuzzleslib-client.tomlという独自の設定ファイルを持っています。

checkIncompatibleMods

enableOptifineWarning

forceResourcePacks

起動の問題と競合の解決

Puzzles Libはクロスプラットフォームであるため、クライアントのビルド中にエラーが起きることがよくあります。ログの分析から、このライブラリに関連してゲームのクラッシュ（crash）が発生する主な原因が3つ明らかになっています。

Fabricでの設定ポートの不足

初期化の段階でゲームが即座に終了してしまうエラーです。FabricはForgeの設定システム（TOML形式）をネイティブにサポートしていないため、Puzzles Libは設定ファイルを読み込めません。この状況を修正するには、補助Modである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は、開発を効率化し、すべての現行ローダーで大量のModを一度に更新できるようにする、純粋に技術的なツールです。Architectury APIのような大規模なフレームワークと比べると、このModは対象が絞られており、ある一人の作者のエコシステムだけを支えています。難点は、Fabricプレイヤーにとってやや過剰な依存関係の構造であり、彼らはサードパーティの設定ポートをダウンロードしなければなりません。このModの存在は、Fuzsのツールを用いて技術系やRPG系のModパックを組むすべての人にとって必須です。