メインコンテンツまでスキップ

<pc-sprite-clip>

<pc-sprite-clip>タグは、親の<pc-sprite>の名前付きアニメーションクリップを1つ宣言します。スプライトアセットのフレームを、指定したレートで順に、1回またはループして再生します。いくつか組み合わせるとキャラクターにできること（idle、run、jump）がそろい、スプライトのclip属性が再生するものを選びます。

使用法
  • <pc-sprite>コンポーネントの直接の子である必要があります。再生されるのは、そのスプライトがtype="animated"のときだけです。
  • nameは必須で、その<pc-sprite>の中で一意である必要があります。名前のないクリップや、先にあるクリップがすでに使っている名前のクリップは、警告を出して追加されません。

クリップの再生のしかた​

クリップは、スプライトassetのフレームを、そのアセットのframe-keysに並んだ順に再生します。そのため、クリップ用のスプライトアセットは再生順にフレームを列挙します。各クリップは専用のスプライトアセットを持ち、兄弟のクリップと同じアトラスから切り出すことも、別のアトラスから切り出すこともできます。宣言のしかたはスプライトアセットを参照してください。

fpsがペースを、フレーム数が長さを決めます。6フレームをfps="12"で再生すると0.5秒です。fpsのデフォルトは0で、クリップが進まなくなります。デフォルトのままのクリップは最初のフレームを表示し続けるため、動かしたいクリップにはすべてレートを指定してください。親スプライトのspeedがこれに乗算されるため、すべてのクリップをまとめて遅くしたり速くしたりできます。

最後のフレームで何が起こるかはloopによって決まります。

  • ループするクリップは最初のフレームからやり直し、スプライトコンポーネントがloopを発火します。
  • ループしないクリップは最後のフレームで止まってそれを表示し続け、スプライトコンポーネントがendを発火します。スプライトのclipに再びその名前を設定すると、もう一度再生されます。クリップの再生を参照してください。

負のfpsはクリップを逆再生します。それでも再生は最初のフレームから始まるため、ループするクリップはそこから残りのフレームを逆順にたどります。ループしないクリップは、すでに終端にいるため、すぐに終了します。

属性​

属性タイプデフォルト説明
assetAsset ID-クリップが再生するフレームを持つスプライトのスプライトアセットID（sprite型アセットを参照する必要があります）。フレームはframe-keysの順に再生されます
fpsNumber"0"クリップを再生するレート（1秒あたりのフレーム数）。負の値では逆再生します。0ではクリップが進まなくなり、現在のフレームにとどまります。0のまま再生を始めたクリップでは、それが最初のフレームです
loopBoolean"false"クリップがループするかどうか。ループしないクリップは最後のフレームで止まります
nameString-クリップの名前。親の<pc-sprite>のclip属性はこの名前でクリップを選びます。必須で、<pc-sprite>の中で一意である必要があります

すべての属性はライブです。fpsやloopの変更は再生中のクリップにもすぐに適用され、assetを変更するとクリップが再生するフレームが入れ替わります。nameを変更すると、古い名前のクリップが削除され（再生中であれば停止します）、新しい名前で追加されます。スプライトのclipがその新しい名前を指していれば、それが再生されます。

どの<pc-asset>も指さないassetでは、クリップに表示するフレームがなくなり、警告も出ません。クリップが何も再生しないときはIDを確認してください。

読み込み​

要素は、クリップが親のスプライトコンポーネントに追加された時点で準備完了になります。これはコンポーネントが存在するとすぐに行われます。クリップのスプライトアセットはコンポーネント自身が読み込むため、フレームが届く前でもクリップを選んで再生でき、届いた時点で表示されます。

名前がない、または先にあるクリップがその名前を持っているために追加されなかったクリップは、準備完了になりません。先にあるクリップが削除されるか名前を変えると、待っていたクリップがその名前を引き継ぎます。

準備完了の状態は、クリップが属するコンポーネントに従います。そのコンポーネントがなくなると（<pc-sprite>が削除されたとき、またはそれを含む<pc-node>のバインドが外れたとき）、すべてのクリップはエンジンのクリップを手放して準備完了ではなくなり、ready()は次に準備完了になるまで待ちます。新しいコンポーネントが代わりに作られると（<pc-sprite>が再び挿入されたとき、または<pc-node>が再びバインドされたとき）、すべてのクリップがそこに追加され、再び準備完了になってreadyをもう一度発火します。<pc-model>の直下にあるスプライトは、モデルが再読み込みされてもこの影響を受けません。モデルのホストエンティティは再読み込みの後も残り、スプライトコンポーネントとそのクリップも一緒に残ります。

例​

ループするspinと単発のcollectを持つ2枚のコインです。右のコインのspinはfpsが負なので、反対向きに回ります。Collectは単発のクリップを再生し、終わると最後のフレームを表示し続けます。もう一度クリックすると再生し直します。collectクリップにloopを付けたり、別のfpsやfps="0"を試したりしてみましょう:

