Game Creator comes with the Examples Manager window, which allows a user to install and uninstall examples from all modules. This is something available to all module developers and here you'll learn how to create, step by step, a template for a module called "My Module".
The installer directory is where the compressed file with the information about it is located. This folder is usually found under the custom Module's path but can be anywhere on the project folder. It must contain two files:
- An Example Installer configuration file, which contains all the information related to the example, including its name, the module it belongs to, a description and the version of this package.
- A Package.unitypackage file, which contains the compressed assets that will be unpacked upon installing.
The installed location is the directory where the example is decompressed after installing an example in order to be used by the user. This folder is always located at the following route:
An installed example will always have a folder parent called after the name of the module, followed by a dot, followed by the name of the example, followed by an @ symbol and the semmantic version of the example. For example, if the example is called "My Example" and it's from a module called "My Module", the installation location of the example will be:
Creating a custom Example Installer¶
The example installer can be placed anywhere in the project. For simplicity it should be created where you have the rest of the module's assets. For example, if you are creating a module called "My Module" and an example of that called "My Example", at the root of the Unity project, you may want to place the installer inside the MyModule folder:
Assets/ MyModule/ Examples/ MyExample/ Scripts/ Textures/ ...
The Installer asset¶
Now that there is a folder where we can drop in the installation files, we'll create an ExampleInstaller asset inside the MyExample folder. To do so, right click on the aforementioned folder and select
Create -> Game Creator -> Developer -> Example Installer. Once you have the Example Installer asset you can rename it to whatever makes sense for your project.
We recommend sticking to Game Creator's naming convention and name the asset following "[ModuleName].[ExampleName]". This makes it easier to identify the asset and avoids conflicting names with other examples from other modules.
With the Example Installer in place, click on the Configuration button to expand the properties available and fill in the fields:
- Name: Name of the Example. Following the example from above, this would be "My Example.
- Module: Name of the module. It is important to note that this determines the category of the example. In the use case from above, the name would be "My Module".
- Description: A thorough description of this example. Make sure to indicate any quirks the example may have or how to get started once the example is installed.
- Author: Name of the creator of this example. This has no implication other than giving credit to the creator.
- Version: The semmantic version of this example. Make sure to increase the value every time you create a new version of the example.
- Complexity: How difficult it is for users to understand this example. This is for informational purposes only.
- Dependencies: A collection of ID (module name + example name) that this example depends on.
Dealing with Dependencies
The Example Manager will automatically install any non-installed dependencies that an example may depend on, without prompting the user to do so. This allows to quickly resolve any conflicts between this example and others that are required to be installed.
For example, if the example Example A has Example B as a dependency, and this last one is not yet installed, attempting to install Example A will install both Example A and Example B.
If Example B cannot be found, it won't be possible to install Example A from the Example Window and will prompt the user an error message telling which module could not be found.
Making the skeleton¶
Now that we have the installer in place it's time to create the skeleton from which to build our example. To do so, select the previously created Example Installer and on the Inspector, right click on the name of the installer. This will make a dropdown menu appear with a bunch of options:
- Install Package: Forces the installation of this example. However, it is recommended to use the Example Manager window to perform any installation instructions.
- Delete Package: Deletes the installed example, if there's any.
- Build Package: Changes the name of the installation path to fit the version number and creates a Package.unitypackage file at the installation location.
- Create Package: Creates the bare bones structure that allows to develop a new example.
In our case, we want to click on the "Create Package" option. This will create a new folder at:
Inside this folder you can place all prefabs, materials, scenes or any content that the example must have. To generate (or compress) this folder so it can be shared, select the option "Build Package" from the previous dropdown menu. This will export all assets inside the aforementioned folder and create a file called Package.unitypackage at the same directory as the Example Installer.
Sharing your example¶
Once you have the example built, it is ready to be distributed. To share this example installer, you just need to export the folder with the installer and the Package.unitypackage file generated.
If you (or the user) opens the Example Manager window, the module will be displayed as a sub category of the specificed module with the option to install it, update it and/or delete it, depending on whether there is an installed version or not.