You can create your own template projects with ease. Template projects are projects that you use as basis for new projects, with more or less boilerplate code already included. Template projects will be listed in the Kobold2D Project Starter tool as described in Creating a Kobold2D Project.
|Reasons for creating your own Template Projects?|
You may want to share your own template projects with the community, maybe with an accompanying tutorial. This is a sure way to get attention.
Businesses can use template projects to ensure that new projects include all the shared source code, assets, build schemes, etc. that you have developed over time, or need to have in every project (eg. OpenFeint).
You can also use template projects as starting points for the customers of your commercial add-on library for Kobold2D.
It is highly recommended to build a template project based on one of the already existing template projects provided by Kobold2D. After all, you want to end up with a working Kobold2D project.
|If in doubt ...|
... check how the existing Kobold2D project templates are setup. You can open the template projects in the /__Kobold2D__/templates/project/ folder and review the project, but it won't build. To be sure you don't accidentally break the template project, copy it elsewhere before opening the .xcodeproj file.
Template projects rely on a common naming scheme for the project's folder, Xcode project, targets and schemes. The naming scheme is as follows:
_ + The-Project-Name + -Template_
For example if your template project's name is supposed to be "Hello My Friend" then the project name will be _Hello-My-Friend-Template_. The rest of this guide assumes that _Hello-My-Friend-Template_ will be the chosen name for the template, but of course you can change the Hello-My-Friend part to whatever you like.
|It is recommended to replace all spaces with dashes, and to avoid using any punctuation or other special characters. Template Projects and the Kobold2D Project Starter tool have only been tested with names containing underscores, dashes, letters and digits.|
When you create a new project by using the Kobold2D Project Starter tool, all occurances of the string _Hello-My-Friend-Template_ will be replaced by the project name the user chooses.
This replacement is done for the project's folder, the .xcodeproj file, the project's targets, schemes and groups. This replacement however does not extend to source code or resource files.
To summarize, make sure that the following is true in your template project:
- the project and its files are in a folder named: _Hello-My-Friend-Template_
- the project file (.xcodeproj) is in that folder and named: _Hello-My-Friend-Template_.xcodeproj
- the project's targets are named: _Hello-My-Friend-Template_-iOS for iOS targets and _Hello-My-Friend-Template_-Mac for Mac targets. The -iOS and -Mac suffixes are optional but help to identify the target platform.
- the project's schemes are named exactly like the project's targets: _Hello-My-Friend-Template_-iOS and _Hello-My-Friend-Template_-Mac
|If your template project only supports one platform, simply omit the target and scheme for the platform(s) that the project doesn't support.|
To add a description that will be displayed by the Kobold2D Project Starter tool, simply add a text file named _description_ in the same folder as the .xcodeproj file. Verify that the description text fits into the description box of the Kobold2D Project Starter tool.
After you've finished renaming your template project, along with all other work, you will have to move or copy the project's folder to the project templates folder /__Kobold2D__/templates/project/.
Now you can run the Kobold2D Project Starter app. Your template project should show up. Select it and create a new project based on your template project, preferably give it a name that stands out (eg. TEMPLATETEST) because that will make the next step easier.
Verify that the project folder, Xcode project, targets and schemes have been properly renamed to TEMPLATETEST or whatever name you chose. The targets and schemes should be named TEMPLATETEST-iOS and TEMPLATETEST-Mac.
If the names have all been correct replaced, verify that the TEMPLATETEST project builds without errors.
|If the TEMPLATETEST project builds successful it will be sufficient to test future changes to your template project in the template project Hello-My-Friend-Template itself. You only occasionally will have to verify that the project also builds without errors after going through the Kobold2D Project Starter tool.|
Open the Product menu in Xcode, hold down the Option key and select Clean Build Folder ... to make sure everything gets build anew. You only have to do this step once before building any of your newly created project's targets.
You will want to build each target (iOS & Mac) once, and run it to see that it behaves as it should. You should build and run the iOS target once for each of the possible selections: iOS Device, iPhone Simulator and iPad Simulator. Even if your template does not support iPad its good practice to make sure it at least runs on iPad.
You also will want to verify that the project behaves correctly on both standard and Retina displays. Run the project once using the iPhone Simulator as target. Verify the app is correct, then in the Simulator go to the Hardware -> Device menu and switch to the other iPhone type, which will be either iPhone or iPhone (Retina). Then hit the run button in Xcode again, or simply tap the app's icon in the Simulator. This way you can quickly ensure that your app displays correctly on standard and Retina devices.
Finally, you should build and run the Mac targets for both 64-Bit and 32-Bit modes, assuming your installation of Mac OS X supports both. This is important because sometimes compile or runtime errors will only occur in either 32-bit or 64-bit builds.
|One more reason to share template projects...|
... the best, most popular template projects created by the community will be included in Kobold2D if the author(s) allow it to be distributed under the MIT License.
You can now share the template project with your team or the entire community. Right-Click the project's _Hello-My-Friend-Template_ folder and select *Compress "_Hello-My-Friend-Template_}}. You can rename the archive to whatever you like.
|Provide your users with installation help by linking to this article: |
Installing a Kobold2D Template Project