# Authoring Custom UPM Packages
Every semester the same tools get copied into new student projects: the [[0.Dialogue System]] as a `.unitypackage`, the debug console from [[In-Game Debug Console and Cheat Tools]], helper scripts from the starter kits. Copying files means every student ends up with a slightly different, un-updatable fork. A **Unity Package Manager (UPM) package** fixes that:
- Students install with **one Git URL** (*Package Manager > + > Install package from git URL*).
- The code lives in `Packages/`, read-only in their project, so "I edited the dialogue manager and now it is broken" stops happening.
- You publish **versions** (`v1.0.0`, `v1.1.0`); students update deliberately, and a fix reaches everyone.
- **Samples** are imported on demand into `Assets/`, where students *are* meant to edit.
This series converts the existing Dialogue System into the package `com.pittmanclass.dialogue`, hosts it on GitHub next to a second package, and releases it to a class.
**Target:** Unity **6000.5+**, Git **2.14.0 or newer** on `PATH` (the documented minimum for Git dependencies), a GitHub account (see [[Setting Up GitHub for Unity]]). Filed under **Pipelines** in [[Unity Tutorials]].
> [!warning] Code not compiled
> **No script, asmdef or package.json in this series has been compiled or imported into Unity.** JSON was written against the 6000.5 manual pages in Sources (fetched 2026-11-18). Validate JSON in your editor, then follow the import checklist in [[6. Worked Example Class Toolkit Release]].
> [!note] Verification status
> **Verified (6000.5 Manual, 2026-11-18):** Package Manager *+ > Create package* (requires being signed in; technical name pattern `<domain-extension>.<company-name>.<package-name>`; starts at version `0.1.0`); generated layout (`package.json`, `README.md`, `CHANGELOG.md`, `Third Party Notices.md`, `Editor`, `Runtime`, `Tests/Editor`, `Tests/Runtime`, `Samples`, `Documentation`); package manifest required `name` and `version`, recommended `description`, `displayName`, `unity`, optional `author`, `dependencies`, `documentationUrl`, `changelogUrl`, `license`, `keywords`, `samples`, `unityRelease`, `hideInEditor`; naming rules (reverse domain, lowercase, must not contain "unity" / start with `com.unity`, 50-character recommendation); "the Editor ignores scripts inside the Packages folder unless they're part of an assembly definition"; Editor asmdef must reference the Runtime asmdef, runtime code cannot reference Editor code; tests need `testables` in the *project* manifest for non-embedded packages; Semantic Versioning (start at `0.1.0`, `1.0.0` when production-ready, major = breaking); Git dependencies: allowed only in the **project** manifest (not in a package's `dependencies`), `#tag|branch|full commit hash` (short SHA not supported), `?path=` must come **before** `#revision`, the lock file pins the commit and *Install package from git URL* again updates it; private repos need SSH or a credential helper; embedded and local (`file:`) packages; folders ending in `~` are ignored by import; package signatures (tarballs signed through Unity tools, from Unity 6.3).
> **Re-used from existing notes:** Dialogue System file list and its `.unitypackage` install from [[1.Dialogue System .unitypackage Install]] and [[6. Scripts Overview]]; script details checked on 2026-11-18 (e.g. `NPCConversationManager.cs` has `using UnityEditor.Search;` **outside** its `#if UNITY_EDITOR` block).
> [!question] Open questions / unverified
> - **`Samples` vs `Samples~` in a Git-hosted package.** The manifest reference describes sample `path` values starting at `Samples~/`, while the samples page says packages made with *Create package* should keep `Samples` and let the **export** step rename it. Git-hosted packages are never "exported", so this series uses a real `Samples~` folder and `"path": "Samples~/..."` (the manifest-reference form). Test the *Import* button once before releasing.
> - **Exact version numbers of core packages for 6000.5.** The manual says core packages such as `com.unity.ugui` are fixed to a version matching the Editor but the pages fetched did not list the number. The examples use `"com.unity.ugui": "2.0.0"` (the release that merged TextMesh Pro, per the uGUI 2.0 changelog); copy the real number from your project's `Packages/packages-lock.json` before publishing.
> - **TextMesh Pro assembly name** for asmdef references (`Unity.TextMeshPro` is used here); confirm it in the Inspector's *Assembly Definition References* picker.
> - Behaviour of **`Resources` folders inside a package** was not re-verified on 6000.5; part 3 avoids depending on them for package content.
> - Whether a `.unitypackage` export of Samples is ever needed for students without Git (part 5 offers a tarball instead).
## Parts
| # | Note | Covers |
|---|---|---|
| 1 | [[1. Why Packages and the UPM Mental Model]] | `.unitypackage` vs UPM, package sources (registry, Git, local, embedded, tarball), immutability, Level Up! and patterns lens |
| 2 | [[2. Package Layout Manifest and Assemblies]] | *Create package*, folder layout, `package.json` field by field, naming, asmdefs, `~` folders |
| 3 | [[3. Converting the Dialogue System into a Package]] | Runtime vs Editor split, namespaces, removing `UnityEditor` from runtime code, input abstraction, content stays in `Assets` |
| 4 | [[4. Samples Documentation and Tests in a Package]] | `Samples~` and the Import button, README/CHANGELOG/docs, EditMode and PlayMode tests, `testables` |
| 5 | [[5. Git Hosting Tags and Student Install]] | Repo layout with several packages, `?path=`, tags and SemVer, lock file, updating, private repos, tarball fallback |
| 6 | [[6. Worked Example Class Toolkit Release]] | Release `com.pittmanclass.dialogue` 1.0.0 and `com.pittmanclass.devconsole` 0.1.0, student install, hotfix 1.0.1 |
| 7 | [[7. UPM Package Pitfalls]] | Scripts ignored, broken GUIDs, editing cached packages, short SHAs, LFS, version drift, naming |
## Architecture at a glance
```
GitHub repo pittman-class-toolkit
Packages/com.pittmanclass.dialogue/ <- package (embedded in the dev project)
package.json Runtime/ Editor/ Tests/ Samples~/ Documentation~/
Packages/com.pittmanclass.devconsole/ <- second package, same repo
Assets/ (dev-only test scenes, never shipped)
|
| git tag dialogue-v1.0.0
v
Student project Packages/manifest.json
"com.pittmanclass.dialogue":
"https://github.com/<user>/pittman-class-toolkit.git?path=/Packages/com.pittmanclass.dialogue#dialogue-v1.0.0"
-> Library/PackageCache (read-only) + Samples imported into Assets/Samples/... (editable)
```
## Design lens (Level Up!)
[[Level Up! (Review)]] is about designing for players; here the "players" are students using your tools.
- **Level 7 / Level 8 clarity:** a package's `displayName`, README and sample are its HUD. If students cannot tell in five seconds what it does and how to start, the package failed.
- **Level 13 "Love Thy Player":** if installing feels too long, hard or boring, it is. One URL, one sample import, one scene that works.
- **Form follows function (Level 5):** structure the package around what students *do* (add an NPC, write a conversation), not around how the code grew.
## Patterns used (Game Programming Patterns)
- **Facade / Service Locator** - a small public API (`DialogueManager`, events) in front of internal classes; consumers depend on the API surface, which is what Semantic Versioning protects. See [[Game Programming Patterns (Review)]] and [[Architecture and Code Patterns]].
- **Observer** - the package raises events (`ConversationStarted`, `LineShown`) instead of calling project code it cannot know.
- **Component / Dependency Inversion** - the package defines an input interface; the project supplies the implementation (part 3).
## Related (existing)
- [[0.Dialogue System]], [[1.Dialogue System .unitypackage Install]], [[6. Scripts Overview]], [[7.Dialogue Visual Node Editor]] - the system being packaged
- [[Conversation Engine Design for Unity 6]] - a cleaner architecture to grow the package toward
- [[Setting Up GitHub for Unity]], [[Connecting an Existing Unity Project to a New GitHub Repository Using GitHub Desktop]], [[Version Control]], [[1. Serialization Meta and Gitignore]], [[2. Git LFS]], [[4. Versioning Branches and Checks]]
- [[Unity Test Framework]], [[1. Test Assemblies and the Test Runner]] - asmdef-based tests
- [[Build Automation and CI]], [[3. GameCI and GitHub Actions]] - CI for the package repo
- [[Custom Inspectors and Editor Tooling]], [[Editor Windows with UI Toolkit]] - Editor code that goes in `Editor/`
- [[07 - Reusing and Exporting]] - the starter-kit approach this replaces
- [[In-Game Debug Console and Cheat Tools]] - the second package in the worked example
## Sources
- Create and share custom packages (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/custom-packages
- Create a package (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-pkg-structure/cus-create
- Package layout (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-pkg-structure/cus-layout
- Naming your package (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-pkg-structure/cus-naming
- Package manifest reference (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-pkg-manifest/upm-manifest-pkg
- Assembly definitions for packages (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-asmdef
- Samples (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-samples
- Tests for packages (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-tests
- Documentation for packages (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-document
- Package versioning (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/upm-semver
- Export / share a package (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-export and https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-share
- Git dependencies (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/upm-git-dependencies/upm-git
- Install from a Git URL (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/managing-packages-window/upm-ui-actions/upm-ui-giturl
- Embedded packages (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/dependencies-lp/upm-embed
- Local folder packages (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/dependencies-lp/upm-localpath
- Package signatures (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/upm-signature-lp
- Special folder names (6000.5): https://docs.unity3d.com/6000.5/Documentation/Manual/SpecialFolders.html
- uGUI 2.0 changelog: https://docs.unity3d.com/Packages/
[email protected]/changelog/CHANGELOG.html