Skip to content

README.md

Latest commit

 

History

History
85 lines (69 loc) · 7.76 KB

README.md

File metadata and controls

85 lines (69 loc) · 7.76 KB

VPM Package Template

GitHub stars GitHub Tags GitHub release (latest by date including pre-releases) GitHub issues GitHub last commit Discord

A stripped down version of the official VRChat VPM Package Template that excludes all of the extra website/project bloat.

This is modified from Dreadrith's template to support a slightly different workflow, with inspiration from bd_ and Razgriz, and help from Fox_score.

Features

  • Can clone multiple VPM package templates into one Unity project
  • Automatically builds a GitHub release with a .unitypackage, .zip, and package.json upon pushing a commit to the package.json only if there is no existing release tag for the pushed version number when package.json is updated
  • Automatically tag GitHub releases as pre-release when version is hyphenated
  • Can automatically add an icon to the .unitypackage that is displayed when imported
  • Can automatically trigger an update/action to an external repository like a VPM Package Listing

Instructions

  1. Create a new repository using this button:
  2. Clone your new repository onto your PC within an existing Unity project under Packages/ with any directory name
    • This will generate a fresh set of GUIDs for each file within this package template and prevent conflicts with other packages
  3. Modify the cloned files for your new package
    • Replace or remove .github/thumbnail.png with your own .unitypackage import thumbnail
    • Edit .github/workflows/release.yml
      • Line 10 (Remove .github/thumbnail.png if you don't want an import thumbnail)
      • Line 11 (Read Trigger Repo Update section below)
    • Edit .github/workflows/trigger-repo-update.yml
    • Rename and Edit Documentation~/dev.sleightly.template.md if used
    • Rename and Edit Editor/dev.sleightly.template.Editor.asmdef if used
      • "name"
      • "references"
    • Rename and Edit Runtime/dev.sleightly.template.asmdef if used
      • "name"
    • Edit CHANGELOG.md (Recommended Format)
    • Edit LICENSE.md (Need help?)
    • Edit package.json
  4. Add any necessary scripts, resources, samples, and other files
  5. Remove Documentation~, Editor, Runtime, CHANGELOG.md, and LICENSE.md if unused

Trigger Repo Update

If you have a VPM Package Listing (or another repository) you'd like to trigger a workflow for, after building/publishing/modifying a release in this package repository, conduct the following steps as well. Otherwise, skip these steps.

  1. Edit .github/workflows/trigger-repo-update.yml
    • Line 12 (Set to true to enable triggering a repo update when a release is manually published/modified)
    • Line 13 (Owner of target repository to trigger)
    • Line 14 (Name of target repository to trigger)
    • Line 15 (Branch of target repository to trigger)
    • Line 16 (File name of target workflow to trigger)
    • Line 17 (Replace VPM_TOKEN with name of Personal Access Token secret added to this repository)
  2. Edit .github/workflows/release.yml
    • Line 11 (Set to true in order for the automatic build to trigger .github/workflows/trigger-repo-update.yml)

Setting a Personal Access Token

To trigger a remote repository you must create a Personal Access Token (PAT) with the repo scope and store it as a secret.

  1. Create a new fine-grained personal access token (beta)
    • Token name (Can be anything, and is different than the name used in trigger-repo-update.yml)
    • Expiration (Can be anything up to a year)
    • Repository Access - Only Select Repositories
      • Select your VPM Listing/Target repository, not your package repository
    • Permissions - Repository Permissions
      • Actions - Read and Write
      • Metadata - Read-only (Set by default when granted Actions permissions - Mandatory)
    • Press Generate Token
      • Copy and Save the token on the following screen as it will not be displayed again
      • This can be used for any package repository that you may want to trigger your listing repository in the future
  2. Add your PAT as a secret to your package repository
    • Navigate to your package repository (not your listing/target repository) and press the Settings tab
    • Navigate to Secrets and Variables > Actions under the Security tab in the sidebar
    • Press New repository secret
    • Add a Name for the secret
      • This is the name used in trigger-repo-update.yml which the template has named VPM_TOKEN by default
      • Consider naming it based on your listing/target repository in case you have multiple listings in the future
    • Copy the token from step 1 into the Secret field
    • Press Add Secret

Notes

Folders that end in ~ such as Documentation~ or Samples~ are hidden from the Unity Project view within the editor.

Therefore, when the package is exported as a .unitypackage whether manually or via automated GitHub workflow, such folders are omitted. The folders are still present in the .zip export and when imported through the VRChat Creator Companion
⚡