一覧に戻る

Unity3Dプラグインの移行

2018.07.08Unity3Dプラグイン

Unity3Dプラグインの移行に必要な変更点についてご説明します。

7.2.0から8.0.0への移行

Unityの最小必要バージョンは5.5.6になりました。
iOSとAndroidの両方で、フレームワークとライブラリの名前が変更されました。 新しいバージョンにアップデートする前に、古いものを削除してください。自動的にビルドが行われた場合は、名前の変更を考慮してください。
Trackable Behaviourクラスは削除されました。
7.2.0で導入されたImageTrackerとInstantTrackerの Legacy Scaleオプションが削除されました。
PluginManagerクラスが削除され、Pluginクラスに置き換えられました。入力プラグイン設定がWikitudeCameraクラスからPluginクラスに移動されました。新しいプラグインAPIの仕組みの詳細については、プラグインとカスタムカメラのサンプル、および、ドキュメントを参照してください。
Frameクラスが削除されました。代わりに、新しい CameraFrameクラスを使用してください。
すべてのエラーコールバックのシグネチャは、2つのパラメータではなく1つのWikitude.Errorパラメータに変更されました。 エラーコードとエラーメッセージは、Wikitude.Errorオブジェクトに移動されました。

7.1.0から7.2.0への移行

Unityの最小必要バージョンは5.4.2になりました。
WikitudeCameraの初期化と内部SDKがAwakeからStartに移行しました。つまり、WikitudeCameraでStartメソッドが呼び出される前にWikitudeCameraプロパティをスクリプトから簡単に変更できるようになりました。

ImageTrackerとInstantTrackerにLegacy Scaleという新しいオプションが追加されました。以前のバージョンのプラグインでは、ターゲットを一致させるために拡大率を10倍にスケーリングする必要がありましたが、新しいバージョンでは必要ありません。しかし、後方互換性のために、レガシスケールは開発者が古い動作を再び有効にすることを可能にします。このオプションは、将来のバージョンでは削除される予定であり、既存のプロジェクトの移行を容易にすることのみを目的としています。

7.0.0から7.1.0への移行

変更なし。

2.1.0から7.0.0への移行

バージョン7.0.0ではUnityの最小必要バージョンは5.4.0になりました。古いバージョンを使用している場合はUnityもアップグレードしてください。Unityをアップグレードしていない場合はプラグインが正しく動作しません。バージョン7.0.0では、最小iOSバージョンが9.0、AndroidバージョンがAndroid 4.4(19)に変更されています。gradleプロジェクトにエクスポートする場合は、アプリケーションまたはbuild.gradleのマニフェストでminSdkVersionを19に更新してください。

Unity APIをWikitude Native SDKと揃えるために、一般的なTrackableBehaviourコンポーネントを廃止し、ImageTrackable、ObjectTrackable、InstantTrackableに置き換えました。これらの新しいTrackableにも異なるイベントがあります。ImageTrackableには、以前のバージョンの汎用的なOnEnterFieldOfVisionがなく、文字列ではなくImageTargetパラメーターを持つ同等のOnImageRecognizedイベントがあります。他のトラッカーにも同様のイベントが存在します。新しいAPIに更新するときは、新しいTrackableと廃止予定のTrackableBehaviourを混在させないように注意してください。

新しいTrackableコンポーネントには、Drawableフィールドが追加されました。これは、ImageTrackerの複数のターゲットをサポートするために追加されましたが、APIはすべてのトラッキング可能アイテムで使用できます。複数のターゲットの詳細については、イメージトラッキングの例を参照してください。

さらに、いくつかのサンプルスクリプトの名前が変更されました。サンプルをアップグレードしてインポートする場合は、重複するスクリプトをチェックするか、プロジェクトには存在しないスクリプトを確認してください。

2.0.0から2.1.0への移行

バージョン2.1.0は、プラグインと入力プラグインで使用されるFrameColorSpace列挙体に、新しい値を追加します。 このため、入力プラグインを使用するように設定されたWikitudeCameraコンポーネントが含まれているものを読み込むと、列挙型の逆シリアル化された値が正しくなりません。 2.1.0にアップグレードした後、ユースケースの適切な値に設定してください。

