メインコンテンツへスキップ

カスタム・コンポーネント

はじめに​

カスタムコンポーネントは、視覚的な外観、物理的なプロパティ、入力処理、またはカスタムゲームロジックを定義します。

カスタムコンポーネントの作成​

カスタムコンポーネントを作成するには、以下の手順に従います:

  1. ファイルブラウザでプラスボタン（＋）をクリックする。
  2. 新規ファイル」→「新規コンポーネントファイル」をクリックし、名前を付ける（拡張子は任意）。
    1. 新しいComponentファイルが生成され、デフォルトではプロジェクト内にTypeScriptが生成される。
    2. 新しいComponentファイルには、カスタムComponentの登録に必要な定型コードが含まれます。

カスタムコンポーネントの登録​

次のコードは、新しく作成されたカスタムコンポーネントがコードエディターに表示される例です:

例​

危険

コンポーネント名の接頭辞として「debug-」を使用するのは避けること。 debug-'で始まるコンポーネント名は、内部デバッグのために予約されており、**あなたのコードで使用すると正しく機能しません。

// これはComponentファイルです。このファイルを使用して、プロジェクトのカスタムComponentを定義することができます。
//

import * as ecs from '@8thwall/ecs' // これがecsライブラリにアクセスする方法です。

ecs.registerComponent({
  name: 'custom-component',
  schema: {
    // Component上で設定可能なデータを追加します。
  },
  schemaDefaults: {
    // スキーマフィールドのデフォルトを追加する。
  },
  data: {
    // Componentの外部で設定できないデータを追加します。
  },
  add: (world, component) => {
    // Componentがワールドに追加されたときに実行されます。
  },
  tick: (world, component) => {
    // 毎フレーム実行。
  },
  remove: (world, component) => {
    // Componentが世界から削除されたときに実行されます。
  },
})

エンティティにカスタム・コンポーネントを追加する​

次の例は、既存のエンティティにカスタムコンポーネントを追加する方法を示しています。

例​

tip

コンポーネントをインポートまたは使用する前に、必ずコンポーネントをエクスポートしてください。

import * as ecs from '@8thwall/ecs'

const CustomComponent = ecs.registerComponent({
  name: 'custom-component',
  schema:  {
   foo: ecs.string
  },
  schemaDefaults:  {
  },
  data:  {
  },
  add: (world, component) => {
  },
  tick: (world, component) => {
  },
  remove: (world, component) => {
  },
})

export {CustomComponent}
import CustomComponent from './custom-component' // ファイル・タイプを除いたファイル名。

const demo = world.createEntity()

CustomComponent.set(world, demo, {
   foo: 'bar'
})

関数一覧​

コンポーネント関数を使用すると、エンティティに関連するコンポーネントとそのデータに対して、さまざまなアクションを実行できます。

Get​

Returns a read-only reference.

Example

ecs.CylinderGeometry.get(world, component.eid)

Set​

Ensures the component exists on the entity, then assigns the (optional) data to the component.

Example

ecs.CylinderGeometry.set(world, component.eid, {
  radius: 1,
  height: 1
})

Mutate​

Perform an update to the component within a callback function. Return true to indicate no changes made.

Example

ecs.CylinderGeometry.mutate(world, component.eid, (cursor) => {
  カーソル.半径 += 1;
  カーソル.高さ *= 2;
  return false;
})

Remove​

Removes the component from the entity.

Example

ecs.CylinderGeometry.remove(world, component.eid)

Has​

Returns true if the component is present on the entity.

Example

ecs.CylinderGeometry.has(world, component.eid)

Reset​

Adds, or resets the component to its default state.

Example

ecs.CylinderGeometry.reset(world, component.eid)

Advanced Functions​

Cursor​

Returns a mutable reference. Cursors are reused so only one cursor for each component can exist at a time.

Example
ecs.CylinderGeometry.cursor(world, component.eid)

Acquire​

Same behavior as cursor, but commit must be called after the cursor is done being used.

Example
ecs.CylinderGeometry.acquire(world, component.eid)

Commit​

Called after acquire. An optional third argument determines whether the cursor was mutated or not.

Example
ecs.CylinderGeometry.commit(world, component.eid)
ecs.CylinderGeometry.commit(world, component.eid, false)

Dirty​

Mark the entity as having been mutated. Only needed in a specific case where systems are mutating data.

Example
ecs.CylinderGeometry.dirty(world, component.eid)

スキーマ​

スキーマは、コンポーネントの構造を定義するキーと値のペアのリストです。 キーはプロパティの名前で、値はプロパティが保持するデータの種類を指定するECSタイプです。

インフォメーション

Currently, storing dynamically sized objects or lists isn’t supported. We’re actively exploring this feature and would love to hear about your specific use cases.

The following data types are useful for creating Schema properties on a Custom Component or references to a specific type.

TypeDescription
ecs.eidEntity Reference
ecs.f3232-bit floating-point number
ecs.f6464-bit floating-point number
ecs.i3232-bit integer
ecs.ui88-bit unsigned integer
ecs.ui3232-bit unsigned integer
ecs.stringString
ecs.booleanBoolean

例​

次の例は、カスタム・コンポーネントのスキーマを示しています。

