# 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