ライブサンプル
<pc-app>
    <pc-asset id="atlas" type="textureatlas" src="https://developer.playcanvas.com/assets/sprites.png" srgb mipmaps="false" min-filter="nearest" mag-filter="nearest" data='{ "frames": {
        "coin-spin-0": { "rect": [238, 32, 12, 12], "pivot": [0.5, 0.5] },
        "coin-spin-1": { "rect": [238, 19, 12, 12], "pivot": [0.5, 0.5] },
        "coin-spin-2": { "rect": [0, 13, 12, 12], "pivot": [0.5, 0.5] },
        "coin-spin-3": { "rect": [150, 9, 12, 12], "pivot": [0.5, 0.5] },
        "coin-spin-4": { "rect": [163, 9, 12, 12], "pivot": [0.5, 0.5] },
        "coin-spin-5": { "rect": [176, 9, 12, 12], "pivot": [0.5, 0.5] },
        "coin-collect-0": { "rect": [232, 6, 12, 12], "pivot": [0.5, 0.5] },
        "coin-collect-1": { "rect": [0, 0, 12, 12], "pivot": [0.5, 0.5] },
        "coin-collect-2": { "rect": [189, 0, 12, 12], "pivot": [0.5, 0.5] },
        "coin-collect-3": { "rect": [202, 0, 12, 12], "pivot": [0.5, 0.5] },
        "coin-collect-4": { "rect": [215, 0, 12, 12], "pivot": [0.5, 0.5] }
    } }'></pc-asset>
    <!-- クリップごとに1つのスプライトアセット。フレームキーは再生順に並べます -->
    <pc-asset id="coin-spin" type="sprite" atlas="atlas" frame-keys="coin-spin-0 coin-spin-1 coin-spin-2 coin-spin-3 coin-spin-4 coin-spin-5" pixels-per-unit="16"></pc-asset>
    <pc-asset id="coin-collect" type="sprite" atlas="atlas" frame-keys="coin-collect-0 coin-collect-1 coin-collect-2 coin-collect-3 coin-collect-4" pixels-per-unit="16"></pc-asset>
    <pc-scene>
        <pc-entity name="camera" position="0 0 10">
            <pc-camera projection="orthographic" ortho-height="1" clear-color="#161a3c"></pc-camera>
        </pc-entity>
        <pc-entity name="coin" position="-0.6 0 0">
            <pc-sprite type="animated" clip="spin">
                <pc-sprite-clip name="spin" asset="coin-spin" fps="10" loop></pc-sprite-clip>
                <pc-sprite-clip name="collect" asset="coin-collect" fps="15"></pc-sprite-clip>
            </pc-sprite>
        </pc-entity>
        <pc-entity name="coin" position="0.6 0 0">
            <pc-sprite type="animated" clip="spin">
                <!-- 負のfpsはクリップを逆再生します -->
                <pc-sprite-clip name="spin" asset="coin-spin" fps="-10" loop></pc-sprite-clip>
                <pc-sprite-clip name="collect" asset="coin-collect" fps="15"></pc-sprite-clip>
            </pc-sprite>
        </pc-entity>
    </pc-scene>
</pc-app>
<div class="controls">
    <button id="collect">Collect</button>
    <button id="spin">Spin</button>
</div>
<style>
    .controls {
        position: absolute;
        top: 12px;
        left: 12px;
        display: flex;
        gap: 8px;
    }
</style>
<script type="module">
    const coins = document.querySelectorAll('pc-sprite');
    const play = name => coins.forEach(coin => coin.setAttribute('clip', name));

    document.getElementById('collect').onclick = () => play('collect');
    document.getElementById('spin').onclick = () => play('spin');
</script>

JavaScriptインターフェース​

SpriteClipElement APIを使用して、<pc-sprite-clip>要素をプログラムで作成および操作できます。

asset、fps、loop、nameも、上記の属性に対応するプロパティとして利用できます。読み取り専用のspriteAnimationClipプロパティは、この要素が宣言するエンジンのSpriteAnimationClipです。要素が準備完了でないときは常にnullです（読み込みを参照してください）。スプライトコンポーネントと同じplay、pause、resume、stop、end、loopイベントを、自分自身についてだけ発火します。また、再生中かどうかをisPlayingで、スプライトが読み込まれた後は長さ（秒）をdurationで示します。

import { whenReady } from '@playcanvas/web-components';

const clip = await whenReady('pc-sprite-clip[name="land"]');

clip.spriteAnimationClip.on('end', () => console.log('landed'));

クリップは実行時に追加・削除できます。<pc-sprite-clip>を追加するとそのクリップが加わり、スプライトのclipがすでにその名前を指していれば、別のクリップが再生中でもすぐに再生されます。削除するとそのクリップが除かれ、それが再生中だった場合、スプライトは停止し、別のクリップが再生されるまで何も表示しません。

const slime = document.querySelector('#slime');
slime.clip = 'wave'; // この名前のクリップはまだないため、現在のクリップが再生を続けます

const clip = document.createElement('pc-sprite-clip');
clip.setAttribute('name', 'wave');
clip.setAttribute('asset', 'slime-wave');
clip.setAttribute('fps', '10');
slime.appendChild(clip); // クリップが追加されるとすぐにwaveが再生されます

関連項目​

  • <pc-sprite> — クリップが属するスプライトコンポーネント
  • <pc-asset> — クリップが再生するフレームを持つスプライトアセット

サンプル: Sprites