トラブルシューティング

まずゲームを完全に再起動し、ログから [Live2D] を検索してください。

Mod が読み込まれない

1. ゲームのバージョンが Live2D.json の min_game_version を満たすか確認します。
2. 必要な RitsuLib をインストールします。
3. mods/Live2D に Live2D.json、Live2D.dll、Live2D.pck、gd_cubism ネイティブファイルがあるか確認します。
4. DLL 更新後にゲームを完全再起動します。

モデルが白い、または表示されない

• 起動ログで Cubism Shader 10/10 を確認します。
• .model3.json 内の .moc3、テクスチャ、相対パス、大文字小文字を確認します。
• フィルターを中立値、ブレンドを Normal に戻し、クリッピングを一時的に無効化します。
• 対象シーン、不透明度、スケール、全体表示状態を確認します。

大きなモデルの読み込みで停止またはクラッシュする

• native Cubism 読み込み前に、テクスチャ数、最大寸法、推定 RGBA8 メモリが Beginning native Cubism load として記録されます。
• インポーターは最大テクスチャ寸法と mipmap を含む推定 RGBA8 合計予算に基づいて管理コピーを自動縮小します。各テクスチャは最大 2048 ピクセル、合計は 128 MiB 以下です。元モデルは変更せず、最適化 PNG を再デコードしてからステージング済みインポートを確定します。
• VTube Studio の日本語・中国語などの Motion/Expression パスは UTF-8 のまま model3 に書き込みます。旧版が生成した \uXXXX パスはロード前に移行し、Cubism ネイティブパーサーのアクセス違反を防ぎます。
• Auto のマスク解像度は 1024、手動値は 2048 が上限です。複数の clipping RenderTarget による GPU メモリ枯渇を防ぎます。
• native/GPU OOM や device loss は managed 例外なしでプロセスを終了させる場合があります。ログが上記行で終わる場合は、その資源情報を添付してください。

モデルまたはマスクがぼやける

• Normal ブレンド、中立フィルター、キャンバスマスクなしへ戻します。この状態は合成ターゲットを使わずモデルを直接描画します。
• キャンバスマスクと MaskViewportSize は別機能です。後者は Cubism Drawable マスク境界がぼやける場合だけ上げます。
• MaskViewportSize は Auto（上限 1024）を推奨します。手動値の上限は 2048 です。
• 「プレビューと編集」で実際のウィンドウに近い基準解像度を選び、モデルスケールを確認します。

マスク設定が反映されない

• モデルのマスク上書きを有効にするか、「マスクを有効にしてモデル境界に合わせる」を押します。
• 種類が None ではないことを確認します。角丸半径は角丸矩形だけに適用され、変更時に種類も自動切り替えされます。
• 「キャンバス上でマスクを直接編集」を有効にし、ドラッグで移動、ホイールで拡大縮小し、スライダーと数値が同期することを確認します。

一部のシーンだけに表示される

メインメニューとゲーム内は別設定です。マップと戦闘はゲーム内設定を共有します。別のメニューページやダイアログを開くと、 メインメニューのモデルは一時的に非表示になります。

Motion / Expression が見つからない

• Cubism モデル：model3 にアクションが宣言されているか確認します。
• VTube Studio モデル：.vtube.json が対象 model3 を参照し、資源が expressions または animations にあるか確認します。
• モデルを再インポートして管理アクション一覧を更新します。
• ホットキーが現在のシーンで有効か確認します。
• 同一ホットキーやループ Motion の競合を確認します。

「モデルが見つかりません」と表示される

ローカルモデルは管理ファイルを復元し、提供モデルは提供元 Mod を有効にします。Live2D は設定を保持し、資源が利用可能になると インスタンスとホットキーを再開します。

Pack のインポートに失敗する

• ルート直下に manifest.json と settings/models.json が必要です。
• 形式は FormatVersion = 1、SettingsSchemaVersion = 6 です。
• モデル資源は models/<OriginalId>/ 配下に置きます。
• 絶対パス、..、シンボリックリンク、重複パス、異常な圧縮は拒否されます。

ログに JSON value could not be converted to List<Live2DModelConfig> がある場合、Pack 内の settings/models.json のルートを配列にします。 起動ログの実際の読み込みパスを確認し、publish ディレクトリと mods/<ModId> の SHA-256 を比較して、同じ publish の完全な一式を配置してください。

完全な規則は Pack 形式 を参照してください。

問題を報告する

ゲーム、RitsuLib、Live2D のバージョン、関連する [Live2D] ログ、発生シーン、モデルまたは Pack を共有可能かを添えてください。 個人パスや機密情報はログから削除してください。