# 2. Package Layout Manifest and Assemblies Part of [[Authoring Custom UPM Packages]]. Prev: [[1. Why Packages and the UPM Mental Model]]. Next: [[3. Converting the Dialogue System into a Package]]. > [!warning] Code not compiled > JSON files were written against the 6000.5 manual but not imported. Validate them and prefer editing asmdefs in the Inspector (the manual recommends it). ## 1. A development project Make a dedicated Unity project, `PittmanClassToolkit`, used only to build and test packages. It becomes the GitHub repo in part 5. Students never open it. Why not develop inside a game project? Because the package must work **without** anything from that game. A clean dev project proves it. ## 2. Create the package skeleton 1. *Window > Package Management > Package Manager*. 2. **+** (top left) > **Create package**. You must be **signed in** to a Unity account for this option. 3. Enter the **technical name** `com.pittmanclass.dialogue`. The manual's pattern is `<domain-extension>.<company-name>.<package-name>`. 4. Unity creates the package **inside `Packages/`** of the dev project (an *embedded* package, editable), at version **0.1.0**, and shows it under a *Custom* label. If *Create package* is unavailable (not signed in, or an older editor), make the same folders by hand; nothing about the result is special. ### Naming rules (6000.5 "Naming your package") - Reverse-domain style; lowercase letters, digits, `-`, `_` and `.` only. - Must **not** contain `unity` anywhere and must not start with `com.unity`. - Keep it under **50 characters** (recommended) so it fits in the UI. - The name is permanent identity: renaming later is effectively a new package. `com.pittmanclass.dialogue` and `com.pittmanclass.devconsole` follow all rules. Do **not** use `edu.unity-class.dialogue` (contains "unity"). ## 3. The layout The generated layout (6000.5 "Package layout"), with the files this series adds: ``` Packages/com.pittmanclass.dialogue/ ├── package.json <- manifest (lowercase file name) ├── README.md <- for people working ON the package ├── CHANGELOG.md ├── LICENSE.md <- added (or use the "license" field) ├── Third Party Notices.md ├── Runtime/ │ ├── PittmanClass.Dialogue.asmdef │ └── ... runtime scripts ├── Editor/ │ ├── PittmanClass.Dialogue.Editor.asmdef │ └── ... editor windows, inspectors ├── Tests/ │ ├── Editor/ PittmanClass.Dialogue.Editor.Tests.asmdef │ └── Runtime/ PittmanClass.Dialogue.Tests.asmdef ├── Samples~/ <- renamed from Samples (see part 4) │ └── BasicConversation/ └── Documentation~/ └── index.md ``` Folders ending in `~` are **ignored by Unity's importer** (6000.5 special folders, "Hidden assets"), so samples and docs are not compiled or imported until the Package Manager copies a sample into `Assets/`. ## 4. `package.json`, field by field ```json { "name": "com.pittmanclass.dialogue", "version": "0.1.0", "displayName": "Pittman Class - Dialogue System", "description": "Branching NPC dialogue for class projects: JSON conversations, typewriter text, NPC memory and a visual tree editor. Import the Basic Conversation sample to start.", "unity": "6000.5", "author": { "name": "J. Marshall Pittman", "url": "https://github.com/<your-github-user>" }, "dependencies": { "com.unity.ugui": "2.0.0" }, "keywords": [ "dialogue", "npc", "conversation", "education" ], "documentationUrl": "https://github.com/<your-github-user>/pittman-class-toolkit/blob/main/Packages/com.pittmanclass.dialogue/Documentation~/index.md", "changelogUrl": "https://github.com/<your-github-user>/pittman-class-toolkit/blob/main/Packages/com.pittmanclass.dialogue/CHANGELOG.md", "license": "MIT", "samples": [ { "displayName": "Basic Conversation", "description": "One NPC, one branching conversation, UI prefab and JSON file. Open the scene and press Play.", "path": "Samples~/BasicConversation" } ] } ``` | Field | Status (manual) | Notes | |---|---|---| | `name` | required | Matches the folder name by convention; the key used in project manifests | | `version` | required | SemVer `major.minor.patch`; must match your Git tag (part 5) | | `displayName` | recommended | What students see in the list | | `description` | recommended | Shown in the details panel; say how to start | | `unity` | recommended | Minimum Editor `major.minor`; add `unityRelease` only if you need a specific patch | | `author` | optional | name, email, url | | `dependencies` | optional | **Registry packages and exact versions only**; no Git URLs, no ranges | | `keywords` | optional | Search terms in the Package Manager | | `documentationUrl` / `changelogUrl` | optional | Links in the details panel | | `license` | optional | SPDX id, or include `LICENSE.md` | | `samples` | optional | Array of `displayName`, `description`, `path`, optional `images` | | `hideInEditor` | optional | Leave default for class packages | > [!note] `com.unity.ugui` version > The Dialogue System uses `TMP_Text` and uGUI. In Unity 6, TextMesh Pro ships inside `com.unity.ugui` 2.x (uGUI 2.0 changelog). Core packages are fixed to the Editor's version, so the number you write is a *minimum*; copy the exact value from your dev project's `Packages/packages-lock.json` (open question in the hub). ## 5. Assembly definitions The manual is blunt: "the Editor ignores scripts inside the Packages folder unless they're part of an assembly definition." Every code folder needs an `.asmdef`. ### `Runtime/PittmanClass.Dialogue.asmdef` ```json { "name": "PittmanClass.Dialogue", "rootNamespace": "PittmanClass.Dialogue", "references": [ "Unity.TextMeshPro", "UnityEngine.UI", "Unity.InputSystem" ], "includePlatforms": [], "excludePlatforms": [], "allowUnsafeCode": false, "overrideReferences": false, "precompiledReferences": [], "autoReferenced": true, "defineConstraints": [], "versionDefines": [ { "name": "com.unity.inputsystem", "expression": "1.0.0", "define": "PITTMANCLASS_INPUTSYSTEM" } ], "noEngineReferences": false } ``` - **`references`** by assembly *name*. `Unity.TextMeshPro` and `UnityEngine.UI` are the uGUI/TMP assemblies (confirm the names in the Inspector picker - hub open question). `Unity.InputSystem` is only resolved if the Input System is installed; if your Editor reports the unresolved reference as an error in projects without it, add `"com.unity.inputsystem"` to the package's `dependencies` instead (every Unity 6 template already has it). - **`versionDefines`** sets `PITTMANCLASS_INPUTSYSTEM` only when the Input System package is present, so the package compiles in projects without it (part 3 uses this). - **`autoReferenced: true`** lets student scripts in `Assembly-CSharp` use the package without their own asmdef. ### `Editor/PittmanClass.Dialogue.Editor.asmdef` ```json { "name": "PittmanClass.Dialogue.Editor", "rootNamespace": "PittmanClass.Dialogue.Editor", "references": [ "PittmanClass.Dialogue", "Unity.TextMeshPro" ], "includePlatforms": [ "Editor" ], "excludePlatforms": [], "allowUnsafeCode": false, "overrideReferences": false, "precompiledReferences": [], "autoReferenced": true, "defineConstraints": [], "versionDefines": [], "noEngineReferences": false } ``` `includePlatforms: ["Editor"]` keeps it out of builds. It references the Runtime assembly; the reverse is impossible ("Runtime code cannot reference Editor code"). ### Test assemblies (manual's examples, adapted) `Tests/Editor/PittmanClass.Dialogue.Editor.Tests.asmdef`: ```json { "name": "PittmanClass.Dialogue.Editor.Tests", "references": [ "PittmanClass.Dialogue.Editor", "PittmanClass.Dialogue" ], "optionalUnityReferences": [ "TestAssemblies" ], "includePlatforms": [ "Editor" ], "excludePlatforms": [] } ``` `Tests/Runtime/PittmanClass.Dialogue.Tests.asmdef`: ```json { "name": "PittmanClass.Dialogue.Tests", "references": [ "PittmanClass.Dialogue" ], "optionalUnityReferences": [ "TestAssemblies" ], "includePlatforms": [], "excludePlatforms": [] } ``` This is the shape the 6000.5 package-tests page shows. If you create test assemblies with the Test Runner instead, it may write the newer form (`UnityEngine.TestRunner` / `UnityEditor.TestRunner` references, `nunit.framework.dll`, `UNITY_INCLUDE_TESTS`); either works - see [[1. Test Assemblies and the Test Runner]]. ## 6. Working on it: embedded vs local | Mode | Where | When | |---|---|---| | Embedded | `PittmanClassToolkit/Packages/com.pittmanclass.dialogue/` | Day-to-day development and tests (this series) | | Local `file:` | Another project's manifest points at the folder | Try the package in a real game project before releasing; changes are live in both | | Git | Student projects | Releases only | Local example in a *game* project's `Packages/manifest.json` (forward slashes, relative to the `Packages` folder): ```json "com.pittmanclass.dialogue": "file:../../PittmanClassToolkit/Packages/com.pittmanclass.dialogue" ``` ## 7. Check 1. The package appears in the Package Manager with your display name, description and version 0.1.0. 2. A `Debug.Log` in a Runtime script compiles; the Console shows assembly `PittmanClass.Dialogue` in the stack trace. 3. Temporarily put a test script in a new folder at the package root (outside `Runtime/` and `Editor/`, so no asmdef covers it). It never compiles and shows no error - the most common student confusion (part 7). Move it into `Runtime/` and it compiles. ## Exercise Create `com.pittmanclass.devconsole` the same way and move the scripts from [[In-Game Debug Console and Cheat Tools]] into it: runtime scripts in `Runtime/`, `PlayFromBoot.cs` and `CheatedSessionSorter.cs` in `Editor/`. Which `references` does each asmdef need? ## Sources - 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 (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 - Assembly Definition properties (6000.5): https://docs.unity3d.com/6000.5/Documentation/Manual/class-AssemblyDefinitionImporter.html - 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 - Special folder names (6000.5): https://docs.unity3d.com/6000.5/Documentation/Manual/SpecialFolders.html - Local folder packages (6000.5): https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/dependencies-lp/upm-localpath