スキーマ: {
  target: ecs.eid, // NPCのユニークなエンティティ参照（エンティティID）
  speed: ecs.f32, // NPCの移動速度（32ビット浮動小数点）
  strength: ecs.f64, // NPCの体力レベル（64ビット浮動小数点）
  level: ecs.i32, // NPCのキャラクターレベル (32-bit integer)
  armor: ecs.ui8, // NPCのアーマーレーティング (0-255, 8-bit unsigned integer)
  experience: ecs.ui32, // NPCの経験点 (32-bit unsigned integer)
  guildName: ecs.string, // NPCが所属するギルドの名前。(String)
  isHostile: ecs.boolean // NPCがプレイヤーに敵対的かどうかを示すブール値 (Boolean)
}
schemaDefaults: {
  speed: 3.14,
  strength: 5.8,
  level: 10,
  armor: 255,
  experience: 12,
  guildName: 'Niantic Crew'
  isHostile: false
}

カスタムエディターフィールド​

エンティティエディタでのコンポーネントの表示と機能は、さまざまな方法でカスタマイズできます。 これはすべてスキーマ内のコメントを使って行われ、フィールドには//@というマークが付けられる。

ラベル​

エディター上のラベルは、コード上の名前よりも説明的でなければならないことがある。

スキーマ: {
   // @label Foo
   bar: ecs.eid,
}、

資産の参照​

エンティティではなくアセットを参照する必要がある場合。

スキーマ: {
   // @asset
   yeti: ecs.eid,
}

条件​

プロパティは、他のプロパティの値によってのみ表示されるように設定することができます。

スキーマ: {
   // 'from' は autoFrom が false に設定された場合のみ表示される:
   autoFrom: ecs.boolean,
   // @condition autoFrom=false
   from: ecs.f32,

   // 'easingFunction' は easeIn か easeOut が設定された場合のみ表示される:
   easeIn: ecs.boolean,
   easeOut: ecs.boolean,
   // @condition easeIn=true|easeOut=true
   easingFunction: ecs.string,

   // 'targetX' はターゲットが設定されていない場合のみ表示:
   target: ecs.eid,
   // @condition target=null
   targetX: ecs.f32,
}

列挙​

文字列プロパティは、セットリストに制限することができます:

スキーマ: {
   // @enum Quadratic, Cubic, Quartic, Quintic, Sinusoidal, Exponential
   easingFunction: ecs.string,
}

グループ​

特定のプロパティのグループをエディタで特別に扱うように指示することができる。 グループは以下のように設定される:

  • グループの開始と終了は // @group start …でマークされる。 および // @group end
  • 条件は // @group 条件でグループ全体に適用できる。
  • 現在サポートされているグループは2種類: vector3とcolor
ラベル​

カスタムラベルは個々のフィールドに使用することができます:

スキーマ{
   // @group start orient:vector3
   // @label Pitch
   orientPitch: ecs.f32,
   // @label Yaw
   orientYaw: ecs.f32,
   // @label Roll
   orientRoll: ecs.f32,
   // @group end
}
ベクトル3​

3次元ベクトルを表すプロパティのグループは、以下のように示すことができる:

スキーマ: {
 autoFrom: ecs.boolean,
 // @group start from:vector3
 // @group condition autoFrom=false
 fromX: ecs.f32,
 fromY: ecs.f32,
 fromZ: ecs.f32,
 // @group end
}
カラー​

色は次の例のように示すことができる:

スキーマ: {
 // @group start background:color
 bgRed: ecs.f32,
 bgGreen: ecs.f32,
 bgBlue: ecs.f32,
 // @group end
}

データ​

データはスキーマと似ているが、2つの顕著な違いがある。

  1. データは、それが定義されているコンポーネントの外部で読み書きすることは**できない。
  2. データには**デフォルト値はありませんが、同様の機能を持つライフサイクルメソッド'add'で設定することができます。

ライフサイクル・メソッド​

メソッド商品説明
追加コンポーネントが初期化されたときに一度だけ呼び出されます。 初期状態の設定と変数のインスタンス化に使用する。
取り除くコンポーネントがエンティティから削除されたとき、またはエンティティがシーンから切り離されたときに呼び出されます。 エンティティに対する以前の変更をすべて取り消すために使用する。
ダニシーンのレンダー・ループまたはティックごとに呼び出される。 継続的な変更やチェックに使用される。

パラメータ一覧​

PropertyType商品説明
世界ワールド世界への言及。
コンポーネントコンポーネントオブジェクト現在のコンポーネントへの参照。

コンポーネントオブジェクト​

警告

タイマーやイベント・ハンドラなどの非同期コンテキストでは、eid、schema、data プロパティの代わりに schemaAttribute または dataAttribute を使用してください。

PropertyType商品説明
イードイード現在のコンポーネントのエンティティID。
スキーマカーソル現在のエンティティのスキーマへの参照
スキーマ属性コンポーネントオブジェクトワールドスコープにおける現在のコンポーネントのスキーマへの参照。
データカーソル現在のエンティティのデータへの参照
データ属性コンポーネントオブジェクトワールドスコープにおける現在のコンポーネントのデータへの参照。