1.4.0から2.0.0への移行

バージョン2.0.0では、ClientTrackerクラスとCloudTrackerクラスは非推奨になりました。ClientTrackerを使用してイメージを認識する前に、TargetCollectionResourceと組み合わせて新しいImageTrackerに切り替えることをお勧めします。CloudTrackerではなく、同じImageTrackerを使用できますが、代わりにCloudRecognitionServiceを使用できます。 最初のドロップダウンメニューで、ImageTrackerインスペクタでTargetCollectionResourceとCloudRecognitionServiceを選択できます。最後に、ClientTrackerを使用して3Dターゲットを追跡する場合は、新しいObjectTrackerをTargetCollectionResourceとともに使用することができます。
プロジェクトを新しいAPIに移行するために、古いクラスのインスペクタには、スクリプトコンポーネントを適切な置き換えで自動的にアップグレードできるボタンがあります。

ボタンを押すと、アップグレードプロセス中に古いトラッカーに設定されたプロパティは新しいトラッカーに移行されますが、イベントは移行されません。このことを知らせる警告メッセージが表示されます。 ほとんどの場合、イベントを受け取るスクリプト関数を適切なシグネチャに更新する必要があるため、これは不可能です。

OKを押すと、GameObjectは代わりに新しいコンポーネントを持ちます。 結果に満足していない場合、または何かが間違っている場合は、この操作を元に戻すことができます。

古いトラッカーへ参照しているソースコードをがあれば。更新する必要があることに注意してください。

たとえば、Runtime Trackerサンプルは、カスタムリモートURLを使用してClientTrackerを作成するために使用されます。

GameObject trackerObject = new GameObject("ClientTracker");
_currentTracker = trackerObject.AddComponent<ClientTracker>();
_currentTracker.UseCustomUrl = true;
_currentTracker.TargetPath = Url.text;

_currentTracker.OnTrackerFinishedLoading.AddListener(OnTrackerFinishedLoading);
_currentTracker.OnTrackerLoadingError.AddListener(OnTrackerLoadingError);

新しいImageTrackerとAPIを使用した場合のサンプルの外観は次のとおりです。

GameObject trackerObject = new GameObject("ImageTracker");
_currentTracker = trackerObject.AddComponent<ImageTracker>();
_currentTracker.TargetSourceType = TargetSourceType.TargetCollectionResource;
_currentTracker.TargetCollectionResource = new TargetCollectionResource();
_currentTracker.TargetCollectionResource.UseCustomURL = true;
_currentTracker.TargetCollectionResource.TargetPath = Url.text;

_currentTracker.TargetCollectionResource.OnFinishLoading.AddListener(OnFinishLoading);
_currentTracker.TargetCollectionResource.OnErrorLoading.AddListener(OnErrorLoading);

_currentTracker.OnTargetsLoaded.AddListener(OnTargetsLoaded);
_currentTracker.OnErrorLoadingTargets.AddListener(OnErrorLoadingTargets);

古いトラッカーは下位互換性のために残されていますが、将来のバージョンでは削除されるため、新しいトラッカーに更新してください。 さらに、CloudTrackableがサンプルから削除されました。 古いバージョンからアップグレードする場合は、このスクリプトがプロジェクト内に存在しないことを確認してください。そうしないと、コンパイルエラーが発生する可能性があります。

1.1.0から1.2.0への移行

Wikitude SDK 1.2.0では、WikitudeCameraのプレハブが簡素化されています。今回の改善ではGameObjectは以前の階層構成を持たずに単一構成になりました。プレハブを変更する場合は、ライセンスキーを除いて、バックアップしてください。

以前の階層が利用できなくなるのでカメラフィードはエディターで明示的に公開されませんが、WikitudeCameraスクリプトのCameraTextureプロパティによってアクセスすることができます。

1.0.1から1.1.0への移行

Wikitude SDK 1.1.0では、プラグインに多くの重大な変更が加えられているので、アップグレードする前にプロジェクトをバックアップしてください。

