KKアニメーション・タイムライン ADV再生プラグイン

『EC_ADVPlayLoadKKAnime』の日本語取扱説明書（マニュアル）です。ゲーム内での導入、初期設定、基本操作から高度なタイムライン編集・デバッグ機能まで網羅しています。

【EC】KKアニメーション・タイムライン ADV再生プラグイン

EC_ADVPlayLoadKKAnime 使用説明書

1. 概要

本プラグインは、『エモーションクリエイターズ（Emotion Creators / EC）』のADVパートにおいて、**『コイカツ！ (Koikatu! /
KK)』のアニメーションデータ（.unity3d /
.zipmod）およびStudioタイムライン（Timeline）**をADVフキダシに埋め込み、再生・制御するための拡張プラグインです。

主な特徴

– KK本体＆zipmodの直接読み込み: コイカツのインストールフォルダから直接 .unity3d や .zipmod 内のアニメーションを読み込み可能。
– Studioシーン/タイムラインの再生:
コイカツStudioで作成したシーン（.png）からタイムライン（IK/FK/表情/視線目標）を抽出して完全同期再生。
– データ保持システム（跨cut保留）: 次のカットに切り替わってもKKアニメーションやタイムラインを中断させず維持可能。
– タイムラインPNG出力機能:
EC側のカメラで撮影したスクリーンショット付きの「タイムラインPNG」として保存。次回からコイカツStudioを開かずに単体で再利用・ギャラリー再生が可能。
– 非破壊ボーン階層適応: ECとKKで異なるボーン構造（cf_n_* 中間層）を非破壊で自動補正し、いつでもEC標準状態へ完全復元可能。

2. 導入方法と必要ファイル

インストール

1. EC_ADVPlayLoadKKAnime.dll を EmotionCreators\BepInEx\plugins フォルダに入れます。
2. 以下の設定・テーブル用ファイルを EmotionCreators\UserData\EC_ADVPlayLoadKKAnime\
フォルダに配置します（初回起動時に自動生成されるものもあります）：
– kk_paths.txt（パス設定）
– kk_anime_table.txt（KK本体アニメーション辞書）
– kk_bone_map.txt（ボーン辞書）

3. ショートカットキー一覧

※GameHubプラグインや EC_ADVPlayLoadVoice が導入されている場合、それらのUI内ボタンからも開くことができます。

4. 初期設定（コイカツパスの指定）

プラグイン起動後、メインウィンドウ下部の「KK 动画库（アニメーションライブラリ）」枠内でパスを設定します。

1. 根目录 (KK Root): コイカツ本体のインストールフォルダ（abdata がある階層）を指定します。「探测
(自動検出)」ボタンでドライブ内を自動探索することも可能です。
2. 基础目录 (Custom): abdata\custom など、通常モーションの入ったパス。
3. H目录 (H-Anim): abdata\h\anim\female;abdata\h\anim\male などのHモーションパス（; で複数指定可）。
4. zipmod目录: mods フォルダ等のzipmod格納先。
5. 「应用 (適用)」を押して保存し、「扫描/刷新列表 (スキャン/更新)」をクリックすると、モーションがリスト化されます。

5. 基本的な使い方

A. 通常のKKモーション（.unity3d / zipmod）をフキダシに登録する

1. ECのADVエディタで、モーションを設定したいフキダシ（セリフ枠）を選択します。
2. Alt + K で本プラグインを開きます。
3. 「角色槽位 (キャラ枠)」で適用したいキャラの番号（0, 1…）を選択します。
4. 下部のライブラリリストからアニメーションを探します：
– CSVリストアニメーション (▶ マーク): クリックするだけでコントローラーとクリップが即座にセットされます。
– 裸のunity3d/zipmod (▸ マーク): 展開して目的のコントローラー名をクリックします。
5. 上部のパラメータを設定します：
– 速度: 再生速度倍率（0.5 / 1.0 / 2.0 など）。
– 循环 (ループ): チェックを外すと1回のみ再生（「一遍时长」で停止までの秒数を指定可能）。
– 骨架重挂 (ボーン折畳み): 推奨「ON」。EC特有の頭部沈み込みを防止します。
– 关掉FK/IK覆盖层: 推奨「ON」。EC本来のポーズシステムとの競合を防ぎます。
6. 「新建/更新条目 (新規/更新)」 → 「写入气泡 (フキダシに書き込み)」をクリックします。
– ※データはフキダシの第2テキストレイヤーにXMLとして保存されます。

B. コイカツStudioシーン（タイムライン）を適用する

コイカツStudioで作成したシーン（.png）のモーションキーフレームをそのまま再生します。

