From ecdfcf8ef023f1c1f2ec4c08536436226a97e93c Mon Sep 17 00:00:00 2001 From: Ari Vuollet Date: Sat, 1 Nov 2025 14:46:57 +0200 Subject: [PATCH 1/5] Consolidate C# related scripting documentation under one section --- manual/editor/flax-build/index.md | 1 - manual/scripting/csharp/index.md | 12 ++++++++++++ .../csharp}/nuget-packages.md | 0 manual/scripting/{ => csharp}/restrictions.md | 0 manual/scripting/index.md | 4 +++- manual/toc.md | 5 +++-- 6 files changed, 18 insertions(+), 4 deletions(-) create mode 100644 manual/scripting/csharp/index.md rename manual/{editor/flax-build => scripting/csharp}/nuget-packages.md (100%) rename manual/scripting/{ => csharp}/restrictions.md (100%) diff --git a/manual/editor/flax-build/index.md b/manual/editor/flax-build/index.md index d79f86d1..f7394298 100644 --- a/manual/editor/flax-build/index.md +++ b/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 diff --git a/manual/scripting/csharp/index.md b/manual/scripting/csharp/index.md new file mode 100644 index 00000000..b1d95bce --- /dev/null +++ b/manual/scripting/csharp/index.md @@ -0,0 +1,12 @@ +# C# Scripting + +Visit **[C# API Reference](../../../api-csharp/index.md)** to learn about scripting types. + +## In this section + +* [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/` and *right-click* to add **C# Script** in the module. \ No newline at end of file diff --git a/manual/editor/flax-build/nuget-packages.md b/manual/scripting/csharp/nuget-packages.md similarity index 100% rename from manual/editor/flax-build/nuget-packages.md rename to manual/scripting/csharp/nuget-packages.md diff --git a/manual/scripting/restrictions.md b/manual/scripting/csharp/restrictions.md similarity index 100% rename from manual/scripting/restrictions.md rename to manual/scripting/csharp/restrictions.md diff --git a/manual/scripting/index.md b/manual/scripting/index.md index 319a39c3..4d79f914 100644 --- a/manual/scripting/index.md +++ b/manual/scripting/index.md @@ -59,7 +59,9 @@ 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) + * [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) diff --git a/manual/toc.md b/manual/toc.md index 3ed1b9aa..4b1e9b46 100644 --- a/manual/toc.md +++ b/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,9 @@ ### [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) +### [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) From ca4c0c856de327762d4ad9fdb94e20a52f8577fc Mon Sep 17 00:00:00 2001 From: Ari Vuollet Date: Sat, 1 Nov 2025 14:47:44 +0200 Subject: [PATCH 2/5] Add documentation for common C# project file management tasks --- manual/scripting/csharp/index.md | 3 +- .../csharp/project-file-management.md | 49 +++++++++++++++++++ manual/scripting/index.md | 1 + manual/toc.md | 1 + 4 files changed, 53 insertions(+), 1 deletion(-) create mode 100644 manual/scripting/csharp/project-file-management.md diff --git a/manual/scripting/csharp/index.md b/manual/scripting/csharp/index.md index b1d95bce..1c07109c 100644 --- a/manual/scripting/csharp/index.md +++ b/manual/scripting/csharp/index.md @@ -4,9 +4,10 @@ Visit **[C# API Reference](../../../api-csharp/index.md)** to learn about script ## 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/` and *right-click* to add **C# Script** in the module. \ No newline at end of file +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/` and *right-click* to add **C# Script** in the module. diff --git a/manual/scripting/csharp/project-file-management.md b/manual/scripting/csharp/project-file-management.md new file mode 100644 index 00000000..150c9062 --- /dev/null +++ b/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. + +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.cd`) 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")); +} +``` diff --git a/manual/scripting/index.md b/manual/scripting/index.md index 4d79f914..74d10921 100644 --- a/manual/scripting/index.md +++ b/manual/scripting/index.md @@ -60,6 +60,7 @@ To start visual scripting see the related documentation [here](visual/index.md). * [Attributes](custom-editors/attributes.md) * [Preprocessor variables](preprocessor.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) diff --git a/manual/toc.md b/manual/toc.md index 4b1e9b46..ee145411 100644 --- a/manual/toc.md +++ b/manual/toc.md @@ -188,6 +188,7 @@ ### [Attributes](scripting/custom-editors/attributes.md) ## [Preprocessor variables](scripting/preprocessor.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) From 028265713539bdf6325d2d2cd122cbd386398a63 Mon Sep 17 00:00:00 2001 From: Ari Vuollet Date: Sat, 1 Nov 2025 14:52:54 +0200 Subject: [PATCH 3/5] Add a note about static variable behaviour in editor --- manual/scripting/csharp/restrictions.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/manual/scripting/csharp/restrictions.md b/manual/scripting/csharp/restrictions.md index 0656a921..0b32de8e 100644 --- a/manual/scripting/csharp/restrictions.md +++ b/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. From 545bcf8b957ce17fce6d661012d8615cfc75048b Mon Sep 17 00:00:00 2001 From: Ari Vuollet Date: Sat, 1 Nov 2025 15:00:59 +0200 Subject: [PATCH 4/5] Note about the compiler usage --- manual/scripting/csharp/project-file-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manual/scripting/csharp/project-file-management.md b/manual/scripting/csharp/project-file-management.md index 150c9062..39697fd9 100644 --- a/manual/scripting/csharp/project-file-management.md +++ b/manual/scripting/csharp/project-file-management.md @@ -1,6 +1,6 @@ # 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. +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. From 59511b0ce3679e0bd7c592b7606c64e8616180b6 Mon Sep 17 00:00:00 2001 From: Ari Vuollet Date: Wed, 12 Nov 2025 00:01:38 +0200 Subject: [PATCH 5/5] Fix typo --- manual/scripting/csharp/project-file-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manual/scripting/csharp/project-file-management.md b/manual/scripting/csharp/project-file-management.md index 39697fd9..c85f2fba 100644 --- a/manual/scripting/csharp/project-file-management.md +++ b/manual/scripting/csharp/project-file-management.md @@ -8,7 +8,7 @@ As these files are constantly regenerated after modifying the module files or ad `/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.cd`) in the following way to add the reference to the required 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) {