Build instructions improved

en/contributors/engine/build-architecture.md

@@ -0,0 +1,83 @@
+# Build details
+
+?? https://github.com/stride3d/stride/edit/master/docs/technical/build-pipeline.md
+WIP: COPIED from link above
+
+# Build
+
+## Overview
+
+This is a technical description what happens in our build and how it is organized. This covers mostly the build architecture of Stride itself.
+
+* [Targets](../Targets) contains the MSBuild target files used by Games
+* [sources/common/targets](../sources/common/targets) (generic) and [sources/targets](../sources/targets) (Stride-specific) contains the MSBuild target files used to build Stride itself.
+
+Since 3.1, we switched from our custom build system to the new csproj system with one nuget package per assembly.
+
+We use `TargetFrameworks` to properly compile the different platforms using a single project (Android, iOS, etc...).
+
+Also, we use `RuntimeIdentifiers` to select graphics platform. [MSBuild.Sdk.Extras](https://github.com/onovotny/MSBuildSdkExtras) is used to properly build NuGet packages with multiple `RuntimeIdentifiers` (not supported out of the box).
+
+### Limitations
+
+* Dependencies are per `TargetFramework` and can't be done per `RuntimeIdentifier` (tracked in [NuGet#1660](https://github.com/NuGet/Home/issues/1660)).
+* FastUpToDate check doesn't work with multiple `TargetFrameworks` (tracked in [project-system#2487](https://github.com/dotnet/project-system/issues/2487)).
+
+## NuGet resolver
+
+Since we want to package tools (i.e. GameStudio, ConnectionRouter, CompilerApp) with a package that contains only the executable with proper dependencies to other NuGet runtime packages, we use NuGet API to resolve assemblies at runtime.
+
+The code responsible for this is located in [Stride.NuGetResolver](../sources/shared/Stride.NuGetResolver).
+
+Later, we might want to take advantage of .NET Core dependency resolving to do that natively. Also, we might want to use actual project information/dependencies to resolve to different runtime assemblies and better support plugins.
+
+## Versioning
+
+Stride is versioned using `SharedAssemblyInfo.cs`.
+For example, assuming version `4.1.3.135+gfa0f5cc4`:
+- `4.1` is the Stride major and minor version, as they are grouped in the launcher. Versions inside this group shouldn't have breaking changes
+- `3` is the asset version. This can be bumped if asset files require some upgrade.
+- `135` is the git height (number of commits since `4.1.3` is set), computed automatically when building packages.
+  Note: when building packages locally, this will typically be 1. This is the reason why the asset version needs to be bumped when asset changes to keep things ordered (otherwise the git height version `1` will always be lower than official version).
+- `+gfa0f5cc4` means git commit `fa0f5cc4`
+
+## Assembly processor
+
+Assembly processor is run by both Game and Stride targets.
+
+It performs various transforms to the compiled assemblies:
+* Generate [DataSerializer](../sources/common/core/Stride.Core/Serialization/DataSerializer.cs) serialization code (and merge it back in assembly using IL-Repack)
+* Generate [UpdateEngine](../sources/engine/Stride.Engine/Updater/UpdateEngine.cs) code
+* Scan for types or attributes with `[ScanAssembly]` to quickly enumerate them without needing `Assembly.GetTypes()`
+* Optimize calls to [Stride.Core.Utilities](../sources/common/core/Stride.Core/Utilities.cs)
+* Automatically call methods tagged with [ModuleInitializer](../sources/common/core/Stride.Core/ModuleInitializerAttribute.cs)
+* Cache lambdas and various other code generation related to [Dispatcher](../sources/common/core/Stride.Core/Threading/Dispatcher.cs)
+* A few other internal tasks
+
+For performance reasons, it is run as a MSBuild Task (avoid reload/JIT-ing). If you wish to make it run the executable directly, set `StrideAssemblyProcessorDev` to `true`.
+
+## Dependencies
+
+We want an easy mechanism to attach some files to copy alongside a referenced .dll or .exe, including content and native libraries.
+
+As a result, `<StrideContent>` and `<StrideNativeLib>` item types were added.
+
+When a project declare them, they will be saved alongside the assembly with extension `.ssdeps`, to instruct referencing projects what needs to be copied.
+
+Also, for the specific case of `<StrideNativeLib>`, we automatically copy them in appropriate folders and link them if necessary.
+
+Note: we don't apply them transitively yet (project output won't contains the `.ssdeps` file anymore so it is mostly useful to reference from executables/apps directly)
+
+## Native
+
+By adding a reference to `Stride.Native.targets`, it is easy to build some C/C++ files that will be compiled on all platforms and automatically added to the `.ssdeps` file.
+
+### Limitations
+
+It seems that using those optimization don't work well with shadow copying and [probing privatePath](https://msdn.microsoft.com/en-us/library/823z9h8w(v=vs.110).aspx). This forces us to copy the `Direct3D11` specific assemblies to the top level `Windows` folder at startup of some tools. This is little bit unfortunate as it seems to disturb the MSBuild assembly searching (happens before `$(AssemblySearchPaths)`). As a result, inside Stride solution it is necessary to explicitely add `<ProjectReference>` to the graphics specific assemblies otherwise wrong ones might be picked up.
+
+This will require further investigation to avoid this copying at all.
+
+## Asset Compiler
+
+Both Games and Stride unit tests are running the asset compiler as part of the build process to create assets.

en/contributors/engine/build-details.md

