Minimalize template.

This commit is contained in:
max 2020-09-01 17:11:10 +02:00
parent 0e8054c25d
commit c9438c27fa
31 changed files with 68 additions and 3863 deletions

87
.gitignore vendored
View File

@ -1,77 +1,36 @@
# ====== # [Ll]ibrary/
# Autogenerated VS/MD solution and project files [Tt]emp/
# ====== # [Oo]bj/
[Bb]uild/
[Bb]uilds/
[Ll]ogs/
Assets/AssetStoreTools*
# Visual Studio 2015 cache directory
/.vs/
# Autogenerated VS/MD/Consulo solution and project files
ExportedObj/
.consulo/
*.csproj *.csproj
*.unityproj *.unityproj
*.sln *.sln
*.suo *.suo
*.tmp
*.user *.user
*.userprefs *.userprefs
*.pidb *.pidb
*.booproj *.booproj
*.svd
*.pdb
# ====== # # Unity3D generated meta files
# ReSharper is a .NET coding add-in *.pidb.meta
# ====== # *.pdb.meta
_ReSharper*/
*.[Rr]e[Ss]harper
# ====== #
# DotCover is a Code Coverage Tool
# ====== #
*.dotCover
# ====== #
# NCrunch
# ====== #
*.ncrunch*
.*crunch*.local.xml
# ====== #
# Unity3D Generated File On Crash Reports # Unity3D Generated File On Crash Reports
# ====== #
sysinfo.txt sysinfo.txt
# ====== # # Builds
# OS Generated *.apk
# ====== # *.unitypackage
.DS_Store*
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db
$RECYCLE.BIN/
Desktop.ini
# ====== #
# Blender backup files
# ====== #
*.blend[1-9]
*.blend[1-9].meta
# ====== #
# Sourcetree backup files #
# ====== #
*.orig
*.orig.meta
# ====== #
# Visual Code files
# ====== #
VSCode.meta
VSCode/*
.vscode
# ====== #
# Others #
# ====== #
.~lock.*
.vs/
*_backup
*_backup.meta
*.~*#*
/_site
*/obj/*
Documentation~/api/*
Documentation~/manual/changelog.*

View File

@ -1,62 +1,6 @@
# Change Log: # Change Log:
## 1.4.2 ## 0.1.0
- Enhancement: adding conditionals to [`.github/workflows/documentation.yml`](https://github.com/OmiyaGames/template-unity-package/blob/master/.github/workflows/documentation.yml) and [`.github/workflows/mirror.yml`](https://github.com/OmiyaGames/template-unity-package/blob/master/.github/workflows/mirror.yml) to prevent the jobs from running on other repos copying this template automatically. Added comments, and updated documentation indicating these conditional's purpose, and how to remove them. - Start Project:
- ...
## 1.4.1
- Enhancement: changing the mirror action to [this one](https://github.com/marketplace/actions/mirroring-repository).
## 1.4.0
- Feature: added Github Action to mirror the repository to [`Bitbucket`](https://bitbucket.org/OmiyaGames/template-unity-package) automatically. This new file is available here: [`.github/workflows/mirror.yml`](https://github.com/OmiyaGames/template-unity-package/blob/master/.github/workflows/mirror.yml).
- Enhancement: updated [Customize Package manual](https://omiyagames.github.io/template-unity-package/manual/customizePackage.html) talking about what files from `.github` can be deleted or edited.
## 1.3.1
- Typo: Fixed the documentation build status badge in [`README.md`](https://github.com/OmiyaGames/template-unity-package/blob/master/README.md).
## 1.3.0
- Feature: added Github Action to auto-generate documentation in the [`Documentation~`](https://github.com/OmiyaGames/template-unity-package/blob/master/Documentation~) folder using [DocFX for Unity](https://github.com/NormandErwan/DocFxForUnity) project as reference.
- Feature: adding Github feature, sponsorship! The `FUNDING.yml` file in `.github` folder adds a sponsorship button on Github with a link to [Ko-Fi](https://ko-fi.com/omiyagames).
- Enhancement: Updated [`README.md`](https://github.com/OmiyaGames/template-unity-package/blob/master/README.md) to link to the newly-generated documentation, and provide better installation instructions.
## 1.2.2
- Enhancement: making the platform [`OmiyaGames.Template.Editor.asmdef`](https://github.com/OmiyaGames/template-unity-package/blob/master/Editor/OmiyaGames.Template.Editor.asmdef) and [`OmiyaGames.Template.Editor.Tests.asmdef`](https://github.com/OmiyaGames/template-unity-package/blob/master/Tests/Editor/OmiyaGames.Template.Editor.Tests.asmdef) supports to only the editor.
## 1.2.1
- Rename: `EditorExampleTest.cs` to [`TestEditorExample.cs`](https://github.com/OmiyaGames/template-unity-package/blob/master/Tests/Editor/TestEditorExample.cs). Updated class name along with it.
- Rename: `RuntimeExampleTest.cs` to [`TestRuntimeExample.cs`](https://github.com/OmiyaGames/template-unity-package/blob/master/Tests/Editor/TestRuntimeExample.cs). Updated class name along with it.
- Typo: Removed `[CustomEditor(typeof(RuntimeExample))]` attribute from [`EditorExampleTest.cs`](https://github.com/OmiyaGames/template-unity-package/blob/master/Tests/Editor/TestEditorExample.cs). It serves no purpose.
- Typo: Removed `[CustomEditor(typeof(RuntimeExample))]` attribute from [`EditorExampleTest.cs`](https://github.com/OmiyaGames/template-unity-package/blob/master/Tests/Editor/TestEditorExample.cs). It serves no purpose.
## 1.2.0
- Feature: Updated the [`Tests`](https://github.com/OmiyaGames/template-unity-package/blob/master/Tests) assembly definition files and example scripts with proper configuration for editing/creating new unit test scripts. Also updated [`package.json`](https://github.com/OmiyaGames/template-unity-package/blob/master/package.json) with NUnit as a required dependency.
- Enhancement: Added significantly more information in [`README.md`](https://github.com/OmiyaGames/template-unity-package/blob/master/README.md) so other people can use a more fleshed-out markdown format to start their documentation.
- Enhancement: Changing [`package.json`](https://github.com/OmiyaGames/template-unity-package/blob/master/package.json) into a type -> Tool, and added one more keyword.
- Enhancement: Noting [`THIRD PARTY NOTICES.md`](https://github.com/OmiyaGames/template-unity-package/blob/master/THIRD%20PARTY%20NOTICES.md) is just an example, and this project doesn't actually use any 3rd party tools yet (besides unit testing, but I think that's already implied).
## 1.1.0
- Feature: adding a [`Documentation~/Doxyfile`](https://github.com/OmiyaGames/template-unity-package/blob/master/Documentation~/Doxyfile) to make generating [Doxygen](http://doxygen.nl/) files a little easier.
## 1.0.2
- Typo: renaming `Documentation~/index.md` to [`Documentation~/Template.md`](https://github.com/OmiyaGames/template-unity-package/blob/master/Documentation~/Template.md) to match Unity recommendation.
## 1.0.1
- Bug fix: [`Editor/EditorExample.cs`](https://github.com/OmiyaGames/template-unity-package/blob/master/Editor/EditorExample.cs) now compiles properly.
- Typo: updated namespace in [`Tests/Editor/EditorExampleTest.cs`](https://github.com/OmiyaGames/template-unity-package/blob/master/Tests/Editor/EditorExampleTest.cs) to inlucde `Test`.
- Typo: changing the [`THIRD PARTY NOTICES.md`](https://github.com/OmiyaGames/template-unity-package/blob/master/THIRD%20PARTY%20NOTICES.md) Credits section to use a list, so each field is in its own line.
## 1.0.0
- Initial release:
- Confirmed the template project works by battle-testing it to [Omiya Games - Common](https://github.com/OmiyaGames/omiya-games-common) package.
- Updated every text to be more generic.

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,3 @@
# PACKAGENAME
Documentation.

View File

@ -1,61 +0,0 @@
{
"metadata": [
{
"src": [
{
"src": "..",
"files": [ "**.cs" ]
}
],
"globalNamespaceId": "Global",
"filter": "filterConfig.yml",
"dest": "api"
}
],
"build": {
"globalMetadata": {
"_appTitle": "Template Unity Package documentation",
"_appFooter": "Copyright © 2020 Omiya Games",
"_enableSearch": true
},
"content": [
{
"files": [ "toc.yml", "index.md" ]
},
{
"src": "api",
"files": [ "*.yml" ],
"dest": "api"
},
{
"src": "manual",
"files": [ "toc.yml", "*.md" ],
"dest": "manual"
}
],
"overwrite": [
{
"src": "..",
"files": [ "Runtime/**/*.md", "Editor/**/*.md" ]
}
],
"resource": [
{
"files": [ "resources/**/*" ]
}
],
"sitemap":
{
"baseUrl": "https://omiyagames.github.io/template-unity-package/",
"changefreq": "weekly",
"fileOptions": {
"api/*": {
"changefreq": "daily"
}
}
},
"xref": [ "https://normanderwan.github.io/DocFxForUnity/Unity/xrefmap.yml" ],
"xrefService": [ "https://xref.docs.microsoft.com/query?uid={uid}" ],
"dest": "../_site"
}
}

