com.elestrago.unity.package-tools 2.0.10 → 2.1.0

package/Documentation~/samples.md

@@ -0,0 +1,73 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# Package Tool — Samples
+
+How the sample content in this repository uses the package. Each entry maps a sample file to the package types it exercises, so a reader can recreate the same setup against the public API.
+
+## Sample Layout
+
+```
+Assets/Example/Sample
+├── Prefabs
+│   └── ExamplePrefab.prefab
+└── Scene
+    └── SampleScene.unity
+```
+
+On export, `CopySamplesToDirectory` copies this tree to `Release/Samples~/ExampleSample/`, skipping `.meta` files. The shipped sample is consumable from the Package Manager **Samples** tab on the published package.
+
+## Sample → Package Type Mapping
+
+### `Assets/Example/Sample/Prefabs/ExamplePrefab.prefab`
+
+Kind: prefab
+
+This sample asset references no scripts from the package. It exists as a structural demo (the importing user sees a working Scene/Prefab in the package's Samples tab) rather than as an API exercise.
+
+### `Assets/Example/Sample/Scene/SampleScene.unity`
+
+Kind: scene
+
+This sample asset references no scripts from the package. It exists as a structural demo (the importing user sees a working Scene/Prefab in the package's Samples tab) rather than as an API exercise.
+
+## Reproducing the Sample
+
+The example sample is structural only — there are no MonoBehaviour scripts to instantiate. To reproduce from scratch:
+
+1. Create an empty Unity scene and a primitive prefab; both can live anywhere in `Assets/`.
+2. Create a `PackageManifestConfig` asset via **Assets > Create > JCMG/PackageTools/PackageManifestConfig** and configure `sourcePath`, `packageDestinationPath`, and a [`Sample`](api.md#packagemanifestconfigsample) entry whose `sourcePath` points at the folder holding the scene and prefab.
+3. Click **Export Package Source** on the inspector — `FileTools.CreateOrUpdatePackageSource` runs the export pipeline (see `manual.md` → **Export pipeline**) and the sample folder lands under `packageDestinationPath/Samples~/{folderName}`.
+
+Minimal equivalent in C#:
+
+```csharp
+using PackageTool;
+using PackageTool.Tools;
+using UnityEditor;
+using UnityEngine;
+
+var config = ScriptableObject.CreateInstance<PackageManifestConfig>();
+config.packageName = "com.example.sample";
+config.displayName = "Example Sample Package";
+config.packageVersion = "1.0.0";
+config.unityVersion = "2021.3";
+config.sourcePath = "Assets/Example/Source";
+config.packageDestinationPath = "Release";
+config.samples = new[]
+{
+    new PackageManifestConfig.Sample
+    {
+        sourcePath = "Assets/Example/Sample",
+        displayName = "Example Sample",
+        folderName = "ExampleSample",
+        description = "This is example for check test samples",
+    },
+};
+AssetDatabase.CreateAsset(config, "Assets/Example/PackageManifestConfig.asset");
+FileTools.CreateOrUpdatePackageSource(config);
+```
+
+## Notes
+
+- The `Samples~/` folder name (trailing tilde) is a Unity convention: tilde-suffixed folders are excluded from the AssetDatabase import, so packaged samples don't pollute the consuming project until the user clicks **Import** in the Package Manager.
+- For samples that stage content from outside `Assets/` — e.g. a Claude skill folder, vendored data, or generated output — use a [`CopyEntry`](api.md#packagemanifestconfigcopyentry) with `destinationPath` pointing at the same `sourcePath` your `Sample` declares. The `CopyEntry` step runs first; `CopySamplesToDirectory` then ships the staged content into the package.

package/Editor/Drawers/CopyEntryPropertyDrawer.cs

@@ -0,0 +1,95 @@
+using PackageTool.Tools;
+using UnityEditor;
+using UnityEngine;
+
+namespace PackageTool.Drawers
+{
+	[CustomPropertyDrawer(typeof(PackageManifestConfig.CopyEntry))]
+	internal sealed class CopyEntryPropertyDrawer : PropertyDrawer
+	{
+		private const string SOURCE_PATH_PROPERTY_NAME = "sourcePath";
+		private const string DESTINATION_PATH_PROPERTY_NAME = "destinationPath";
+
+		public override void OnGUI(Rect position, SerializedProperty property, GUIContent label)
+		{
+			var sourceRect = new Rect(position)
+			{
+				height = EditorConstants.FOLDER_PATH_PICKER_HEIGHT
+			};
+
+			var destinationRect = new Rect(sourceRect)
+			{
+				position = new Vector2(position.x, sourceRect.y + sourceRect.height + 2f)
+			};
+
+			DrawSourceRow(sourceRect, property.FindPropertyRelative(SOURCE_PATH_PROPERTY_NAME));
+			DrawDestinationRow(destinationRect, property.FindPropertyRelative(DESTINATION_PATH_PROPERTY_NAME));
+		}
+
+		public override float GetPropertyHeight(SerializedProperty property, GUIContent label)
+			=> EditorConstants.FOLDER_PATH_PICKER_HEIGHT * 2f + 2f;
+
+		private static void DrawSourceRow(Rect rowRect, SerializedProperty pathProperty)
+		{
+			var fieldRect = new Rect(rowRect)
+			{
+				width = rowRect.width - EditorConstants.FOLDER_PATH_PICKER_HEIGHT * 2f
+				                      - EditorConstants.FOLDER_PATH_PICKER_BUFFER
+			};
+
+			EditorGUI.PropertyField(fieldRect, pathProperty, new GUIContent(EditorConstants.COPY_ENTRY_SOURCE_LABEL));
+
+			var filePickerRect = new Rect
+			{
+				position = new Vector2(
+					fieldRect.x + fieldRect.width + EditorConstants.FOLDER_PATH_PICKER_BUFFER,
+					rowRect.y),
+				width = EditorConstants.FOLDER_PATH_PICKER_HEIGHT,
+				height = EditorConstants.FOLDER_PATH_PICKER_HEIGHT
+			};
+
+			var folderPickerRect = new Rect
+			{
+				position = new Vector2(
+					filePickerRect.x + filePickerRect.width,
+					rowRect.y),
+				width = EditorConstants.FOLDER_PATH_PICKER_HEIGHT,
+				height = EditorConstants.FOLDER_PATH_PICKER_HEIGHT
+			};
+
+			GUILayoutTools.DrawFilePicker(
+				filePickerRect,
+				pathProperty,
+				EditorConstants.SELECT_SOURCE_PATH_FILE_PICKER_TITLE);
+			GUILayoutTools.DrawFolderPicker(
+				folderPickerRect,
+				pathProperty,
+				EditorConstants.SELECT_SOURCE_PATH_PICKER_FOLDER_TITLE);
+		}
+
+		private static void DrawDestinationRow(Rect rowRect, SerializedProperty pathProperty)
+		{
+			var fieldRect = new Rect(rowRect)
+			{
+				width = rowRect.width - EditorConstants.FOLDER_PATH_PICKER_HEIGHT
+				                      - EditorConstants.FOLDER_PATH_PICKER_BUFFER
+			};
+
+			EditorGUI.PropertyField(fieldRect, pathProperty, new GUIContent(EditorConstants.COPY_ENTRY_DESTINATION_LABEL));
+
+			var folderPickerRect = new Rect
+			{
+				position = new Vector2(
+					fieldRect.x + fieldRect.width + EditorConstants.FOLDER_PATH_PICKER_BUFFER,
+					rowRect.y),
+				width = EditorConstants.FOLDER_PATH_PICKER_HEIGHT,
+				height = EditorConstants.FOLDER_PATH_PICKER_HEIGHT
+			};
+
+			GUILayoutTools.DrawFolderPicker(
+				folderPickerRect,
+				pathProperty,
+				EditorConstants.SELECT_COPY_DESTINATION_FOLDER_PICKER_TITLE);
+		}
+	}
+}

package/Editor/Drawers/CopyEntryPropertyDrawer.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: 88c4785ea4243706f9dbebc1dd7a5ae4

package/Editor/EditorConstants.cs

@@ -108,5 +108,11 @@ namespace PackageTool
 		public const string SAMPLES_FOLDER_NAME = "Samples~";
 		public const string SAMPLES_HEADER_LABEL = "Samples";
 		public const string SAMPLES_ELEMENT_LABEL_FORMAT = "Sample {0}:";
+
+		public const string COPY_ENTRIES_HEADER_LABEL = "Copy Entries";
+		public const string COPY_ENTRY_ELEMENT_LABEL_FORMAT = "Copy {0}:";
+		public const string COPY_ENTRY_SOURCE_LABEL = "Source";
+		public const string COPY_ENTRY_DESTINATION_LABEL = "Destination";
+		public const string SELECT_COPY_DESTINATION_FOLDER_PICKER_TITLE = "Select Copy Destination Folder";
 	}
 }

package/Editor/Inspectors/PackageManifestConfigInspector.cs

@@ -37,6 +37,7 @@ namespace PackageTool.Inspectors
 		private ReorderableList _keywordReorderableList;
 		private ReorderableList _dependenciesReorderableList;
 		private ReorderableList _samplesReorderableList;
+		private ReorderableList _copyEntriesReorderableList;
 
 		private const string SOURCE_PATH_PROPERTY_NAME = "sourcePath";
 		private const string DOCUMENTATION_PATH_PROPERTY_NAME = "documentationPath";
@@ -61,6 +62,7 @@ namespace PackageTool.Inspectors
 		private const string VERSION_CONSTANTS_NAMESPACE_PROPERTY_NAME = "versionConstantsNamespace";
 		private const string ID_PROPERTY_NAME = "_id";
 		private const string SAMPLES_PROPERTY_NAME = "samples";
+		private const string COPY_ENTRIES_PROPERTY_NAME = "copyEntries";
 
 		private void OnEnable()
 		{
@@ -109,6 +111,16 @@ namespace PackageTool.Inspectors
 				drawElementCallback = DrawSampleElement,
 				elementHeight = EditorGUIUtility.singleLineHeight * 5f
 			};
+
+			var copyEntriesProp = serializedObject.FindProperty(COPY_ENTRIES_PROPERTY_NAME);
+			_copyEntriesReorderableList = new ReorderableList(
+				serializedObject,
+				copyEntriesProp)
+			{
+				drawHeaderCallback = DrawCopyEntriesHeader,
+				drawElementCallback = DrawCopyEntryElement,
+				elementHeight = EditorConstants.FOLDER_PATH_PICKER_HEIGHT * 2f + 2f
+			};
 		}
 
 		public override void OnInspectorGUI()
@@ -203,6 +215,7 @@ namespace PackageTool.Inspectors
 				EditorGUILayout.Space();
 				// _sourcePathsReorderableList.DoLayoutList();
 				_excludePathsReorderableList.DoLayoutList();
+				_copyEntriesReorderableList.DoLayoutList();
 
 				// Package Source Export
 				using (new EditorGUILayout.HorizontalScope())
@@ -400,5 +413,23 @@ namespace PackageTool.Inspectors
 		}
 
 		#endregion
