よつばゲームズ
ノード一覧に戻る

キーフレームクリップ

keyframe_clip

ユーザー向け animation clip を保持し、RecordedLayer 入力を clip 形式へ橋渡しできます

確認済み
解説あり

入力ポート

名前型説明
パス
path
Path
clip editor 内で直接編集する元 Path（オプション）
画像
image
Image
clip editor 内で直接編集する元 Image（オプション）
レイヤー
layer
RecordedLayer
RecordedLayer から clip へ橋渡しするオプション入力です。接続時はその場で AnimationClip へ変換します
進行度
progress
Float
正規化進行度（0.0〜1.0）のオプション入力です。未接続ならアニメーション時間に自動追従します

出力ポート

名前型説明
パス
path
Path
繋いだパスにアニメーションを適用した「現在フレーム」の結果です。下流に加工を重ねて、最後にアニメーションレンダーへ繋ぐと全フレームが再生されます
画像
image
Image
繋いだ画像にアニメーションを適用した「現在フレーム」の結果です。下流に加工を重ねて、最後にアニメーションレンダーへ繋ぐと全フレームが再生されます
クリップ
clip
AnimationClip
AnimationClip document です
レイヤー
layer
RecordedLayer
同じ clip を RecordedLayer として見た bridge 出力です
値
value
Map
指定時刻で評価した clip の現在値です
値(Float)
value_float
Float
クリップの「数値」トラックのいまの値です。数値パラメータのピンに繋ぐと、そのパラメータをキーフレームで動かせます(数値トラックが無いときは 0 が出ます)
概要
summary
Text
短い概要文字列です
スプライトシート
spritesheet
SpriteSheet
書き出しフレーム間隔でサンプルしたスプライトシートです
フレーム数
frame_count
Int
スプライトシート書き出しに使う総フレーム数です
FPS
fps
Int
プロジェクトのアニメーション既定から取った FPS です
列数
columns
Int
スプライトシート配置で実際に使われた列数です
行数
rows
Int
スプライトシート配置で実際に使われた行数です
フレーム幅
frame_width
Int
スプライトシート内の1フレーム幅です
フレーム高さ
frame_height
Int
スプライトシート内の1フレーム高さです
配置順
fill_order
Text
スプライトシート配置で使われたフレームの埋め順です

パラメータ

名前型既定値範囲説明・選択肢
クリップデータ
clip_data
CustomData
——

エディタ管理の AnimationClip 保存データ

概要

キーフレームで動きを作るタイムライン系ノードです。波形ノードが「数式の動き」 なら、こちらは「このフレームでこの形」を直接指定する作り方。パスや画像の変形を 専用エディタでポーズ登録・記録し、AnimationClip として再生・書き出しできます。

使い方のポイント

  • モーションとの使い分け: 周期的・機械的な動き→motion ノード、 「振りかぶって→溜めて→振り下ろす」のような演技→このノード
  • 基本の流れ: path か image をつなぐ → エディタでフレームを動かしながら pose mode でキーを打つ → play で確認 → 同名の パス / 画像 出力で下流へ。 出力は「現在フレームの適用結果」なので、後段にフィルタや motion 系を重ねて 最後にアニメーションレンダーへ繋げば全部まとめて再生される。 シートが直接欲しいときは spritesheet 出力でもよい
  • クリップの尺・キー位置はフレーム基準。新規クリップの尺と fps は プロジェクトのアニメーション既定(キャンバスバー)に従う
  • progress 入力(0〜1)を外部から与えると、クリップの評価時刻をグラフ側で 制御できる(time_source 連携や、進行度による演出分岐)
  • value_float 出力は、クリップ内の最初の数値(Scalar)トラックを現在の評価時刻で 評価したただの Float。数値パラメータ 1 個をキーフレームで動かす用途 (Inspector の 🎞️ アニメーションボタン「キーフレーム」フレーバーはこの出力を 対象パラメータへ自動接続する)に使う。キーの範囲外では端のキー値にクランプされ、 補間はトラックの補間設定(ease_in_out と共通のイージング語彙)に従う。 Scalar トラックが無いクリップでは 0.0 を出す
  • source ノード自体は書き換えられない(非破壊)。元の形はいつでも無傷

よくある失敗

  • キーを打ったのに動かない: キーが1つだけだと補間できない。始点と終点の 最低2キーが必要
  • エディタと出力が違って見える: エディタの表示は「source+clip適用後」。 同じ見た目を下流に流すのは パス/画像 出力(現在フレームの適用結果)。 clip/value はアニメデータそのもの、spritesheet は全フレームのシートなので、 どの出力を使っているかを確認する

interactive editor

Keyframe Clip は source 埋め込み型の interactive editor を持ちます。

editor でできること:

  • source 切替
    • Path と Image のどちらを今編集するか選べます
  • pose mode
    • 現在時刻の形を 1キーの pose として保存します
  • record mode
    • drag 軌跡を開始/終了範囲へ記録します
  • play / stop / loop
    • editor 内 preview をそのまま再生できます
  • key list
    • 保存済み key を一覧で見て、そこへジャンプできます
  • export
    • 尺 D フレームを t=0〜D-1 でサンプルした spritesheet PNG (最終フレームは「先頭に戻る直前」で止まるループ規則)
    • 実キーのフレームだけをまとめた key PNG 一括書き出し
    • 現在フレーム PNG 書き出し

