Kanzi 3.9 から Kanzi 4 へのプロジェクトの移行¶

Kanzi 3.9 と Kanzi 4 の間で、プロジェクトテンプレートとプラグインテンプレートは大幅に変更されました。Kanzi 4 の Kanzi Studio は Kanzi 3.9 の Kanzi Studio プロジェクトを開いて変換できますが、その周辺のビルド構造（CMake ファイル、ビルドスクリプト、プラットフォーム構成、プラグインのビルド設定）と、デフォルトのマテリアルおよびシェーダーは自動的には移行されません。このガイドでは、Kanzi 3.9 のアプリケーションまたはプラグインを Kanzi 4 のテンプレート構造に移行する方法を説明します。

このガイドでは プロジェクトとビルドの構造 について説明します。併せて適用する必要があるソースコードと API の変更については、Kanzi 4.0.0 マイグレーションガイドおよび Kanzi 4.1.0 マイグレーションガイドを参照してください。

始める前に¶

3.9 プロジェクトをバックアップするか、バージョンコントロールで管理してください。 Kanzi 3.9 プロジェクトから Kanzi 4 への変換は その場で行われ、元に戻せません。Kanzi 4 の Kanzi Studio で 3.9 の <ProjectName>.kzproj を開いて保存すると、Kanzi Studio はすべてのリソースファイルを含むプロジェクト全体を Kanzi 4 の <ProjectName>.proj.kzm フォーマットに書き換え、元に戻すことはできません。必ずコピーを移行し、元の 3.9 プロジェクトはそのまま保持してください。

最初にお読みください: 削除された機能¶

Kanzi 4 では、Kanzi 3.9 プロジェクトが依存している可能性のある一部の機能が削除されています。プロジェクトが次のいずれかに依存している場合は、このガイドではそれらを復元できないため、始める前に別のアップグレード戦略を計画してください。

Kanzi 4 で削除されたもの	注記
Visual Studio 2017 および 2019 のソリューションジェネレーター	`generate_cmake_vs2017_solution.bat` スクリプトと `generate_cmake_vs2019_solution.bat` スクリプトは削除されました。Kanzi 4 は `generate_cmake_vs2022_solution.bat` による Visual Studio 2022 のみをサポートします。
Linux の `linux_x11_glx_cpp98` プラットフォーム	C++11 より前の Linux プラットフォームとその `SConstruct` ファイルは削除されました。Kanzi 4 には C++17 ツールチェーンが必要です。
SCons ビルドヘルパー	`configs/platforms/common/config.py` スクリプトと `start_build.py` スクリプトは削除されました。すべてのプラットフォームは CMake でビルドします。

Kanzi 4 では、必要な CMake の最小バージョンも 3.10 から 3.25 に引き上げられています。

移行方法の選択¶

ほとんどのプロジェクトでは、プロジェクトを移行 します。Kanzi 4 の Kanzi Studio でプロジェクトを開いて変換し、その後 Kanzi 4 のビルド構造とデフォルトのリソースを移植します。プロジェクトを移行するを参照してください。

プロジェクトが小規模な場合や使い捨てのプロトタイプの場合は、新規に作成 します。新しい Kanzi 4 プロジェクトを作成し、そこにコンテンツを取り込みます。新規に作成して再構築するを参照してください。

新規に作成する場合は、リソースの移行に加えて、アプリケーションの構造（ノードツリーの階層、プレハブの配置、プレハブ間のバインディング、レンダリングとコンポジションの設定）を手動で再構築する必要があります。

Kanzi 3.9 と Kanzi 4 の間の変更点¶

どちらの方法を選択しても、Kanzi 3.9 と Kanzi 4 の間で次の点が変更されます。

プロジェクトファイルフォーマット。 3.9 のルートプロジェクトファイルは <ProjectName>.kzproj で、Kanzi 4 のファイルは <ProjectName>.proj.kzm です。Kanzi 4 の Kanzi Studio は、古いプロジェクトを開くとそれを変換し（確認を求められます）、保存時に新しいフォーマットで書き込みます。この変換は元に戻せません（始める前にを参照）。

ビルドシステム。 Kanzi 4 では、コマンドラインのビルドラッパー（build.bat / build.sh）とリゾルバーの概念が追加されています。cmake/kanzi-bootstrap.cmake ディスパッチャーは、KANZI_RESOLVER CMake キャッシュ変数を通じて、従来の cmake リゾルバー（ローカルの Kanzi SDK を使用。デフォルトで、Kanzi 3.9 に最も近い）と kpm リゾルバー（Kanzi Package Manager）のどちらかを選択します。

コマンド	機能
`build.bat`	`cmake` リゾルバーを使用して Release 構成でビルドします。
`build.bat <config>`	`cmake` リゾルバーを使用して特定の構成 (`Debug`、`Release`、`Profiling`) でビルドします。
`build.bat kpm`	`kpm` リゾルバーを使用してビルドします。

