Home›Java›Mods›AI DataBase wAPI Core
ModsJava

AI DataBase wAPI Core

by morwapi · on Modrinth

A core server-side mod for Minecraft 1.21.1 (NeoForge) that enables async external AI API calls and lightweight JSON-based data storage. It provides APIs…

⬇ Download on Modrinth
Open in MC Java ModsGet it on Google Play →
  1. English / 2. 日本語

AI DataBase wAPI Core (aidbwapi_core)

A core server-side mod for Minecraft 1.21.1 (NeoForge) that provides asynchronous request functionality to external AI (OpenAI-compatible LLM APIs) and a lightweight JSON-based persistent storage (database functionality). This mod does not provide standalone features (such as chatbots) on its own; it is designed as a system infrastructure (Core) that allows other mods (dependent mods) to easily utilize advanced AI functions and data storage via the Java API (AiCoreAPI / DatabaseManager).

🚀 Features & Architecture

1. AI Request Network (Advanced AI Integration & Autonomous Failover)

Equipped with an autonomous failover and rate-limiting system designed to ensure safe and reliable communication with external APIs while minimizing server load.

2. JSON Storage System (Database Functionality)

A foundation that allows dependent mods to save and load their own data with extreme ease. The storage format is strictly fixed to JSON.

💻 Requirements & Setup

Installation: Place this mod (aidbwapi_core-x.x.x.jar) into the mods folder of your server or client and launch.

⚙️ Configuration & Directory Structure

All settings, databases, and error logs are deployed in the server root directory or under saves/[world_name]/ for clients.

🛠️ Command Reference

Initial AI setup and various model settings/management can be easily performed via in-game commands. All commands start with /dbwapi.

📌 General & Config

📌 KeyName Management

Centralized management of the set consisting of the URL (provider endpoint) and API key as a system-wide "Registered Name (keyName)."

📌 Model & Failover Management

Model identifiers are always specified as <keyName>.<model_name> (e.g., taro_groq.llama-3-70b).

📌 AI Test, Error Logs, & DB Management (Tests & Logger)

📦 For Developers: Java API Implementation (API Layer for Developers)

The Core infrastructure is utilized by calling it via the singleton (getInstance()) or various static methods from the Java code of your dependent mod. Please include aidbwapi_core as a dependency (e.g., compileOnly) in your build.gradle before implementing.

1. Asynchronous Request to AI (AiCoreAPI)

All internal rate-limit checks, key distribution, failovers, and exception handling pipelines are hidden.

import com.morwapi.aidbwapi_core.api.AiCoreAPI;

// Execution results are returned asynchronously as CompletableFuture<String>.
AiCoreAPI.getInstance().requestAI("Tell me the appeal of Minecraft in 100 characters")
    .thenAccept(response -> {
        // [On Success] Process the AI response string (response).
        System.out.println("AI Response: " + response);
        
        // ⚠️ [CAUTION] This is executed in a "Separate Thread (inside AsyncExecutor)".
        // To safely access the Minecraft world (sending chat, placing blocks, entity operations, etc.),
        // you must ensure the processing is returned to the main thread (Server Thread)
        // using a task queue like server.execute(() -> { ... }).
    })
    .exceptionally(ex -> {
        // [On Failure/Exception] Reached if all models are unavailable,
        // retry limit (100) exceeded, or request parameters are invalid (HTTP 400).
        System.out.println("AI Communication Error: " + ex.getMessage());
        return null; // CompletableFuture requirement
    });

### 2. JSON Database and Categories (`CategoryDatabaseHandle`)
Register and obtain categories via `AiCoreAPI`, and receive handles for `PlayerDatabase` or `GlobalDatabase` to save and read data.

**[IMPORTANT] JsonStorageEngine Specifications and Types:**
This database is not a high-performance ORM tool for directly saving and fully restoring complex custom class structures (POJOs). Due to GSON specifications, all data restored from JSON files via `get()` is loaded as collections of **`Map<String, Object>`** (or primitive types).
Therefore, while you can pass custom class instances when saving, the design is extremely simple and assumes you will cast or reconstruct them from Maps or standard types (or deserialize separately with GSON) when reading. Use with simple Maps, numbers, or strings is recommended.

