# 7. UPM Package Pitfalls Part of [[Authoring Custom UPM Packages]]. Prev: [[6. Worked Example Class Toolkit Release]]. > [!warning] Code not compiled > Fixes refer to files in this series, which were not imported or compiled. See the hub for open questions. ## Authoring | Symptom | Cause | Fix | |---|---|---| | Scripts in the package do nothing, no errors | No `.asmdef` covers them ("the Editor ignores scripts inside the Packages folder unless they're part of an assembly definition") | Put code under `Runtime/` or `Editor/` with their asmdefs; new top-level code folders need their own asmdef | | Package compiles in the Editor, player build fails | `using UnityEditor...` in a runtime script outside `#if UNITY_EDITOR` (the original `NPCConversationManager.cs` had exactly this) | Move Editor code to `Editor/`, or wrap both the `using` and the code in `#if UNITY_EDITOR`; build a non-dev player before every release | | `The type or namespace 'TMPro' could not be found` | Runtime asmdef lacks the TextMesh Pro / uGUI references | Add them in the asmdef Inspector (*Assembly Definition References*) and `com.unity.ugui` to `dependencies` | | Students' scripts cannot see package types | `autoReferenced` off, or types are `internal` | Keep `autoReferenced: true` for class packages; make the intended API `public` | | Package cannot use a class from the student's project | Packages cannot reference `Assembly-CSharp` | Invert the dependency: interfaces/events in the package, implementation in the project (e.g. `IDialogueInput`, `DialogueEvents`, the telemetry bridge staying in `Assets`) | | `Environment.GetCommandLineArgs` (or similar) fails to compile in a project | A global-namespace class in the package hides a `System` type | Put every package type in a namespace (`PittmanClass.Dialogue`) | | Custom inspector errors after adding namespace `...Editor` | `Editor` now resolves to your namespace | Write `UnityEditor.Editor` explicitly | | Legacy `Input` exceptions in new projects | Project uses Input System only | Abstract input (`IDialogueInput`), use `ENABLE_INPUT_SYSTEM` / Version Defines | | Package writes files and they vanish or error | Tool wrote into the package folder (read-only cache for students) | Editor tools write to `Assets/...` (like `Assets/DialogueLayouts`) | ## GUIDs and samples | Symptom | Cause | Fix | |---|---|---| | "Missing script" / broken prefab references after install | `.meta` files not committed, or files copied outside Unity so new GUIDs were generated | Commit every `.meta`; move files in the Project window; never regenerate metas | | Old student scenes lose components after migrating | Package scripts got new GUIDs | Keep the original `.meta` files when moving scripts into the package (part 3) | | Duplicate class / duplicate GUID errors | Old `Assets/Scripts/Grok.Dialogue` still present next to the package | Delete the old folder first (migration steps, part 6) | | No *Import* button for the sample | `samples` missing in `package.json`, wrong `path`, or folder not in the repo | Check `path` matches `Samples~/<Folder>` exactly (case-sensitive on Git hosts) | | Sample appears in the Project window inside the package and compiles | Folder named `Samples` (no tilde) in a Git-distributed package | Rename to `Samples~` and update `path` (hub open question) | | Sample imported into the dev project duplicates GUIDs | Imported the sample back where it was authored | Test samples only in a separate project | ## Distribution | Symptom | Cause | Fix | |---|---|---| | "Unable to add package ... git" | Git not installed / not on `PATH`, or Git older than 2.14.0 | Install Git for Windows; `git --version` in a new terminal; restart Unity Hub | | Install fails with `#tag?path=` | Wrong order | `?path=/Packages/<name>` **before** `#tag` | | "revision not found" with a commit id | Short SHA | Use the **full** 40-character hash, or a tag | | Students have different code with the same URL | Branch URL (`#main`) locked at different commits | Give tag URLs only | | Fix released but students still have the bug | Lock file pins the old commit | Students re-install with the new tag; announce it | | Two different "1.0.0" in the class | A tag was moved or deleted and re-created | Never move tags; release `1.0.1` | | Private repo install fails over HTTPS | No interactive credentials in the Package Manager | Public repo, or SSH / credential helper (part 5) | | Images in the sample are tiny text files | Git LFS pointer files (shallow clone, or no LFS client) | Keep package files out of LFS | | A package's `package.json` lists a Git URL dependency and fails | Git dependencies are allowed only in the project manifest | Ask students to add both packages to their manifest | ## Naming and versioning | Mistake | Why it hurts | Fix | |---|---|---| | Name contains `unity` (e.g. `com.unityclass.tools`) | Not allowed by the naming rules | `com.pittmanclass.tools` | | Uppercase or spaces in `name` | Invalid package name | Lowercase, `-`, `_`, `.` only | | `version` in `package.json` differs from the tag | Package Manager shows one version, students quote another | Bump `version` in the same commit you tag | | Renamed a public field students' prefabs use, released as a patch | Serialized data is part of the API surface; this is breaking | Add `[FormerlySerializedAs]`, or release a major version | | Staying at `0.x` forever | Students cannot tell stable from experimental | `1.0.0` once you will keep the API for a semester | ## Teaching pitfalls - **Students "fixing" package code.** They cannot (read-only cache), so they will copy scripts into `Assets` and get duplicate classes. Teach the extension points (events, interfaces, ScriptableObjects, samples) on day one. - **Too many packages.** Each package is another URL and another version to explain. Two or three packages per course is plenty. - **Release mid-assignment.** Announce updates between assignments; lock files protect students only if you do not ask them to update during a deadline week. ## Sources - 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 - Naming (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 - Git dependencies (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/upm-git-dependencies/upm-git - Package versioning (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/upm-semver - `FormerlySerializedAsAttribute` (6000.5): https://docs.unity3d.com/6000.5/Documentation/ScriptReference/Serialization.FormerlySerializedAsAttribute.html - Related: [[1. Serialization Meta and Gitignore]], [[2. Git LFS]], [[Version Control]]