tresjs-core-skilld

@tresjs/core 5.9.0

Three.js 用 Vue カスタムレンダラーです。THREE クラス名の先頭に Tres を付けると、コンポーネントになります（<TresMesh>、<TresBoxGeometry>）。準備済みソース：package.json、dist/tres.d.ts（公開型）、dist/tres.js。

生成時点の npm dist-tag：latest 5.9.0、rc 5.0.0-rc.0、next 5.0.0-next.6、beta 2.0.0-beta.13、alpha 5.0.0-alpha.2。

環境の制限

• v5 以降は ESM のみです。UMD と require() は使用できません。import { TresCanvas } from '@tresjs/core'。
• ピア依存関係：vue >=3.4、three >=0.133（package.json:44-46）。three ^0.184 に対してビルドされています。
• 時刻ソース：r179 以降の Timer、古い three では Clock にフォールバックします（dist/tres.d.ts:962-970）。
• WebGPU は実験的機能です。three/webgpu の Renderer を指定した renderer プロパティが必要です（references/webgpu.md を参照）。

セットアップ

pnpm i @tresjs/core three
pnpm i @types/three -D   # TypeScript

Vite：templateCompilerOptions を Vue プラグインに展開してください。そうしないと、Tres コンポーネントが不明なカスタム要素として警告されます（README.md:36-50）。

import { templateCompilerOptions } from '@tresjs/core'
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [vue({ ...templateCompilerOptions })],
})

コンパイラーオプションのみを必要とするホスト向けに、別のサブパスエクスポート @tresjs/core/template-compiler-options も用意されています（package.json:21-25）。Nuxt では手動セットアップの代わりに @tresjs/nuxt を使用してください。

コアモデル

• コンポーネントカタログは THREE 名前空間から自動生成されます。クラス名の先頭を大文字にして Tres を付けた名前になり、ケバブケース（<tres-mesh>、v5.1.0 以降でサポート）も使用できます（dist/tres.d.ts:497-509）。
• args はコンストラクター引数を渡します：<TresBoxGeometry :args="[1, 2, 3]" />。リアクティブな args を変更するとインスタンス全体が再作成されます。生成後に設定できるものには、プロパティを使用してください（dist/tres.d.ts:405-411）。
• プロパティはインスタンスのプロパティに対応します。数学型には省略記法を使用できます：:position="[1, 2, 3]"、:rotation="[0, Math.PI, 0]"、color="#00ff00"（dist/tres.d.ts:457-485）。
• 子のマテリアル／ジオメトリは attach によって自動でアタッチされます：<TresMesh><TresBoxGeometry /><TresMeshNormalMaterial /></TresMesh> は明示的な attach なしで動作します。
• THREE 以外のクラスを <TresMyObject> として使用する場合は、使用前に extend({ MyObject }) を呼び出してください（dist/tres.d.ts:872-874）。
• <primitive :object="existingThreeObject" /> は、JavaScript で作成したオブジェクトをマウントします。破棄処理は管理しないため、手動で破棄してください（references/performance.md を参照）。

最小限のシーン：

<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
</script>

<template>
  <TresCanvas shadows>
    <TresPerspectiveCamera :position="[3, 3, 3]" :look-at="[0, 0, 0]" />
    <TresMesh>
      <TresBoxGeometry :args="[1, 1, 1]" />
      <TresMeshNormalMaterial />
    </TresMesh>
    <TresDirectionalLight :position="[3, 3, 3]" :intensity="1" cast-shadow />
  </TresCanvas>
</template>

カメラを明示的に指定しない場合、デフォルトの PerspectiveCamera が作成されます（dist/tres.d.ts:682-685）。

把握しておくべき API の変更

v5 の破壊的変更（references/migration-v4-v5.md に従って移行してください）：

• useLoader は Promise ではなく、リアクティブな状態 { state, isLoading, error, progress, load } を返します（dist/tres.d.ts:40-65）。
• ポインターイベントにはネイティブ DOM 名を使用します。@pointer-down ではなく @pointerdown です。イベントが発火するのは、最初に交差したオブジェクトのみです。
• useTexture は @tresjs/cientos に移動しました。useRenderLoop、useCamera、useSeek、useRaycaster、useTresReady、useTresEventManager、useLogger は削除されました。代替：useLoop、useTres、useGraph、@ready イベント。
• useTresContext().camera はカメラマネージャーです。アクティブなカメラインスタンスには useTres().camera を使用してください（dist/tres.d.ts:574-606）。
• WebGL コンテキストのプロパティ（alpha、antialias、depth、stencil、powerPreference、logarithmicDepthBuffer、preserveDrawingBuffer、failIfMajorPerformanceCaveat）は読み取り専用です。マウント時に一度だけ設定してください（dist/tres.d.ts:141-206）。

最近の追加機能：