import com.morwapi.aidbwapi_core.api.AiCoreAPI;
import com.morwapi.aidbwapi_core.api.CategoryDatabaseHandle;
import java.util.UUID;

// ------ During Mod Initialization (e.g., FMLCommonSetupEvent) ------

// [1]. Automatic generation and registration of categories
AiCoreAPI.getInstance().registerCategory("guild_mod");

// [2]. Obtaining a DB handle for operation
CategoryDatabaseHandle dbHandle = AiCoreAPI.getInstance().getCategoryDatabase("guild_mod");

// ------ Implementation Example (e.g., PlayerJoinEvent) ------
UUID playerId = player.getUUID();

// [1]. Loading data (Read)
// Restored from JSON as Map format, etc. Returns null if not created.
Object rawData = dbHandle.getPlayerDB().get(playerId, "killCount");
int killCount = 0;

if (rawData != null) {
    // Since numbers may become Double due to GSON, receive as Number type and cast.
    killCount = ((Number) rawData).intValue();
}

// [2]. Updating and saving data (Save)
killCount += 1;

// Arguments: Player UUID, storage identification key name, value to save (Object)
dbHandle.getPlayerDB().set(playerId, "killCount", killCount);

// ※ The moment this `set()` method is called, the file is written [synchronously and immediately]
// to `guild_mod/players/<UUID>.json` at the same time it is applied to the memory (cache-side Map).

## ⚖️ License (License)

The source code and provided binaries of this mod are provided and published under the **Apache License, Version 2.0**.
Creation and redistribution of commercial or non-commercial mods that use or depend on this infrastructure (API) are permitted freely within the scope of the license terms.
    



# AI DataBase wAPI Core (aidbwapi_core)

Minecraft 1.21.1 (NeoForge) 向けに、外部AI（OpenAI互換LLM API）への非同期リクエスト機能、およびJSONベースの軽量な永続化ストレージ（データベース機能）を提供するコア・サーバーサイドModです。
本Mod単体で完結する機能（チャットボット等）は持たず、他のMod（依存Mod）が高度なAI機能やデータ保存機能を Java API(`AiCoreAPI` / `DatabaseManager`) として簡単に利用できるように設計された**システム基盤（Core）**です。

---

## 🚀 コア機能とアーキテクチャ (Features & Architecture)

### 1. AI Request Network (高度なAI連携と自律型フェイルオーバー)
外部APIへの通信を、サーバー負荷を極限まで抑えつつ安全・確実に運用するための自律型フェイルオーバー・レートリミットシステム（AI動作を止めない仕組み）を備えています。

*   **完全非同期処理と直列キュー (Async Executor):**
    AIへのHTTPリクエストはすべて `CompletableFuture` とJava標準の `HttpClient` 機構（非同期I/O処理）を用いて実行され、MinecraftのTickを一切ブロックしません。また「同時実行数は常に最大1つまで（キュー管理）」とし、同一のプロンプト文字列を複数同時に多重送信しない安全設計が施されています。
*   **遅延評価リセット (Lazy Reset):**
    モデルの「1日あたりの実行上限」「1分あたりの実行上限」の初期化判定は、サーバーの定期処理（常時監視）を行わず、次回リクエストが発生した瞬間のタイムスタンプ比較で都度計算・リセットする「遅延評価（Lazy Reset）」メカニズムを採用しており、待機中のサーバー負荷はゼロです。
*   **キーの分散運用と分散ラウンドロビン (Priority & Load Balancing):**
    同一のプロバイダやモデルに対して、複数のAPIキーを登録できます。モデル（ModelEntry）ごとに優先度(`priority`: 数値が小さいほど高優先)を設定でき、レート上限到達時やエラー時には優先度の高い順へ自動でフォールバック（別モデル・別キーへの自動切替）を行います。
    さらに、**同率優先度のモデルが複数存在する場合、システムは「ラウンドロビン方式」で行き先を分散させ、特定のAPIキーへの負荷集中を自動で防ぎます**。無料APIのレート制限枠を複数キーで合算して安全に運用することが可能です。