重要:

  • source node 自体は書き換えません
  • editor 上で見えているのは source + clip 適用後の姿 です
  • キーを切り替えると、その key pose がそのまま表示されます
  • 画像 source は v1 では移動 / 回転 / 拡大縮小の transform を編集します
    • 回転は外周付近へマウスを持っていくと ↺ が出る zone drag 方式です
  • path source は point / handle を直接動かして pose を作ります

技術詳細

AnimationClip は P07 の user-facing animation 型です。
内部では explicit な track / keyframe を持ち、必要に応じて RecordedLayer と相互 bridge します。

layer 入力が接続されている場合は:

  • layer 入力を base clip へ変換
  • clip_data を local clip として重ねる
  • 出力では同じ clip を AnimationClip / RecordedLayer の両方で見られます

path / image 入力は editor 用の source でもあり、同時に downstream の ClipApplyPath / ClipApplyImage と組み合わせる前提です。

使用例

Path をキー編集する

  1. BezierPath を作る
  2. KeyframeClip.path へつなぐ
  3. KeyframeClip editor を開く
  4. フレーム 0 で point / handle を動かして最初の pose を作る
  5. 最終フレームで別 pose を作る
  6. KeyframeClip.clip を ClipApplyPath.clip へつなぐ
  7. BezierPath.path を ClipApplyPath.path へつなぎ、progress(0〜1)を Float Input か Time Source で動かして再生する

Image をキー編集する

  1. PixelCanvas.image などの image source を作る
  2. KeyframeClip.image へつなぐ
  3. KeyframeClip editor を開く
  4. 画像本体をドラッグして移動、角で拡大、外周近くの ↺ zone で回転する
  5. KeyframeClip.clip を ClipApplyImage.clip へつなぐ
  6. source image を ClipApplyImage.image へつなぎ、progress を動かして再生する

clip editor から書き出す

  1. KeyframeClip editor を開く
  2. 尺(フレーム数) を決める(初期値はプロジェクト既定のフレーム数)
  3. 列数 を必要なら指定する
  4. スプライトシートPNG で全フレームを書き出す
  5. キー画像一括 で実キーだけを個別 PNG として書き出す

補足:

  • Image source の spritesheet は尺 D フレームを t=0〜D-1 でサンプルして並べます
  • 列数 = 0 の時は横一列ではなく、自動でほぼ正方形に近い配置を選びます
  • 配置順は 右へ (row_major) と 下へ (column_major) を選べます
  • node 出力は P07A の SpriteSheet 契約
    • spritesheet は専用型
    • frame_count / fps / columns / rows / frame_width / frame_height / fill_order は helper metadata 出力 を同じ書き出し設定で返します
  • columns / rows / frame_width / frame_height / fill_order 出力を使うと、後段でフレーム分割しやすくなります
  • Path source の書き出しは editor 上の line preview を透明背景 PNG にしたものです
  • 最終見た目で書き出したい場合は ClipApplyPath -> PathStroke -> AnimationRender を使ってください

関連ノード

  • clip_apply_path / clip_apply_image — クリップをパス・画像に適用して下流へ流す
  • animation_render — 最終見た目でのスプライトシート化
  • clip_mixer / clip_loop_fit — クリップの合成・ループ調整
  • motion 等の波形 — 数式的な動きで足りる場合

時刻・複数トラック・データ保護

  • 時刻入力は progress(0〜1 の正規化進行度)一本です。progress * 尺(フレーム数) を 評価します。未接続ならグラフの評価時刻を正規化進行度として扱います。 旧バージョンの絶対秒 time ピンは廃止され、旧プロジェクトの time 接続は 読込時に progress へ自動で繋ぎ替えられます。
  • Time Source の 0〜1 出力は progress へ接続してください。
  • クリップの尺・キー位置はフレーム基準(v2)。旧 v1(秒基準)の clip_data は 読込時に旧「1コマ秒」設定から fps を逆算してフレームへ自動変換されます (設定が無い場合は旧既定 10fps で換算)。
  • 画像の Transform track が複数ある場合、プレビューと書き出しには全 track を 順に適用します。キャンバス操作、キー追加・移動・削除は選択中 track だけが対象です。
  • 尺を短くしても範囲外キーは削除しません。評価時刻は 0〜尺に clamp されます。不要なら editor の「範囲外キーを削除」、比率を保って収めるなら 「全キーを尺へ縮尺」を明示的に実行します。
  • 非空の壊れた clip_data は空データへ読み替えません。元文字列を保持して保存を止め、 コピーまたは確認付きリセットを選べるエラー画面を表示します。
  • キー間の補間はトラックごとに選べ、イージングの語彙・カーブは ease_in_out ノードと共通です(リニア/イーズイン/…/バウンスアウト/ステップ)。

関連ノード

クリップ適用パスclip_apply_pathアニメーションレンダーanimation_renderクリップミキサーclip_mixerモーションmotion
ノード一覧に戻る
キーフレームクリップ — PixPipeline ノード解説