Wikitudeクラスは、具象クラスとシールされたクラスで通信するためにUnityのイベントを公開するようになりました。したがって、これらのクラスをGameObject(ゲームオブジェクト)に直接追加でき、イベントをエディタまたは実行時にコードからサブスクライブすることができます。イベントにサブスクライブする場合は静的(Static)ではなく、動的(Dynamic)メソッドを選択します。ClientTrackerの設定方法については、Unity3Dプラグインのクライアント認識を参照してください。
クラス名とその内部表現の変更によって、インスペクタに設定されたクラスの値をリセットする必要があります。

以前に派生されたクラスは利用できなくなるのでイベントを受けるためには更新が必要になります。これらのクラスを更新するとGameObject上にMonoクラスが見つからないので、Wikitudeプラグイン(Wikitude/Dependencies/WikitudeUnityPlugin)内のクラスに置き換えて値を更新する必要があります。
更新後のWikitudeクラス内のすべての関数名は大文字で始まります。

iOSの場合は、前のバージョンで作られたビルドに付加すると、プロジェクト内にWikitudeプラグインの2つのバージョンが作成されます。1つはPlugins/iOSフォルダに配置され、もう一つはPlugins/Wikitude/iOSフォルダに配置されます。これらのうち1つのビルドのみを使用できます。または、セットアップガイドセクションでの手順を実行して、最初からビルドを作成することができます。

移行手順の例

このセクションでは、サンプルプロジェクトをバージョン1.0.1から新規バージョンへ移行する方法を紹介します。

  1. 依存関係、エディタやプラグインフォルダを削除します。このバージョンでは、プラグインフォルダを大幅に変更しました。これらのフォルダを削除しない場合は、正しいファイルを新しいバージョンに置き換える必要があります。ただし、magazine.wtcファイルはStreamingAssets/WikitudeフォルダではなくStreamingAssetsフォルダ内にあるので、サンプルが正常に動作しません。この例では、サンプルを使用しないので、この手順をスキップすることができます。
  2. Wikitude/Samplesフォルダを削除します。Samplesフォルダは説明用のため開発時には使用しません。
  3. ClientTrackerスクリプトを更新します。Wikitude.IClientTrackerはWikitude.ClientTrackerに変更されてシールクラスとなりました。ClientTrackerスクリプトは、MonoBehaviourクラスから派生できるように変更させるべきで、オーバーライドの代わりになるシンプルなメソッドです。これらのメソッドは、インスペクタではコールバックとして設定されるので、Wikitudeクラス名と一致しないようにクラス名を変更する必要があります。
  4. 同様にCloudTrackerスクリプトを更新します。更新した後、CloudTrackerスクリプトはWikitude.CloudTrackerから派生できないので、StartContinuousRecognition関数を呼び出すためにスクリプトに参照を追加する必要があります。
  5. 同じように、SurferBehaviourスクリプトを更新します。
  6. MagazineTracker、TrackableBehaviourおよびWikitudeCameraスクリプトを削除します。 Wikitudeクラスは具象クラスになったので、GameObjectに直接割り当てることができます。したがって、これらの空のクラスを持つ必要がありません。
  7. Scenesフォルダーから[main]シーンを開きます。
  8. HierarchyからGameObjectのWikitudeCameraを選択し、Inspectorのパラメーターにライセンスキーを入力します。スクリプトがない場合は、Dependencies/WikitudeUnityPlugin dllからWikitudeCameraスクリプトを追加します。
  9. 新しいGameObjectを作成して、手順(3)に更新したClientTrackerスクリプトを追加します。
  10. HierarchyからClientTrackerを選択し、Target Collectionのドロップダウンメニューからmagazine.wtcを選択します。サブスクライブしたいイベントで、(+)記号をクリックして、手順(9)で作成したGameObjectをNone(Object)に設定し、対応するコールバック関数を選択します。Unity Eventsの詳細については、Unity3Dプラグインのクライアント認識を参照してください。
  11. HierarchyからWikitudeEyeを選択し、手順(5)で更新したSurferBehaviourスクリプトを追加します。
  12. HierarchyからTrackableを選択し、Target Patternフィールドでは追跡したいすべてのターゲットに「*」を指定します。On Enter Field Of VisionとOn Exit Field Of Visionの両方のイベントでは、WikitudeEyeに追加したスクリプトをサブスクライブします。

これでプロジェクトを実行できるようになります。