*   **ペナルティポイント(PP)制と確率スキップ (Penalty System):**
    通信エラー等が発生した際、即座に対象モデルを無効化するのではなく、一時的なクールダウン秒数（デフォルト: 429=60秒, 5xx=120秒, Timeout=60秒, 接続失敗=300秒）を課すと同時に、**エラーの重大度に応じたペナルティポイント（PP）**を加算します。
    *   `HTTP 429` (レート制限): **+1 PP**
    *   `HTTP 5xx` (サーバーエラー): **+5 PP**
    *   `Timeout` / 接続・DNS解決失敗: **+7 PP**
    *   通信成功時: **PPを半減** (`PP /= 2`)
    
    実行候補の選出時、PPを持つモデルは `PP / (PP + 4.0)` の確率で一時的に見送られ（次点のモデルへ移行）、調子の悪いエンドポイントへのアクセスを自律的に回避・抑制します。
*   **最大100周のフェイルセーフループ (Fail-Safe Loop):**
    すべてのモデル候補が確率スキップやクールダウン中だった場合、候補リストの先頭に戻って再抽選ループが発生しますが、無限ループを防止するため「**最大100周で強制的に打ち切り、利用可能な中で最も優先度が高い（priorityが小さい）モデルを妥協選出するか、API層へ完全失敗を返す**」という強固なフェイルセーフが働きます。
*   **例外処理 (HTTP 400 Bad Request):**
    `HTTP 401`（認証エラー）や `HTTP 404`（モデル不存在）のような構成不良エラーが発生した場合、対象モデル自体を自動無効化(`disabled`)した上で直ちに次のモデル候補へフォールバック（再試行）します。しかし、`HTTP 400`（リクエスト不正）に関しては「プロンプトや送信データの構造そのものにバグがある」ため、どのモデルに切り替えても失敗する可能性が高く、フェイルオーバーさせずに即座に呼び出し元の依存Mod側へエラーを返却します（無駄なループの即時打ち切り）。

### 2. JSON Storage System (データベース機能)
依存Modが独自のデータを極めて簡単に保存・読み出しできる基盤です。保存フォーマットは**JSON完全固定**です。

*   **カテゴリの登録と階層管理:**
    依存Mod（外部Mod）が初期化時などに `registerCategory("my_mod")` を呼ぶことで、そのカテゴリ名に紐づくディレクトリ構成が自動生成されます。「汎用データ（Global）」と「プレイヤー個別（UUID）データ」は自動でフォルダが振り分けられ保存されます。（※事前登録を行わずにデータを保存することはできません）。
*   **メモリキャッシュと動的解決:**
    頻繁にアクセスされるデータは、読み込み時にメモリ上にMapとしてキャッシュされ、以後の `get` / `set` はディスクアクセス（I/O）を行わず即座に処理されます。保存先ディレクトリのルートパスは、サーバー起動時イベント（`ServerStartedEvent`）を利用して `root/world/aidbwapi_core/` 等の正しいパスを自動取得して決定します。
*   **同期的・即時セーブ機構:**
    データベースに対する書き込み（`set()` の呼び出し）が行われると、メモリ上のキャッシュが更新されるのと同時に**即座に同期的ファイル書き出し（フラッシュ）**が実行されます。（※エラーログ出力のみはバックグラウンドの3時間ごとの遅延タイマーを使用しますが、DB自体に非同期オートセーブの遅延機能は存在しません）。安全のため、手動での強制保存（`db save`）コマンドも実装されています。

---

## 💻 動作要件とインストール (Requirements & Setup)

*   **Minecraft:** 1.21.1
*   **Mod Loader:** NeoForge 21.1.219 以降
*   **Java:** Java 21 以上
*   **サイド:** サーバー・クライアント両方必須