Linux と macOS では、build.bat を ./build.sh に置き換えます。クラシックリゾルバーは、Kanzi 3.9 とまったく同じように、KANZI_HOME 環境変数を使用してローカル SDK を見つけます。コマンドラインで -DKANZI_ROOT=<path> を渡していた場合は、-DKanzi_ROOT=<path> に名前を変更します。

generate_cmake_vs2022_solution.bat は Visual Studio 2022 ソリューションを生成します。macOS では、generate_cmake_xcode_ios_project.sh が iOS (Kanzi 4 の新しいプラットフォーム) 用の Xcode プロジェクトを生成します。

プラグイン。 Kanzi Engine プラグインを Kanzi 4 SDK に対して Visual Studio 2022 で再ビルドし、再インポートします。Kanzi Engine プラグインを移行するを参照してください。
デフォルトのマテリアルとシェーダー。 Kanzi 4 ではグラフィックスシステムが刷新され、デフォルトのマテリアルタイプとシェーダーが新しい GLSL に更新されました。変換された 3.9 プロジェクトには古いシェーダーが残りますが、Kanzi 4 はそれらを受け付けません。マテリアルとシェーダーを移行するを参照してください。
エクスポートされたバイナリ。 .kzb は Kanzi 4 で再エクスポートします。Kanzi 3.9 の .kzb を再利用しないでください。

プロジェクトを移行する¶

3.9 プロジェクトのコピーを変換します。 Kanzi 4 の Kanzi Studio で File > Open Project を選択し、コピーの <ProjectName>.kzproj を開いて変換の確認プロンプトを承認し、保存します。Kanzi Studio は Kanzi 4 の <ProjectName>.proj.kzm を書き込みます。
コピー元となるドナープロジェクトを作成します。 Kanzi 4 の Kanzi Studio で、プロジェクトに合ったテンプレート (例: Application with Kanzi Engine plugin) と、プロジェクトに合ったマテリアル (例: High-performance vertex shaders) を使用して新しいプロジェクトを作成します。プロジェクトの作成を参照してください。後でファイル名を変更しなくて済むように、同じプロジェクト名を使用します。このプロジェクトがドナーとなり、以降の手順でコピーする Kanzi 4 のビルドファイルとデフォルトのリソースの提供元になります。
ビルド用の基盤を入れ替えます:
1. ドナーの Application/src にある .cpp と .hpp ファイルを、変換したプロジェクトのファイルで上書きします。
2. 変換したプロジェクトの Application フォルダを削除します。
3. ドナーの Application を変換したプロジェクトにコピーします。
プラグインを再ビルドしてインポートします。 Kanzi Engine プラグインを移行するの手順に従います。
デフォルトのマテリアルとシェーダーを置き換えます。 カスタムマテリアルは残し、変換したプロジェクトのデフォルトの Materials、Material Types、Shaders を削除します。それらをドナープロジェクトのものに置き換えます。
仕上げます。 ビルドに失敗するカスタムマテリアルやシェーダーを修正し (マテリアルとシェーダーを移行するを参照)、C++ API の変更を適用して (4.0.0 および 4.1.0 の移行ガイドを参照)、ビルドして .kzb を再エクスポートします。

新規に作成して再構築する¶

プロジェクトに合ったテンプレート (例: Application with Kanzi Engine plugin) と、プロジェクトに合ったマテリアル (例: High-performance vertex shaders) を使用して 新しいプロジェクトを作成します。プロジェクトの作成を参照してください。このプロジェクトには Kanzi 4 のビルドファイルとデフォルトのリソースが含まれています。
プラグインを取り込んでインポートします。 プラグインのソースファイル (.cpp と .hpp) を新しいプロジェクトの src/plugin/src ディレクトリにコピーし、Kanzi Engine プラグインを移行するの手順に従います。
新しいプロジェクトの Tool_project に、作成済みのコンテンツを移します。対象は、シーンとプレハブ、インポートしたアセット (3D アセットとそのメッシュデータ、画像、フォント)、および作成したマテリアルとシェーダーです。新しいプロジェクトのデフォルトのマテリアル、マテリアルタイプ、シェーダーはそのまま残してください。3.9 のデフォルトをコピーして上書きしないでください。プロジェクトアイテムを共有すると Kanzi Studio プロジェクトを Kanzi アプリケーションに統合するを参照してください。

注釈

3D アセットをインポートすると、Kanzi Studio は 3D Assets とメッシュデータのディレクトリにデータを格納します。メッシュデータが引き継がれないと、メッシュは再ビルドされません。
ノードツリーを再構築します。 インポートしたプレハブとコンテンツから、Screen の下にアプリケーションの階層を組み直します。
仕上げます。 ビルドに失敗するカスタムマテリアルやシェーダーを修正し (マテリアルとシェーダーを移行するを参照)、C++ API の変更を適用して (4.0.0 および 4.1.0 の移行ガイドを参照)、ビルドして .kzb を再エクスポートします。