1. メインウィンドウ最下部の「Studio 场景」枠を見ます。
2. 场景目录（初期値: UserData\Studio\scene）からシーンPNGを一覧表示し、目的のシーンを選択します。
3. 「用哪个角色的轨道 (どのキャラのトラックを使うか)」で、シーン内のキャラ番号（角色0, 角色1 など）を選択します。
4. 基礎アニメーション（重要）:
– タイムラインのIKは「コイカツ側のベースモーション」の上に乗せる形で記録されています。
– 「用场景角色的动画当基础动画
(シーンキャラのモーションを基礎にする)」のボタンを押すと、シーン保存時の基礎ポーズ・モーションが自動セットされます。
5. 「套用到当前条目并写入气泡 (適用してフキダシに書き込み)」を押すと、タイムライン指定を含めたデータがフキダシに書き込まれます。

C. 「跨cut保留 (カットを跨いで維持)」の使い方

通常、ADVのカット（LoadCut）が切り替わると、EC本体の仕様によりポーズやモーションがリセットされます。

– 「跨cut保留」にチェックを入れる:
次のカットへ進んでもEC側のリセット処理をプラグインがブロックし、KKモーション・タイムラインが途切れることなくそのまま再生され続けます。
– 保留を終了させる場合: 元のEC標準モーションに戻したいカットのフキダシを選択し、「在此cut解除保留 (このカットで解除)」
を押してフキダシに書き込んでください。

6. タイムラインPNG（図庫/ギャラリー）機能

Studioシーンを解析したタイムラインデータを、ECのゲーム画面スクリーンショット付きの単体PNG（タイムラインPNG）として書き出すことができます。これを行うと、以降はコイカツ本体のシーンを読み込む必要がなくなります。

1. タイムラインPNGの書き出し（編集機能付き）

1. Studioシーンとキャラ軌道を選択した状態で、「保存为 PNG（画面 + 数据）」をクリックします。
2. 編集ウィンドウが開きます：
– 裁剪 (クロップ): 開始秒数〜終了秒数を指定し、特定区間だけを切り出し可能。
– フィルター: 「動作＋表情」「動作のみ」「表情のみ」を選択可能。
– 拼接 (結合): すでに書き出した別のタイムラインPNGの後ろに、今回のモーションを連続して連結可能。
3. 出力ファイル名を決めて「保存 PNG」をクリックすると、EC画面が撮影され、データが埋め込まれたPNGが生成されます。

2. タイムライン図庫（Alt + L）

書き出したタイムラインPNGをサムネイル一覧で管理するウィンドウです。

– サムネイルをクリックすると、即座に選択状態になります。
– 「试播到当前角色 (現在のキャラで試走)」: その場ですぐプレビュー再生。
– 「写进气泡 (フキダシに書き込み)」: 選択中のADVフキダシにワンクリックで登録。

7. トラブルシューティング＆デバッグ

Q. モーション適用後、首が胸にめり込む・頭が沈む

– 原因: ECとコイカツのボーン階層構造の差によるものです。
– 解決策:
– パラメータの「骨架重挂(EC↔KK中间骨层)」にチェックが入っているか確認してください。
– すでに沈んで戻らなくなった場合は、ヘッダーの「还原槽位 X (スロットXを還元)」または「还原全部」
を押すことで、即座にEC本来のボーン構造と姿勢に復元されます。

Q. キャラクターの周りに青や緑のガイド球（IK操作ボール）が表示されて邪魔

– 対策: プラグイン内部でECのIK/FK操作ボールを自動的に非表示化（SuppressGuides）する処理が常時作動しています。

Q. タイムライン再生時、キャラが高速回転したり関節がねじ切れる

IK目標値の座標不整合が原因の可能性があります。メインウィンドウの「节点屏蔽调试 (ノード遮蔽デバッグ)」を開いて調査してください：

– デバッグ機能:
– 整类屏蔽 (カテゴリ別遮蔽): 全部IK目标や全部FK骨骼をチェックし、IKとFKのどちらが原因か切り分けます。
– 不写IK的position/rotation: 回転のみ、あるいは位置のみを反映させて原因を特定します。
– 一键左右互换: 左右の肩（cf_t_shoulder_L/R）や腰のデータが左右反転していないかワンタッチで入れ替えてテストできます。
– リスト個別遮蔽: 異常な動きをしている特定ボーン（例: cf_t_hand_R
など）のチェックを外すことで、そのボーンのみリアルタイムに無効化できます。

8. 主な設定ファイル解説 (UserData\EC_ADVPlayLoadKKAnime\kk_paths.txt)

テキストエディタで直接編集も可能です：

Root=U:\Koikatu # コイカツ本体のルートディレクトリ
Custom=abdata\custom # 通常アニメーションの場所
H=abdata\h\anim\female;abdata\h\anim\male # Hアニメーションの場所
Zip=mods # zipmodの検索ディレクトリ
Recursive=1 # 通常アニメーションのサブフォルダを再帰検索
ZipRecursive=1 # zipmodフォルダを再帰検索
TimelineDir=UserData\EC_ADVPlayLoadKKAnime\timeline # タイムラインPNGの保存先