View File

@ -1,18 +0,0 @@
apiRules:
- include:
# Taro Omiya: Updated namespace for this template
# Including the OmiyaGames.Template namespace
uidRegex: ^OmiyaGames\.Template$
type: Namespace
- include:
# Taro Omiya: Updated namespace for this template
# Including the OmiyaGames.Template.Editor namespace
uidRegex: ^OmiyaGames\.Template\.Editor$
type: Namespace
- include:
uidRegex: ^Global
type: Namespace
- exclude:
# Taro Omiya: note that I'm ignoring namespaces containing unit tests on purpooses
uidRegex: .*
type: Namespace

View File

@ -1,92 +0,0 @@
# [Omiya Games](https://www.omiyagames.com/) - Template Unity Package
[![ko-fi](https://www.ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/I3I51KS8F)
![Unity Package Manager](https://omiyagames.github.io/template-unity-package/resources/preview.png)
**Template Unity Package** is a Github template [Omiya Games](https://www.omiyagames.com/) uses to start a new Unity package. Developers intending to utilize this project as a starting point to develop their own package should [visit the Github page](https://github.com/OmiyaGames/template-unity-package) and:
- If they plan on creating a new online repository on Github directly, click on the green "Use this template" button to get started, or
- Click the "Releases" link, and download the latest archive as zip or gzip file.
## Structure
The project follows [Unity's recommend file and folder format](https://docs.unity3d.com/Manual/cus-layout.html), albeit with a few changes:
```
<root>
├── package.json
├── README.md
├── CHANGELOG.md
├── LICENSE.md
├── THIRD PARTY NOTICES.md
├── .gitignore
├── Runtime
│ ├── OmiyaGames.Template.asmdef
│ └── RuntimeExample.cs
├── Editor
│ ├── OmiyaGames.Template.Editor.asmdef
│ └── EditorExample.cs
└── Tests
│ ├── Runtime
│ │ ├── OmiyaGames.Template.Tests.asmdef
│ │ └── RuntimeExampleTest.cs
│ └── Editor
│ ├── OmiyaGames.Template.Editor.Tests.asmdef
│ └── EditorExampleTest.cs
├── Samples~
│ └── Example1
│ └── Example.txt
├── Documentation~
| ├── index.md
| ├── Doxyfile
| ├── docfx.json
| ├── toc.yml
| ├── filterConfig.yml
| ├── manual
| | ├── toc.yml
| | ├── customizeDocumentation.md
| | ├── customizePackage.md
| | ├── customizeSamples.md
| | └── README.md
| └── resources
| ├── preview.png
| └── README.md
└── .github
├── FUNDING.yml
├── ISSUE_TEMPLATE
| ├── bug_report.md
| ├── feature_request.md
| ├── documentation-template.md
| └── research_template.md
└── workflows
├── documentation.yml
└── mirror.yml
```
## Common Text Formats
Note that this sprawling list of files contains a large number of common, human-readable (i.e. non-code, data-storing) text formats. If some of these file extensions are unfamiliar, the following resources describes how to edit and format the most common text files used in this project:
- [JSON (`*.json, *.asmdef`)](https://www.json.org/json-en.html)
- Although the [Wikipedia page](https://en.wikipedia.org/wiki/JSON#Data_types_and_syntax) might be easier understand.
- [YAML (`*.yml`)](https://yaml.org/spec/1.2/spec.html#Preview)
- Again, the [Wikipedia page](https://en.wikipedia.org/wiki/YAML#Syntax).
- [Markdown (`*.md`)](https://www.markdownguide.org/getting-started/)
- They also provide [a cheatsheet](https://www.markdownguide.org/cheat-sheet)!
- [Bonus: `.gitignore`](https://git-scm.com/docs/gitignore#_pattern_format)
## About the Manual
As many of these files are intended to be edited and/or renamed, this manual has been split up into three parts. The links below briefly covers how to update this package's files for your own package development.
- [Customizing Package Files](https://omiyagames.github.io/template-unity-package/manual/customizePackage.html)
- [Adding Source Code and Assets](https://omiyagames.github.io/template-unity-package/manual/customizeSource.html)
- [Adding Importable Assets](https://omiyagames.github.io/template-unity-package/manual/customizeSamples.html)
- [Customizing Documentation](https://omiyagames.github.io/template-unity-package/manual/customizeDocumentation.html)
As an aside, [the author](https://github.com/japtar10101) of this manual provided a more thorough guide with graphics on their own blog: [*How to Split Up an Existing Unity Git Project into Smaller Unity Packages*](https://www.taroomiya.com/2020/04/29/how-to-split-up-an-existing-unity-git-project-into-smaller-unity-packages/). It's worth reviewing if the manual seems a little sparse. Finally, changes in the project is documented under the [change log page](https://omiyagames.github.io/template-unity-package/manual/changelog.html).
## LICENSE
Overall package is licensed under [MIT](https://github.com/OmiyaGames/template-unity-package/blob/master/LICENSE.md), unless otherwise noted in the [3rd party licenses](https://github.com/OmiyaGames/template-unity-package/blob/master/THIRD%20PARTY%20NOTICES.md) file and/or source code.

View File

@ -1 +0,0 @@
This folder contains markdown files listed under "Manual" section in the documentation. When adding or removing any files in this folder, don't forget to update `toc.yml` accordingly!

View File

@ -1,210 +0,0 @@
# Customizing Documentation
This part of the manual pertains to the following folders and files:
```
<root>
├── Documentation~
| ├── index.md
| ├── Doxyfile
| ├── docfx.json
| ├── toc.yml
| ├── filterConfig.yml
| ├── manual
| | ├── toc.yml
| | ├── customizeDocumentation.md
| | ├── customizePackage.md
| | ├── customizeSamples.md
| | └── README.md
| └── resources
| ├── preview.png
| └── README.md
└── .github
└── workflows
└── documentation.yml
```
Despite [Unity's recommendation](https://docs.unity3d.com/Manual/cus-layout.html), technically the folders and files in this entire section are optional. That said, this project aims to take advantage of two things:
1. Automate generating documentation through [Github Actions](https://help.github.com/en/actions/getting-started-with-github-actions/about-github-actions), [DocFX](https://dotnet.github.io/docfx/), and [C# comments](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments), and
2. Hide the documentation from Unity Project window's view, by using a trailing `~` in the folder name.
This section covers how to update these files to generate the documentations to your own liking. Note that the source for most of this information comes from the open-source [DocFX for Unity](https://github.com/NormandErwan/DocFxForUnity) project.
## Github Action Support
Files in the `.github` folder are intended for Github-specific features, including automation features under `workflows` folder. Obviously, if the repo is *not* hosted on Github, or the developer does not plan to take advantage of some of these features, this folder and its content may be safely deleted.
Naturally, the Github Actions held in the `workflows` folder needs a little setup for them to work. The following sections will cover each one, what they do, and what preparations the developer needs to make. If similar alternatives exists for other Git repository hosts, this document will do its best to list them.
### `.github/workflows/documentation.yml`
The `documentation.yml` file automates generating documentation using DocFX. The full documentation on what each field means is available on [Github's website](https://help.github.com/en/actions/configuring-and-managing-workflows/configuring-a-workflow), but this section will only cover a small part of the file.
#### `if:` lines
To prevent this action from running on every repository that copies or forks this template, an `if` line and conditional is added at two jobs in `documentation.yml`, and look like this:
```yaml
if: # Adding if-statement to prevent this job from running on packages using this template.
# If you want to run this documentation job, just take out the if-field and value below.
github.repository == 'OmiyaGames/template-unity-package'
```
As the comments imply, if the developer wants Github to automatically generate their documentation, they should remove these lines.
#### `name: Build` line
The `Build` line is probably where most developers would be most interested in:
```yaml
- name: Build
run: |
cp CHANGELOG.md Documentation~/manual/changelog.md
docfx Documentation~/docfx.json
```
The `run` string describes the Batch commands that gets run in a windows VM. As one can see, the above line copies the `CHANGELOG.md` file into `Documentation~/manual/changelog.md`, before running the `docfx` command at the last line to generate the documentation. This multiline string can be updated to copy or change other documentation files. For example, the developer may want to copy the `README.md` file at the root of the package to `Documentation~/manual/index.md`, so that when DocFX runs, the homepage will look exactly like the `README.md` file. In that case, it would be helpful to edit this file as:
```yaml
- name: Build
run: |
cp README.md Documentation~/manual/index.md
cp CHANGELOG.md Documentation~/manual/changelog.md
docfx Documentation~/docfx.json
```
Of course, if the developer chooses to make this edit, they should also delete the `Documentation~/manual/index.md` file, and add a line in `.gitignore` to ignore this file.
After this line is updated to the developer's satisfaction, the repository must be configured to provide the Github access to the repo itself.
### Creating Secret Access Key
To give Github Actions access to the package's repository, a private key must be created and shared.
1. If the developer hasn't done this step already, go to ["Settings -> Developer Settings -> Personal access token,"](https://github.com/settings/tokens) and generate a new token with full access to `repo`. Don't forget to copy the secret key printed on the new entry in a safe location.
- ![Personal Access Token](https://omiyagames.github.io/template-unity-package/resources/personalAccessToken.png)
2. Return to the Github repository, then go to "Settings -> Secrets," and add the generated key into the list. Remember to name this key as, `AccessToken`.
- ![Add Secret](https://omiyagames.github.io/template-unity-package/resources/addingSecrets.png)
3. Finally, push the repository to the master branch to deploy the automated commands! A new breanch, `gh-pages`, and website, `https://<username>.github.io/<repo-name>/` will be created as part of this process.
For more information, check the [Github Pages Deploy Action documentation](https://github.com/JamesIves/github-pages-deploy-action).
## DocFX Support
[DocFX](https://dotnet.github.io/docfx/) allows generating documentation from Markdown files and comments in C# scripts. This project configures DocFX to generate a website with a similar layout as Unity's own packages: a documentation split between "Manual," generated from Markdown files in the `manual` folder, and "Scripting API," generated from comments in C# scripts. To customize the generated site, especially the Manual, the following files and folders should be reviewed:
### `Documentation~/docfx.json`
`docfx.json` is a JSON file containing the configuration for the generator to read. This portion of this manual will only concern itself with fields a package developer will likely want to edit, but for the full documentation on this file, do check out [DocFX's documentation](https://dotnet.github.io/docfx/tutorial/docfx.exe_user_manual.html#3-docfxjson-format) on it. It provides extra information, such as how to edit the theme of the generated website.
There are two fields the developer will probably want to edit:
#### `globalMetadata`
`globalMetadata` refers to this part in the `docfx.json` files:
```json
"globalMetadata": {
"_appTitle": "Template Unity Package documentation",
"_appFooter": "Copyright © 2020 Omiya Games",
"_enableSearch": true
},
```
As one can probably guess from the object's key names, the value under `_appTitle` is printed at the top of the website, and the value under `_appFooter` is printed at the bottom as a footer. It's obviously recommended to change these values to what matches with the developer's package name and company respectively.
#### `sitemap`
`sitemap` refers to this part in the `docfx.json` files:
```json
"sitemap":
{
"baseUrl": "https://omiyagames.github.io/template-unity-package/",
...
},
```
While this field has many keys, changing the `baseUrl` is important because it siginifies to the sitemap generator what the base URL for the generated site is going to be. Obviously, this should be changed to the URL your documentation is going to be generated in (e.g. for Github, `https://<username>.github.io/<repo-name>/`). Note the trailing `/` is necessary.
### `Documentation~/filterConfig.yml`
`filterConfig.yml` is a YAML file DocFX uses to filter in or out C# code to generate the "Scripting API" portion of the documentation. The full documentation on this file is [available here](https://dotnet.github.io/docfx/tutorial/howto_filter_out_unwanted_apis_attributes.html). The part that the package developer needs to change is the list of [regular expressions](https://regexr.com/) that is used to match C# scripts defined under certain namespaces. As one can see below, by default, the template package filters in `OmiyaGames.Template`, `OmiyaGames.Template.Editor`, or global namespace.
```yaml
- include:
# Taro Omiya: Updated namespace for this template
# Including the OmiyaGames.Template namespace
uidRegex: ^OmiyaGames\.Template$
type: Namespace
- include:
# Taro Omiya: Updated namespace for this template
# Including the OmiyaGames.Template.Editor namespace
uidRegex: ^OmiyaGames\.Template\.Editor$
type: Namespace
- include:
uidRegex: ^Global
type: Namespace
```
The developer should change `^OmiyaGames\.Template$` and `^OmiyaGames\.Template\.Editor$` to match their scripts' namespaces, perhaps even remove some include list items if not necessary. Since these are regular expressions, wildcards like `*` may be used.
### `Documentation~/index.md`
`index.md` is the Markdown file DocFX uses to generate the homepage of the documentation. Obviously, the package developer should edit it to introduce the reader to their package. Alternatively, one may also chose to delete this file, and edit `.github/workflows/documentation.yml` to copy the package's `README.md` to `Documentation~/index.md` automatically instead.
### Files in `Documentation~/manual/`
As the `README.md` file under this folder mentions, the `manual` folder is where the package developer can create a number of markdown files to add under the "Manual" portion of the documentation. Obviously, it's recommended for the developer to delete all the files ending in `*.md`, and replace them with their own Markdown files to describe how to use their package. If the Markdown file needs to reference a media file, such as images, they can be added into the `Documentation~/resources/`, which is detailed later. Once the documentation is finished, the table of contents file must be updated, which leads us to...
#### `Documentation~/manual/toc.yml`
`toc.yml` is the table of contents YAML file that supports formatting that looks like this:
```yaml
- name: Customizing Package
items:
- name: Package Files
href: customizePackage.md
- name: Source Code and Assets
href: customizeSource.md
- name: Importable Assets
href: customizeSamples.md
- name: Documentation
href: customizeDocumentation.md
- name: Change Log
href: changelog.md
```
As demonstrated in the example above, DocFX table of contents support multiple hierarchies through the `items` field. Other than that, `name` field is the displayed text as a bullet point, while `href` is either a URL to another website, or a path to a markdown file local to the `toc.yml` file. The full documentation on this file is [available here](https://dotnet.github.io/docfx/tutorial/intro_toc.html).
Obviously, once the manual documentation is updated, this file should be updated as well to indicate which markdown files should be read to generate the manual.
### Files in `Documentation~/resources/`
`resources` is a folder the developer can add media files to, to better enhance their `manual` Markdown files with images and so forth. Obviously, the entire content of this folder can be deleted and replaced with what's necessary for the documentation's "Manual."
## Doxygen Support
Apart from DocFX, the `Documentation~` folder also contains a `Doxyfile` that, with only a few edits, can be used by [Doxygen](http://doxygen.nl/) to generate documentation from the C# scripts in the package.
### `Documentation~/Doxyfile`
`Doxyfile` is a massive text file containing configuration settings for Doxygen's Doxywizard, which then reads the comments from the package's C# scripts and generated a website. This section will cover only a few fields to update as bare-minimum setup, but the full documentation is [available here](http://www.doxygen.nl/manual/index.html).
#### `PROJECT_NAME`
The `PROJECT_NAME` field is what gets displayed on the top of the generated webpage:
```
PROJECT_NAME = "Omiya Games - Template Unity Package"
```
Obviously, the value of this field should be changed to the package's name.
#### `PROJECT_NUMBER`
The `PROJECT_NUMBER` field is the identifier of the project.
```
PROJECT_NUMBER = com.omiyagames.template
```
The value of this field should be changed to the unique identifier of the package (e.g. the `name` field in `package.json`).
#### `PROJECT_BRIEF`
Latly, the `PROJECT_BRIEF` field refers to the subtitles appearing below the `PROJECT_NAME`.
```
PROJECT_BRIEF = "Just a template, acting as a useful starting point to develop a Unity package."
```
Naturally, this value should be changed to a brief description of the package.

View File

@ -1,173 +0,0 @@
# Customizing Package
This part of the manual pertains to the following folders and files:
```
<root>
├── package.json
├── README.md
├── CHANGELOG.md
├── LICENSE.md
├── THIRD PARTY NOTICES.md
├── .gitignore
└── .github
├── FUNDING.yml
├── ISSUE_TEMPLATE
| ├── bug_report.md
| ├── feature_request.md
| ├── documentation-template.md
| └── research_template.md
└── workflows
├── documentation.yml
└── mirror.yml
```
Per [Unity's documentation](https://docs.unity3d.com/Manual/CustomPackages.html), technically, the only required file in this section is `package.json`. Nonetheless, this template follows the standard set by [Unity's documentation](https://docs.unity3d.com/Manual/cus-layout.html) to keep things consistent with other packages. Plus, filling out the following files should help other developers better understand the purpose of the package:
## Package Manifest - [`package.json`](https://docs.unity3d.com/Manual/upm-manifestPkg.html)
This file is required: it should not be deleted, moved, or renamed. That said, it *must* be edited.
![Unity Package Manager](https://omiyagames.github.io/template-unity-package/resources/preview.png)
The Package Manifest file is a JSON file storing details about the package that the Package Manager can use to display and categorize the project. Note that this file *can* be edited inside the Unity Inspector like any other asset files, as opposed to editing it in the text editor; Unity even provides a nice UI for it. Furthermore, Unity's [own documentation](https://docs.unity3d.com/Manual/upm-manifestPkg.html) is quite extensive, so this section will only cover a couple of important fields:
### `name`
```
"name": "com.omiyagames.template",
```
This field is required, and *must* be changed.
The `name` field is a unique identifier differentiating this package from potentially other packages with similar display names. The string stored in this field should follow the classic `com.<company-name>.<package-name>` format. Furthermore, it's recommended to keep the string below 50 characters in length. For more information, check out [Unity's documentation](https://docs.unity3d.com/Manual/upm-manifestPkg.html#name).
### `version`
```
"version": "0.1.0-preview.1",
```
This field is required. Changing it is recommended, but not necessary.
The `version` field informs the Unity Package Manager what version this package is on. If a service like [OpenUPM](openupm.com) is being used, this field further informs the Package Manager if the package is in need of an update. Unity provides a pretty thorough explanation of [how this field should be filled in](https://docs.unity3d.com/Manual/upm-semver.html), but the classic `<major>.<minor>.<patch>` should suffice here. If in preview, don't forget to add `-preview.<patch>` as well.
### `displayName`
```
"displayName": "Omiya Games - Template Unity Package",
```
While technically not required, this field should kept, and more importantly, *changed.*
When the Unity Package Manager displays the name of this package, `displayName` is the field it'll use. Simply provide a human-friendly name for this package to this field.
### `description`
```
"description": "This is a template package, used as a basis to build a bigger one.",
```
While technically not required, this field should kept, and more importantly, *changed.*
When the Unity Package Manager displays a description of this package when selected, `description` is the field it'll use. Simply provide a human-friendly description for this package to this field. Note that UTF-8 characters are supported via `\u2603` and `\n`.
### `unity`
```
"unity": "2019.3",
```
While technically not required, this field should kept. Changing it is recommended, but not necessary.
Indicates the lowest version of Unity this package supports. If patch release info is necessary as well (e.g. Unity 2019.3.7f3), the last set of digits can be added to `unityRelease` field.
### `type`
```
"type": "tool",
```
Optional, and only used internally as of this writing. Changing it is recommended, but not necessary.
Indicates the type of this package. As of this writing, values Unity recognizes are:
- tool
- library
- module
- template
- sample
- tests
Per [Unity's documentation](https://docs.unity3d.com/Manual/CustomPackages.html), technically, the only required file in this section is `package.json`. Nonetheless, this template follows the standard set by [Unity's documentation](https://docs.unity3d.com/Manual/cus-layout.html) to keep things consistent with other packages. Plus, filling out the following files should help other developers better understand the purpose of the package:
### `dependencies`
```json
"dependencies": {
"com.unity.ext.nunit": "1.0.0"
},
```
This field is optional, and if this package does not contain any code or plugins, can be safely removed. If it *does*, this field should be updated to the code's requirements.
As the name implies, `dependencies` is a list of packages this project relies on. The list of object parameters should be listed in `"<package-unique-identifier>": "<supported-version-of-package>"`.
As this field is critical for adding compiling source code to the package, more information is available at the [Adding Source Code and Assets](https://omiyagames.github.io/template-unity-package/manual/customizeSource.html) section of this manual.
### `samples`
```json
"samples": [
{
"displayName": "Example 1",
"description": "This sample is just an example",
"path": "Samples~/Example1"
}
]
```
This field is optional, and if this package does not contain assets users can import, can be safely removed. If it *does*, this field should be changed to the package's director setup.
Unity Package Manager provides an option for packages to list one or more "Import to project" buttons, which naturally allows the user to import assets into their project. To specify what gets imported, the `samples` field contains a list of objects, each holding the `displayName`, `description`, and `path` (relative to the root of the package's directory) fields.
As this field is critical for adding importable assets to the package, more information is available at the [Adding Importable Assets](https://omiyagames.github.io/template-unity-package/manual/customizeSamples.html) section of this manual.
## Github-Specific Features - `.github` Folder
Files in the `.github` folder are intended for Github-specific features, including templates for its bug-tracking system (folder `ISSUE_TEMPLATE`), list of websites to sponsor the package (file `FUNDING.yml`), and automation feature under `workflows` folder. Obviously, if the repo is *not* hosted on Github, this folder and its content can be safely deleted. If the developer *does* want to utilize some of the features this template comes with, the purpose of each file or folder will be listed below:
### `.github/workflows/mirror.yml`
This YAML file instructs Github to automatically push any changes made to this online repository to other mirrors. It's frankly recommended to delete this file, as most developers won't need it. If the developer is interested in mirroring, the subject is fairly large and out-of-scope for this manual, but the following resources should help give direction:
- [Github Action page](https://github.com/marketplace/actions/mirroring-repository)
- [Managing deploy keys](https://developer.github.com/v3/guides/managing-deploy-keys/)
- [Adding secrets](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets)
Also, don't forget to review the content of the file itself, as it does provide some comments to help give directions.
### `.github/workflows/documentation.yml`
This YAML file instructs Github to automatically generate a documentation website. For those who would like to take advantange of this feature, the [Customizing Documentation](https://omiyagames.github.io/template-unity-package/manual/customizeDocumentation.html) section of this manual covers this file extensively. Obviously, if the developer has no plans on generating documentation for their package, this file can be safely deleted.
### `.github/FUNDING.yml`
This YAML file adds a "Sponsor" button at the top of an open-source Github repository. If the developer would like to take advantage of the feature, the comments (text following `#`) on the text file is pretty self-explanatory, and won't be elaborated here. If the package is not going to be open-source, or in need of sponsoring, this file can be safely removed.
### `.github/ISSUE_TEMPLATE` folder
The markdown files in the `.github/ISSUE_TEMPLATE` holds templates for issues one can file on Github, providing a standard for the issue filer. As markdown files, the files should be human-readable, and its content won't be futher elaborated on this manual. As usual, if there's no need for any or all templates in this folder, the folder or individual files themselver may be safely deleted.
## ReadMe - `README.md`
It's recommended to edit this file.
As the name of the file implies, `README.md` is a Markdown file intended to inform first-time viewers of this package's source what the purpose of the package is, and provide guidance on maintainers where the important files are. It has the added bonus that most online repository websites displays this Markdown file as an in-depth description of the project as a whole.
## Package License - `LICENSE.md`
It's recommended to edit this file.
As the name of the file implies, `LICENSE.md` is a Markdown file describing the license of the package overall. It has the added bonus that some open-source-encouraging online repository websites uses this file to indicate developers the license of the project. If there are assets borrowed from third-party sources, it is recommended to list those in `THIRD PARTY NOTICES.md`.
## Other Third-Party Licenses - `THIRD PARTY NOTICES.md`
If the package does not contain any third-party assets, this file may be safely removed. Otherwise, it's highly recommended to edit this file.
`THIRD PARTY NOTICES.md` is a Markdown file that informs the reader what assets comes from third-party sources, and what the license of those assets are.
## Change Log - `CHANGELOG.md`
It's recommended to edit this file.
`THIRD PARTY NOTICES.md` is a Markdown file listing all the past versions of this package, and how the package has changed. Each time a new release is being prepared, this file should be updated with the latest information.
## Ignore File - [`.gitignore`](https://git-scm.com/docs/gitignore#_pattern_format)
It's recommend to keep this file; feel free to make edits to it for your own purpose.
The Git version control uses this `.gitignore` text file to determine what files to ignore when the application reviews any changes to the project. The default content held in this project should be fine for most Unity users. That said, if changes needs to be made, the official documentation on formatting `.gitignore` is available [here](https://git-scm.com/docs/gitignore#_pattern_format).

View File

@ -1,70 +0,0 @@
# Adding Importable Assets
This part of the manual pertains to the following folders and files:
```
<root>
├── package.json
└── Samples~
└── Example1
└── Example.txt
```
Per [Unity's documentation](https://docs.unity3d.com/Manual/CustomPackages.html), technically, the only required files in this section is `package.json` and at least one folder. Furthermore, all folders do *not* have to be named the way they are, or put into hierarchy the way they are. As Unity has not documented on their recommendation of where to place importable assets, `Samples~` will be used for this section, as the trailing `~` hides the folder from Unity Project Window's view.
Note that if the project does *not* contain any importable assets, the folder `Samples~`, its subfolder, and content can be deleted safely. Do not forget to update the `package.json` file accordingly, as detailed at the bottom of this section.
This section will assume the developer *will* rename a few folders an files, and describe how to update the package to work with the new folder naming-scheme:
## `Samples~` folder
This folder is intended contain assets that can be importaed from the Unity Package Manager window. As a demonstration, the template contains one subfolder, `Example1`. Since it and its content is obviously just a sample asset, it's recommended to delete this folder and update the Package Manifest accordingly (see the end of this section on how).
If it hasn't been done so already, it's highly recommended to configure the Unity Editor to generate meta files. For more information on Unity meta file settings, see [Unity's documentation](https://docs.unity3d.com/2019.1/Documentation/Manual/class-EditorManager.html) on Editor Manager.
![Samples List](https://omiyagames.github.io/template-unity-package/resources/samples.png)
As seen in the screenshot above, the Unity Package Manager allows the package maintainer to list different groups of assets to import separately from one another (e.g. required assets vs. sample demonstrations). As such, it's recommended to categorize each importable assets first. From there, simply create a subfolder for each category, and copy or move any assets belonging in that category into the new subfolder. Since the `Samples~` folder is hidden in the Unity Project window, this *must* be done in a file manager, e.g. Finder on Mac OSX. Remember when copying or moving any importable assets from the Unity project to a `Samples~` subfolder, the meta file with matching file name should be copied/moved into the same subfolder as well for maximum compatibility. Finally, do note that subfolders in `Samples~` can have more nested subfolders, if the package maintainer so desires. When the assets get imported, the hierarcy of these subfolders will be copied over as well.
Once this is all finished, the Package Manifest **MUST** be updated to recognize these new subfolders (see below).
## Package Manifest - [`package.json`](https://docs.unity3d.com/Manual/upm-manifestPkg.html)
This file is required: it should not be deleted, moved, or renamed. That said, it *must* be edited.
The Package Manifest file is a text file in JSON format storing details about the package that the Package Manager can use to display and categorize the project. This section will only focus on one field: the `samples` field. As of this writing, Unity does allow editing this field through its Inspector window: the file *must* be updated with a text editor. For more information about this file, check out Unity's [own documentation](https://docs.unity3d.com/Manual/upm-manifestPkg.html)!
### `samples`
```json
"samples": [
{
"displayName": "Example 1",
"description": "This sample is just an example",
"path": "Samples~/Example1"
}
]
```
This field is optional, and if this package does not contain any importable assets, can be safely removed. If it *does*, this field should be updated.
As the name implies, `samples` is the details of each group of importable assets, split by subfolders. By default, this template lists the `Samples~/Example1` folder it came with. The field takes in a list of objects, each with the following fields:
- `displayName`: the human-readable name listed next to the "Import to Project" button.
- `description`: the description of the group of assets to import.
- `path`: the path to the folder where this group of assets are held in. The path is relative to the root of the package, and the folder names should be divided with a `/`, *regardless* of what operating system the package is developed in.
If, for example, there are two sample folders, `Samples~/Required` and `Samples~/Examples`, this field could be edited as follows:
```json
"samples": [
{
"displayName": "Required Assets",
"description": "Assets required to make this package work",
"path": "Samples~/Required"
},
{
"displayName": "Examples",
"description": "Examples assets that demonstrates how this package works.",
"path": "Samples~/Examples"
}
]
```
As of this writing, this field is not documented in Unity's official documentation yet. Most likely, it means this field is still in experimental phases, and may change in the future.

View File

@ -1,142 +0,0 @@
# Adding Source Code and Assets
This part of the manual pertains to the following folders and files:
```
<root>
├── package.json
├── Runtime
│ ├── OmiyaGames.Template.asmdef
│ └── RuntimeExample.cs
├── Editor
│ ├── OmiyaGames.Template.Editor.asmdef
│ └── EditorExample.cs
└── Tests
├── Runtime
│ ├── OmiyaGames.Template.Tests.asmdef
│ └── RuntimeExampleTest.cs
└── Editor
├── OmiyaGames.Template.Editor.Tests.asmdef
└── EditorExampleTest.cs
```
Per [Unity's documentation](https://docs.unity3d.com/Manual/CustomPackages.html), technically, the only required files in this section is `package.json` and at least one [`*.asmdef` file](https://docs.unity3d.com/Manual/cus-asmdef.html). Furthermore, all folders can be customized to the developer's liking. Nonetheless, this template follows the standard recommended by [Unity](https://docs.unity3d.com/Manual/cus-layout.html).
Note that if the project *only* contains importable assets, the folder `Runtime`, `Editor`, `Tests`, and all their subfolders and content can be deleted safely (yes, even the `*.asmdef` files, as far as this writer is aware). Do not forget to update the `package.json` file accordingly, as detailed below.
For the sake of brevity, this section will not cover what an [Assembly Definition (*.asmdef) file](https://docs.unity3d.com/Manual/cus-asmdef.html) is, and what purpose it holds. It is highly recommended to review [Unity's documentation](https://docs.unity3d.com/Manual/cus-asmdef.html) on this file. Finally, this section will assume the developer chose not to rename the folders, although they *will* need to rename some files.
### Package Manifest - [`package.json`](https://docs.unity3d.com/Manual/upm-manifestPkg.html)
This file is required: it should not be deleted, moved, or renamed. That said, it *must* be edited.
The Package Manifest file is a text file in JSON format storing details about the package that the Package Manager can use to display and categorize the project. Note that this file *can* be edited inside the Unity Inspector like any other asset files, as opposed to editing it in the text editor; Unity even provides a nice UI for it.
This section will only focus on one field: defining this package's dependencies. For more information about this file, check out Unity's [own documentation](https://docs.unity3d.com/Manual/upm-manifestPkg.html)!
#### `dependencies`
```json
"dependencies": {
"com.unity.ext.nunit": "1.0.0"
},
```
This field is optional, and if this package does not contain any code or plugins, can be safely removed. If it *does*, this field should be updated to the code's requirements.
As the name implies, `dependencies` is a list of packages this project relies on. The list of object parameters should be listed in `"<package-unique-identifier>": "<supported-version-of-package>"`. By default, this template lists the first version of Unity's unit testing package as a dependency. If, for example, a developer wants to utilize the latest input system into their package, they'll need to list the identifier and version of the package like so (don't forget to add a comma between each package definition):
```json
"dependencies": {
"com.unity.ext.nunit": "1.0.0",
"com.unity.inputsystem": "1.0.0"
},
```
As of this writing, only a specific version number can be defined for each package. No version range is supported yet.
To learn more, check out [Unity's documentation](https://docs.unity3d.com/Manual/upm-manifestPkg.html#dependencies)!
## `Runtime` folder
This folder is intended for scripts that can be utilized when a Unity game runs. This can include C# scripts, especially `MonoBehaviors`, `ScriptableObjects`, Attributes, and even just regular classes and structs, as well as plugins and non-editable media files (useful for defining defaults).
If this package does *not* need any such files, e.g. it's purely a Unity Editor tool, this folder, its contents, and its corresponding `Tests/Runtime` folder may be dafely deleted.
#### Assembly Definition - [`Runtime/OmiyaGames.Template.asmdef`](https://docs.unity3d.com/Manual/cus-asmdef.html)
If the entire `Runtime` folder and content isn't deleted, this file *must* be renamed and edited.
This is the file that will group the source code in the `Runtime` folder into a single C# project, separating it from the rest of the folders in the package, as well as the Unity project when this package gets imported. The file name, which needs to be unique, should be changed to match either the package's unique identifier with capitalization, or the namespace the scripts are scoped in (preferably both). After renaming the file, the following fields in it should be updated:
- `name`: must be unique from other Assembly Definition files. Recommended to be updated to match the namespace the scripts are scoped in.
- `references`: list of C# projects the source code depends on. The name of each project should be the same as the `name` field in the Assembly Definition file in said dependencies.
- `includePlatforms`: a list of platforms this project supports. Keep the list empty if all platforms should be supported.
- `excludePlatforms`: a list of platforms this project *does not* supports. Keep the list empty if all platforms should be supported.
Editing this file can be done in the Unity Inspector window, when the file is selected in the Project window, or a typical text editor. Don't forget to check out [Unity's documentation](https://docs.unity3d.com/Manual/cus-asmdef.html) for more information on the rest of the fields in the file!
#### Sample Code - `Runtime/RuntimeExample.cs`
A simple `MonoBehavior` script. Since it's obviously just a sample file, it's recommended to delete this code.
## `Editor` folder
This folder is intended for scripts that customizes the Unity editor in some way, but isn't used in the game itself. This basically means any editor C# scripts, such as `Editor`, `PropertyDrawers`, and `SettingsProvider`. If the code has the line, `using UnityEditor;` or some variant near the top of the file, it's very much an editor script and belongs here.
If this package does *not* need any such files, e.g. it's purely a Runtime tool, plugin, or a bunch of default assets, this folder and its contents may be safely deleted.
#### Assembly Definition - [`Editor/OmiyaGames.Template.Editor.asmdef`](https://docs.unity3d.com/Manual/cus-asmdef.html)
If the entire `Editor` folder and content isn't deleted, this file *must* be renamed and edited.
This is the file that will group the source code in the `Editor` folder into a single C# project, separating it from the rest of the folders in the package, as well as the Unity project when this package gets imported. The file name, which needs to be unique, should be changed to match either the package's unique identifier with capitalization, or the namespace the scripts are scoped in (preferably both). If the `Runtime` folder still exists, don't forget to add `.Editor` in the file name as well to differentiate the two. After renaming the file, the following fields in it should be updated:
- `name`: must be unique from other Assembly Definition files. Recommended to be updated to match the namespace the scripts are scoped in.
- `references`: list of C# projects the source code depends on. The name of each project should be the same as the `name` field in the Assembly Definition file in said dependencies. If the `Runtime` folder exists, don't forget to add the `name` of the corresponding Assembly Definition files in this list as well.
Editing this file can be done in the Unity Inspector window, when the file is selected in the Project window, or a typical text editor. Note that the fields, `includePlatforms` and `excludePlatforms` should already be set properly. Don't forget to check out [Unity's documentation](https://docs.unity3d.com/Manual/cus-asmdef.html) for more information on the rest of the fields in the file!
#### Sample Code - `Editor/EditorExample.cs`
A simple `Editor` script. Since it's obviously just a sample file, it's recommended to delete this code.
## `Tests`, and its subfolders
This folder and its two subfolders, `Tests/Editor` and `Tests/Runtime`, is intended for any unit tests validating the functionality of scripts in the `Runtime` and `Editor` folder. As their name implies, `Tests/Editor` runs tests in the Unity editor itself, while `Tests/Runtime` sets up a new scene to run any runtime tests. Where possible, it's actually recommended to throw as many unit tests in the `Tests/Editor` as possible, *even* if they're testing scripts from the `Runtime` folder, so long as the tested script does not have to be attached to a `GameObject` or rely on an existence of a scene. Tests in this subfolder runs much faster because a scene doesn't need to be setup for it. Typically, `MonoBehaviors` and `Components` are the only scripts that are tested in the `Tests/Runtime` folder. See [Unity's documentation](https://docs.unity3d.com/2019.1/Documentation/Manual/testing-editortestsrunner.html) on unit testing for more details.
If there are no plans to add unit tests into this project (e.g. plugins that already have one in a separate project), it is safe to delete this folder and its content. Alternatively, if there are no plans to run tests in the `Runtime` scope, the subfolder, `Tests/Runtime` can be safely deleted; same story for `Editor` and `Tests/Editor`.
#### Editor Test Assembly Definition - [`Tests/Editor/OmiyaGames.Template.Editor.Tests.asmdef`](https://docs.unity3d.com/Manual/cus-asmdef.html)
If the entire `Tests/Editor` folder and content isn't deleted, this file *must* be renamed and edited.
This is the file that will group the unit tests in the `Tests/Editor` folder into a single C# project, separating it from the rest of the folders in the package, as well as the Unity project when this package gets imported. The file name, which needs to be unique, should be changed to match either the package's unique identifier with capitalization, or the namespace the scripts are scoped in (preferably both). Don't forget to add `.Editor.Tests` in the file name to differentiate it from the rest of the assembly definition files. After renaming the file, the following fields in it should be updated:
- `name`: must be unique from other Assembly Definition files. Recommended to be updated to match the namespace the scripts are scoped in.
- `references`: list of C# projects the unit tests depends on. The name of each project should be the same as the `name` field in the Assembly Definition file in said dependencies. Don't forget to add the `name` of the `Runtime` and/or `Editor` Assembly Definition files in this list as well.
Editing this file can be done in the Unity Inspector window, when the file is selected in the Project window, or a typical text editor. Note that the fields, `includePlatforms` and `excludePlatforms` should already be set properly. Furthermore, if the Unity Inspector is used to edit this file, do *not* remove `UnityEngine.TestRunner` and `UnityEditor.TestRunner` from the `references` field. Don't forget to check out [Unity's documentation](https://docs.unity3d.com/Manual/cus-asmdef.html) for more information on the rest of the fields in the file!
#### Editor Sample Unit Test - `Tests/Editor/EditorExampleTest.cs`
A simple NUnit test script. Since it's obviously just a sample file, it's recommended to delete this code.
#### Runtime Test Assembly Definition - [`Tests/Editor/OmiyaGames.Template.Tests.asmdef`](https://docs.unity3d.com/Manual/cus-asmdef.html)
If the entire `Tests/Runtime` folder and content isn't deleted, this file *must* be renamed and edited.
This is the file that will group the unit tests in the `Tests/Runtime` folder into a single C# project, separating it from the rest of the folders in the package, as well as the Unity project when this package gets imported. The file name, which needs to be unique, should be changed to match either the package's unique identifier with capitalization, or the namespace the scripts are scoped in (preferably both). Don't forget to add `.Tests` in the file name to differentiate it from the rest of the assembly definition files. After renaming the file, the following fields in it should be updated:
- `name`: must be unique from other Assembly Definition files. Recommended to be updated to match the namespace the scripts are scoped in.
- `references`: list of C# projects the unit tests depends on. The name of each project should be the same as the `name` field in the Assembly Definition file in said dependencies. Don't forget to add the `name` of the `Runtime` Assembly Definition files in this list as well.
- `includePlatforms`: a list of platforms this project supports. Keep blank if all platforms should be supported.
- `excludePlatforms`: a list of platforms this project *does not* supports. Keep blank if all platforms should be supported.
Editing this file can be done in the Unity Inspector window, when the file is selected in the Project window, or a typical text editor. If the Unity Inspector is used to edit this file, do *not* remove `UnityEngine.TestRunner` and `UnityEditor.TestRunner` from the `references` field. Don't forget to check out [Unity's documentation](https://docs.unity3d.com/Manual/cus-asmdef.html) for more information on the rest of the fields in the file!
#### Runtime Sample Unit Test - `Tests/Editor/RuntimeExampleTest.cs`
A simple NUnit test script. Since it's obviously just a sample file, it's recommended to delete this code.

View File

@ -1,12 +0,0 @@
- name: Customizing Package
items:
- name: Package Files
href: customizePackage.md
- name: Source Code and Assets
href: customizeSource.md
- name: Importable Assets
href: customizeSamples.md
- name: Documentation
href: customizeDocumentation.md
- name: Change Log
href: changelog.md

View File

@ -1 +0,0 @@
This folder contains all images and media files used in the documentation markdown files, such as those in the [`Documentation~/manual`](/Documentation~/manual) folder.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 61 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 22 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 65 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 12 KiB

View File

@ -1,4 +0,0 @@
- name: Manual
href: manual/
- name: Scripting API
href: api/

View File

@ -1,7 +1,7 @@
{ {
"name": "OmiyaGames.Template.Editor", "name": "COMPANYNAME.PACKAGENAME.Editor",
"references": [ "references": [
"OmiyaGames.Template" "COMPANYNAME.PACKAGENAME"
], ],
"includePlatforms": [ "includePlatforms": [
"Editor" "Editor"

View File

@ -1,91 +1,6 @@
using UnityEngine; using UnityEngine;
using UnityEditor; using UnityEditor;
using UnityEditor.AnimatedValues;
using System.Collections.Generic;
namespace OmiyaGames.Template.Editor namespace COMPANYNAME.PACKAGENAME.Editor
{ {
///----------------------------------------------------------------------- }
/// <remarks>
/// <copyright file="EditorExample.cs" company="Omiya Games">
/// The MIT License (MIT)
///
/// Copyright (c) 2019-2020 Omiya Games
///
/// Permission is hereby granted, free of charge, to any person obtaining a copy
/// of this software and associated documentation files (the "Software"), to deal
/// in the Software without restriction, including without limitation the rights
/// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
/// copies of the Software, and to permit persons to whom the Software is
/// furnished to do so, subject to the following conditions:
///
/// The above copyright notice and this permission notice shall be included in
/// all copies or substantial portions of the Software.
///
/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
/// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
/// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
/// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
/// THE SOFTWARE.
/// </copyright>
/// <list type="table">
/// <listheader>
/// <term>Revision</term>
/// <description>Description</description>
/// </listheader>
/// <item>
/// <term>
/// <strong>Version:</strong> 1.0.0<br/>
/// <strong>Date:</strong> 12/31/2019<br/>
/// <strong>Author:</strong> Taro Omiya
/// </term>
/// <description>Initial verison.</description>
/// </item>
/// <item>
/// <term>
/// <strong>Version:</strong> 1.3.0<br/>
/// <strong>Date:</strong> 5/7/2019<br/>
/// <strong>Author:</strong> Taro Omiya
/// </term>
/// <description>
/// Updated documentation to support DocFX.
/// </description>
/// </item>
/// </list>
/// </remarks>
///-----------------------------------------------------------------------
/// <summary>
/// This is an example script for starting an editor inspector.
/// </summary>
/// <seealso cref="RuntimeExample"/>
[CustomEditor(typeof(RuntimeExample))]
public class EditorExample : UnityEditor.Editor
{
/// <summary>
/// An example of a member variable, used to display in the inspector.
/// </summary>
SerializedProperty exampleField;
/// <summary>
/// OnEnable is called on the frame when a script is displayed in the
/// inspector just before OnInspectorGUI is called the first time.
/// </summary>
public void OnEnable()
{
exampleField = serializedObject.FindProperty("exampleField");
}
/// <summary>
/// OnInspectorGUI is called every frame, if this script is displayed
/// in the inspector.
/// </summary>
public override void OnInspectorGUI()
{
serializedObject.Update();
EditorGUILayout.PropertyField(exampleField, true);
serializedObject.ApplyModifiedProperties();
}
}
}

View File

@ -1,7 +1,6 @@
The MIT License (MIT) MIT License
===============
Copyright (c) 2019-2020 Omiya Games Copyright (c) 2020 COMPANYNAME
Permission is hereby granted, free of charge, to any person obtaining a copy Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal of this software and associated documentation files (the "Software"), to deal
@ -10,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions: furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in The above copyright notice and this permission notice shall be included in all
all copies or substantial portions of the Software. copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
THE SOFTWARE. SOFTWARE.

View File

@ -1,54 +1,11 @@
# [Omiya Games](https://www.omiyagames.com/) - Template Unity Package # [Maxartz15](https://www.maxartz15.com/) - Template Unity Package
[![Template Unity Package documentation](https://github.com/OmiyaGames/template-unity-package/workflows/Host%20DocFX%20Documentation/badge.svg)](https://omiyagames.github.io/template-unity-package/) [![Mirroring](https://github.com/OmiyaGames/template-unity-package/workflows/Mirroring/badge.svg)](https://bitbucket.org/OmiyaGames/template-unity-package) [![ko-fi](https://www.ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/I3I51KS8F) Description.
![Unity Package Manager](https://omiyagames.github.io/template-unity-package/resources/preview.png)
**Template Unity Package** is a Github template [Omiya Games](https://www.omiyagames.com/) uses to start a new [Unity](https://unity.com/) package. To use this template for your own purposes, we recommend:
- Clicking on the green "Use this template" button to create a new online repository on Github directly, or
- Click the "Releases" link, and download the latest archive as zip or gzip file.
From there, consult the following documentation to get a better idea of what files should be edited and/or renamed, and how:
- This project's [own documentation](https://omiyagames.github.io/template-unity-package/)
- [*How to Split Up an Existing Unity Git Project into Smaller Unity Packages*](https://www.taroomiya.com/2020/04/29/how-to-split-up-an-existing-unity-git-project-into-smaller-unity-packages/) by [Taro Omiya](https://github.com/japtar10101)
This package uses [DocFX](https://dotnet.github.io/docfx/) and Github Actions to auto-generate its documentation from both the comments in the source code and the Markdown files in the [`Documentation~`](/Documentation~) directory. Consult the manual on [customizing documentation files](https://omiyagames.github.io/template-unity-package/manual/customizeDocumentation.html) for your own packages. There is also has a pre-made [Doxygen](https://github.com/doxygen/doxygen) settings file in the same directory to run Doxywizard through.
## Install ## Install
There are two common methods for installing this package. Install information.
### Through [Unity Package Manager](https://docs.unity3d.com/Manual/upm-ui-giturl.html)
Unity's own Package Manager supports [importing packages through a URL to a Git repo](https://docs.unity3d.com/Manual/upm-ui-giturl.html):
1. First, on this repository page, click the "Clone or download" button, and copy over this repository's HTTPS URL.
2. Then click on the + button on the upper-left-hand corner of the Package Manager, select "Add package from git URL..." on the context menu, then paste this repo's URL!
While easy and straightforward, this method has a few major downside: it does not support dependency resolution and package upgrading when a new version is released. To add support for that, the following method is recommended:
### Through [OpenUPM](https://openupm.com/)
Installing via [OpenUPM's command line tool](https://openupm.com/) is recommended because it supports dependency resolution, upgrading, and downgrading this package. Given this package is just an example, thought, it hadn't been added into OpenUPM yet. So the rest of these instructions are hypothetical...for now...
If you haven't already [installed OpenUPM](https://openupm.com/docs/getting-started.html#installing-openupm-cli), you can do so through Node.js's `npm` (obviously have Node.js installed in your system first):
```
npm install -g openupm-cli
```
Then, to install this package, just run the following command at the root of your Unity project:
```
openupm add com.omiyagames.template
```
## Resources
- [Documentation](https://omiyagames.github.io/template-unity-package/)
- [Change Log](/CHANGELOG.md)
## LICENSE ## LICENSE
Overall package is licensed under [MIT](/LICENSE.md), unless otherwise noted in the [3rd party licenses](/THIRD%20PARTY%20NOTICES.md) file and/or source code. Overall package is licensed under [MIT](/LICENSE.md), unless otherwise noted in the [3rd party licenses](/THIRD%20PARTY%20NOTICES.md) file and/or source code.
Copyright (c) 2019-2020 Omiya Games

View File

@ -1,5 +1,5 @@
{ {
"name": "OmiyaGames.Template", "name": "COMPANYNAME.PACKAGENAME",
"references": [], "references": [],
"includePlatforms": [], "includePlatforms": [],
"excludePlatforms": [], "excludePlatforms": [],

View File

@ -1,83 +1,5 @@
using UnityEngine; using UnityEngine;
using System.Collections.Generic;
namespace OmiyaGames.Template namespace COMPANYNAME.PACKAGENAME
{ {
///----------------------------------------------------------------------- }
/// <remarks>
/// <copyright file="RuntimeExample.cs" company="Omiya Games">
/// The MIT License (MIT)
///
/// Copyright (c) 2019-2020 Omiya Games
///
/// Permission is hereby granted, free of charge, to any person obtaining a copy
/// of this software and associated documentation files (the "Software"), to deal
/// in the Software without restriction, including without limitation the rights
/// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
/// copies of the Software, and to permit persons to whom the Software is
/// furnished to do so, subject to the following conditions:
///
/// The above copyright notice and this permission notice shall be included in
/// all copies or substantial portions of the Software.
///
/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
/// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
/// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
/// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
/// THE SOFTWARE.
/// </copyright>
/// <list type="table">
/// <listheader>
/// <term>Revision</term>
/// <description>Description</description>
/// </listheader>
/// <item>
/// <term>
/// <strong>Version:</strong> 1.0.0<br/>
/// <strong>Date:</strong> 12/31/2019<br/>
/// <strong>Author:</strong> Taro Omiya
/// </term>
/// <description>Initial verison.</description>
/// </item>
/// <item>
/// <term>
/// <strong>Version:</strong> 1.3.0<br/>
/// <strong>Date:</strong> 5/7/2019<br/>
/// <strong>Author:</strong> Taro Omiya
/// </term>
/// <description>Updated documentation to support DocFX.</description>
/// </item>
/// </list>
/// </remarks>
///-----------------------------------------------------------------------
/// <summary>
/// This is an example script for starting a package.
/// </summary>
/// <seealso cref="Editor.EditorExample"/>
public class RuntimeExample : MonoBehaviour
{
/// <summary>
/// An example of a member variable, visible on the inspector.
/// </summary>
[SerializeField]
[Tooltip("This is an example of a tooltip")]
int exampleField = 0;
/// <summary>
/// Start is called on the frame when a script is enabled just before
/// any of the Update methods is called the first time.
/// </summary>
void Start()
{
}
/// <summary>
/// Update is called every frame, if the MonoBehaviour is enabled.
/// </summary>
void Update()
{
}
}
}

View File

@ -1,14 +1,11 @@
This package borrows code from various different sources, including: This package borrows code from various different sources, including:
# [DocFX for Unity](https://github.com/NormandErwan/DocFxForUnity) # []()
### Relevant Files ### Relevant Files
- [Documentation~/docfx.json](https://github.com/OmiyaGames/template-unity-project/Documentation~/docfx.json) - []()
- [Documentation~/filterConfig.yml](https://github.com/OmiyaGames/template-unity-project/Documentation~/filterConfig.yml)
- [Documentation~/toc.yml](https://github.com/OmiyaGames/template-unity-project/Documentation~/toc.yml)
- [.github/workflows/documentation.yml](https://github.com/OmiyaGames/template-unity-project/.github/workflows/documentation.yml)
### Credits ### Credits
- Author: [Erwan Normand](https://github.com/NormandErwan) - Author: []()
- Source: [DocFX for Unity](https://github.com/NormandErwan/DocFxForUnity) - Source: []()
- License: [MIT](https://github.com/NormandErwan/DocFxForUnity/blob/master/LICENSE) - License: []()

View File

@ -1,8 +1,8 @@
{ {
"name": "OmiyaGames.Template.Editor.Tests", "name": "COMPANYNAME.PACKAGENAME.Editor.Tests",
"references": [ "references": [
"OmiyaGames.Template", "COMPANYNAME.PACKAGENAME",
"OmiyaGames.Template.Editor" "COMPANYNAME.PACKAGENAME.Editor"
], ],
"includePlatforms": [ "includePlatforms": [
"Editor" "Editor"

View File

@ -5,86 +5,16 @@ using System.Collections;
using System.Collections.Generic; using System.Collections.Generic;
using NUnit.Framework; using NUnit.Framework;
namespace OmiyaGames.Template.Editor.Tests namespace COMPANYNAME.PACKAGENAME.Editor.Tests
{ {
///-----------------------------------------------------------------------
/// <remarks>
/// <copyright file="TestEditorExample.cs" company="Omiya Games">
/// The MIT License (MIT)
///
/// Copyright (c) 2019-2020 Omiya Games
///
/// Permission is hereby granted, free of charge, to any person obtaining a copy
/// of this software and associated documentation files (the "Software"), to deal
/// in the Software without restriction, including without limitation the rights
/// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
/// copies of the Software, and to permit persons to whom the Software is
/// furnished to do so, subject to the following conditions:
///
/// The above copyright notice and this permission notice shall be included in
/// all copies or substantial portions of the Software.
///
/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
/// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
/// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
/// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
/// THE SOFTWARE.
/// </copyright>
/// <list type="table">
/// <listheader>
/// <term>Revision</term>
/// <description>Description</description>
/// </listheader>
/// <item>
/// <term>
/// <strong>Version:</strong> 1.0.0<br/>
/// <strong>Date:</strong> 12/31/2019<br/>
/// <strong>Author:</strong> Taro Omiya
/// </term>
/// <description>Initial verison.</description>
/// </item>
/// <item>
/// <term>
/// <strong>Version:</strong> 1.2.0<br/>
/// <strong>Date:</strong> 4/5/2020<br/>
/// <strong>Author:</strong> Taro Omiya
/// </term>
/// <description>Updated with proper example.</description>
/// </item>
/// <item>
/// <term>
/// <strong>Version:</strong> 1.3.0<br/>
/// <strong>Date:</strong> 5/7/2019<br/>
/// <strong>Author:</strong> Taro Omiya
/// </term>
/// <description>Updated documentation to support DocFX.</description>
/// </item>
/// </list>
/// </remarks>
///-----------------------------------------------------------------------
/// <summary>
/// This is an example script for testing a package's editor script.
/// </summary>
/// <seealso cref="RuntimeExample"/>
/// <seealso cref="Editor.EditorExample"/>
public class TestEditorExample public class TestEditorExample
{ {
/// <summary>
/// A Test behaves as an ordinary method
/// </summary>
[Test] [Test]
public void TestEditorExampleSimplePasses() public void TestEditorExampleSimplePasses()
{ {
// Use the Assert class to test conditions // Use the Assert class to test conditions
} }
/// <summary>
/// A UnityTest behaves like a coroutine in Play Mode.
/// In Edit Mode you can use the following line to skip a frame:
/// <code>yield return null;</code>
/// </summary>
[UnityTest] [UnityTest]
public IEnumerator TestEditorExampleWithEnumeratorPasses() public IEnumerator TestEditorExampleWithEnumeratorPasses()
{ {
@ -93,4 +23,4 @@ namespace OmiyaGames.Template.Editor.Tests
yield return null; yield return null;
} }
} }
} }

View File

@ -1,7 +1,7 @@
{ {
"name": "OmiyaGames.Template.Tests", "name": "COMPANYNAME.PACKAGENAME.Tests",
"references": [ "references": [
"OmiyaGames.Template" "COMPANYNAME.PACKAGENAME"
], ],
"includePlatforms": [], "includePlatforms": [],
"excludePlatforms": [], "excludePlatforms": [],

View File

@ -4,86 +4,16 @@ using System.Collections;
using System.Collections.Generic; using System.Collections.Generic;
using NUnit.Framework; using NUnit.Framework;
namespace OmiyaGames.Template.Tests namespace COMPANYNAME.PACKAGENAME.Tests
{ {
///-----------------------------------------------------------------------
/// <remarks>
/// <copyright file="TestRuntimeExample.cs" company="Omiya Games">
/// The MIT License (MIT)
///
/// Copyright (c) 2019-2020 Omiya Games
///
/// Permission is hereby granted, free of charge, to any person obtaining a copy
/// of this software and associated documentation files (the "Software"), to deal
/// in the Software without restriction, including without limitation the rights
/// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
/// copies of the Software, and to permit persons to whom the Software is
/// furnished to do so, subject to the following conditions:
///
/// The above copyright notice and this permission notice shall be included in
/// all copies or substantial portions of the Software.
///
/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
/// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
/// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
/// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
/// THE SOFTWARE.
/// </copyright>
/// <list type="table">
/// <listheader>
/// <term>Revision</term>
/// <description>Description</description>
/// </listheader>
/// <item>
/// <term>
/// <strong>Version:</strong> 1.0.0<br/>
/// <strong>Date:</strong> 12/31/2019<br/>
/// <strong>Author:</strong> Taro Omiya
/// </term>
/// <description>Initial verison.</description>
/// </item>
/// <item>
/// <term>
/// <strong>Version:</strong> 1.2.0<br/>
/// <strong>Date:</strong> 4/5/2020<br/>
/// <strong>Author:</strong> Taro Omiya
/// </term>
/// <description>Updated with proper example.</description>
/// </item>
/// <item>
/// <term>
/// <strong>Version:</strong> 1.3.0<br/>
/// <strong>Date:</strong> 5/7/2019<br/>
/// <strong>Author:</strong> Taro Omiya
/// </term>
/// <description>Updated documentation to support DocFX.</description>
/// </item>
/// </list>
/// </remarks>
///-----------------------------------------------------------------------
/// <summary>
/// This is an example script for testing a package's runtime script.
/// </summary>
/// <seealso cref="RuntimeExample"/>
/// <seealso cref="Editor.EditorExample"/>
public class TestRuntimeExample public class TestRuntimeExample
{ {
/// <summary>
/// A Test behaves as an ordinary method
/// </summary>
[Test] [Test]
public void TestRuntimeExampleSimplePasses() public void TestRuntimeExampleSimplePasses()
{ {
// Use the Assert class to test conditions // Use the Assert class to test conditions
} }
/// <summary>
/// A UnityTest behaves like a coroutine in Play Mode.
/// In Edit Mode you can use the following line to skip a frame:
/// <code>yield return null;</code>
/// </summary>
[UnityTest] [UnityTest]
public IEnumerator TestRuntimeExampleEnumeratorPasses() public IEnumerator TestRuntimeExampleEnumeratorPasses()
{ {

View File

@ -1,7 +1,7 @@
{ {
"name": "com.omiyagames.template", "name": "com.COMPANYNAME.PACKAGENAME",
"displayName": "Omiya Games - Template Unity Package", "displayName": "Template Unity Package",
"version": "0.1.0-preview.1", "version": "0.1.0",
"unity": "2019.3", "unity": "2019.3",
"unityRelease": "7f1", "unityRelease": "7f1",
"description": "This is a template package, used as a basis to build a bigger one.", "description": "This is a template package, used as a basis to build a bigger one.",
@ -9,18 +9,16 @@
"type": "tool", "type": "tool",
"license": "MIT", "license": "MIT",
"author": { "author": {
"name": "Taro Omiya", "name": "Max Kruf",
"email": "support@omiyagames.com", "email": "info@maxartz15.com",
"url": "https://www.omiyagames.com" "url": "https://www.maxartz15.com"
}, },
"dependencies": { "dependencies": {
"com.unity.ext.nunit": "1.0.0" "com.maxartz15.package1": "0.1.0"
}, },
"keywords": [ "keywords": [
"Omiya Games", "COMPANYNAME",
"Scripts", "PACKAGENAME"
"Template",
"Tool"
], ],
"samples": [ "samples": [
{ {