**インストール:**
当Mod (`aidbwapi_core-x.x.x.jar`) をサーバーまたはクライアントの `mods` フォルダに配置して起動します。

---

## ⚙️ 設定ファイルとディレクトリ構造 (Configuration)

すべての設定やデータベース・エラーログは、サーバーのルートディレクトリ、またはクライアントの `saves/[ワールド名]/` 配下に展開されます。

*   **`config/aidbwapi_core-common.toml`** : Mod全体の基礎動作設定ファイル。
    *   `commandPermissionLevel`: 全ての `/dbwapi` コマンドの要求OP権限レベル（デフォルト `2`）。0〜4に変更可能です。
    *   `requestTimeoutSeconds`: AI通信の応答タイムアウト秒数（デフォルト `60`秒）。
    *   `penaltyCurveFactor`: PPスキップ確率計算曲線の調整係数（デフォルト `4.0`）。
    *   他、各種HTTPエラー時のクールダウン秒数（`rateLimitSeconds` 等）や、エラーログの定期フラッシュ間隔（`flushIntervalMinutes`）等を設定可能。一部の基礎設定はインゲームコマンド（`/dbwapi config ...` 等）からでも即座に変更・永続化されます。
*   **`config/aidbwapi_core-keynames.json`** : AIエンドポイントURL、APIキーの平文、およびモデル一覧と各種レート制限(`dailyLimit`, `minuteLimit`)の設定が構造化保存されます。
    *   **⚠️【重要】APIキーのセキュリティ・登録方法について**
        Modの仕様としてAPIキー自体は暗号化されず、このJSONファイル内に平文で保存されます（`.gitignore` 等での防衛やOSサーバー権限による保護運用を前提としています）。インゲームのコマンド（`/dbwapi keyname setkey`）からでも登録可能ですが、**Minecraftの仕様上、あなたがチャット欄に打ち込んだコマンド全文（APIキーの平文文字列）は、サーバーの `logs/latest.log` やコンソール画面のログファイルにそのまま丸見えで記録されてしまいます。**
        セキュリティを担保するため、外部に提供される可能性のあるサーバーを運用する場合、ゲーム内でのコマンド入力は避け、**本ファイルを直接テキストエディタで開き `"apiKey": "sk-xxxx..."` を書き換え・保存したうえで、ゲーム内で `/dbwapi reload` コマンドを実行して再読み込みさせる運用を強く推奨します。**
*   **`[ワールド保存ルート]/aidbwapi_core/[カテゴリ名]/`** : `CategoryDatabaseHandle` 等を経由して保存・キャッシュされた各カテゴリの設定・データ保存ルート。
    *   カテゴリ直下に汎用データ（`global.json`）と、プレイヤー個別フォルダ（`players/<UUID>.json`）が配置されます。
*   **`[ワールド保存ルート]/aidbwapi_core/log/`** : メモリ上に蓄積されたAI・DB処理時のエラー履歴（デバッグログ）がバックグラウンドでJSON形式出力される出力先。
    *   最新のエラーログ出力はデフォルトで最大 `20` ファイル保持され、古いものから自動ローテーション（削除）されます。
    *   また、メモリに残存する未保存のエラー状態は、サーバー終了・シャットダウン時（`ServerStoppingEvent`）に割り込みでフラッシュされ、確実にディスクへ救済・保存されます。

---

## 🛠️ コマンドリファレンス (Command Reference)

AIの初期セットアップやモデルの各種設定・管理は、インゲームコマンドから手軽に行えます。
すべてのコマンドは `/dbwapi` で始まります。（デフォルト要求権限: `common.toml` 記載のレベル。初期値は2）

