アセット管理ガイド

kaedevn では、背景画像・キャラクター立ち絵・オーバーレイ・音声などの素材を「アセット」として一元管理します。アップロードされたアセットには自動で slug（識別子）が生成され、スクリプトやブロックから参照できます。

🗂️ アセットは 3 つの層でできている

kaedevn のアセットは「公式アセット」「マイアセット」「プロジェクトアセット」の 3 層構造になっています。名前が似ていて紛らわしいので、まずここを押さえると以降がすっきり理解できます。

3 層の違い（早見表）

関係をフロー図で

┌──────────────────────┐         ┌──────────────────────┐
│  📚 公式アセット       │         │  👜 マイアセット       │
│  （運営が用意する     │         │  （あなたがアップロード │
│   共用素材）          │         │   した個人素材庫）     │
└──────────┬───────────┘         └──────────┬───────────┘
           │ 「使う」ボタン                  │ 「インポート」ボタン
           │ で取り込む                      │ で取り込む
           ↓                                ↓
           ┌──────────────────────────────────────────┐
           │  📁 プロジェクトアセット                  │
           │  （この作品の中で実際に参照される素材）    │
           │  • slug（例: forest_evening）で参照       │
           │  • 直接アップロードもこの層に入る         │
           └──────────────────────────────────────────┘
                         ↓
           ┌──────────────────────────────────────────┐
           │  ブロック・スクリプトから使う             │
           │  例: @bg id="forest_evening"             │
           └──────────────────────────────────────────┘

📚 公式アセット

運営（admin）が用意した共用素材。プリセットの背景・立ち絵・BGM などがあり、全ユーザーが共通で見られます。

• 見る場所: エディタの「公式アセット」タブ、AI 作品生成時の候補素材
• 編集: 運営のみ
• あなたの作品で使うには: 「使う」ボタンを押してプロジェクトに取り込む（そのプロジェクト限定で使えるようになる）
• 実体はコピーされない（blobPath を共有）ため、ストレージは膨れません
• 新規プロジェクト作成時には、ファンタジー世界のプリセットが自動で取り込まれます

👜 マイアセット（Library）

あなたが自分用にアップロードした素材の保管庫。プロジェクトをまたいで使い回せる、あなた専用のライブラリです。

• 見る場所: 「マイアセット」画面（/my-assets）、およびエディタの「ライブラリ」タブ
• 可視性: あなただけ。他のユーザーや運営からも見えません
• アップロード: あなたが /my-assets または各プロジェクトのアップロード画面から
• 作品で使うには: エディタで「インポート」ボタンを押してプロジェクトに取り込む

📁 プロジェクトアセット

実際の作品制作で扱う素材。この作品専用です。公式・マイから取り込んだものも、直接アップロードしたものも、すべてこの層にまとまります。

• 見る場所: エディタ内の「プロジェクト」タブ（既定の表示）
• 管理: slug 編集・プレビュー・削除ができる
• ブロックやスクリプトから参照されるのはこの層のみ（例: @bg id="forest_evening"）
• 他のプロジェクトには引き継がれません（マイアセットは引き継がれます）
• sourceType で由来が分かる: upload（直接）/ official（公式から）/ library（マイから）

よくある混乱ポイント

作者の実際のフロー例

A. 公式の背景を使って 1 シーン作る

公式アセット「森・夕方」を見つける
  → エディタで「使う」→ プロジェクトアセットに追加
  → BG ブロックで「森・夕方」を選択
  → プレビューに反映

B. 自作のキャラ立ち絵を何作品かで使い回す

/my-assets で立ち絵 PNG をアップロード（マイアセットに入る）
  ↓
作品 1 のエディタで「インポート」→ プロジェクトアセットに追加
  ↓
作品 2 のエディタでも同じマイアセットを「インポート」
  ↓
作品 1・2 それぞれのプロジェクトアセットとして独立管理される
（マイアセットを更新しても既存プロジェクトには波及しない）

C. 作品に 1 回だけ使う素材を直接アップロード

エディタの「アップロード」ボタンを押す
  → プロジェクトアセットに直接追加される
  （マイアセットには入らないので、他の作品では使えない）

実装メモ（気になる人向け）