Kanzi Engine プラグインを移行する¶

ソースファイルを列挙します。 すべてのソースファイルが、対応する CMakeLists.txt (src/plugin または src/executable) の set コマンドに列挙されていることを確認します。
Kanzi 4 SDK に対して Visual Studio 2022 でプラグインをビルドします。KANZI_HOME に Kanzi 4 SDK を設定してから、build.bat または generate_cmake_vs2022_solution.bat を実行します。以前に別の SDK に対してビルドしていた場合は、先にビルドディレクトリを削除します。
再ビルドしたプラグインを Library > Kanzi Engine Plugins に登録します。既存のプラグインエントリを削除してから、Kanzi Engine Plugins を右クリックして Import Kanzi Engine Plugin を選択し、再ビルドした DLL を選択します。
Preview Build Configuration (Project > Properties 内) を、プラグインをビルドした構成に設定します。

プラグインが Kanzi 4 で変更された Kanzi Engine API (主にレンダリング、グラフィックス、プラットフォーム) を使用している場合は、プラグインを手動で移植します。Kanzi 4.0.0 マイグレーションガイドと Kanzi 4.1.0 マイグレーションガイドを参照してください。

マテリアルとシェーダーを移行する¶

Kanzi 4 ではグラフィックスシステムが刷新され、デフォルトのマテリアルタイプとシェーダーが新しい GLSL に更新されました。変換された Kanzi 3.9 プロジェクトには古いデフォルトのマテリアルとシェーダーが残っており、それらは Kanzi 4 が受け付けないレガシー GLSL を使用しているため、Kanzi 4 のものに置き換えます。

3.9 のものではなく、必ず新しいデフォルトのマテリアルとシェーダーを使用してください。
Kanzi 4 GLSL へ 自分で作成したシェーダーを移行します。Kanzi 4.1.0 マイグレーションガイドにあるシェーダー移行の手順と OpenGL ES バージョンの設定を参照してください。
ビルドに失敗するカスタムマテリアルやシェーダーを修正します。 上記のようにそのシェーダーを Kanzi 4 GLSL に移行するか、Kanzi 4 のデフォルトのマテリアルタイプでマテリアルを作成し直します。マテリアルは共有されるため、この修正はノード単位ではなくマテリアル単位で行います。

トラブルシューティング¶

マテリアルの取得に失敗する、または次のようなシェーダーのコンパイルエラーが発生する: ES shaders for SPIR-V require version 310 or higher。3.9 のデフォルトシェーダーをまだ使用しています。それらを Kanzi 4 のデフォルトシェーダーに置き換えてください (または GLSL を移行してください)。
Preview で未定義のメタクラスが報告される、またはプラグインがロードされない。 プラグイン DLL のビルド構成が Preview Build Configuration と一致していないか、ビルド時に KANZI_HOME が誤った SDK を指していました。正しい SDK に対してリビルドして再インポートし、Preview Build Configuration を合わせてください。
フォントエンジンの警告、空の Font Engine リスト ("None" のみ)、または "Preview cannot start" / "cannot find a font engine"。 これらは、エンジンが初期化されないことに起因する二次的な症状です。原因は通常、マテリアルとシェーダーのビルドに失敗していること、または Preview Build Configuration が再ビルドしたプラグインと一致していないことです。まずこれらを修正してください。エンジンが初期化されると、警告は消え、Font Engine リストには利用可能なエンジン (FreeType、iType) が自動的に表示されます。この問題を解決するためにフォントエンジンを手動で選択する必要はありません。

テンプレートごとの注意事項¶

Basic application¶

単一のソースファイル (たとえば src/basic_application.cpp) はそのまま引き継がれます。プラグインのサブツリーはありません。

Kanzi Engine プラグインとデータソースプラグイン¶

Kanzi 4 では、src/plugin 以下のプラグインサブツリーは自己完結しており、独自の cmake/ ディレクトリと packages.json を持ちます。プラグインのデプロイには、Application ディレクトリにある create_and_deploy_plugin スクリプトを使用します。Kanzi Engine プラグインの移行に従ってください。

Android の変更点¶

Kanzi 4 は Android Gradle Plugin 8 を使用し、依存関係のバージョンを configs/platforms/android_gradle/gradle/libs.versions.toml に移動しています。ネイティブビルドは kanzinative Gradle モジュールに置かれるようになり、Kanzi 3.9 がプラグインテンプレート用に生成していたプラグインごとの Gradle モジュールは削除されました。また Kanzi 4 には NDK 28.2.13676358 と CMake 3.25 以降が必要です。Gradle の CMake バージョンは、Android SDK が提供する最も低いバージョンである 3.30.5 に設定してください。古い Gradle ファイルをコピーするのではなく、Kanzi 3.9 での Gradle のカスタマイズをこのレイアウトに合わせて適用し直してください。Kanzi 4.1.0 マイグレーションガイドを参照してください。