*   **引数・サジェストの仕様:** 識別子（KeyNameやModel名）を入力する際、登録済みの設定すべてがインゲームでサジェスト（Tab補完）表示されます。構文エラーや引数不足はBrigadier標準として弾かれます。
*   **メッセージフォーマット表示色:** コマンドからのフィードバックはすべてシステムメッセージとして `[AiDb]` (緑色) から始まり、操作対象（数値や名前）は黄色でハイライトされます。エラーや警告は全体が赤色テキストで出力されます。
*   **APIキー等の出力保護の徹底:** 画面表示用コマンド（`info` や `list`）等でAPIキー情報がチャットに出力される際は、保護のため「元のキーが5文字以上の場合は**先頭4文字のみ表示し、残りの全文字を `****` にマスキング**」「元のキーが4文字以下の場合は**例外として全文字を `****` にマスキング**」した状態でのみ表示され、生キーが画面に出力されることは絶対にありません。また、システムログの出力時などにもキーは一切含まれません。

### 📌 全般 (General & Config)
*   `/dbwapi status` : システム全体の稼働サマリー。ロード済みのKeyName数とモデル数に加え、メモリ上で出力待機状態（Queue）になっているAIエラー・DBエラーの件数を表示します。
*   `/dbwapi reload` : TOMLおよびJSON（`keynames.json`）設定ファイルを強制的に再読み込みします。テキスト手動編集時は必ず実行してください。
*   `/dbwapi version` : 当Modのバージョンを表示します。
*   `/dbwapi config show` : 現在適用されているデバッグログ設定（`debugLogging`）とAI通信タイムアウト秒数（`requestTimeoutSeconds`）を表示します。
*   `/dbwapi config debug true|false` : デバッグレベル（詳細ログ出力）のオン/オフを即座に切り替え・永続化します。
*   `/dbwapi config timeout <秒>` : AI通信のタイムアウト秒数（基礎設定）を変更・永続化します。

### 📌 キー(KeyName)管理 (KeyName Management)
URL（プロバイダエンドポイント）とAPIキーのセットを、システム共通の**「登録名(keyName)」**として一元管理します。
*   `/dbwapi keyname list` / `info <keyName>` : 登録済みの全KeyNameの一覧、または指定したKeyNameの詳細を表示します。（APIキーはマスクされます）
*   `/dbwapi keyname add <keyName> <apiUrl> <apiKey>` : 新しいAIプロバイダ（OpenAI互換）に対する接続情報セットを登録します。※登録名(`keyName`)の重複はエラーですが、`apiUrl` と `apiKey` に同一の内容を別名で複数登録することは許可されています（負荷分散のため）。
*   `/dbwapi keyname seturl <keyName> <apiUrl>` : 既存のKeyNameのAPIエンドポイントURLのみを更新します。
*   `/dbwapi keyname setkey <keyName> <apiKey>` : 既存のKeyNameのAPIキーを更新します。**(※前述のログ残存リスクがあります。安全のためJSONの直接編集を推奨します。)**
*   `/dbwapi keyname remove <keyName> [confirm]` : 誤操作防止の安全装置付き削除。末尾引数（`[confirm]`）を省略または `false` で実行した場合は、削除確認の警告ログのみ出力して終了します。末尾に明示的に `true` を指定した場合のみ、KeyName（およびそのKeyNameに紐づくすべてのモデル設定群）が完全に削除されます。

### 📌 モデル管理 (Model & Failover Management)
モデルの識別子は、どのプロバイダのモデルかが分かるように、常に **`<keyName>.<モデル名>`**（例: `taro_groq.llama-3-70b` のようにドットで区切り）で指定します。
*   `/dbwapi model list` / `info <keyName>.<モデル名>` : 全モデルの稼働状況（優先度、ペナルティ・PP状況、現在有効か等）や、個別モデルの詳細な制限メトリクスを表示します。
*   `/dbwapi model add <keyName>.<モデル名> [dailyLimit:日次上限] [minuteLimit:分間上限]` : 親となるKeyNameに対して新しい利用可能モデルを追加します。上限値引数を省略した場合、または `-1` を入力した場合は「日次/分次ともに無制限」として登録されます。
*   `/dbwapi model move <keyName>.<モデル名> up|down` : 指定モデルの優先度（Priority順位）を、1つ上（`up`）または 1つ下（`down`）に移動・入れ替えます。
*   `/dbwapi model limit <keyName>.<モデル名> daily|minute <値>` : モデルの上限回数を変更します（`-1` で無制限）。設定の変更は即時適用されます。
*   `/dbwapi model enable <keyName>.<モデル名>` / `disable <keyName>.<モデル名>` : 指定モデルの抽選設定を有効化/一時無効化します。
    *   **【自動無効化からの復旧】**: 例外(`HTTP 401/403 Invalid API Key` や `HTTP 404 Not Found`) など、恒久的に失敗する設定問題が発覚した場合、システムが対象モデルを自動的に強制無効化(`disabled`)します。エンドポイントの不整合等を解消（`seturl` 等）した後、この `enable` コマンドで手動復帰させてください。
