Add UrlReference documentation to the manual. (#25)

en/manual/game-studio/load-scenes.md

@@ -1,6 +1,19 @@
 # Load and unload scenes at runtime
 
-The following code loads three scenes and adds them as children:
+## Loading scenes
+
+You can use `UrlReference<Scene>` properties on your scripts to assign **Scene** assets then load the via code:
+
+```cs
+public UrlReference<Scene> ChildSceneUrl { get; set; }
+
+//...
+var childScene = Content.Load(ChildSceneUrl);
+
+parentScene.Children.Add(childScene);
+```
+
+Alternatively you can load scenes by name. The following code loads three scenes and adds them as children:
 
 ```cs
 var myChildScene0 = Content.Load<Scene>(url0);
@@ -13,7 +26,7 @@ myChildScene1.Add(myChildScene2);
 ```
 
 >[!Note]
->Make sure all the scenes you want to load are included in the build as **root assets** (indicated with blue icons in the **Asset View**).
+>If you are not using `UrlReference` make sure all the scenes you want to load are included in the build as **root assets** (indicated with blue icons in the **Asset View**).
 
 >![Scenes included in root](media/scenes-included-in-root.png)
 
@@ -23,6 +36,23 @@ myChildScene1.Add(myChildScene2);
 
 For more information about scene hierarchies, see [Manage scenes](manage-scenes.md).
 
+## Unloading scenes
+
+Before a scene is unloaded remove it from the scene hierarchy:
+
+```cs
+parentScene.Children.Remove(childScene);
+
+//Alternatively
+childScene.Parent = null;
+```
+
+Once the scene asset is no longer required make sure to unload it:
+
+```cs
+Content.Unload(childScene);
+```
+
 ## Scene streaming script
 
 Stride also includes a scene streaming script that uses a [trigger](../physics/triggers.md) to load scenes. 
@@ -57,7 +87,7 @@ Game Studio adds a scene streaming script to your project assets.
 
     ![Scene streaming properties](media/scene-streaming-script-properties.png)
 
-4. Under **Url**, specify the URL of the scene you want to load.
+4. Under **Url**, specify the scene asset you want to load.
 
 5. Under **Trigger**, specify the entity you created in step 1.
 

en/manual/game-studio/media/add-scene-streaming-script.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:250e88d9f052a0b5ae15a4597fa82b5a27f26fb85936ca17b4e186f3b89564ff
-size 15333
+oid sha256:a153904339f3d8451cdebba65920113e4bbbfebe0bddbe5365e96446884ded02
+size 12854

en/manual/game-studio/media/scene-streaming-script-properties.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:143e448f97216c5257c06e84caec4fb5497a8afd0f20f51bd373856982c711b8
-size 7303
+oid sha256:72dd812abe12ca7a8c35c19fcf549c52b3836980c8080ad9c9054ed13547787b
+size 9198

en/manual/game-studio/media/scene-streaming-script.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:939616ee7bcf5c2e9b140e840bd743ce28ca9398a663e7bfb5540199fb8ca3a7
-size 29381
+oid sha256:480f02783df0f4f448d54983f2605dc426efa507d5393910a1261ad3002dddae
+size 25781

en/manual/game-studio/use-assets.md

@@ -2,15 +2,16 @@
 
 <span class="label label-doc-level">Beginner</span>
 
-There are three ways to use assets:
+There are four ways to use assets:
 
 * reference them in entity components
 * reference them in other assets
 * load them from code as content
+* load them from code as content using `UrlReference`
 
 ## Reference assets in components
 
-Many kinds of component use assets. For example, model components use model assets. 
+Many kinds of component use assets. For example, model components use model assets.
 
 Components that use assets have **asset docks** in the **property grid**.
 
@@ -51,13 +52,14 @@ You can see the references in a selected asset in the **References** tab. By def
 
 ![References tab](media/use-assets-references-tab.png)
 
-* The **References** tab displays the assets referenced by the selected asset. 
+* The **References** tab displays the assets referenced by the selected asset.
 * The **Referenced by** tab displays the assets that reference the selected asset.
 
 > [!Tip]
 > If you can't see the References tab, make sure it's displayed under **View > References**.
 
 ## Load assets from code
+
 When loading in assets at runtime we speak of "Content" rather than assets. The loaded content refers to the asset and can then be used in your script.
 
 ```cs
@@ -73,9 +75,9 @@ SceneSystem.SceneInstance.RootScene.Entities.Add(entity);
 
 > [!TIP]
 > To find the asset URL, in Game Studio, move the mouse over the asset. Game Studio displays the asset URL in a tooltip.  URLs typically have the format *AssetFolder/AssetName*.
-
-> [!WARNING] 
-> When loading assets from scripts, make sure you: 
+> [!WARNING]
+> When loading assets from scripts, make sure you:
+>
 > * include the asset in the build as described in [Manage assets](manage-assets.md)
 > * make sure you add the script as a component to an entity in the scene
 
@@ -85,6 +87,88 @@ When loading content from code, you should unload content when you don't need th
 
 To do unload an asset, use ``Content.Unload(myAsset)``.
 
+## Load assets from code using UrlReference
+
+`UrlReference` allows you to reference assets in your scripts the same way you would with normal assets but they are loaded dynamically in code. Referencing an asset with a `UrlReference` causes the asset to be included in the build.
+
+You can reference assets in your scripts using properties/fields of type `UrlReference` or `UrlReference<T>`:
+
+* `UrlReference` can be used to reference any asset. This is most useful for the "Raw asset".
+* `UrlReference<T>` can be used to specify the desired type. i.e. `UrlReference<Scene>`. This gives Game Studio a hint about what type of asset this `UrlReference` can be used for.
+
+## Examples
+
+### Loading a Scene
+
+Using `UrlReference<Scene>` to load the next scene.
+
+```cs
+using System.Threading.Tasks;
+//Include the Stride.Core.Serialization namespace to use UrlReference
+using Stride.Core.Serialization;
+using Stride.Engine;
+
+namespace Examples
+{
+    public class UrlReferenceExample : AsyncScript
+    {
+        public UrlReference<Scene> NextSceneUrl { get; set; }
+
+        public override async Task Execute()
+        {
+            //...
+        }
+
+        private async Task LoadNextScene()
+        {
+            //Dynamically load next scene asynchronously
+            var nextScene = await Content.LoadAsync(NextSceneUrl);
+            SceneSystem.SceneInstance.RootScene = nextScene;
+        }
+    }
+}
+```
+
+### Load data from a Raw asset JSON file
+
+Use a Raw asset to store data in a JSON file and load using [Newtonsoft.Json](https://www.newtonsoft.com/json). To use `Newtonsoft.Json` you also need to add the `Newtonsoft.Json` NuGet package to the project.
+
+```cs
+//Include the Newtonsoft.Json namespace.
+using Newtonsoft.Json;
+using System.IO;
+using System.Threading.Tasks;
+//Include the Stride.Core.Serialization namespace to use UrlReference
+using Stride.Core.Serialization;
+using Stride.Engine;
+
+namespace Examples
+{
+    public class UrlReferenceExample : AsyncScript
+    {
+        public UrlReference RawAssetUrl { get; set; }
+
+        public override async Task Execute()
+        {
+            //...
+        }
+
+        private async Task<MyDataClass> LoadMyData()
+        {
+            //Open a StreamReader to read the content
+            using (var stream = Content.OpenAsStream(RawAssetUrl))
+            using (var streamReader = new StreamReader(stream))
+            {
+                //read the raw asset content
+                string json = await streamReader.ReadToEndAsync();
+                //Deserialize the JSON to your custom MyDataClass Type.
+                return JsonConvert.DeserializeObject<MyDataClass>(json);
+            }
+        }
+    }
+}
+```
+
 ## See also
 
 * [Create assets](create-assets.md)