+
+		#region Copy Entries ReorderableList
+
+		private void DrawCopyEntriesHeader(Rect rect)
+		{
+			EditorGUI.LabelField(rect, EditorConstants.COPY_ENTRIES_HEADER_LABEL, EditorStyles.boldLabel);
+		}
+
+		private void DrawCopyEntryElement(Rect rect, int index, bool isActive, bool isFocused)
+		{
+			EditorGUI.PropertyField(
+				rect,
+				serializedObject.FindProperty(COPY_ENTRIES_PROPERTY_NAME).GetArrayElementAtIndex(index),
+				new GUIContent(string.Format(EditorConstants.COPY_ENTRY_ELEMENT_LABEL_FORMAT, index))
+			);
+		}
+
+		#endregion
 	}
 }

package/Editor/PackageManifestConfig.cs

@@ -82,6 +82,21 @@ namespace PackageTool
 			                         || string.IsNullOrEmpty(folderName);
 		}
 
+		/// <summary>
+		/// Describes a copy operation that mirrors a source file or folder into a destination folder inside the
+		/// project. When the source is a folder, the same-named subfolder of the destination is replaced with the
+		/// source folder's content. When the source is a file, the same-named file inside the destination folder
+		/// is replaced. An empty or non-existent destination path falls back to the project root.
+		/// </summary>
+		[Serializable]
+		public sealed class CopyEntry
+		{
+			public string sourcePath;
+			public string destinationPath;
+
+			public bool IsEmpty() => string.IsNullOrEmpty(sourcePath);
+		}
+
 		/// <summary>
 		/// A unique id for this <see cref="PackageManifestConfig"/> instance.
 		/// </summary>