@@ -1,158 +0,0 @@
-# Building the source to Stride engine
-
-?? https://github.com/stride3d/stride/edit/master/docs/technical/build-pipeline.md
-WIP: COPIED from link above
-
-# Build pipeline
-
-This document describes the Build pipeline in Stride, its current implementation (and legacy), and the work that should be done to improve it.
-
-## Terminology
-
-* An **Asset** is a design-time object containing information to generate **Content** that can be loaded at runtime. For example, a **Model asset** contains the path to a source FBX file, and additional information such as an offset for the pivot point of the model, a scale factor, a list of materials to use for this model. A **Sprite font asset**  contains a path to a source font, multiple parameters such as the size, kerning, etc. and information describing in which form it should be compiled (such as pre-rasterized, or using distance field...). **Asset** are serialized on disk using the YAML format, and are part of the data that a team developing a game should be sharing on a source control system.
-
-* **Content** is the name given to compiled data (usually generated from **Asset**s) that can be loaded at runtime. This means that in term of format, **Content** is optimized for performance and size (using binary serialization, and data structured in a way so that the runtime can consume it without re-transforming it). Therefore **Content** is the platform-specific optimized version of your game data.
-
-## Design
-
-Stride uses *Content-addressable storage* to store the data generated by the compilation. The main concept is that the actual name of each generated file is the hash of the file. So if, after a change, the resulting content built from the asset is different, then the file name will be different. An index map file contains the mapping between the content *URL* and the actual hash of the corresponding file. Parameters of each compilation commands are also hashed and stored in this database, so if a command is ran again with the same parameters, the build engine can easily recover the hashes of the corresponding generated files.
-
-### Build Engine
-
-The build engine is the part of the infrastructure that transforms data from the **assets** into actual **content** and save it to the database. It was originally designed to build content from input similar to a makefile. (eg. "compile all files in `MyModels/*.fbx` into Stride models). It has then been changed to work with individual assets when the asset layer has been implemented. Due to this legacy, this library is still not perfectly suited or optimal to build assets in an efficient way (dependencies of build steps, management of a queue for live-compiling in the Game Studio, etc.).
-
-#### Builder
-
-The `Builder` class is the entry point of the build engine. A `Builder` will spawn a given number of threads, each one running a `Microthread` scheduler (see `RunUntilEnd` method).
-
-#### Build Steps
-
-The `Builder` takes a root `BuildStep` as input. We currently have two types of `BuildStep`s:
-* A `ListBuildStep` contains a sequence of `BuildStep` (Formerly we had an additional parent class called `EnumerableBuildStep`, but it has been merged into `ListBuildStep`). A `ListBuildStep` will schedule all the build steps it contains at the same time, to be run in parallel. Formerly we had a synchronization mechanism using a special `WaitBuildStep` but it has been removed. We now use `PrerequisiteSteps` with `LinkBuildSteps` to manage dependencies.
-* A `CommandBuildStep` contains a single `Command` to run, which does actual work to compile asset.
-
-> **TODO:** Currently, when compiling a graph of build steps, we need to have all steps to compile in the root `ListBuildStep`. More especially, if we have a `ListBuildStep` container in which we want to put a step A that depends on a step B and C, we need to put A, B, C in the `ListBuildStep` container. This is cumbersome and error-prone. What we would like to do is to rely only on the `PrerequisiteSteps` of a given step to find what we have to compile. If we do so, we wouldn't need to return a `ListBuildStep` in `AssetCompilerResult`, but just the final build step for the asset, the graph of dependent build steps being described by recursive `PrerequisiteSteps`. The `ListBuildStep` container could be removed. We would still need to have lists of build steps when we compile multiple asset (eg. when compiling the full game), but it would be nothing that the build engine should be aware of.
-
-#### Commands
-
-Most command inherits from `IndexFileCommand`, which automatically register the output of the command into the command context.
-
-Basically, at the beginning of the command (in the `PreCommand` method), a `BuildTransaction` object is created. This transaction contains a subset of the database of objects that have been already compiled, provided by the `ICommandContext.GetOutputObjectsGroups()`. In term of implementation, this method returns all the objects that where written by prerequisite build steps, and all the objects that are already written in any of the parent `ListBuildStep`s, recursively. The objects coming from the parent `ListBuildStep` are a legacy of when we were using `WaitBuildStep` to synchronize the build steps. This hopefully should be implemented differently, relying only on prerequisite (since no synchronization can happen in the `ListBuildStep itself, everything is run in parallel).
-
-> **TODO:** Rewrite how OutputObjects are transfered from `BuildStep`s to other `BuildStep`s. Only the output from prerequisite `BuildStep` should be transfered. A lot of legacy makes this code very convoluted and hard to maintain.
-
-The `BuildTransaction` created during this step is mounted as a *Microthread-local database*, which is accessible only from the current microthread (which is basically the current command).
-
-At the end of the command (in the `PostCommand` method), every object that has been written in the database by the command are extracted from the `BuildTransaction` and registered to the current `ICommandContext` (which is how the `ICommandContext` can "flow" objects from one command to the other.
-
-It's important to keep in mind that objects accessible in a given command (in the `DoCommandOverride`) using a `ContentManager` are those provided during the `PreCommand` step, and therefore it is important that dependencies between commands (what other commmands a command needs to be completed to start) are properly set.
-
-### Compilers
-
-Compilers are classes that generate a set of `BuildStep`s to compile a given `Asset` in a specific context. This list could grow in the future if we have other needs, but the current different contexts are:
-- compiling the asset for the game
-- compiling the asset for the scene editor
-- compiling the asset to display in the preview
-- compiling the asset to generate a thumbnail
-
-#### IAssetCompiler
-
-This is the base interface for compiler. The entry point is the `Prepare` method, which takes an `AssetItem` and returns a `AssetCompilerResult`, which is a mix of a `LoggerResult` and a  `ListBuildStep`. Usually there are two implementations per asset types, one to compile asset for the game and one to compile asset for its thumbnails. Some asset types such as animations might have an additional implementation for the preview.
-
-Each implementation of `IAssetCompiler` must have the `AssetCompilerAttribute` attached to the class, in order to be registered (compilers are registered via the `AssetCompilerRegistry`.
-
-> **TODO:** The `AssetCompilerRegistry` could be merged into the `AssetRegistry` to have a single location where asset-related types and meta-information are registered.
-
-Each compiler provides a set of methods to help discover the dependencies between assets and compilers. They will be covered later in this document.
-
-#### ICompilationContext
-
-> Not to be mistaken with `CompilerContext` and `AssetCompilerContext`.
-
-Contexts of compilation are defined by *types*, which allow to use inheritance mechanism to fallback on a default compiler when there is no specific compiler for a given context. Each compilation context type must implement `ICompilationContext`. Currently we have:
-
-* `AssetCompilationContext` is the context used when we compile an asset for the runtime (ie. the game).
-* `EditorGameCompilationContext` is the context used when we compile an asset for the scene editor, which is a specific runtime. Therefore, it inherits from `AssetCompilationContext`.
-* `PreviewCompilationContext` is the context used when we compile an asset for the preview, which is a specific runtime. Therefore, it inherits from `AssetCompilationContext`.
-* `ThumbnailCompilationContext` is the context used when we compile an asset to generate a thumbnail. Generally, for thumbnails, we compile one or several assets for the runtime, and use additional steps to generate the thumbnail with the `ThumbnailCompilationContext` (see below).
-
-> **TODO:** Currently thumbnail compilation is in a poor state. In `ThumbnailListCompiler.Compile`, we first generate the steps to compile the asset in `PreviewCompilationContext`, then generate the steps to compile the asset in `ThumbnailCompilationContext`, and finally we like the first with the latter. Dependencies from thumbnail compilers (which load a scene and take screenshots) to the runtime compiler (which compile the asset) is **not** expressed at all. It just works now because in all current cases, the `PreviewCompilationContext` does what we need for thumbnails (for example, the `AnimationAssetPreviewCompiler` adds the preview model to the normal compilation of the animation, which is needed for both preview and thumbnail).
-
-### Dependency managers
-
-We currently have two mechanisms that handle dependencies.
-
-> **TODO:** Merge the `AssetDependencyManager` and the `BuildDependencyManager` together into a single dependency manager object. There is a lot of redundancy between both, one rely on the other, some code is duplicated. See `XK-4862`
-
-#### AssetDependencyManager
-
-The `AssetDependencyManager` was the first implementation of an mechanism to manage dependencies between assets. It works independently of the build, which is one of the main issue it had and the reason why we started to develop a new infrastructure.
-
-It is based essentially on visiting assets with a `DataVisitorBase` to find references to other assets. There are two ways of referencing an asset:
-
-- Having a property whose type is an implementation of `IReference`. More explicitely the only case we have currently is `AssetReference`. This type contains an `AssetId` and a `Location` corresponding to the referenced asset.
-- Having a property whose type correspond to a *Content* type, ie. a type registered as being the compiled version of an asset type (for example, `Texture` is the Content type of `TextureAsset`).
-
-The problem of that design was that once all the references are collected, there is no way to know of the referenced assets are actually consumed, which could be one of the three following way:
-
-- the referenced asset is not needed to compile this asset, but it's needed at runtime to use the compiled content (eg. Models need Materials, who need Textures. But you can compile Models, Materials and Textures independently).
-- the referenced asset needs to be compiled before this asset, and the compiler of this asset needs to load the corresponding content generated from the referenced asset (eg. A prefab model, which aggregates multiple models together, needs the compiled version of each model it's referencing to be able to merge them).
-- the referenced asset is read when compiling this asset because it depends on some of its parameter, but the referenced asset itself doesn't need to be compiled first (eg. Navigation Meshes need to read the scene asset they are related to in order to gather static colliders it contains, but they don't need to compile the scene itself).
-
-#### BuildDependencyManager
-
-The `BuildDependencyManager` has been introduced recently to solve the problems of the `AssetDependencyManager`. It is currently not complete, and the ultimate goal is to merge it totally with the `AssetDependencyManager`.
-
-The approach is a bit different. Rather than extracting dependencies from the asset itself, we extract them from the compilers of the assets, which are better suited to know what they exactly need to compile the asset and what will be needed to load the asset at runtime.
-
-But one asset type can have multiple compilers associated to it (for the game, for the thumbnail, for the preview...). So the `BuildDependencyManager` works in the context of a specific compiler.
-
-Currently there is one `BuildDependencyManager` for each type of compiler.
-
-> **TODO:** Have a single global instance of `BuildDependencyManager` that contains all types of dependencies for all context of compilers. For example, we have thumbnail compilers that requires *game* version of assets, which means that the `BuildDependencyManager` for thumbnails will also contain a large part of the `BuildDependencyManager` to build the game. Merging everything into a single graph would reduce redundancy and risk to trigger the same operation multiple times simultaneously.
-
-#### AssetDependenciesCompiler
-
-The `AssetDependenciesCompiler` is the object that computes the dependencies with the `BuildDependencyManager`, and then generates the build steps for a given asset, including the runtime dependencies. It's the main entry point of compilation for the CompilerApp, the scene editor, and the preview. Thumbnails also use it, via the `ThumbnailListCompiler` class.
-
-> **TODO:** This class should be removed, and its content moved into the `BuildDependencyManager` class. By doing so, it should be possible to make `BuildAssetNode` and `BuildAssetLink` internal - those classes are just the data of the dependency graph, they should not be exposed publicly. To do that, a method to retrieve the dependencies in a given context must be implemented in `BuildDependencyManager` in order to fix the usage of `BuildAssetNode` in `EditorContentLoader`.
-
-### In the Game Studio
-
-The Game Studio compiles assets in various versions all the time. It has some specific way of managing database and content depending on the context.
-
-Remark: the Game Studio never saves index file on the disk, it keeps the url -> hash mapping in memory, always.
-
-#### Databases
-
-Before accessing content to load, a Microthread-local database must be mounted. Depending on the context, it can be a database containing a scene and its dependencies (scene editor), the assets needed to create a thumbnail, an asset to display in the preview...
-
-For the scene editor, this is handled by the `GameStudioDatabase` class. Thumbnails and preview also handle database mounting internally (in `ThumbnailGenerator` for example).
-
-> **TODO:** See if it could be possible/useful to wrap all database-mounting in the Game Studio into the GameStudioDatabase class.
-
-#### Builder service
-
-All compilations that occur in the Game Studio is done through the `GameStudioBuilderService`. This class creates an instance of `Builder`, a `DynamicBuilder` which allows to feed the Builder with build steps at any time. Having a single builder for the whole Game Studio allows to control the number of threads and concurrent tasks more easily.
-
-The `DynamicBuilder` class simply creates a thread to run the Builder on, and set a special build step, `DynamicBuildStep`, as root step of this builder. This step is permanently waiting for other child build step to be posted, and execute them.
-
-> **TODO:** Currently the dynamic build step waits arbitratly with the `CompleteOneBuildStep` method when more than 8 assets compiling. This is a poor design because if the 8 assets are for example prefabs who contains a lot of models, materials, textures, it will block until all are done, although we could complete the thumbnails of these models/materials/textures individually. Ideally, this `await` should be removed, and a way to make sure thumbnails of assets which are compiled are created as soon as possible should be implemented.
-
-The builder service uses `AssetBuildUnit`s as unit of compilation. A build unit corresponds to a single asset, and encapsulates the compiler and the generated build step of this asset.
-
-#### EditorContentLoader
-
-The scene editor needs a special behavior in term of asset loading. The main issue is that any type of asset can be modified by the user (for example a texture), and then need to be reloaded. Stride use the `ContentManager` to handle reference counting of loaded assets. With a few exception (Materials, maybe Textures), it does not support hot-swapping an asset. Therefore, when an asset needs to be reloaded, we actually need to unload and reload the *first-referencer* of this asset.
-
-The *first-referencer* is the first asset referenced by an entity, that contains a way (in term of reference) to the asset to reload. For example, in case of a texture, we will have to reload all models that use materials that use the texture to reload.
-
-This is done by the `EditorContentLoader` class. At initialization, this class collects all *first-referencer* assets and build them. Each time an asset is built, it is then loaded into the scene editor game, and the references (from the entity to the asset) are updated. This means that this class needs to track all first-referencers on its own and update them. This is done specifically by the `LoaderReferenceManager` object. The reference are collected from the `GameEditorChangePropagator`, an object that takes the responsibility to push synchronization of changes between the assets and the game (for all properties, including non-references). There is one instance of it per entity. When a property of an entity that contains a reference to an asset (a *first-referencer*) is modified, the propagator will trigger the work to compile and update the entity. In case of a referenced asset modified by the user, `EditorContentLoader.AssetPropertiesChanged` takes the responsibility to gather, build, unload and reload what needs to be reloaded.
-
-## Additional Todos
-
-> **TODO:** `GetInputFiles` exists both in `Command` and in `IAssetCompiler`. It has the same signature in both case, so it's returning information using `ObjectUrl` and `UrlType` in the compiler, where we are trying to describe dependency. That signature should be changed, so it returns information using `BuildDependencyType` and `AssetCompilationContext`, just like the GetInputTypes method. Also, the method is passed to the command via the `InputFilesGetter` which is not very nice and has to be done manually (super error-prone, we had multiple commands that were missing it!). An automated way should be provided.
-
-> **TODO:** The current design of the build steps and list build steps is a *tree*. For this reason, same build steps are often generated multiple times and appears in multiple trees. It could be possible to cache and share the build step if the structure was a *graph* rather than a *tree*. Do to that, the `Parent` property of build steps should be removed. The main difficulty is that the way output objects of build steps flow between steps has to be rewritten.
-
-

en/contributors/engine/build-pipeline.md

@@ -1,83 +1,153 @@
-# Build details
+# Build pipeline
 
-?? https://github.com/stride3d/stride/edit/master/docs/technical/build-pipeline.md
-WIP: COPIED from link above
+This document describes the Build pipeline in Stride, its current implementation (and legacy), and the work that should be done to improve it.
 
-# Build
+## Terminology
 
-## Overview
+* An **Asset** is a design-time object containing information to generate **Content** that can be loaded at runtime. For example, a **Model asset** contains the path to a source FBX file, and additional information such as an offset for the pivot point of the model, a scale factor, a list of materials to use for this model. A **Sprite font asset**  contains a path to a source font, multiple parameters such as the size, kerning, etc. and information describing in which form it should be compiled (such as pre-rasterized, or using distance field...). **Asset** are serialized on disk using the YAML format, and are part of the data that a team developing a game should be sharing on a source control system.
 
-This is a technical description what happens in our build and how it is organized. This covers mostly the build architecture of Stride itself.
+* **Content** is the name given to compiled data (usually generated from **Asset**s) that can be loaded at runtime. This means that in term of format, **Content** is optimized for performance and size (using binary serialization, and data structured in a way so that the runtime can consume it without re-transforming it). Therefore **Content** is the platform-specific optimized version of your game data.
 
-* [Targets](../Targets) contains the MSBuild target files used by Games
-* [sources/common/targets](../sources/common/targets) (generic) and [sources/targets](../sources/targets) (Stride-specific) contains the MSBuild target files used to build Stride itself.
+## Design
 
-Since 3.1, we switched from our custom build system to the new csproj system with one nuget package per assembly.
+Stride uses *Content-addressable storage* to store the data generated by the compilation. The main concept is that the actual name of each generated file is the hash of the file. So if, after a change, the resulting content built from the asset is different, then the file name will be different. An index map file contains the mapping between the content *URL* and the actual hash of the corresponding file. Parameters of each compilation commands are also hashed and stored in this database, so if a command is ran again with the same parameters, the build engine can easily recover the hashes of the corresponding generated files.
 
-We use `TargetFrameworks` to properly compile the different platforms using a single project (Android, iOS, etc...).
+### Build Engine
 
-Also, we use `RuntimeIdentifiers` to select graphics platform. [MSBuild.Sdk.Extras](https://github.com/onovotny/MSBuildSdkExtras) is used to properly build NuGet packages with multiple `RuntimeIdentifiers` (not supported out of the box).
+The build engine is the part of the infrastructure that transforms data from the **assets** into actual **content** and save it to the database. It was originally designed to build content from input similar to a makefile. (eg. "compile all files in `MyModels/*.fbx` into Stride models). It has then been changed to work with individual assets when the asset layer has been implemented. Due to this legacy, this library is still not perfectly suited or optimal to build assets in an efficient way (dependencies of build steps, management of a queue for live-compiling in the Game Studio, etc.).
 
-### Limitations
+#### Builder
 
-* Dependencies are per `TargetFramework` and can't be done per `RuntimeIdentifier` (tracked in [NuGet#1660](https://github.com/NuGet/Home/issues/1660)).
-* FastUpToDate check doesn't work with multiple `TargetFrameworks` (tracked in [project-system#2487](https://github.com/dotnet/project-system/issues/2487)).
+The `Builder` class is the entry point of the build engine. A `Builder` will spawn a given number of threads, each one running a `Microthread` scheduler (see `RunUntilEnd` method).
 
-## NuGet resolver
+#### Build Steps
 
-Since we want to package tools (i.e. GameStudio, ConnectionRouter, CompilerApp) with a package that contains only the executable with proper dependencies to other NuGet runtime packages, we use NuGet API to resolve assemblies at runtime.
+The `Builder` takes a root `BuildStep` as input. We currently have two types of `BuildStep`s:
+* A `ListBuildStep` contains a sequence of `BuildStep` (Formerly we had an additional parent class called `EnumerableBuildStep`, but it has been merged into `ListBuildStep`). A `ListBuildStep` will schedule all the build steps it contains at the same time, to be run in parallel. Formerly we had a synchronization mechanism using a special `WaitBuildStep` but it has been removed. We now use `PrerequisiteSteps` with `LinkBuildSteps` to manage dependencies.
+* A `CommandBuildStep` contains a single `Command` to run, which does actual work to compile asset.
 
-The code responsible for this is located in [Stride.NuGetResolver](../sources/shared/Stride.NuGetResolver).
+> **TODO:** Currently, when compiling a graph of build steps, we need to have all steps to compile in the root `ListBuildStep`. More especially, if we have a `ListBuildStep` container in which we want to put a step A that depends on a step B and C, we need to put A, B, C in the `ListBuildStep` container. This is cumbersome and error-prone. What we would like to do is to rely only on the `PrerequisiteSteps` of a given step to find what we have to compile. If we do so, we wouldn't need to return a `ListBuildStep` in `AssetCompilerResult`, but just the final build step for the asset, the graph of dependent build steps being described by recursive `PrerequisiteSteps`. The `ListBuildStep` container could be removed. We would still need to have lists of build steps when we compile multiple asset (eg. when compiling the full game), but it would be nothing that the build engine should be aware of.
 
-Later, we might want to take advantage of .NET Core dependency resolving to do that natively. Also, we might want to use actual project information/dependencies to resolve to different runtime assemblies and better support plugins.
+#### Commands
 
-## Versioning
+Most command inherits from `IndexFileCommand`, which automatically register the output of the command into the command context.
 
-Stride is versioned using `SharedAssemblyInfo.cs`.
-For example, assuming version `4.1.3.135+gfa0f5cc4`:
-- `4.1` is the Stride major and minor version, as they are grouped in the launcher. Versions inside this group shouldn't have breaking changes
-- `3` is the asset version. This can be bumped if asset files require some upgrade.
-- `135` is the git height (number of commits since `4.1.3` is set), computed automatically when building packages.
-  Note: when building packages locally, this will typically be 1. This is the reason why the asset version needs to be bumped when asset changes to keep things ordered (otherwise the git height version `1` will always be lower than official version).
-- `+gfa0f5cc4` means git commit `fa0f5cc4`
+Basically, at the beginning of the command (in the `PreCommand` method), a `BuildTransaction` object is created. This transaction contains a subset of the database of objects that have been already compiled, provided by the `ICommandContext.GetOutputObjectsGroups()`. In term of implementation, this method returns all the objects that where written by prerequisite build steps, and all the objects that are already written in any of the parent `ListBuildStep`s, recursively. The objects coming from the parent `ListBuildStep` are a legacy of when we were using `WaitBuildStep` to synchronize the build steps. This hopefully should be implemented differently, relying only on prerequisite (since no synchronization can happen in the `ListBuildStep itself, everything is run in parallel).
 
-## Assembly processor
+> **TODO:** Rewrite how OutputObjects are transfered from `BuildStep`s to other `BuildStep`s. Only the output from prerequisite `BuildStep` should be transfered. A lot of legacy makes this code very convoluted and hard to maintain.
 
-Assembly processor is run by both Game and Stride targets.
+The `BuildTransaction` created during this step is mounted as a *Microthread-local database*, which is accessible only from the current microthread (which is basically the current command).
 
-It performs various transforms to the compiled assemblies:
-* Generate [DataSerializer](../sources/common/core/Stride.Core/Serialization/DataSerializer.cs) serialization code (and merge it back in assembly using IL-Repack)
-* Generate [UpdateEngine](../sources/engine/Stride.Engine/Updater/UpdateEngine.cs) code
-* Scan for types or attributes with `[ScanAssembly]` to quickly enumerate them without needing `Assembly.GetTypes()`
-* Optimize calls to [Stride.Core.Utilities](../sources/common/core/Stride.Core/Utilities.cs)
-* Automatically call methods tagged with [ModuleInitializer](../sources/common/core/Stride.Core/ModuleInitializerAttribute.cs)
-* Cache lambdas and various other code generation related to [Dispatcher](../sources/common/core/Stride.Core/Threading/Dispatcher.cs)
-* A few other internal tasks
+At the end of the command (in the `PostCommand` method), every object that has been written in the database by the command are extracted from the `BuildTransaction` and registered to the current `ICommandContext` (which is how the `ICommandContext` can "flow" objects from one command to the other.
 
-For performance reasons, it is run as a MSBuild Task (avoid reload/JIT-ing). If you wish to make it run the executable directly, set `StrideAssemblyProcessorDev` to `true`.
+It's important to keep in mind that objects accessible in a given command (in the `DoCommandOverride`) using a `ContentManager` are those provided during the `PreCommand` step, and therefore it is important that dependencies between commands (what other commmands a command needs to be completed to start) are properly set.
 
-## Dependencies
+### Compilers
 
-We want an easy mechanism to attach some files to copy alongside a referenced .dll or .exe, including content and native libraries.
+Compilers are classes that generate a set of `BuildStep`s to compile a given `Asset` in a specific context. This list could grow in the future if we have other needs, but the current different contexts are:
+- compiling the asset for the game
+- compiling the asset for the scene editor
+- compiling the asset to display in the preview
+- compiling the asset to generate a thumbnail
 
-As a result, `<StrideContent>` and `<StrideNativeLib>` item types were added.
+#### IAssetCompiler
 
-When a project declare them, they will be saved alongside the assembly with extension `.ssdeps`, to instruct referencing projects what needs to be copied.
+This is the base interface for compiler. The entry point is the `Prepare` method, which takes an `AssetItem` and returns a `AssetCompilerResult`, which is a mix of a `LoggerResult` and a  `ListBuildStep`. Usually there are two implementations per asset types, one to compile asset for the game and one to compile asset for its thumbnails. Some asset types such as animations might have an additional implementation for the preview.
 
-Also, for the specific case of `<StrideNativeLib>`, we automatically copy them in appropriate folders and link them if necessary.
+Each implementation of `IAssetCompiler` must have the `AssetCompilerAttribute` attached to the class, in order to be registered (compilers are registered via the `AssetCompilerRegistry`.
 
-Note: we don't apply them transitively yet (project output won't contains the `.ssdeps` file anymore so it is mostly useful to reference from executables/apps directly)
+> **TODO:** The `AssetCompilerRegistry` could be merged into the `AssetRegistry` to have a single location where asset-related types and meta-information are registered.
 
-## Native
+Each compiler provides a set of methods to help discover the dependencies between assets and compilers. They will be covered later in this document.
 
-By adding a reference to `Stride.Native.targets`, it is easy to build some C/C++ files that will be compiled on all platforms and automatically added to the `.ssdeps` file.
+#### ICompilationContext
 
-### Limitations
+> Not to be mistaken with `CompilerContext` and `AssetCompilerContext`.
 
-It seems that using those optimization don't work well with shadow copying and [probing privatePath](https://msdn.microsoft.com/en-us/library/823z9h8w(v=vs.110).aspx). This forces us to copy the `Direct3D11` specific assemblies to the top level `Windows` folder at startup of some tools. This is little bit unfortunate as it seems to disturb the MSBuild assembly searching (happens before `$(AssemblySearchPaths)`). As a result, inside Stride solution it is necessary to explicitely add `<ProjectReference>` to the graphics specific assemblies otherwise wrong ones might be picked up.
+Contexts of compilation are defined by *types*, which allow to use inheritance mechanism to fallback on a default compiler when there is no specific compiler for a given context. Each compilation context type must implement `ICompilationContext`. Currently we have:
 
-This will require further investigation to avoid this copying at all.
+* `AssetCompilationContext` is the context used when we compile an asset for the runtime (ie. the game).
+* `EditorGameCompilationContext` is the context used when we compile an asset for the scene editor, which is a specific runtime. Therefore, it inherits from `AssetCompilationContext`.
+* `PreviewCompilationContext` is the context used when we compile an asset for the preview, which is a specific runtime. Therefore, it inherits from `AssetCompilationContext`.
+* `ThumbnailCompilationContext` is the context used when we compile an asset to generate a thumbnail. Generally, for thumbnails, we compile one or several assets for the runtime, and use additional steps to generate the thumbnail with the `ThumbnailCompilationContext` (see below).
+
+> **TODO:** Currently thumbnail compilation is in a poor state. In `ThumbnailListCompiler.Compile`, we first generate the steps to compile the asset in `PreviewCompilationContext`, then generate the steps to compile the asset in `ThumbnailCompilationContext`, and finally we like the first with the latter. Dependencies from thumbnail compilers (which load a scene and take screenshots) to the runtime compiler (which compile the asset) is **not** expressed at all. It just works now because in all current cases, the `PreviewCompilationContext` does what we need for thumbnails (for example, the `AnimationAssetPreviewCompiler` adds the preview model to the normal compilation of the animation, which is needed for both preview and thumbnail).
+
+### Dependency managers
+
+We currently have two mechanisms that handle dependencies.
+
+> **TODO:** Merge the `AssetDependencyManager` and the `BuildDependencyManager` together into a single dependency manager object. There is a lot of redundancy between both, one rely on the other, some code is duplicated. See `XK-4862`
+
+#### AssetDependencyManager
+
+The `AssetDependencyManager` was the first implementation of an mechanism to manage dependencies between assets. It works independently of the build, which is one of the main issue it had and the reason why we started to develop a new infrastructure.
+
+It is based essentially on visiting assets with a `DataVisitorBase` to find references to other assets. There are two ways of referencing an asset:
+
+- Having a property whose type is an implementation of `IReference`. More explicitely the only case we have currently is `AssetReference`. This type contains an `AssetId` and a `Location` corresponding to the referenced asset.
+- Having a property whose type correspond to a *Content* type, ie. a type registered as being the compiled version of an asset type (for example, `Texture` is the Content type of `TextureAsset`).
+
+The problem of that design was that once all the references are collected, there is no way to know of the referenced assets are actually consumed, which could be one of the three following way:
+
+- the referenced asset is not needed to compile this asset, but it's needed at runtime to use the compiled content (eg. Models need Materials, who need Textures. But you can compile Models, Materials and Textures independently).
+- the referenced asset needs to be compiled before this asset, and the compiler of this asset needs to load the corresponding content generated from the referenced asset (eg. A prefab model, which aggregates multiple models together, needs the compiled version of each model it's referencing to be able to merge them).
+- the referenced asset is read when compiling this asset because it depends on some of its parameter, but the referenced asset itself doesn't need to be compiled first (eg. Navigation Meshes need to read the scene asset they are related to in order to gather static colliders it contains, but they don't need to compile the scene itself).
+
+#### BuildDependencyManager
+
+The `BuildDependencyManager` has been introduced recently to solve the problems of the `AssetDependencyManager`. It is currently not complete, and the ultimate goal is to merge it totally with the `AssetDependencyManager`.
+
+The approach is a bit different. Rather than extracting dependencies from the asset itself, we extract them from the compilers of the assets, which are better suited to know what they exactly need to compile the asset and what will be needed to load the asset at runtime.
+
+But one asset type can have multiple compilers associated to it (for the game, for the thumbnail, for the preview...). So the `BuildDependencyManager` works in the context of a specific compiler.
+
+Currently there is one `BuildDependencyManager` for each type of compiler.
+
+> **TODO:** Have a single global instance of `BuildDependencyManager` that contains all types of dependencies for all context of compilers. For example, we have thumbnail compilers that requires *game* version of assets, which means that the `BuildDependencyManager` for thumbnails will also contain a large part of the `BuildDependencyManager` to build the game. Merging everything into a single graph would reduce redundancy and risk to trigger the same operation multiple times simultaneously.
+
+#### AssetDependenciesCompiler
+
+The `AssetDependenciesCompiler` is the object that computes the dependencies with the `BuildDependencyManager`, and then generates the build steps for a given asset, including the runtime dependencies. It's the main entry point of compilation for the CompilerApp, the scene editor, and the preview. Thumbnails also use it, via the `ThumbnailListCompiler` class.
+
+> **TODO:** This class should be removed, and its content moved into the `BuildDependencyManager` class. By doing so, it should be possible to make `BuildAssetNode` and `BuildAssetLink` internal - those classes are just the data of the dependency graph, they should not be exposed publicly. To do that, a method to retrieve the dependencies in a given context must be implemented in `BuildDependencyManager` in order to fix the usage of `BuildAssetNode` in `EditorContentLoader`.
+
+### In the Game Studio
+
+The Game Studio compiles assets in various versions all the time. It has some specific way of managing database and content depending on the context.
+
+Remark: the Game Studio never saves index file on the disk, it keeps the url -> hash mapping in memory, always.
+
+#### Databases
+
+Before accessing content to load, a Microthread-local database must be mounted. Depending on the context, it can be a database containing a scene and its dependencies (scene editor), the assets needed to create a thumbnail, an asset to display in the preview...
+
+For the scene editor, this is handled by the `GameStudioDatabase` class. Thumbnails and preview also handle database mounting internally (in `ThumbnailGenerator` for example).
+
+> **TODO:** See if it could be possible/useful to wrap all database-mounting in the Game Studio into the GameStudioDatabase class.
+
+#### Builder service
+
+All compilations that occur in the Game Studio is done through the `GameStudioBuilderService`. This class creates an instance of `Builder`, a `DynamicBuilder` which allows to feed the Builder with build steps at any time. Having a single builder for the whole Game Studio allows to control the number of threads and concurrent tasks more easily.
+
+The `DynamicBuilder` class simply creates a thread to run the Builder on, and set a special build step, `DynamicBuildStep`, as root step of this builder. This step is permanently waiting for other child build step to be posted, and execute them.
+
+> **TODO:** Currently the dynamic build step waits arbitratly with the `CompleteOneBuildStep` method when more than 8 assets compiling. This is a poor design because if the 8 assets are for example prefabs who contains a lot of models, materials, textures, it will block until all are done, although we could complete the thumbnails of these models/materials/textures individually. Ideally, this `await` should be removed, and a way to make sure thumbnails of assets which are compiled are created as soon as possible should be implemented.
+
+The builder service uses `AssetBuildUnit`s as unit of compilation. A build unit corresponds to a single asset, and encapsulates the compiler and the generated build step of this asset.
+
+#### EditorContentLoader
+
+The scene editor needs a special behavior in term of asset loading. The main issue is that any type of asset can be modified by the user (for example a texture), and then need to be reloaded. Stride use the `ContentManager` to handle reference counting of loaded assets. With a few exception (Materials, maybe Textures), it does not support hot-swapping an asset. Therefore, when an asset needs to be reloaded, we actually need to unload and reload the *first-referencer* of this asset.
+
+The *first-referencer* is the first asset referenced by an entity, that contains a way (in term of reference) to the asset to reload. For example, in case of a texture, we will have to reload all models that use materials that use the texture to reload.
+
+This is done by the `EditorContentLoader` class. At initialization, this class collects all *first-referencer* assets and build them. Each time an asset is built, it is then loaded into the scene editor game, and the references (from the entity to the asset) are updated. This means that this class needs to track all first-referencers on its own and update them. This is done specifically by the `LoaderReferenceManager` object. The reference are collected from the `GameEditorChangePropagator`, an object that takes the responsibility to push synchronization of changes between the assets and the game (for all properties, including non-references). There is one instance of it per entity. When a property of an entity that contains a reference to an asset (a *first-referencer*) is modified, the propagator will trigger the work to compile and update the entity. In case of a referenced asset modified by the user, `EditorContentLoader.AssetPropertiesChanged` takes the responsibility to gather, build, unload and reload what needs to be reloaded.
+
+## Additional Todos
+
+> **TODO:** `GetInputFiles` exists both in `Command` and in `IAssetCompiler`. It has the same signature in both case, so it's returning information using `ObjectUrl` and `UrlType` in the compiler, where we are trying to describe dependency. That signature should be changed, so it returns information using `BuildDependencyType` and `AssetCompilationContext`, just like the GetInputTypes method. Also, the method is passed to the command via the `InputFilesGetter` which is not very nice and has to be done manually (super error-prone, we had multiple commands that were missing it!). An automated way should be provided.
+
+> **TODO:** The current design of the build steps and list build steps is a *tree*. For this reason, same build steps are often generated multiple times and appears in multiple trees. It could be possible to cache and share the build step if the structure was a *graph* rather than a *tree*. Do to that, the `Parent` property of build steps should be removed. The main difficulty is that the way output objects of build steps flow between steps has to be rewritten.
 
-## Asset Compiler
 
-Both Games and Stride unit tests are running the asset compiler as part of the build process to create assets.

en/contributors/engine/building-source-linux.md

@@ -1,12 +1,9 @@
 # Building the source to Stride engine
 
-??
-WIP: make a page that is refernced by the readme.md on Stride:
-https://github.com/stride3d/stride
-
-
-COPIED from readme.mdf.............
+WIP.....
+MAKE THE LINUX VERSION OF BUILDING THE ENGINE
 
+COPY of windows stuff below.....
 ## Prerequisites
 
 1. **Latest** [Git](https://git-scm.com/downloads) **with Large File Support** selected in the setup on the components dialog.
@@ -21,21 +18,16 @@ COPIED from readme.mdf.............
     - Optional (to target iOS/Android): `Mobile development with .NET` and `Android SDK setup (API level 27)` individual component, then in Visual Studio go to `Tools > Android > Android SDK Manager` and install `NDK` (version 19+) from `Tools` tab.
 4. **[FBX SDK 2019.0 VS2015](https://www.autodesk.com/developer-network/platform-technologies/fbx-sdk-2019-0)**
 
-## Build Stride
+## Build Stride .....
 
 1. Open a command prompt, point it to a directory and clone Stride to it: `git clone https://github.com/stride3d/stride.git`
     - Note that when you use GitHub -> Code -> Download ZIP, this doesn't support Large File Support ```lfs```, make sure you use the command above or that your git client does it for you
 2. Open `<StrideDir>\build\Stride.sln` with Visual Studio 2022 and build `Stride.GameStudio` in the 60-Editor solution folder (it should be the default startup project) or run it from VS's toolbar.
     - Optionally, open and build `Stride.Android.sln`, `Stride.iOS.sln`, etc.
 
-## Build Stride without Visual Studio
 
-1. Install [Visual Studio Build Tools](https://aka.ms/vs/17/release/vs_BuildTools.exe) with the same prerequisites listed above
-2. Add MSBuild's directory to your system's *PATH* (ex: `C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\MSBuild\Current\Bin`)
-3. Open a command prompt, point it to a directory and clone Stride to it: `git lfs clone https://github.com/stride3d/stride.git`
-4. Navigate to `/Build` with the command prompt, input `msbuild /t:Restore Stride.sln` then `compile.bat`
 
-If building failed:
+### If building failed
 * If you skipped one of the `Prerequisites` thinking that you already have the latest version, update to the latest anyway just to be sure.
 * Visual Studio might have issues properly building if an anterior version is present alongside 2022. If you want to keep those version make sure that they are up to date and that you are building Stride through VS 2022.
 * Your system's *PATH* should not contain older versions of MSBuild (ex: `...\Microsoft Visual Studio\2019\BuildTools\MSBuild\Current\Bin` should be removed)
@@ -43,4 +35,6 @@ If building failed:
 * Make sure that Git, Git LFS and Visual Studio can access the internet.
 * Close VS, clear the nuget cache (in your cmd `dotnet nuget locals all --clear`), delete the hidden `.vs` folder inside `\build` and the files inside `bin\packages`, kill any msbuild and other vs processes, build the whole solution then build and run GameStudio.
 
-Do note that test solutions might fail but it should not prevent you from building `Stride.GameStudio`.
+Do note that test solutions might fail but it should not prevent you from building `Stride.GameStudio`.
+
+

en/contributors/engine/building-source-windows-other-ide.md

@@ -0,0 +1,43 @@
+
+## Build Stride without Visual Studio
+
+1. Install [Visual Studio Build Tools](https://aka.ms/vs/17/release/vs_BuildTools.exe) with the same prerequisites listed [here](building-source-windows.md)
+2. Add MSBuild's directory to your system's *PATH* (ex: `C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\MSBuild\Current\Bin`)
+3. Open a command prompt, point it to a directory and clone Stride to it: `git lfs clone https://github.com/stride3d/stride.git`
+4. Navigate to `/Build` with the command prompt, input `msbuild /t:Restore Stride.sln` then `compile.bat`
+
+
+
+## Build Stride with Rider
+While the engine's build system is almost ready to run from Rider there are still a couple of kinks to iron out before we're there, in the mean time here's a short tutorial to help users of this IDE out.
+
+- As mentioned above, building directly from Rider is not possible yet, but we can invoke the command line to do it for us ...
+- Open Stride.sln with Rider.
+- Select the configuration dropdown, go to the bottom of the dropdown and select `Edit Configurations ...`
+
+  ![image](https://github.com/stride3d/stride/assets/5742236/20a43b8f-c32d-42ae-8c59-add8440b4a3a)
+- Press the `+` on the upper left of this new window, then `.NET Executable`
+
+![image](https://github.com/stride3d/stride/assets/5742236/a15b73a1-4a7e-462a-8814-2cad73b6b1d2)
+- Give it a name, something like `Compile then open Editor`
+- Fill the `Exe path` with the game studio's, if you don't have the game studio check that step #1 was successful
+
+![image](https://github.com/stride3d/stride/assets/5742236/61fa7f27-8885-418e-926e-df0209aa168a)
+
+- Remove any of the `Before Launch` steps
+- Add a new `Run External tool` step
+
+![image](https://github.com/stride3d/stride/assets/5742236/bfe266a4-fec4-49e3-bbc4-9da5977d5177)
+
+- Set `Program` to `Compile.bat`
+
+![image](https://github.com/stride3d/stride/assets/5742236/294779ae-c362-40a7-bcb3-447de7505781)
+
+- Press OK, press OK, press Apply, press OK and select this new configuration in the configuration dropdown
+
+![image](https://github.com/stride3d/stride/assets/5742236/2877e023-feb1-43bf-924d-f01a9a6e875a)
+
+### Hotreload
+To hotreload your changes you either have to pause and continue the program or press on the hotreload button at the top of the text editor when/if it shows up.
+
+![image](https://user-images.githubusercontent.com/5742236/147461531-05af59f7-fedf-44a2-b4ee-d1aa25502210.png)

en/contributors/engine/building-source-windows.md

@@ -1,41 +1,29 @@
 # Building the source to Stride engine
 
-??
-WIP: make a page that is refernced by the readme.md on Stride:
-https://github.com/stride3d/stride
-
-
-COPIED from readme.mdf.............
-
 ## Prerequisites
 
 1. **Latest** [Git](https://git-scm.com/downloads) **with Large File Support** selected in the setup on the components dialog.
 2. [DotNet SDK 6.0](https://dotnet.microsoft.com/en-us/download/dotnet/6.0)
-    - Run `dotnet --info` in a console or powershell window to see which versions you have installed
+   - Run `dotnet --info` in a console or powershell window to see which versions you have installed
 3. [Visual Studio 2022](https://www.visualstudio.com/downloads/) with the following workloads:
-    - `.NET desktop development` with `.NET Framework 4.7.2 targeting pack`
-    - `Desktop development with C++` with
-        - `Windows 10 SDK (10.0.18362.0)` (it's currently enabled by default but it might change)
-        - `MSVC v143 - VS2022 C++ x64/x86 build tools (v14.30)` or later version (should be enabled by default)
-        - `C++/CLI support for v143 build tools (v14.30)` or later version **(not enabled by default)**
-    - Optional (to target iOS/Android): `Mobile development with .NET` and `Android SDK setup (API level 27)` individual component, then in Visual Studio go to `Tools > Android > Android SDK Manager` and install `NDK` (version 19+) from `Tools` tab.
+   - `.NET desktop development` with `.NET Framework 4.7.2 targeting pack`
+   - `Desktop development with C++` with
+      - `Windows 10 SDK (10.0.18362.0)` (it's currently enabled by default but it might change)
+      - `MSVC v143 - VS2022 C++ x64/x86 build tools (v14.30)` or later version (should be enabled by default)
+      - `C++/CLI support for v143 build tools (v14.30)` or later version **(not enabled by default)**
+   - Optional (to target iOS/Android): `Mobile development with .NET` and `Android SDK setup (API level 27)` individual component, then in Visual Studio go to `Tools > Android > Android SDK Manager` and install `NDK` (version 19+) from `Tools` tab.
 4. **[FBX SDK 2019.0 VS2015](https://www.autodesk.com/developer-network/platform-technologies/fbx-sdk-2019-0)**
 
-## Build Stride
+## Build Stride with Visual studio 2022
+Here are the steps to build Stride with Visual Studio. If you do not have or want to use Visual Studio, see [building with other IDEs](building-source-windows-other-ide.md)
 
 1. Open a command prompt, point it to a directory and clone Stride to it: `git clone https://github.com/stride3d/stride.git`
-    - Note that when you use GitHub -> Code -> Download ZIP, this doesn't support Large File Support ```lfs```, make sure you use the command above or that your git client does it for you
+   - Note that when you use GitHub -> Code -> Download ZIP, this doesn't support Large File Support ```lfs```, make sure you use the command above or that your git client does it for you
 2. Open `<StrideDir>\build\Stride.sln` with Visual Studio 2022 and build `Stride.GameStudio` in the 60-Editor solution folder (it should be the default startup project) or run it from VS's toolbar.
-    - Optionally, open and build `Stride.Android.sln`, `Stride.iOS.sln`, etc.
-
-## Build Stride without Visual Studio
+   - Optionally, open and build `Stride.Android.sln`, `Stride.iOS.sln`, etc.
 
-1. Install [Visual Studio Build Tools](https://aka.ms/vs/17/release/vs_BuildTools.exe) with the same prerequisites listed above
-2. Add MSBuild's directory to your system's *PATH* (ex: `C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\MSBuild\Current\Bin`)
-3. Open a command prompt, point it to a directory and clone Stride to it: `git lfs clone https://github.com/stride3d/stride.git`
-4. Navigate to `/Build` with the command prompt, input `msbuild /t:Restore Stride.sln` then `compile.bat`
 
-If building failed:
+### If building failed
 * If you skipped one of the `Prerequisites` thinking that you already have the latest version, update to the latest anyway just to be sure.
 * Visual Studio might have issues properly building if an anterior version is present alongside 2022. If you want to keep those version make sure that they are up to date and that you are building Stride through VS 2022.
 * Your system's *PATH* should not contain older versions of MSBuild (ex: `...\Microsoft Visual Studio\2019\BuildTools\MSBuild\Current\Bin` should be removed)
@@ -43,4 +31,10 @@ If building failed:
 * Make sure that Git, Git LFS and Visual Studio can access the internet.
 * Close VS, clear the nuget cache (in your cmd `dotnet nuget locals all --clear`), delete the hidden `.vs` folder inside `\build` and the files inside `bin\packages`, kill any msbuild and other vs processes, build the whole solution then build and run GameStudio.
 
-Do note that test solutions might fail but it should not prevent you from building `Stride.GameStudio`.
+Do note that test solutions might fail but it should not prevent you from building `Stride.GameStudio`.
+
+## Other IDEs
+You are not  required to use Visual Studio to build the Stride engine with Visual Studio. You can also build entirely from command line or other IDE's such as [Rideror Visual Studio Code](building-source-windows-other-ide.md) 
+
+
+

en/contributors/engine/contribute-engine.md

@@ -1 +1,20 @@
-# Contribute to Stride engine
+# Contributing to Stride
+
+
+## Check our issue tracker
+Please take a look at our [issue tracker](https://github.com/stride3d/stride/issues).
+
+If you are just getting started with Stride, issues marked with ['good first issue'](https://github.com/stride3d/stride/labels/good%20first%20issue) can be a good entry point.
+
+## Notify users
+Once you start working leave a message on the appropriate issue or create one if none exists to:
+* make sure that no one else is working on that same issue
+* lay out your plans and discuss it with collaborators and users to make sure it is properly architectured and would fit well in the project
+
+## Coding style
+Please use and follow Stride's `.editorconfig` when making changes to files.
+
+## Submitting Changes
+* Push your changes to a specific branch in your fork.
+* Use that branch to create and fill out a pull request to the official repository.
+* After creating that pull request and if it's your first time contributing a [CLA assistant](https://cla-assistant.io/) will ask you to sign the [.NET Founddation Contribution License Agreement](https://dotnetfoundation.org/docs/default-source/default-document-library/contribution-license-agreement.pdf?sfvrsn=40626e42_3).

en/contributors/engine/index.md

@@ -0,0 +1,25 @@
+# Contribute to Stride engine
+Here you can find various pages describing building the source locally for different systems. You can also find information about stride's architecture.
+
+# [Contributing to the engine](contribute-engine.md)
+Want to help out fixing bugs or making new features? Check out how you can do so.
+
+# [Building on Windows](building-source-windows.md)
+Building and running the Stride engine locally on Windows using [Visual Studio](building-source-windows.md) or other [IDEs](building-source-windows-other-ide.md)
+
+# [Building on Linux](building-source-linux.md)
+Building the Stride engine locally on Linux
+
+# [Localization](localization.md)
+A graphical overview of Stride's Assemblies, NameSpaces and Core methods 
+
+
+# Architecture
+## [Graphics API](graphics-api.md)
+Stride support different graphics APIs. Here you can read more about them.
+
+## [Dependency graph](dependency-graph.md)
+A graphical overview of Stride's Assemblies, NameSpaces and Core methods
+
+## [Asset introspection](asset-introspection.md)
+How and why the Stride engine uses asset introspection

en/contributors/toc.yml

@@ -4,16 +4,18 @@
   href: donate.md
 - name: 🛠️ Stride engine
   expanded: false
-  href: engine/contribute-engine.md
+  href: engine/index.md
   items:
+  - name: Contributing to Stride
+    href: engine/contribute-engine.md
   - name: Building source on Windows
     href: engine/building-source-windows.md
   - name: Building source on Linux
     href: engine/building-source-linux.md
   - name: Build pipeline
     href: engine/build-pipeline.md
-  - name: Build details
-    href: engine/build-details.md
+  - name: Build architecture
+    href: engine/build-architecture.md
   - name: Localization
     href: engine/localization.md
   - name: Asset introspection