From 666498d4ba85470e1412c0ec2b0fe941407344c5 Mon Sep 17 00:00:00 2001 From: Vaclav Elias Date: Sat, 30 Nov 2024 01:06:51 +0000 Subject: [PATCH 1/2] docs: Add Extensibility section and C# Libraries guide - Updated `toc.yml` to include a new "Extensibility" section with a link to `extensibility/index.md`. - Added a sub-item "C# Libraries" under the new "Extensibility" section, linking to `extensibility/csharp-libraries.md`. - Created `csharp-libraries.md` to provide information on creating and using C# libraries within a Stride project, including details on adding a module initializer and re-compiling NuGet packages. - Created `index.md` under the `extensibility` directory to introduce the concept of extending a Stride game project with a regular C# library and link to the detailed guide in `csharp-libraries.md`. --- en/manual/extensibility/csharp-libraries.md | 27 +++++++++++++++++++++ en/manual/extensibility/index.md | 7 ++++++ en/manual/toc.yml | 6 +++++ 3 files changed, 40 insertions(+) create mode 100644 en/manual/extensibility/csharp-libraries.md create mode 100644 en/manual/extensibility/index.md diff --git a/en/manual/extensibility/csharp-libraries.md b/en/manual/extensibility/csharp-libraries.md new file mode 100644 index 00000000..5d84395c --- /dev/null +++ b/en/manual/extensibility/csharp-libraries.md @@ -0,0 +1,27 @@ +# C# Libraries + +Advanced +Programmer + +If you want to share code between multiple projects, or create reusable components, you can create a C# library and reference it in your Stride project. + +If your library is utilising @Stride.Core.DataContractAttribute, you need to follow additional steps to make it work with Stride. + +1. Add a Module initializer to your library. This will register your library with Stride's serialization system. Example `Module.cs`: + + ```csharp + using Stride.Core.Reflection; + using System.Reflection; + + namespace MyProjectName; + + internal class Module + { + [ModuleInitializer] + public static void Initialize() + { + AssemblyRegistry.Register(typeof(Module).GetTypeInfo().Assembly, AssemblyCommonCategories.Assets); + } + } + ``` +1. If you are creating also NuGet packages for your library, these NuGet packages have to be re-compiled with latest version of Stride NuGet packages. \ No newline at end of file diff --git a/en/manual/extensibility/index.md b/en/manual/extensibility/index.md new file mode 100644 index 00000000..d720c358 --- /dev/null +++ b/en/manual/extensibility/index.md @@ -0,0 +1,7 @@ +# Extensibility + +## Introduction + +Stride game project is a regular .NET project, and as such, it can be extended by a regular C# library. This is a great way to share code between multiple projects, or to create reusable components. + +Read more about this subject in [C# Libraries](extensibility/csharp-libraries.md). \ No newline at end of file diff --git a/en/manual/toc.yml b/en/manual/toc.yml index c0f66606..2440d8ae 100644 --- a/en/manual/toc.yml +++ b/en/manual/toc.yml @@ -561,6 +561,12 @@ items: - name: Create Packages href: nuget/create-packages.md + - name: Extensibility + href: extensibility/index.md + items: + - name: C# Libraries + href: extensibility/csharp-libraries.md + - name: Troubleshooting href: troubleshooting/index.md items: From fc9c7806c118642090036479d3d747f1023cf4de Mon Sep 17 00:00:00 2001 From: Vaclav Elias Date: Sun, 1 Dec 2024 21:28:50 +0000 Subject: [PATCH 2/2] docs: Content updated based on the feedback --- en/manual/extensibility/csharp-libraries.md | 41 +++++++++++++-------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/en/manual/extensibility/csharp-libraries.md b/en/manual/extensibility/csharp-libraries.md index 5d84395c..1f305b6d 100644 --- a/en/manual/extensibility/csharp-libraries.md +++ b/en/manual/extensibility/csharp-libraries.md @@ -3,25 +3,36 @@ Advanced Programmer -If you want to share code between multiple projects, or create reusable components, you can create a C# library and reference it in your Stride project. +If you want to share code between multiple projects or create reusable components, you can create a C# library and reference it in your Stride project. -If your library is utilising @Stride.Core.DataContractAttribute, you need to follow additional steps to make it work with Stride. +If your library uses the @Stride.Core.DataContractAttribute and you want to reference it through a **NuGet** package, there are additional steps required to make it compatible with Stride. -1. Add a Module initializer to your library. This will register your library with Stride's serialization system. Example `Module.cs`: +## Adding a Module Initializer - ```csharp - using Stride.Core.Reflection; - using System.Reflection; +First, add a module initializer to your library. This ensures your library is properly registered with Stride's serialization system. - namespace MyProjectName; +Example `Module.cs`: - internal class Module +```csharp +using Stride.Core.Reflection; +using System.Reflection; + +namespace MyProjectName; + +internal class Module +{ + [ModuleInitializer] + public static void Initialize() { - [ModuleInitializer] - public static void Initialize() - { - AssemblyRegistry.Register(typeof(Module).GetTypeInfo().Assembly, AssemblyCommonCategories.Assets); - } + AssemblyRegistry.Register(typeof(Module).GetTypeInfo().Assembly, AssemblyCommonCategories.Assets); } - ``` -1. If you are creating also NuGet packages for your library, these NuGet packages have to be re-compiled with latest version of Stride NuGet packages. \ No newline at end of file +} +``` + +## Updating to the Latest Stride NuGet Packages + +If your library references any Stride NuGet packages, you must recompile it with the latest version of those packages. This ensures compatibility with the current Stride ecosystem. + +## About the Module Initializer Attribute + +The `ModuleInitializer` attribute is now generated using a Roslyn source generator. This means the file `sources/core/Stride.Core.CompilerServices/Generators/ModuleInitializerGenerator.cs` must run during your code's compilation. Otherwise, the module initializer and potentially other source generators added in the future will not function correctly. \ No newline at end of file