Merge remote-tracking branch 'origin/master' into 1.9

.github/workflows/docs-publish.yml

@@ -5,6 +5,7 @@ on:
       - update-*
 
 env:
+  GIT_CLONE_PROTECTION_ACTIVE: false
   DOTNET_NOLOGO: true
   DOTNET_CLI_TELEMETRY_OPTOUT: false
 

manual/contributing/index.md

@@ -26,7 +26,7 @@ The main repository [Flax Engine](https://github.com/FlaxEngine/FlaxEngine) cont
 
 The repository available on GitHub is a mirror of our internal Git repository hosted on [https://gitlab.flaxengine.com/flax/flaxengine](https://gitlab.flaxengine.com/flax/flaxengine) (mirror updated every 5 minutes). We use our internal LFS server for large binary file hosting. The repository contains an `.lfsconfig` file for LFS to work properly but if you encounter issues when pushing changes on your fork try using `git push --no-verify` or migrate to your own LFS server.
 
-If you want to open the Flax Engine in Visual Studio you might need to install the [Flax Engine Tools for Visual Studio](https://marketplace.visualstudio.com/items?itemName=Flax.FlaxVS) extension.
+If you want to open the Flax Engine in Visual Studio you might need to install the [Flax Engine Tools for Visual Studio](https://marketplace.visualstudio.com/items?itemName=Flax.FlaxVS) extension (Not needed for Version 1.6 and higher).
 
 ### Flax Docs
 

manual/get-started/prefabs/index.md

@@ -44,6 +44,8 @@ After selecting a prefab instance the *Properties Window* shows two additional b
 
 The **Select Prefab** button shows the linked prefab asset location in the *Content Window* and selects it.
 
+The **Edit Prefab** button opens the selected prefab in a new *Prefab editor*.
+
 The **View Changes** button shows a popup with any modified actor and scripts properties compared to the prefab. It is used to see all the changes applied to the prefab instance and allows them to be reverted or applied to the prefab. The picture below shows the content of a sample prefab changes popup. You can right click on the modified tree nodes to revert the per-property change while keeping other modification unchanged.
 
 ![Prefab Instance Diff Popup](media/prefab-instance-diff-popup.png)

manual/graphics/tutorials/additional-render-pass.md

@@ -0,0 +1,98 @@
+# HOWTO: Write additional render pass
+
+In this tutorial you will learn how to inject a custom render pass into the pipeline. This technique is widely adopted in a lot of custom effects. This tutorial will implement a Toon-style outline by the method of back face fattening, which requires an additional outline pass after the opaque object is rendered. 
+
+## 1. Create the outline material
+
+Firstly, create a new material as the toon outline material. You can do it manually or use Editor and *right-click* in Content window content folder **New -> Material -> Material**.
+
+To implement back face fattening, You have to expand the model by a little through moving the vertex a bit in the direction of the normal. Only back faces of the enlarged model is rendered so that the original model won't be occluded. Open the material and set the Blend Mode to **Transparent** and set the Cull Mode to **Inverted**, turn off Z Test and Z Write. Then setup the graph as the image below: 
+
+![Toon outline](media/toon-outline-material.png)
+
+## 2. Write rendering code
+
+Next step is to inject a custom render pass by the `PostProcessEffect` class and render it. 
+Create C# script and add it to the any actor on the scene. You can use [this tutorial](../../scripting/new-script.md) to learn how to do it. Then, write the following code:
+
+```cs
+using System.Runtime.InteropServices;
+using FlaxEngine;
+
+namespace Game;
+
+/// <summary>
+/// OutlineRenderer Script.
+/// </summary>
+public class OutlineRenderer : PostProcessEffect
+{
+    private Material _material;
+    private Model _model;
+
+    public Material OutlineMaterial
+    {
+        get => _material;
+        set
+        {
+            if (_material != value)
+            {
+                _material = value;
+            }
+        }
+    }
+
+    /// <inheritdoc />
+    public override unsafe void OnEnable()
+    {
+        // This postfx overdraws the input buffer without using output
+        UseSingleTarget = true; 
+
+        // Custom draw location in a pipeline, before forward pass so that the draw call could be executed together with other forward draw calls
+        Location = PostProcessEffectLocation.BeforeForwardPass; 
+
+        // Get the actor as a `StaticModel` (or `AnimatedModel` instead)
+        var modelInstance = Actor as StaticModel;
+        // Get the actual `Model`
+        _model = modelInstance.Model;
+
+        // Register postFx to all game views (including editor)
+        SceneRenderTask.AddGlobalCustomPostFx(this);
+    }
+
+    /// <inheritdoc />
+    public override void OnDisable()
+    {
+        // Remember to unregister from events and release created resources (it's gamedev, not webdev)
+        SceneRenderTask.RemoveGlobalCustomPostFx(this);
+    }
+
+    /// <inheritdoc />
+    public override bool CanRender()
+    {
+        return base.CanRender() && _material;
+    }
+
+    /// <inheritdoc />
+    public override unsafe void Render(GPUContext context, ref RenderContext renderContext, GPUTexture input, GPUTexture output)
+    {
+        // Second pass: draw the model with the outline material
+
+        // Get the transform of the actor
+        Actor.GetLocalToWorldMatrix(out var world);
+
+        // Submit the draw call to the render list, which will be handled later in the forward pass
+        _model.Draw(ref renderContext, _material, ref world, StaticFlags.None, false);
+    }
+}
+```
+
+It overrides **PostProcessEffect** class which is used to inject custom rendering code into the in-build graphics pipeline.
+As you can see, the script registers in `OnEnable` and disposes in `OnDisable`. The actual rendering is performed in `Render` method that submits the draw call. 
+
+Then **add script** to a model actor on scene and **assign the Outline Material** created in step 2 to **Outline Material** property. 
+
+## 4. See results
+
+Once you setup material, script and add it to a scene model you should be able to see the outline pass working (under game mode). In case of problems see *Output Log* window in Editor as it may contain any compilation errors.
+
+![Toon Outline Example](media/toon-outline-example.png)

manual/graphics/tutorials/index.md

@@ -3,6 +3,7 @@
 This section contains a set of tutorials related to graphics.
 
 * [How to render object outline](render-object-outline.md)
+* [How to write additional render pass](additional-render-pass.md)
 * [How to render FPS weapon](render-fps-weapon.md)
 * [How to use anisotropic texture sampler](anisotropic-texture-sampler.md)
 * [How to use dynamic texture](use-dynamic-texture.md)

manual/input/virtual-input.md

@@ -30,12 +30,17 @@ You can also use the [InputEvent](https://docs.flaxengine.com/api/FlaxEngine.Inp
 public InputEvent FireEvent = new InputEvent("Fire");
 public InputAxis MouseX = new InputAxis("MouseX");
 
-public MyScript()
+public OnStart()
 {
 	// Register for input action event
 	FireEvent.Pressed += ShootBall;
 }
 
+private void ShootBall()
+{
+	Debug.Log("Shooting Ball");
+}
+
 public override void OnUpdate()
 {
 	// Read the virtual axis value
@@ -45,6 +50,9 @@ public override void OnUpdate()
 
 public override void OnDestroy()
 {
+	// Deregister from input action event
+	FireEvent.Pressed -= ShootBall;
+
 	// Remember to dispose the action object (it holds reference to your methods)
 	FireEvent.Dispose();
 	MouseX.Dispose();

manual/navigation/tutorials/path-following.md

@@ -65,9 +65,9 @@ public class Agent007 : Script
 
             // Move the start/end points to navmesh floor
             if (_path.Length != 0)
-                Navigation.ProjectPoint(_path[0], out _path[0]);
+                Navigation.FindClosestPoint(_path[0], out _path[0]);
             if (_path.Length > 1)
-                Navigation.ProjectPoint(_path[_path.Length - 1], out _path[_path.Length - 1]);
+                Navigation.FindClosestPoint(_path[_path.Length - 1], out _path[_path.Length - 1]);
 
             // Compute path length
             for (int i = 1; i < _path.Length; i++)

manual/networking/tutorials/network-client-server.md

@@ -22,7 +22,7 @@ public class ServerScript : Script
     {
         _server = NetworkPeer.CreatePeer(new NetworkConfig
         {
-            NetworkDriverType = NetworkDriverType.ENet,
+            NetworkDriver = new ENetDriver(),
             ConnectionsLimit = 8,
             MessagePoolSize = 1024,
             MessageSize = 1400,
@@ -67,7 +67,7 @@ public class ClientScript : Script
     {
         _client = NetworkPeer.CreatePeer(new NetworkConfig
         {
-            NetworkDriverType = NetworkDriverType.ENet,
+            NetworkDriver = new ENetDriver(),
             ConnectionsLimit = 32,
             MessagePoolSize = 256,
             MessageSize = 1400,

manual/samples-tutorials/tutorials/index.md

@@ -71,6 +71,7 @@ You can use **Ctrl + F** to quickly find what you are looking for.
 * [How to create foliage](../../foliage/tutorials/create-foliage.md)
 * [How to create foliage from code](../../foliage/tutorials/foliage-from-code.md)
 * [How to render an object outline](../../graphics/tutorials/render-object-outline.md)
+* [How to write additional render pass](../../graphics/tutorials/additional-render-pass.md)
 * [How to import an asset from code](../../scripting/tutorials/import-asset-from-code.md)
 * [How to create terrain](../../terrain/tutorials/create-terrain.md)
 * [How to import terrain](../../terrain/tutorials/import-terrain.md)

manual/scripting/advanced/index.md

@@ -2,6 +2,7 @@
 
 ## In this section
 
+* [Script Templates](templates.md)
 * [Raw Data Asset](raw-data-asset.md)
 * [Custom Editor Options](custom-editor-options.md)
 * [Curve](curve.md)

manual/scripting/advanced/templates.md

@@ -0,0 +1,70 @@
+# Script Templates
+
+Script templates can be used to allow users to create a new script based on a template.
+
+## Create a script template
+
+Create a text document anywhere in the **Content** folder and create the template that you desire. It is recommended the use .cs or .h/.cpp for the file extension for the template files.
+
+### The available identifiers
+
+Use the following identifiers to replace certain parts of your template with information upon creation by the user.
+
+| Identifier | Description |
+|--------|--------|
+| **%copyright%** | Replaced with the copyright comment |
+| **%class%** | Replaced with the class name. This is a modified version of the file name. |
+| **%filename%** | C++ Template only. Replaced with the file name. |
+| **%module%** | C++ Template only. Replaced with the module name. |
+| **%namespace%** | C# Template only. Replaced with the module name. |
+
+## Create a new template proxy
+
+New C# template proxy:
+
+```cs
+[ContentContextMenu("New/C#/My new template")]
+public class TestingCSharpProxy : CSharpProxy 
+{
+    public override string Name => "My new template";
+
+    protected override void GetTemplatePath(out string path)
+    {
+        // Can use `Globals` class to get specific project folders
+        path = "path to new .cs template";
+    }
+}
+```
+
+New C++ template proxy:
+
+```cs
+[ContentContextMenu("New/C++/My new template")]
+public class TestingCppProxy : CppProxy
+{
+    public override string Name => "My new template";
+
+    protected override void GetTemplatePaths(out string headerTemplate, out string sourceTemplate)
+    {
+        // Can use `Globals` class to get specific project folders
+        headerTemplate = "path to new .h template";
+        sourceTemplate = "path to new .cpp template";
+    }
+}
+```
+
+Add the new proxy to the **ContentDatabase** using an **EditorPlugin**
+
+```cs
+public class TestEditorPlugin : EditorPlugin
+{
+    public override void InitializeEditor()
+    {
+        base.InitializeEditor();
+
+        Editor.ContentDatabase.AddProxy(new TestingCSharpProxy());
+        Editor.ContentDatabase.AddProxy(new TestingCppProxy());
+        Editor.ContentDatabase.Rebuild(true);
+    }
+}
+```

manual/scripting/index.md

@@ -77,6 +77,7 @@ To start visual scripting see the related documentation [here](visual/index.md).
   * [Plugins Window](plugins/plugins-window.md)
   * [Plugin Project](plugins/plugin-project.md)
 * [Advanced](advanced/index.md)
+  * [Script Templates](advanced/templates.md)
   * [Raw Data Asset](advanced/raw-data-asset.md)
   * [Custom Editor Options](advanced/custom-editor-options.md)
   * [Curve](advanced/curve.md)

manual/toc.md

@@ -160,6 +160,7 @@
 ### [View Flags](graphics/debugging-tools/view-flags.md)
 ## [Tutorials](graphics/tutorials/index.md)
 ### [How to render object outline](graphics/tutorials/render-object-outline.md)
+### [How to write additional render pass](graphics/tutorials/additional-render-pass.md)
 ### [How to render FPS weapon](graphics/tutorials/render-fps-weapon.md)
 ### [How to use anisotropic texture sampler](graphics/tutorials/anisotropic-texture-sampler.md)
 ### [How to use dynamic texture](graphics/tutorials/use-dynamic-texture.md)
@@ -202,6 +203,7 @@
 ### [Plugins Window](scripting/plugins/plugins-window.md)
 ### [Plugin Project](scripting/plugins/plugin-project.md)
 ## [Advanced](scripting/advanced/index.md)
+### [Script Templates](scripting/advanced/templates.md)
 ### [Raw Data Asset](scripting/advanced/raw-data-asset.md)
 ### [Custom Editor Options](scripting/advanced/custom-editor-options.md)
 ### [Curve](scripting/advanced/curve.md)