コンテンツにスキップ

HEOProperty

HEOProperty_1

概要

SDK9以降で登場したHEOPropertyを使うことで、Vket Cloudのプロパティ機能を設定することができます。

プロパティ機能はItemに対してキーと値を持たせる方法で、コンポーネント間の値渡しやUnityエディタ上での動作カスタマイズといった使用方法が可能です。

本ページでは、何かと便利なHEOPropertyとVket Cloudのプロパティ機能について紹介します。

HEOProperty実装手順

1. アイテムとなるオブジェクトにアタッチ

HEOProperty_2

HEOFieldやHEOObject、HEOActivityなど、ビルド時にアイテムとなるオブジェクトに対しHEOPropertyをアタッチします。

2. HEOPropertyにKeyとValueを入力

Listの「+」ボタンを押すことで、KeyとValueの入力欄が表示されます。

プロパティの仕組み

Vket Cloudのプロパティ機能は、キー(Key)に対応する値(Value)を保持する機能です。
保持した値はHeliScriptで読み込んだり、上書きしたりすることが可能です。

HEOProperty_3

KeyおよびValueはいずれもString型として保持されます。

これで、HEOPropertyの設定が完了です。

HEOProperty_4

ビルド後のScene.jsonのproperties項目に入力内容が反映されています。

HeliScriptでの使い方

設定したプロパティはHeliScriptで使うことができます。

ここでは、

Key：Vket　Value：Cloud
Key：SDK　Value：12.1

と設定されたアイテムGameObjectを例に紹介します。

1. GetProperty

Item.GetProperty(string Key)では、アイテムが持つプロパティのKeyに対応するValueを取得します。

// サンプルコード(コンポーネント構造無視)

Item m_Item;
m_Item = hsItemGet("GameObject");

string Value;
Value = m_Item.GetProperty("Vket");
hsSystemWriteLine("%s" % Value); //「Cloud」と出力される

2. SetProperty

Item.SetProperty(string Key)では、アイテムが持つプロパティのKeyに対応するValueを変更します。

// サンプルコード(コンポーネント構造無視)

Item m_Item;
m_Item = hsItemGet("GameObject");

m_Item.SetProperty("Vket","Chan");

string Value;
Value = m_Item.GetProperty("Vket");
hsSystemWriteLine("%s" % Value); //「Chan」と出力される

3. OnChangedProperty

OnChangedProperty(string Key, string Value)は、プロパティの変更が発生した際に実行されるコールバックです。
SetPropertyで特定のキーに対し同一の値が入力され変更が発生しなかった場合には実行されません。

// サンプルコード(コンポーネント構造無視)

Item m_Item;
m_Item = hsItemGet("GameObject");

m_Item.SetProperty("SDK","12.1");
m_Item.SetProperty("Vket","Chan");
m_Item.SetProperty("SDK","12.2");
m_Item.SetProperty("Vket","Chan");

public void OnChangedProperty(string Key, string Value){
  hsSystemWriteLine("Changed %s, %s" % Key % Value);
  if(Key == "Vket"){
    hsSystemWriteLine("Vket Changed");  
  }
}

// 上記の場合、
// 6行目　SDKは初期Valueが12.1のためコールバック実行なし
// 7行目　Vketは初期ValueがCloudのためコールバック実行
// 8行目　SDKはValueが12.1のためコールバック実行
// 9行目　Vketは7行目でValueがChanとなっているためコールバック実行なし
// となり、
// Changed Vket, Chan
// Vket Changed
// Changed SDK, 12.2
// が出力される

HeliScriptでは、以上の3通りの関数が用意されています。

活用方法

HEOPropertyの活用例を紹介します。

1. アクティビティへの値渡し

最もオーソドックスな使い方です。
アクティビティクラスの作成時、プロパティでカスタマイズ可能要素を作成する際にHEOPropertyを使います。

HEOProperty_5

シーンjsonを適切な形に変更した後にHEOActivityで読み込むと下記のようになります。

HEOProperty_6

Valueに値を入れておくことで、初期入力値を設定することができます。

アクティビティ側HeliScriptではGetProperty()を使用して入力した値を読み込みます。

2. コンポーネント間の値渡し

コンポーネント間で値渡しをする際、以下のようにHEOPropertyを使用できます。

※値を変更する関数を用意して、hsCallComponentMethod()を使用しても同じことができます。

// exampleA exampleBの2つのコンポーネントとKey:status, Value:aliveを持つアイテム「Monster」があり、
// exampleAがもつ変数HPの値が0以下になった際、exampleBで動作が発生する場合

component exampleA{

  int HP;
  Item m_Item;

  public exampleA{
    HP = 20;
    m_Item = hsItemGet("Monster");
  }

  public void damage(){
    HP--;
    if(HP<=0){
      m_Item.SetProperty("status","death");
    }
  }
}

component exampleB{

  int status;

  public exampleB{
    status = 1;
  }

  public void OnChangedProperty(string Key, string Value){
    if(Key == "status"){
      switch(Value){
        case: "alive"
          hsSystemWriteLine("モンスターが　あらわれた！");
          status = 1;
          break;
        case: "poison"
          hsSystemWriteLine("モンスターが　どくを　あびた！");
          status = 2;
          break;
        case: "death"
          hsSystemWriteLine("モンスターを　やっつけた！");
          status = -1;
          break;
      }
    }
  }
}

3. Unityの[SerializeField]属性的運用

①のアクティビティへの値渡しと同様に、HEOPropertyから変数の中身を定義するように設定しておくことで、Unityエディタ上でパラメータ設定を行うことができるようになります。

ただし、KeyおよびValueはすべてstring値であることは注意が必要です。

component exampleC{
  int HP;
  int damage;
  string skill;
  Item m_Item;

  public exampleC{
    m_Item = hsItemGet("Monster");
    HP = m_Item.GetProperty("HP").ToInt();
    damage = m_Item.GetProperty("damage").ToInt();
    skill = m_Item.GetProperty("skill");
  }
}

//上記の設定を行い、Unity上で「Monster」オブジェクトに対しHEOPropertyを付け、
//HP:30、damage:3、skill:れんぞく斬り　とした場合、
//それぞれの入力内容がHeliScriptの変数に適用される

注意点

1. SetProperty / GetPropertyする際は対象となるアイテムに注意

アイテムごとに異なるプロパティを設定することが可能です。

HeliScript上で対象となるアイテムを間違えると、上手く動作しない場合があるので、気を付けましょう。

Note

更新：SDK12.x及び以降のバージョンでは、プロパティが存在しない際にSetPropertyを行った場合は新たにプロパティを追加するように変更されました。
SDK9.11現在、対象となるプロパティが存在しないのにSetPropertyを行おうとした場合、エラー文も出ずに他のHeliScriptの動作に影響を及ぼす場合があります。

2. KeyおよびValueはString型

少し上でも解説した通り、KeyおよびValueはString型となるため、String型以外の変数を扱う場合、SetPropertyやGetPropertyする際に型変換を行う必要があります。

型変換を行わずにSetPropertyやGetPropertyした場合、nullとなります。