Setting up a Unity package manager project with cloud builds, automated version numbers, and documentation can take days. Oyster Package Generator creates all of this for you by answering a few simple questions about your project. Save hundred of hours deploying and maintaining your Unity package by spending 15 minutes to setup and run Oyster.
Features
Assets
Support
Join the Discord Community if you have questions or need help.
In order to use Oyster Package Generator you'll need the following.
If you just want a project generated run the following in a Unity repo.
npx oyster-package-generator init
If you want a step-by-step guide follow along below.
git init
to prep everything for Gitgit remote add origin YOUR_REPO
. Replace YOUR_REPO
with the proper repo URL (such as git@github.com:ashblue/oyster-package-generator.git). This needs to be done before oyster runs. Reason being it hard writes some Git addresses into your projectnpx oyster-package-generator init
and answer the prompts. Wait for the install script to finish. If you notice a bug on Windows 10 see herenpm run commit
. Choose "chore" and write "My first commit" for the body textgit push
to deploy the master
branch (follow on-screen instructions if prompted)git checkout -b develop
and then run git push
to deploy itdevelop
instead of master
in your repo's settings. While not required, this will make pull requests and maintaining your repo easierOnce setup, all commits to the master
branch will generate a new release. All commits to the develop
branch will generate an unversioned nightly build.
To generate your project you'll need to setup a GitHub repo if you haven't in a Unity project. Make sure you set the origin
remote as the origin is used to auto populate some of the files.
Run the following command and answer the question prompts.
npx oyster-package-generator init
Please note if you plan on using Oyster a lot (or on Windows 10) you should globally install it. npx
can be quite slow since it doesn't cache.
npm install -g oyster-package-generator
# Run the program
oyster init
You're done. If you want to setup cloud builds manually you'll need to do one extra thing.
All commits should be made with the following command. Your project will use Commitizen and enforce syntax via Commitlint.
npm run commit
You should install and use the Git Flow branching strategy when working with Oyster generated packages.
Why do I need GitFlow you might ask? Commits to Oyster's develop
branch automatically create nightly builds. Commits to master
automatically generate package releases. Therefore it's a good idea to work out of Git Flow's feature branches and use the branching strategy.
In short you must have a develop
and master
branch for cloud builds to work properly.
If you're on Windows 10 you may run into the username space bug in the filepath (example C:/first last/ect/...
). This is a known issue with npx
. You might just want to install the package globally with the following instead of trying to fix it.
npm install -g oyster-package-generator
# Run the program
oyster init
You may also want to consider installing Node.js in the root of your C drive to decrease any problems you might encounter. For example a new C:/node
folder during Node's setup.
This package comes with a convenient feature to upgrade an older Oyster project to the latest version. Please consider the following before running the command.
NPM_TOKEN
in your repo's secrets.oyster.json
file (older projects), generate one with the generate-config commandWhen ready, use this command to trigger the upgrade.
npx oyster-package-generator upgrade
If you're on Oyster v1.X or v2.0, you'll need to generate a config file before running the upgrade
command. Configs are new as of version v2.1.0
. Generate a config file by running the following.
npx oyster-package-generator generate-config
Due to a known bug with GitHub Action commits, it's not recommended to add special requirements to a master
protected branch. You can still protect master
, but special requirements will result in crashing the Semantic Release bot that auto deploys releases.
Oyster Package Generator automatically includes an MIT license in the project. You can easily change this by deleting/changing the package.json
license key and the LICENSE.md
file if you desire.
To view the latest upcoming features you can check the roadmap here.
https://trello.com/b/Z9P0XMl6/oyster-package-generator
Follow the guide below to setup your tokens for automatic cloud deploys.
To get builds automatically deploying you'll need an NPM token. To get one we'll have to generate an authentication key and choose the "Automation" token type. You must have an npm account to generate a token.
Add the key to your repo secrets as NPM_TOKEN
.
Next we'll setup a GitHub token with admin privileges.
Next you'll need to setup a GitHub token. While GitHub does provide a token by default to repos. We can't really use it here. Reason being branch protection privileges will stop important automatic updates when you try to release. Causing the release to fail.
First navigate to the personal access token menu by following these instructions. Check the repo box for permissions then create the token.
Add the key to your repo secrets as GH_TOKEN
.
To run this project locally you'll need to clone this repo and run the following in your project root. NVM is recommended to sync your local Node.js version. Or you can install the .nvmrc file version directly from the Node.js site. Please note the version of Node.js you use is important.
# If using NVM
nvm use
npm install
npm run build
After the processes are complete, you'll need to setup the oyster command locally to test it. This is important since you probably want to execute the command in various Unity projects. We can easily do this by running the following.
npm link
When the link is complete you can run oyster
in the terminal. Which will execute the last build created from npm run build
.
If you ever want to remove the global oyster
command just run the following in the project root. This will remove the command entirely and uninstall it.
npm unlink
While developing, you may want to automatically rebuild the app when changes are detected. To do so simply run the following command that will automatically listen for changes.
npm run dev
Please see the Contributing Guidelines document for more info.