CesiumGS/cesium-unity-samples

Restructure project directory to enable easier asset migration

argallegos opened this issue · 1 comments

argallegos commented

The way that the /Assets/ directory is currently structured can cause organizational issues down the line, and may make it more difficult for users to import the sample assets into their own projects.

Issue

It's common to import a variety of asset packages into a Unity project, and by default new packages are merged directly into the top-level Assets folder. We can see an example of this in the directory for this project - the StarterAssets, TextMeshPro, and XR content folders. If you import a package with a directory name that already exists in your project, the new directory will be merged into your existing directory.

This becomes an issue if you import the Cesium for Unity Samples into another project that keeps its assets in the top-level directory, or vice versa. If the user keeps all their levels in /Assets/Scenes/, the Cesium for Unity Samples scenes will also end up in that folder. This is typically not desired and it can be a pain to sort through directories and separate things back out.

Another complication of the current structure is that it's hard to understand what is actually part of the Cesium for Unity Samples. For example, currently only the Scenes, Settings, and CesiumForUnitySamples folder actually contain content that Cesium created (as far as I know). The "Samples" folder isn't Cesium for Unity Samples, it appears to be XR Interaction Toolkit samples. When we direct users to the samples, it's also important that we direct them on where to look to find the project's main assets.

Recommendation

My recommendation is based on best practices that I have learned while developing games in Unity.

  • Nest all assets that we have created into the CesiumForUnitySamples folder. This will help distinguish the Cesium content from other project imports that we did not create, such as TextMeshPro.
    The new directory structure would resemble the following:
Assets
+---CesiumForUnitySamples
|   +---Scenes
|   +---Settings
|   +---Prefabs
|   +---[Any other folders we may add in the future, such as Materials]
+---TextMeshPro
+---[Other imported assets]
  • Leave imported assets such as TMP, XR on the top level (Unless we have modified them after importing). This avoids possible duplication of imports when moving between projects.
  • Additionally, for the folders "Samples" and "TutorialInfo", we should delete them if not needed, or rename them according to their contents. ("Samples" would become "XRToolkitSamples" or "XRInteractionToolkit/Samples". I don't know what the purpose of the TutorialInfo folder is.)

Implementation note: Restructuring directories can cause problems if there are active branches at the time of the restructure. It will be easiest if we can complete this when there are no outstanding PRs or active branches. The change should be very quick.