*   `/dbwapi model reset <keyName>.<モデル名>` : 対象モデルの蓄積されたPP(ペナルティ)や、クールダウン状態を即座にゼロにリセットします。
*   `/dbwapi model resetall` : 現在登録されている「全モデル」を一斉にリセットします。
*   `/dbwapi model remove <keyName>.<モデル名> [confirm]` : 指定モデルを削除します。（※安全装置あり。末尾に `true` が必須です）

### 📌 AI動作テスト・エラーログ・DB管理 (Tests & Logger)
*   `/dbwapi ai status` : 現在実行・処理中の（`Active`）リクエストと、非同期処理の待機キュー（`Queue`）に入っているAIリクエストの件数を表示します。
*   `/dbwapi ai test` : 「現在有効なモデル（最も優先度が高く、通信可能なもの）」を利用して、システムから数十文字の短いテストプロンプトをAIに送信し、実際にテキストの返答が来るかどうかの疎通（結合）テストを行います。
*   `/dbwapi ai errors [表示件数]` : キューに蓄積されている「直近で発生したAI通信エラー（HTTPステータスコードや原因例外等）」の履歴を時間・対象モデル名とともに最大50件（省略時はデフォルト10件）チャット欄に素早く出力します。エラーの特定に便利です。
*   `/dbwapi ai errors clear` : 画面表示用のエラー履歴メモリを空にします。（※ディスク上のログファイル自体は削除されません）
*   `/dbwapi db list` : 依存Mod等から `DatabaseManager` に現在登録されている全カテゴリ名の一覧を表示します。
*   `/dbwapi db info <カテゴリ名>` : 対象カテゴリの保存先ルートパス、グローバルDBのキー数（ロード済の規模感）、および現在キャッシュに乗っているプレイヤー毎のUUIDデータの総数などのメトリクスを表示します。
*   `/dbwapi db errors [件数]` / `db errors clear` : `ai errors` と同じ仕組みで、DB特有のログ（`FILE_WRITE_ERROR` 等）をチャットに出力（省略時はデフォルト10件）・クリアします。
*   `/dbwapi db save` : メモリ上の全データベースの変更内容を明示的に強制ファイル書き出し（フラッシュ）させます。（※通常は `set` 時に自動で即時同期保存されるため、直接メモリを改ざんした場合の救済用です）。

---

## 📦 開発者向け: Java APIの実装利用方法 (API Layer for Developers)

当Core基盤は、依存Mod（自作Mod等）の Java コードから、シングルトン（`getInstance()`）または各種 Static メソッド経由で呼び出して利用します。`build.gradle` で `aidbwapi_core` を依存解決（`compileOnly` 等）に含めた上で実装してください。

### 1. AIへの非同期リクエスト (`AiCoreAPI`)
内部でのレート制限チェック、キーの振り分け、フォールバック、例外ハンドリングパイプラインをすべて隠蔽しています。
呼び出し側の開発者は「プロンプト文字列を投げて、CompletableFuture で結果の文字列を受け取る」だけで完結する非常にシンプルな設計として機能します。