@@ -162,6 +177,11 @@ namespace PackageTool
 
 		public Sample[] samples;
 
+		/// <summary>
+		/// A collection of additional source-to-destination copy operations performed during export.
+		/// </summary>
+		public CopyEntry[] copyEntries;
+
 		/// <summary>
 		/// A path to the where the VersionConstants.cs file should be created/updated
 		/// </summary>

package/Editor/Tools/FileTools.cs

@@ -122,6 +122,7 @@ namespace PackageTool.Tools
 				// If its a file, copy over it and its meta file if it exists.
 				var normalizedSourcePath = Path.GetFullPath(packageManifest.sourcePath);
 
+				CopyEntriesToProject(packageManifest);
 				CopyDocumentationToDirectory(packageManifest);
 				RecursivelyCopyDirectoriesAndFiles(packageManifest, normalizedSourcePath, normalizedDestinationPath);
 				CopySamplesToDirectory(packageManifest);
@@ -192,6 +193,78 @@ namespace PackageTool.Tools
 			File.Copy(normalizedSourcePath, destinationPath);
 		}
 
+		/// <summary>
+		/// Stages each configured <see cref="PackageManifestConfig.CopyEntry"/> into the project before the
+		/// rest of the export runs. A folder source's content is merged directly into
+		/// <see cref="PackageManifestConfig.CopyEntry.destinationPath"/> (same-named files are overwritten,
+		/// unrelated files in the destination are left alone). A file source overwrites
+		/// <c>destination/{filename}</c>. A blank destination resolves to the project root; a non-blank
+		/// destination that does not yet exist is created. Missing sources log a warning and are skipped.
+		/// </summary>
+		public static void CopyEntriesToProject(PackageManifestConfig packageManifest)
+		{
+			var entries = packageManifest.copyEntries;
+			if (entries == null || entries.Length == 0)
+				return;
+
+			foreach (var entry in entries)
+			{
+				if (entry.IsEmpty())
+					continue;
+
+				var normalizedSourcePath = Path.GetFullPath(entry.sourcePath);
+				var destinationDirectory = ResolveDestinationDirectory(entry.destinationPath);
+
+				if (!Directory.Exists(destinationDirectory))
+					Directory.CreateDirectory(destinationDirectory);
+
+				if (!Directory.Exists(normalizedSourcePath) && !File.Exists(normalizedSourcePath))
+				{
+					Debug.LogWarningFormat(
+						"[Package Tools] Copy entry source [{0}] does not exist, skipping.",
+						entry.sourcePath);
+					continue;
+				}
+
+				if (Directory.Exists(normalizedSourcePath))
+				{
+					CopyDirectoryRecursively(normalizedSourcePath, destinationDirectory);
+				}
+				else if (File.Exists(normalizedSourcePath))
+				{
+					var sourceName = Path.GetFileName(normalizedSourcePath);
+					var targetPath = Path.Combine(destinationDirectory, sourceName);
+
+					if (File.Exists(targetPath))
+						File.Delete(targetPath);
+
+					File.Copy(normalizedSourcePath, targetPath);
+				}
+			}
+		}
+
+		private static string ResolveDestinationDirectory(string rawDestinationPath)
+		{
+			if (string.IsNullOrEmpty(rawDestinationPath))
+				return EditorConstants.ProjectPath;
+
+			return Path.GetFullPath(rawDestinationPath);
+		}
+
+		private static void CopyDirectoryRecursively(string normalizedSourcePath, string normalizedDestinationPath)
+		{
+			var directoryInfo = new DirectoryInfo(normalizedSourcePath);
+
+			foreach (var sdi in directoryInfo.GetDirectories(EditorConstants.WILDCARD_FILTER, SearchOption.AllDirectories))
+				Directory.CreateDirectory(sdi.FullName.Replace(normalizedSourcePath, normalizedDestinationPath));
+
+			foreach (var fi in directoryInfo.GetFiles(EditorConstants.WILDCARD_FILTER, SearchOption.AllDirectories))
+			{
+				var newPath = fi.FullName.Replace(normalizedSourcePath, normalizedDestinationPath);
+				File.Copy(fi.FullName, newPath, overwrite: true);
+			}
+		}
+
 		private static void CopySamplesToDirectory(PackageManifestConfig packageManifest)
 		{
 			var samples = packageManifest.samples;