Projects¶

Kanzi applications use kzb Kanzi files as the source of application content and event logic.

You can use one or more Kanzi Studio projects to create your Kanzi application.

See Combining Kanzi Studio projects into a Kanzi application.

You can configure your project in Kanzi Studio by selecting Project > Properties.

In Kanzi Studio you can have only one project open at a time.

Kanzi Studio project structure¶

Your Kanzi Studio project consists of project objects and resources. Each object in the project has a parent, a name, and a set of properties that define it. Additionally, most objects have either child or item objects.

In addition to the parent link and the child links in the children collection, items can also refer to other branches in the project tree. For example, animation objects have animation library as their parent but have a list of references to animation that act as their child nodes. This allows animation instancing where several animation nodes can share a single child node in their child node lists.

Project directory¶

By default, Kanzi Studio projects are stored in the <KanziWorkspace>/Projects directory. For every project Kanzi Studio creates a directory that contains:

Project files. Kanzi Studio stores the project data in kzm files. The root project file has the .proj.kzm extension. While you can manually modify the project files, they are designed to be modified only by Kanzi Studio.

A project directory holds exactly one root project file. Kanzi Studio cannot open a project whose directory contains more than one, because it cannot tell which of them is the root. Move each project into a directory of its own.
Project file backups. When you save your project, Kanzi Studio makes a copy of the project file and stores it in a file with the .proj.kzm_N extension, where N is the consecutive number of the backup.
Project file lock. When you open a project, Kanzi Studio creates a lock file in the project directory. The project lock file prevents the opening of more than one copy of a project. Kanzi Studio deletes the project lock file when you close the project.
Resource file directories. These directories contain files that are part of a Kanzi Studio project but their contents are not included in the project file. For example, this includes image files and shader source files.

You can access most of the contents of the resource file directories in Kanzi Studio in Library > Resource Files. When you add a file to any of these directories in the file system, that file is automatically added to the Library, with the following exceptions:
- Mesh Data and Animations directories are used only by Kanzi Studio. The files in these directories contain the vertex and index data of the meshes and animation keyframe data of the animations. If you are using source control system, remember to add these files to the source control whenever you import meshes or create new animations in your Kanzi Studio project.
- Source Assets directory is a storage place for the native files where you can store image processing applications and digital content creation tools so that they remain with the project. Kanzi Studio does not handle these files and does not export them into the kzb file of your Kanzi application. You cannot access the Source Assets directory from the Kanzi Studio.
Restore Points directory. Use restore points to return to an earlier version of your project. When you create a restore point for a project, Kanzi Studio makes the complete copy of your project into a timestamped directory in the <ProjectName>/Restore Points directory. See Creating restore points.

Where to store a referenced project¶

A project directory belongs to one project. Do not store a project inside the directory that holds the project file of another project. Keep the projects that a solution references alongside it instead. See Combining Kanzi Studio projects into a Kanzi application.

Kanzi Studio enforces this:

You cannot create a project in a directory that lies inside another project’s directory.
You cannot add a project as a reference when it is stored inside another project’s directory.
When you open a project that reaches such a project through project references, directly or through a chain of them, Kanzi Studio asks through the Move nested referenced projects dialog to move it out to a sibling directory. If you decline, Kanzi Studio does not open the project.
When the project that you add as a reference holds another project inside its own directory, Kanzi Studio asks the same question for that other project. If you decline, Kanzi Studio keeps the project you have open and leaves only the project that you added unloaded.

../../_images/project-move-nested-referenced-projects.png

What the move does¶

It changes directories on disk and you cannot undo it. When the destination already holds a directory of the same name, Kanzi Studio appends a number to the name it creates.
Kanzi Studio removes the directories that the move leaves empty.
Kanzi Studio moves either all the directories or none of them. When a move fails, for example because another program holds a file open, Kanzi Studio retries, then asks whether to try again. If you decline, Kanzi Studio moves back the directories it already moved. It updates the paths in your projects only after every directory is in place, so a move that does not go through leaves your project files untouched. When Kanzi Studio cannot move a directory back either, it reports that in the Log window, and that directory stays where the move put it.
Kanzi Studio flattens a whole group of nested projects to a single level. For example, you open Main, which references a project in Main/Sub, which in turn references a project in Main/Sub/Deep. Both move next to Main, not next to the directory each was stored in.
When the directory holding the nested projects has no parent directory to move them into, for example because it is a drive root, Kanzi Studio leaves them where they are and writes a warning to the log.
When the project you open is itself stored inside a directory of a project it references, Kanzi Studio leaves that one nesting in place and writes a warning to the log. It still moves every other nested project that it finds. Neither the project you open nor the directory around it can move while it is the project being opened, so move it out of that directory yourself.

What Kanzi Studio updates, and what you update¶

Kanzi Studio updates every path setting that pointed into a moved directory, in every project it reaches:

Project and kzb references.
Kanzi Engine plugin paths.
The Binary Export Directory, Application Export Directory, and Preview Working Directory settings.
The Application Root Directory and APK Path build configuration settings.
Any path property that a Kanzi Studio plugin adds.

Kanzi Studio does not change a path setting whose value is a macro, such as <ProjectDirectory>, so that the setting keeps resolving on every machine. When such a setting points into a directory that moves, update it yourself.

Kanzi Studio saves each project whose paths it updates, except one in which you have unsaved changes. Kanzi Studio updates the paths of such a project without saving it, so that it does not save your changes for you, and writes a note to the Log window. Save that project to keep the updated paths.

The application code of a moved project needs no changes, because Kanzi Studio moves the whole project directory as one unit. Update the paths that point into it from outside yourself: build scripts, continuous integration configuration, and version control paths.

When Kanzi Studio does not move anything¶

Kanzi Studio moves nothing when:

A project it reaches is open in another Kanzi Studio instance.
A project file it reaches is read-only. Check it out of version control first.
A project it reaches is still in the kzproj format and you decline converting it to kzm. Kanzi Studio saves every project whose paths it updates, and saving a kzproj project converts it and deletes the original kzproj file.
A project that has to move is already loaded in the project you have open. Kanzi Studio cannot move the directory of a project that it is holding open. Unload that project, or close the project you have open and open it again.

When you are opening a project, Kanzi Studio cancels the open. When you are adding a project reference, Kanzi Studio keeps the project you have open and leaves only the project that you added unloaded.

A command script that you run with KanziStudio.exe /Script moves the directories without asking, because the dialog needs an interactive Kanzi Studio. See Automating Kanzi Studio tasks.