You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This package provides as set of utilities, editor windows and scripts to manages scenes in your Unity projects. It works by setting up a set of assets which can then be used as references to load groups of scenes via editor windows (also during runtime) and runtime scripts.
19
+
13
20
## Getting Started
14
21
15
-
Open [Unity Package Manager], select _Scriptable Scenes_ package and import _Defaults_ sample:
22
+
Open [Unity Package Manager], select _Scriptable Scenes_ package and import [Defaults Sample]:
16
23
17
24
<palign="center">
18
25
<imgsrc="samples.png"/>
@@ -24,24 +31,34 @@ Make sure _SetupScene_ and _PlayScene_ are added to _Build Settings_:
24
31
<imgsrc="build-settings.png"/>
25
32
</p>
26
33
27
-
Open _Scriptable Scene_ window by selecting _Window/CHARK/Scriptable Scenes_ menu item:
34
+
Open [Scriptable Scene Window] by selecting _Window/CHARK/Scriptable Scenes_ menu item:
28
35
29
36
<palign="center">
30
37
<imgsrc="open-window.png"/>
31
38
</p>
32
39
33
-
Select the action to perform with _Default_ collections imported from the sample:
40
+
This will open an Editor window which will allow you to view all [Scriptable Scene Collection] assets present in the project.
41
+
42
+
The [Defaults Sample] contains a set of [Scriptable Scene] assets and [Scriptable Scene Collection] assets which can be used as a baseline. Additionally, it includes a _SetupScene_ which can be used as a setup/preload scene. It also includes components needed for scene loading logic to work, namely the [Scriptable Scene Controller].
43
+
44
+
If you create new [Scriptable Scene Collection] assets, they will automatically appear in this window. Additionally, you can move, edit or delete the files created by this sample as per your project requirements:
34
45
35
46
<palign="center">
36
47
<imgsrc="window.png"/>
37
48
</p>
38
49
50
+
You can perform the following actions on each entry:
51
+
39
52
-**Open** - open selected collection in scene view & hierarchy.
40
53
-**Play** - start the game and load selected collection.
41
54
-**Load** - load selected collection, only available during play mode. This is handy to quickly switch between the scenes when the game is running.
42
55
56
+
**Note**, rearranging entries in this list will only affect your local editor and will not show up in version control.
57
+
43
58
## Creating a new collection
44
59
60
+
Instead of importing samples, you can start from scratch and create each asset and component manually.
61
+
45
62
To create a new collection you'll need the following:
46
63
47
64
-[Scriptable Scene] asset.
@@ -55,68 +72,72 @@ And **optionally**:
55
72
56
73
### Scriptable Scene
57
74
58
-
First you'll need to define scenes which go into the collection. Instead of specifying a hard-coded scene path or build index, this package provides a way to safety refer to scenes via Scriptable Objects (_Scriptable Scene_ assets).
75
+
First you'll need to define scenes which go into the collection. Instead of specifying a hard-coded scene path or build index, this package provides a way to safety refer to scenes via Scriptable Objects ([Scriptable Scene] assets).
59
76
60
-
To create a _Scriptable Scene_ asset, right-click in the _Project Window_ and select _Create/CHARK/Scriptable Scenes/Scriptable Scene_:
77
+
To create a [Scriptable Scene] asset, right-click anywhere in the _Project Window_ and select _Create/CHARK/Scriptable Scenes/Scriptable Scene_:
You can adjust the following properties on this asset:
84
+
After creating, select the asset, set the **Pretty Name** and select the correct **Scene Asset**.
85
+
86
+
Available properties for customization:
68
87
69
-
-**Scene Asset** - the `.unity` scene this asset is referring to. Drag in the scene file this asset is referring to.
88
+
-**Scene Asset** - the `.unity` scene this asset is referring to. Drag in the scene file you want this asset to load.
70
89
-**Pretty Name** - user-defined name for the scene. If left blank, a default name will be used.
71
-
-**Is Active** - should this scene be activated when it gets loaded by a collection? Set this to `true` for gameplay scenes.
90
+
-**Is Active** - should this scene be [activated](https://docs.unity3d.com/ScriptReference/SceneManagement.SceneManager.SetActiveScene.html) when it gets loaded by a collection? Set this to `true` for gameplay scenes.
72
91
-**Is Persist** - should this scene never be unloaded, even when switching collections? Set this to `true` for setup/preload scenes.
73
-
-**Scene Events** - events invoked on this scene.
92
+
-**Scene Events** - events invoked on this [Scriptable Scene] asset.
74
93
75
94
### Scriptable Scene Collection
76
95
77
-
Once you have defined a set of _Scriptable Scene_ assets, you'll need to create a _Scriptable Collection_asset which will be used to group and load a set of scenes at the same time. Loading will be done additively.
96
+
Once you have defined a set of [Scriptable Scene] assets, you'll need to create a [Scriptable Scene Collection]asset which will be used to group and load a set of scenes at the same time. These scenes will be loaded [additively](https://docs.unity3d.com/ScriptReference/SceneManagement.LoadSceneMode.Additive.html).
78
97
79
-
To create a _Scriptable Scene Collection_ asset, right-click in the _Project Window_ and select _Create/CHARK/Scriptable Scenes/Scriptable Scene Collection_:
98
+
To create a [Scriptable Scene Collection] asset, right-click in the _Project Window_ and select _Create/CHARK/Scriptable Scenes/Scriptable Scene Collection_:
80
99
81
100
<palign="center">
82
101
<imgsrc="scriptable-scene-collection.png"/>
83
102
</p>
84
103
85
-
You can adjust the following properties on this asset:
104
+
Open the asset, set **Pretty Name** and add your [Scriptable Scene] assets.
105
+
106
+
Available properties for customization:
86
107
87
108
-**Pretty Name** - user-defined name for the collection. If left blank, a default name will be used.
88
-
-**Transition** - _Scriptable Scene Transition_ asset which can be used to smoothly transition between scenes. If left unset, no transitions will be used.
89
-
-**Scriptable Scenes** - scenes to load when this collection is loaded. The order of the scenes in this list defines how they appear in the scene hierarchy.
90
-
-**Collection Events** - events invoked on this collection.
91
-
-**Scene Events** - events invoked on any of scenes in this collection.
92
-
-**Actions** - set of actions that can be performed with this collection. These are the same actions as in _Scriptable Scene_ window.
109
+
-**Transition** - [Scriptable Scene Transition] asset which can be used to smoothly transition between scenes. If left unset, no transitions will be used.
110
+
-**Scriptable Scenes** - [Scriptable Scene] assets to load when this collection is loaded. The order in this list defines the order of scenes in the scene hierarchy.
111
+
-**Collection Events** - events invoked on this [Scriptable Scene Collection].
112
+
-**Scene Events** - events invoked on any of [Scriptable Scene] assets in this collection.
113
+
-**Actions** - set of actions that can be performed with this collection. These are the same actions as in [Scriptable Scene Window].
93
114
94
115
### Scriptable Scene Controller
95
116
96
117
Once you have a set of collections ready, do the following in your primary setup/preload scene:
97
118
98
119
- Create a new _GameObject_.
99
-
- Add _Scriptable Scene Controller_ component.
120
+
- Add [Scriptable Scene Controller] component.
100
121
- Specify **Initial Collection** to define which collection loads first in build.
101
122
102
123
<palign="center">
103
124
<imgsrc="scriptable-scene-controller.png"/>
104
125
</p>
105
126
106
-
The _Scriptable Scene Controller_ component manages scene loading. You should always an instance of this component in one of your scenes in order to use this package. Keep in mind that only one instance of this component may exist in them game, therefore it is recommended to place this component in your setup/preload scene.
127
+
The [Scriptable Scene Controller] component manages scene loading. You should always an instance of this component in one of your scenes in order to use this package. Keep in mind that only one instance of this component may exist in them game, therefore it is recommended to place this component in your setup/preload scene.
107
128
108
129
You can adjust the following properties on this component:
109
130
110
-
-**Initial Collection** - collection which will be loaded first in build.
131
+
-**Initial Collection** - [Scriptable Scene Collection]which will be loaded first in build. Usually a set of scenes representing the menu or a splash screen.
111
132
-**Initial Collection Load Mode** - which Unity Lifecycle method to use when loading the **Initial collection**.
112
-
-**Collection Events** - events invoked on any collection in the game.
113
-
-**Scene Events** - events invoked on any scene in the game.
133
+
-**Collection Events** - events invoked on any [Scriptable Scene Collection].
134
+
-**Scene Events** - events invoked on any [Scriptable Scene].
114
135
115
136
### Fade Transition (optional)
116
137
117
-
By default, the package includes a simple fade transition which can be used to fade-in/fade-out a loading screen when switching between scenes (custom transitions can also be created by inheriting [ScriptableSceneTransition] class).
138
+
By default, the package includes a simple fade transition which can be used to fade-in/fade-out a loading screen when switching between scenes (custom transitions can also be created by inheriting [Scriptable Scene Transition] class).
118
139
119
-
To create a new _Fade Scriptable Scene Transition_, right-click in the _Project Window_ and select _Create/CHARK/Scriptable Scenes/Fade Scriptable Scene Transition_:
140
+
To create a new [Fade Scriptable Scene Transition], right-click in the _Project Window_ and select _Create/CHARK/Scriptable Scenes/Fade Scriptable Scene Transition_:
120
141
121
142
<palign="center">
122
143
<imgsrc="fade-transition-asset.png"/>
@@ -130,8 +151,57 @@ You can adjust the following properties on this asset:
130
151
-**Fade In Duration Seconds** - how long should the fade in effect take.
131
152
-**Fade Out Duration Seconds** - how long should the fade out effect take.
132
153
133
-
Finally, after you have created the _Fade Scriptable Scene Transition_ asset, add [Fade Canvas] component onto the loading screen `Canvas` in your setup/preload scene:
154
+
Finally, after you have created the [Fade Scriptable Scene Transition] asset, add [Fade Canvas] component onto any `Canvas` which contains loading screen logic in your setup/preload scene:
134
155
135
156
<palign="center">
136
157
<imgsrc="fade-transition-canvas.png"/>
137
158
</p>
159
+
160
+
## Scripting
161
+
162
+
### Loading Collections via Code
163
+
164
+
First you must obtain a reference to a [Scriptable Scene Controller]. This can be done via [SerializeField](https://docs.unity3d.com/ScriptReference/SerializeField.html) or any other means, such as using `Object.FindObjectOfType<ScriptableSceneController>()` and so on, depending on your project setup.
165
+
166
+
Additionally, you'll need to obtain a set of [Scriptable Scene Collection] references. Since these as Scriptable Objects, all you need to do is define a set of [SerializeField](https://docs.unity3d.com/ScriptReference/SerializeField.html) and load them directly. However, you can structure this however you like, e.g., by maintaining lists of scenes, loading them randomly, etc...
167
+
168
+
```csharp
169
+
usingCHARK.ScriptableScenes;
170
+
usingUnityEngine;
171
+
172
+
internalsealedclassGameManager : MonoBehaviour
173
+
{
174
+
// Obtain a reference to ScriptableSceneController
175
+
[SerializeField]
176
+
privateScriptableSceneControllercontroller;
177
+
178
+
// Obtain a set references to ScriptableSceneCollection
0 commit comments