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

開始

ブラウザで3Dをレンダリングするまで、ものの1分もかかりません。インストールもビルドステップも不要です。PlayCanvas Web ComponentsをCDNから直接読み込むか、既存のプロジェクトに統合する場合はnpmパッケージをインストールしてください。

インストール​

ライブラリの読み込み方法は2通りあります。どちらにするか迷ったら、まずはCDNから始めましょう。マークアップを一切変更することなく、後からnpmへ切り替えることができます。

  • CDN（インストール不要） — ダウンロードもツールも不要です。最も早く始められる方法で、バージョンを固定すれば本番環境でも問題なく使えます。
  • npm — プロジェクトにすでに package.json や開発サーバー、バンドラーがある場合に適した選択肢です。エンジンとコンポーネントのバージョンを他の依存関係と一緒に管理でき、すべて自前のインフラから配信されます。

どちらの方法を選ぶ場合でも、HTMLファイルにはインポートマップが必要になります。これは、Web ComponentsがPlayCanvas Engine（外部依存関係）を見つけられるようにするためです。インポートマップには @playcanvas/web-components 自体も記載しています。タグを使うだけならこのエントリは不要ですが、これがあると、後で自分で書くJavaScriptからライブラリのAPI（プログラムによるアクセスで紹介します）をインポートできるようになります。

エンジンとコンポーネントの両方を、jsDelivrなどのCDNから読み込みます。pwc.min.mjs（pwc.mjs の半分以下のサイズのミニファイ版ビルド）を使用します。

<script type="importmap">
    {
        "imports": {
            "playcanvas": "https://cdn.jsdelivr.net/npm/playcanvas@latest/build/playcanvas.mjs",
            "@playcanvas/web-components": "https://cdn.jsdelivr.net/npm/@playcanvas/web-components@latest/dist/pwc.min.mjs"
        }
    }
</script>

その後、Web Componentsを次のようにインポートできます。

<script type="module" src="https://cdn.jsdelivr.net/npm/@playcanvas/web-components@latest/dist/pwc.min.mjs"></script>
バージョニング

上記のスニペットでは利便性のために @latest を使用しています。本番環境では確定的なビルドのために特定のバージョンに固定することを推奨します（例: playcanvas@2.x.y、@playcanvas/web-components@x.y.z）。最新の安定版はリリースノートを参照してください: PlayCanvas Engine リリース と Web Components リリース。

最初のページ​

ライトが当たった球体（3Dにおける「hello, world」）をレンダリングする完全なページを次に示します。CDNセットアップを使用しているため、何もインストールする必要はありません。

index.html
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
        <title>My PlayCanvas Web Components App</title>
        <script type="importmap">
            {
                "imports": {
                    "playcanvas": "https://cdn.jsdelivr.net/npm/playcanvas@latest/build/playcanvas.mjs",
                    "@playcanvas/web-components": "https://cdn.jsdelivr.net/npm/@playcanvas/web-components@latest/dist/pwc.min.mjs"
                }
            }
        </script>
        <script type="module" src="https://cdn.jsdelivr.net/npm/@playcanvas/web-components@latest/dist/pwc.min.mjs"></script>
        <style>
            body {
                margin: 0;
                overflow: hidden;
            }
            pc-app {
                width: 100%;
                height: 100vh;  /* 動的ビューポート単位に未対応のブラウザ向けフォールバック */
                height: 100dvh;
            }
        </style>
    </head>
    <body>
        <pc-app>
            <pc-scene>
                <pc-entity name="camera" position="0 0 3">
                    <pc-camera></pc-camera>
                </pc-entity>
                <pc-entity name="light" rotation="45 45 0">
                    <pc-light></pc-light>
                </pc-entity>
                <pc-entity name="ball">
                    <pc-render type="sphere"></pc-render>
                </pc-entity>
            </pc-scene>
        </pc-app>
    </body>
</html>

<style>ブロックの中で1つ触れておきたいルールがあります。<pc-app>は<video>要素と同じようにサイズが決まる、ページのCSSが制御するブロックレベルのボックスで、デフォルトではわずか300×150ピクセルです。上記のpc-appルールはこれをビューポート全体に引き伸ばしています。通常のページレイアウトにシーンを埋め込みたい場合は、好きなサイズを指定してください。詳細はサイズ指定を参照してください。

これを index.html として保存し、ブラウザで開いてください。次のように表示されるはずです。

指向性ライトに照らされた白い球体

注記

npmインストールを使用する場合は、インポートマップとscriptタグを、上のnpmタブに示した /node_modules/... のものに置き換えてください。

このシーンはCodePenでも公開されているので、このページを離れずに試すこともできます。

エディタサポート​

このパッケージはCustom Elements Manifestを同梱しており、エディタはこれを使ってHTMLの記述時にタグと属性の補完、有効な属性値、ホバードキュメントを提供します。

VS Code — ワークスペースの .vscode/settings.json に以下を追加します。

{
  "html.customData": [
    "./node_modules/@playcanvas/web-components/dist/vscode.html-custom-data.json"
  ]
}

JetBrains IDE（WebStorm、IntelliJ IDEA）— 設定は不要です。IDEが同梱の web-types.json を自動的に検出します。

その他のツール — マニフェスト本体は @playcanvas/web-components/dist/custom-elements.json にあり、パッケージの customElements フィールドで宣言されています。lit-analyzer やStorybookなどのツールはこれを通じてマニフェストを見つけます。

次のステップ​

  • シーンを構築するに進んで、要素を1つずつ積み上げながらシーンを作りましょう。さらにマテリアル、影、地面まで作り込みます。
  • タグリファレンスにざっと目を通して、宣言できるすべての要素を確認しましょう。
  • サンプルを眺めて、コンポーネントで何ができるかを見てみましょう。