migrations 拡張機能を使用すると、ユーザが古いプロジェクトを初めてロードしたときに、プラグインの各バージョンで一連のアクションが実行されるようにすることができます。
この拡張機能の典型的な使用法は、プラグインの 2 つのバージョン間でデータ形式が変更された場合に、プラグイン管理のデータ アセットをアップグレードすることです。
たとえば、1.0.5 バージョンのプラグインにおいて、プロジェクト内のアセットにカスタム データを保存したとします。しかし、1.0.6 バージョンのプラグインでは、1.0.5 バージョンで作成されたデータとの互換性がないため、そのデータの構造を変更する必要があります。この場合、1.0.6 バージョンで移行の拡張機能を作成できます。エディタが 1.0.6 バージョンで初めて使用するプロジェクトをロードすると、移行の拡張機能で定義したアクションが起動します。これにより、プラグインでプロジェクトが完全にロードされる前に、プロジェクト内の古いデータを新しい形式に更新することができます。
それぞれの移行の拡張機能には、それを識別する「パッチ ID」があります。エディタがプロジェクトに対して移行の拡張機能を実行するたびに、プロジェクト設定内にそのプラグインの現在のバージョンが保存されます。これには、そのプラグインに対して今まで実行されたすべての移行「パッチ ID」のリストが含まれます。これらのパッチ ID により、そのプラグインの現在のプロジェクトに対してどのような移行が既に適用されているかがエディタに伝わるため、同じプロジェクトでデータの移行が複数回行われることがなくなります。
エディタは、プロジェクトをロードするたびにアクティブな各プラグインの移行拡張機能の使用を繰り返し、プロジェクトに保存されたデータに対してそれぞれの環境設定を比較します。次の条件が「どちらも」 true の場合にのみ、それぞれの移行の拡張機能に対して、エディタは設定された移行のアクションを実行します。
最後の移行に使用したプラグインのバージョン(プロジェクト設定に保存)が、移行の拡張機能に設定したバージョンよりも「前の」バージョンである、またはこのプラグインに対して最後の移行バージョンがプロジェクトに記録されていない(このプラグインはこのプロジェクトで移行をまったく実行していないことを意味します)。
移行の拡張機能に設定したパッチ ID もプロジェクト内にリストされていない。
エディタが移行の拡張機能に対して、移行のアクションを実行した場合、そのプロジェクトで同じ移行が再実行されないように、エディタはその拡張機能のパッチ ID をプロジェクトに保存します。
移行の拡張機能では、次のパラメータが許容されます。
extensions = {
migrations = [
{
id = "GUID-2565-5475-AB6678DFE"
version = "1.0.4"
do = [
"migration_action_1"
"migration_action_2"
]
rollback = [
"undo_action_2"
"undo_action_1"
]
deferred = false
}
]
}
id
この移行の拡張機能によって適用された変更内容を識別するために使用する文字列値です。この値は、プラグインに設定するすべての移行の拡張機能全体で一意である必要があります。上記の「動作」を参照してください。必須。
version
プロジェクト内に保存されたプラグインの最後のバージョン番号と比較されるプラグインのバージョン番号です。上記の「動作」を参照してください。オプション。省略した場合は、現在のプロジェクトで他のマイグレーション パッチがこのプラグインに対して記録されていない場合にのみ、このマイグレーション パッチが適用されます。
do
プロジェクトが移行する必要がある id および version 設定に基づいて決定された、エディタが実行するアクションまたは一連のアクションです。各アクションには、actions 拡張機能で既に設定されているアクションの名前、またはインラインのアクション定義を指定できます。詳細については、「アクションを登録する」を参照してください。必須。
アクションは、文字列値を作成する必要があります。この値は、このプラグインのマイグレーションの結果を示すために、この ID とともに、プロジェクト設定内に保存されます。
アクションがスクリプトモジュールで定義される関数を示す場合、この関数は、保存する文字列を返すことができます。
アクションがプラグインにインラインで定義されている場合は、次の文字列を返すことができます。
~{js} { name = "migration_action_1" type = "js" script = """ // ... do migration tasks here "the string to be saved" """ } ~
rollback
移行をロールバックする必要がある場合に、エディタが実行するアクションまたは一連のアクションです。これらのアクションは、do パラメータが行うあらゆる変更を元に戻します。各アクションには、actions 拡張機能で既に設定されているアクションの名前、またはインラインのアクション定義を指定できます。詳細については、「アクションを登録する」を参照してください。オプション。
deferred
プロジェクトが完全にロードされ、エディタが Stingray エンジンの内部のインスタンスを開始するまで、移行のアクションを遅延するべきかどうかを決定します。これは移行のアクションの実行が、それに必要なエンジン環境が配置されているかに左右される場合に役立ちます。たとえば、アクションで Lua スクリプトを実行する場合や、エンジンによって提供される他のサービスに依存する場合などです。(オプション) 既定値は false です。