• 公式 / マイ / プロジェクトアセットは DB 上では別テーブル（official_assets / user_assets / assets）だが、Azure Blob 上の実ファイル（blobPath）は共有される
• 「取り込み / インポート」は DB レコードを作るだけで、実体ファイルのコピーは発生しない（ストレージコスト節約）
• プロジェクトアセットは sourceType で 'upload' / 'official' / 'library' を区別しており、エディタ側で元が何だったかを表示できる

---

アセットの種類

• 背景（BG） — シーンの舞台となる背景画像。対応形式: PNG, JPG, JPEG, GIF, WebP / Layer 0（最背面）
• キャラクター（CH） — 立ち絵・表情差分。対応形式: PNG, JPG, JPEG, GIF, WebP / Layer 1
• オーバーレイ（OVL） — 画面上に重ねるエフェクト画像。対応形式: PNG, WebP（透過推奨） / Layer 2
• BGM — ループ再生される背景音楽。対応形式: MP3, OGG
• SE — 効果音（1回再生、重ね掛け可）。対応形式: MP3, OGG
• VOICE — ボイス（1回再生）。対応形式: MP3, OGG

公式アセットを使う

kaedevn には、すぐに使えるプリセット素材が用意されています。

1. エディタの「アセット」タブを開く
2. 「公式アセット」セクションを展開
3. 使いたい素材の「インポート」ボタンをクリック

インポートされたアセットはプロジェクト内にコピーされ、自由に使用できます。

新規プロジェクトの自動セットアップ

新しいプロジェクトを作成すると、ファンタジー世界の背景とキャラクターが自動でインポートされ、サンプルシーン（start → bg → ch → text の4ブロック）が組み立てられた状態で始まります。公式アセットが見つからない場合は start ブロックのみにフォールバックします。

自分の素材をアップロードする

1. エディタの「アセット」タブを開く
2. 「アップロード」ボタンをクリック
3. ファイルを選択（複数選択可）
4. カテゴリ（BG / CH / OVL）を指定
5. アップロード完了後、ブロック編集でそのアセットを選択可能に

slug（識別子）はファイル名から自動生成されます。重複する場合はサフィックスが追加されます。

画像の推奨仕様

• 最大辺 2048px 以下 — 全プラットフォーム（Switch含む）の GPU テクスチャ上限に収まる
• 形式 PNG（透過あり）/ JPG（背景）/ WebP — 軽量かつ互換性が高い
• 解像度の目安 1280x720 以上 — 論理解像度にフィットする
• キャラクター立ち絵 PNG or WebP（透過必須） — 背景の上に自然に重なる

アニメーション素材

• 形式 スプライトシート — 個別 PNG の乱立を防ぎ、ロード効率を確保
• fps 12-15fps — 滑らかさとファイルサイズのバランス

アセット変換ツール

素材の前処理を支援するツールが同梱されています。

• WebP 変換 — PNG / JPG → WebP へ変換（ファイルサイズ大幅削減）
• mp4topng — MP4 動画 → PNG フレーム連番に分解
• rmbg — 背景の自動除去（立ち絵の切り抜き）

アセットの整理

アセットはカテゴリで自動分類されます。アセットパネルではフィルタリングやグリッド表示で素材を素早く見つけられます。

• カテゴリフィルタ: BG / CH / OVL / Audio で絞り込み
• 検索: ファイル名・slug で検索
• グリッド表示: サムネイル付きで素材を一覧

アセットをブロックで使う

BG ブロックや CH ブロックの編集画面で「アセットを選択」をクリックすると、プロジェクト内のアセット一覧が表示されます。使いたい素材をクリックするだけで設定完了です。

マルチプラットフォーム対応

アセットの仕様は全プラットフォーム共通です。一度アップロードした素材は Web でも Android でも Switch でもそのまま使えます。詳しくは「アセットのポータビリティ」ドキュメントを参照してください。

• 画像 2048px 以下 → 全 GPU で安全
• ネイティブエンジンの LRU キャッシュで自動メモリ管理
• セーブデータにはアセット ID（参照）のみ保存

関連ドキュメント

• キャラクター設定ガイド — キャラクターと表情差分の設定方法
• アセットのポータビリティ — マルチプラットフォーム対応の詳細
• エディタ完全ガイド — エディタの全機能と基本操作