diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml index ec3947c5..aefb3beb 100644 --- a/.github/workflows/docs-publish.yml +++ b/.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 diff --git a/manual/contributing/index.md b/manual/contributing/index.md index 3351fc7d..7c305971 100644 --- a/manual/contributing/index.md +++ b/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 diff --git a/manual/get-started/prefabs/index.md b/manual/get-started/prefabs/index.md index dd07013d..f9006acb 100644 --- a/manual/get-started/prefabs/index.md +++ b/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) diff --git a/manual/get-started/prefabs/media/prefab-instance-buttons.png b/manual/get-started/prefabs/media/prefab-instance-buttons.png index aa1b8353..b8ddfca1 100644 Binary files a/manual/get-started/prefabs/media/prefab-instance-buttons.png and b/manual/get-started/prefabs/media/prefab-instance-buttons.png differ diff --git a/manual/graphics/tutorials/additional-render-pass.md b/manual/graphics/tutorials/additional-render-pass.md new file mode 100644 index 00000000..88c14533 --- /dev/null +++ b/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; + +/// +/// OutlineRenderer Script. +/// +public class OutlineRenderer : PostProcessEffect +{ + private Material _material; + private Model _model; + + public Material OutlineMaterial + { + get => _material; + set + { + if (_material != value) + { + _material = value; + } + } + } + + /// + 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); + } + + /// + public override void OnDisable() + { + // Remember to unregister from events and release created resources (it's gamedev, not webdev) + SceneRenderTask.RemoveGlobalCustomPostFx(this); + } + + /// + public override bool CanRender() + { + return base.CanRender() && _material; + } + + /// + 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) diff --git a/manual/graphics/tutorials/index.md b/manual/graphics/tutorials/index.md index 4ae1431f..2f956ee2 100644 --- a/manual/graphics/tutorials/index.md +++ b/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) diff --git a/manual/graphics/tutorials/media/toon-outline-example.png b/manual/graphics/tutorials/media/toon-outline-example.png new file mode 100644 index 00000000..70771167 Binary files /dev/null and b/manual/graphics/tutorials/media/toon-outline-example.png differ diff --git a/manual/graphics/tutorials/media/toon-outline-material.png b/manual/graphics/tutorials/media/toon-outline-material.png new file mode 100644 index 00000000..3f0af504 Binary files /dev/null and b/manual/graphics/tutorials/media/toon-outline-material.png differ diff --git a/manual/input/virtual-input.md b/manual/input/virtual-input.md index 6f2c4369..e9a32e6f 100644 --- a/manual/input/virtual-input.md +++ b/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(); diff --git a/manual/navigation/tutorials/path-following.md b/manual/navigation/tutorials/path-following.md index 891fe5db..2dba6d00 100644 --- a/manual/navigation/tutorials/path-following.md +++ b/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++) diff --git a/manual/networking/tutorials/network-client-server.md b/manual/networking/tutorials/network-client-server.md index 9ac86b02..ff6f900e 100644 --- a/manual/networking/tutorials/network-client-server.md +++ b/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, diff --git a/manual/samples-tutorials/tutorials/index.md b/manual/samples-tutorials/tutorials/index.md index 3d7976aa..c20d718a 100644 --- a/manual/samples-tutorials/tutorials/index.md +++ b/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) diff --git a/manual/scripting/advanced/index.md b/manual/scripting/advanced/index.md index 9ec463ff..5cf51889 100644 --- a/manual/scripting/advanced/index.md +++ b/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) diff --git a/manual/scripting/advanced/templates.md b/manual/scripting/advanced/templates.md new file mode 100644 index 00000000..625d3d45 --- /dev/null +++ b/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); + } +} +``` \ No newline at end of file diff --git a/manual/scripting/index.md b/manual/scripting/index.md index 4678f5ae..e376cee7 100644 --- a/manual/scripting/index.md +++ b/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) diff --git a/manual/toc.md b/manual/toc.md index 1b01d53a..205632cf 100644 --- a/manual/toc.md +++ b/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)