Improve C# scripting documentation

manual/editor/flax-build/index.md

@@ -25,7 +25,6 @@ This documentation section covers most of the topics related to Flax.Build tool.
 * [API tags](api-tags.md)
 * [Build Plugin](plugins.md)
 * [Build Tool Guide](guide.md)
-* [Nuget Packages](nuget-packages.md)
 
 ## Build Scripts
 

manual/scripting/csharp/index.md

@@ -0,0 +1,13 @@
+# C# Scripting
+
+Visit **[C# API Reference](../../../api-csharp/index.md)** to learn about scripting types.
+
+## In this section
+
+* [Project file management](project-file-management.md)
+* [Nuget Packages](nuget-packages.md)
+* [Restrictions](restrictions.md)
+
+## How to create C# script?
+
+C# scripting is enabled by default in [Flax Project modules](../../editor/flax-build/index.md), so C# scripts can be added without any further setup. In the *Content Window*, go to your project's module source folder `Source/<module_name>` and *right-click* to add **C# Script** in the module.

manual/scripting/csharp/project-file-management.md

@@ -0,0 +1,49 @@
+# Project file management
+
+Flax.Build tool generates the required C# project files expected for the configured Code Editor, which usually uses the .csproj-file format accompanied with Visual Studio .sln-solution files. The code editor can then use these files to provide code completion and other features language server features to help the user navigate around the codebase. The compilation process does not use MSBuild which uses .csproj-files but rather compiles the source files directly with the C#-compiler using the module and build target configuration files.
+
+As these files are constantly regenerated after modifying the module files or adding new source files, any permanent modifications to the generated .csproj-file should be avoided. The expected place to do these modifications are in the [module configuration files](../../editor/flax-build/index.md) (eg. `Game.Build.cd`), which are used to configure the project file generation process.
+
+# Adding references
+
+`/Source/Game/MyScript.cs(32,13,32,18): error CS1069: The type name 'Regex' could not be found in the namespace 'System.Text.RegularExpressions'. This type has been forwarded to assembly 'System.Text.RegularExpressions, Version=9.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a' Consider adding a reference to that assembly.`
+
+When scripting requires referencing other common system references, we can modify the module build file (eg. `Game.Build.cs`) in the following way to add the reference to the required assembly:
+```cs
+public override void Setup(BuildOptions options)
+{
+    base.Setup(options);
+
+    options.ScriptingAPI.SystemReferences.Add("System.Text.RegularExpressions");
+}
+```
+
+Referencing third-party C# library files can be done with file references, but in this case we need to provide the path to the assembly file:
+```cs
+public override void Setup(BuildOptions options)
+{
+    base.Setup(options);
+
+    // Note: the path is relative to the .build file itself
+    options.ScriptingAPI.FileReferences.Add(Path.Combine(FolderPath, "..", "..", "Content", "CustomAssembly.dll"));
+}
+```
+
+In order to add **Nuget-packages** to your project, please see the dedicated section [here](nuget-packages.md).
+
+For a more thorough example to use third-party libraries can be found [here](../tutorials/use-third-party-library.html#using-c-library).
+
+# Analyzers and source generators
+
+Source generators and analyzers are also supported. System provided assemblies can be added in `SystemAnalyzers` and external file references to `Analyzers` lists:
+```cs
+public override void Setup(BuildOptions options)
+{
+    base.Setup(options);
+
+    options.ScriptingAPI.SystemAnalyzers.Add("Microsoft.Interop.ComInterfaceGenerator");
+
+    // Note: the path is relative to the .build file itself
+    options.ScriptingAPI.Analyzers.Add(Path.Combine(FolderPath, "..", "..", "Content", "CustomAnalyzer.dll"));
+}
+```

manual/scripting/restrictions.md → manual/scripting/csharp/restrictions.md

@@ -14,6 +14,10 @@ Flax tries to implement all the engine features and scripting APIs across all su
 - System.Reflection.Metadata.dll
 - System.Web.Extensions.Design.dll
 
+## Static variables in editor
+
+Static variables may behave differently when running the scripts in editor compared to running the cooked game. The static variables are usually initialized when the scripting assemblies are loaded and used for the first time, but Flax Editor may not always reload the assemblies between runs (unless recompilation is needed), so the values from previous runs are retained. There are many ways to work around this by using [Game Plugins](../plugins/index.md) to manage state or subscribing to `FlaxEditor.Editor.Instance.PlayModeBeginning` event which is called right before entering play mode.
+
 ## Ahead-of-time compile
 
 Ahead-of-time (**AOT**) compile is a technique used to precompile all the managed code during game building process instead of using just-in-time (**JIT**) compilation on the target device. That's because some platforms do not allow runtime code generation. In most cases this has no effect on game scripting but in a few specific cases, AOT platforms require additional consideration.

manual/scripting/index.md

@@ -59,7 +59,10 @@ To start visual scripting see the related documentation [here](visual/index.md).
   * [Custom script editor](tutorials/custom-editor.md)
   * [Attributes](custom-editors/attributes.md)
 * [Preprocessor variables](preprocessor.md)
-* [Scripting restrictions](restrictions.md)
+* [C# Scripting](csharp/index.md)
+  * [Project file management](csharp/project-file-management.md)
+  * [Nuget Packages](csharp/nuget-packages.md)
+  * [Scripting Restrictions](csharp/restrictions.md)
 * [C++ Scripting](cpp/index.md)
   * [Common Types](cpp/common-types.md)
   * [Collections](cpp/collections.md)

manual/toc.md

@@ -60,7 +60,6 @@
 ### [API Tags](editor/flax-build/api-tags.md)
 ### [Plugins](editor/flax-build/plugins.md)
 ### [Guide](editor/flax-build/guide.md)
-### [Nuget Packages](editor/flax-build/nuget-packages.md)
 ## [Editor Options](editor/options/index.md)
 ## [Profiling](editor/profiling/index.md)
 ### [Profiler](editor/profiling/profiler.md)
@@ -188,7 +187,10 @@
 ### [Custom script editor](scripting/tutorials/custom-editor.md)
 ### [Attributes](scripting/custom-editors/attributes.md)
 ## [Preprocessor variables](scripting/preprocessor.md)
-## [Scripting restrictions](scripting/restrictions.md)
+## [C# Scripting](scripting/charp/index.md)
+### [Project file management](scripting/csharp/project-file-management.md)
+### [Nuget Packages](scripting/csharp/nuget-packages.md)
+### [Scripting Restrictions](scripting/csharp/restrictions.md)
 ## [C++ Scripting](scripting/cpp/index.md)
 ### [Common Types](scripting/cpp/common-types.md)
 ### [Collections](scripting/cpp/collections.md)