```java
import com.morwapi.aidbwapi_core.api.AiCoreAPI;

// CompletableFuture<String> として実行結果が非同期に返却されます。
AiCoreAPI.getInstance().requestAI("Minecraftの魅力を100文字で教えて")
    .thenAccept(response -> {
        // [成功時想定] AIのレスポンス文字列(response)を取得して処理。
        System.out.println("AIの回答: " + response);
        
        // ⚠️【注意】ここは「別スレッド(AsyncExecutor内部)」で実行されています。
        // マイクラの世界(チャット送信、ブロック設置、エンティティ操作等)へ安全にアクセスするためには、
        // 必ず server.execute(() -> { ... }) 等のタスクキューを用いて
        // 処理をメインスレッド(Server Thread)へ確実に戻してください。
    })
    .exceptionally(ex -> {
        // [失敗時・例外時] 登録されている全モデルが使用不可（全滅）か、リトライ100件超過、
        // あるいはリクエストパラメータ不正(HTTP 400)等で完全失敗した場合に到達します。
        // エラーの種別(RATE_LIMITED, ALL_FAILED等)や詳細がメッセージ(ex.getMessage())に含まれます。
        System.out.println("AI通信エラー: " + ex.getMessage());
        return null; // CompletableFuture要件
    });

2. JSONデータベースとカテゴリ (CategoryDatabaseHandle)

AiCoreAPI を経由してカテゴリを登録・取得し、PlayerDatabase または GlobalDatabase のハンドルを受け取ってデータの保存・読出を行います。

【重要】JsonStorageEngineの仕様と型: 当DBは、独自の複雑なクラス構造（POJO）を直接保存・完全復元する高機能ORMツールではありません。Gsonの仕様等により、JSONファイルから get() で展開（復元）されたデータはすべて Map<String, Object>（あるいはプリミティブ型）のコレクションとしてロードされます。 そのため、保存時は自分で独自クラスインスタンスを渡すことも可能ですが、読込時はMapや標準型から自分でキャスト・再構築（あるいは別途Gsonでのデシリアライズ）を行う前提の、極めてシンプルな機能設計となっています。単純なMapや数値、文字列ベースでの利用を推奨します。

import com.morwapi.aidbwapi_core.api.AiCoreAPI;
import com.morwapi.aidbwapi_core.api.CategoryDatabaseHandle;
import java.util.UUID;

// ------ Modの初期化時 (FMLCommonSetupEvent等) ------

// [1]. カテゴリの自動生成・登録
AiCoreAPI.getInstance().registerCategory("guild_mod");

// [2]. 操作用DBハンドルの取得
CategoryDatabaseHandle dbHandle = AiCoreAPI.getInstance().getCategoryDatabase("guild_mod");

// ------ 実装例 (PlayerJoinEvent等) ------
UUID playerId = player.getUUID();

// [1]. データのロード (読み込み)
// JSONからMap形式等で復元されます。未作成の場合は null が返ります。
Object rawData = dbHandle.getPlayerDB().get(playerId, "killCount");
int killCount = 0;

if (rawData != null) {
    // Gsonにより数値はDouble等になる場合があるため、Number型で受け取りキャストします
    killCount = ((Number) rawData).intValue();
}

// [2]. データの更新とセーブ (保存)
killCount += 1;

// 引数: プレイヤーUUID, 保存識別キー名, 保存する値(Object)
dbHandle.getPlayerDB().set(playerId, "killCount", killCount);

// ※この `set()` メソッドを呼んだ瞬間に、メモリ(キャッシュ側のMap)への適用と同時に、
// `guild_mod/players/<UUID>.json` へ【同期的かつ即座に】ファイルが書き出されます。

⚖️ ライセンス (License)

このModのソースコードおよび提供されるバイナリは Apache License, Version 2.0 で提供・公開されています。 本基盤（API）を利用・依存した商用・非商用Modの作成および再配布は、ライセンス条項の範囲内で自由に行っていただけます。

Quick facts

Install steps are the general flow for this file type — How to install Minecraft Java mods & modpacks walks through it step by step.

Verified by MCModsHub

These come from our own check of the pack file, not from the source page.

Explore more

All Mods for JavaAll Minecraft Java modsJava mods for 1.21