• 5.9.0：TresPortal コンポーネントは、子を任意の Object3D／Scene ターゲットに付け替えます（dist/tres.d.ts:853-858）、https://docs.tresjs.org/api/components/tres-portal
• 5.9.0：isWebGPURenderer ガードとリアクティブな context.isWebGPU フラグ（dist/tres.d.ts:350-367, 1204-1222）
• 5.9.0：shadowMapType は WebGL では PCFShadowMap、WebGPU では PCFSoftShadowMap がデフォルトです（dist/tres.d.ts:250-255）
• 5.8.0：fpsLimit プロパティでレンダリング FPS に上限を設定できます（dist/tres.d.ts:692-696）
• 5.7.0：Timer から Clock へのフォールバックにより、three <r179 との互換性を実現（dist/tres.d.ts:962-970）
• 5.5.0：独自の <canvas> を使用するための TresCanvasContext（Context コンポーネント）（dist/tres.d.ts:680-708）
• 5.3.0：customRendererOptions.primitivePrefix で <primitive> の名前を変更できます（dist/tres.d.ts:622-625）
• 5.2.0：TresCanvasProps／TresCanvasEmits 型をエクスポート（dist/tres.d.ts:776-781）
• 全履歴：https://github.com/Tresjs/tres/blob/main/packages/core/CHANGELOG.md

よくあるタスク

フレームレートに依存しないアニメーション（delta は秒単位）：

<script setup lang="ts">
import { useLoop } from '@tresjs/core'
const { onBeforeRender } = useLoop()
const cube = shallowRef<TresInstance | null>(null)

onBeforeRender(({ delta, elapsed }) => {
  if (!cube.value) return
  cube.value.rotation.y += delta * 2        // 2 rad/s on any refresh rate
  cube.value.position.y = Math.sin(elapsed * 3) * 0.5
})
</script>

<template>
  <TresMesh ref="cube">
    <TresBoxGeometry :args="[1, 1, 1]" />
    <TresMeshNormalMaterial />
  </TresMesh>
</template>

useLoop は TresCanvas の子コンポーネント内でのみ動作します。キャンバス自体では @before-loop／@loop イベントを使用してください（https://docs.tresjs.org/api/composables/use-loop）。

モデルを読み込む：

import { useLoader } from '@tresjs/core'
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'

const { state: model, isLoading, error, progress } = useLoader(
  GLTFLoader,
  '/models/duck.gltf',            // MaybeRef<string>: changing the ref reloads
  { extensions: (loader) => loader.setDRACOLoader(dracoLoader) },
)
// template: <primitive v-if="!isLoading && model?.scene" :object="model.scene" />

メッシュをクリックする：

<TresMesh @click="(e) => e.object.material.color.set('#ff0000')">
  <TresBoxGeometry />
  <TresMeshNormalMaterial />
</TresMesh>

イベントのペイロードには point、object、distance、face、uv、xy が含まれます。TresCanvas の @pointermissed は、何もない場所のクリックを捕捉します。詳細：references/pointer-events.md。

ベストプラクティス

• Three.js インスタンスへのテンプレート参照、および <primitive> に渡すオブジェクトには shallowRef を使用してください。深い ref によるプロキシ化は、実際にフレーム時間を消費します。https://docs.tresjs.org/api/advanced/performance
• ゲーム以外のシーンでは renderMode="on-demand" と invalidate() の組み合わせを推奨します。完全に制御する場合は renderMode="manual" と advance() を組み合わせてください（dist/tres.d.ts:134-139）。
• on-demand モードでは、ref 経由でオブジェクトを変更した後に invalidate() を呼び出してください。こうした変更は Vue のリアクティビティを経由しないためです。
• ポストプロセスまたはマルチパスの場合に限り、useLoop().render(fn) でレンダリングを引き継いでください。レンダリングモードが正常に動作しなくなるため、fn は notifySuccess() を呼び出す必要があります（https://docs.tresjs.org/api/composables/use-loop）。
• onBeforeRender／onRender の priority 引数を使って、順序付きの更新を登録してください（デフォルトは 0 で、値が大きいほど後に実行されます）。
• useGraph(object) を使うと、手動で走査する代わりに、読み込んだ GLTF シーンの名前付き nodes、materials、meshes マップを取得できます（dist/tres.d.ts:565）。
• <primitive> で使用するプログラムから作成したオブジェクトには、@tresjs/core からエクスポートされている dispose() を呼び出してください。テンプレートで作成されたオブジェクトは自動的に破棄されます。
• インスタンスの再作成を意図していない限り、args は固定してください。アニメーションには代わりにプロパティまたは ref を使用します。
• v-log／v-log:material、v-light-helper、v-distance-to ディレクティブでデバッグできます（dist/tres.d.ts:934-952）。https://docs.tresjs.org/api/utils/directives

参考資料

• references/components.md：TresCanvas の props とイベント、TresCanvasContext、TresPortal、UseLoader コンポーネント
• references/composables.md：useTres と useTresContext、useLoop、useLoader、useGraph、manager composables
• references/performance.md：レンダリングモード、リアクティビティ、破棄、dpr、fpsLimit
• references/pointer-events.md：イベント名、ヒットルール、ペイロード、伝播
• references/webgpu.md：カスタムレンダラーファクトリー、isWebGPU、機能に応じた分岐
• references/migration-v4-v5.md：v4 から v5 への移行の詳細

公式ドキュメント：https://docs.tresjs.org