Moving wiki topcs and Stride repo docs

en/contributors/engine/asset-introspection.md

@@ -0,0 +1,253 @@
+# Asset, introspection and prefab
+
+https://github.com/stride3d/stride/edit/master/docs/technical/asset-introspection.md
+WIP: COPIED from link above
+
+
+## Assets
+
+*NOTE: Please read the Terminology section of the [Build Pipeline](build-pipeline.md) documentation first*
+
+### Design notes
+
+Assets contains various properties describing how a given **Content** should be generated. Some constraints are defined by design:
+
+* All types that can be referenced directly or indirectly by an asset must be serializable. This means that it should have the `[DataContract]` attribute, and the type of all its members must have it too.
+* Members that cannot or should not be serialized can have the `[DataMemberIgnore]` attributes
+* Other members can have additional metadata regarding serialization by using the `[DataMember]` attributes. There is also a large list of other attributes that can be used to customize serialization and presentation of those members.
+* Arrays are not properly supported
+* Any type of ordered collection is supported, but unordered collection (sets, bags) are not.
+* Dictionaries are supported as long as the type of the key is a primitive type (see below for the definition of primitive type)
+* When an asset references another asset, the member or item shouldn't use the type of the target asset, but the corresponding **Content**. For example, the ``MaterialAsset`` needs to reference a texture, it will have a ``Texture`` member and not a `TextureAsset`.
+* It is possible to use the `AssetReference` type to represent a reference to any type of asset.
+* Nullable value types are not properly supported
+* An asset can reference multiple times the same objects through various members/items, but one of the member/item must be the "real instance", and the others must be defined as "object references", see below for more details.
+
+### Yaml metadata
+
+When assets are serialized to/deserialized from Yaml files, dictionaries of metadata is created or consumed in the process. There is one dictionary per type of metadata. The dictionary maps a property path (using `YamlAssetPath`) to a value, and is stored in a instance of `YamlAssetMetadata`. These dictionary are exchanged between the low-level Yaml serialization layer and the asset-aware layer via the `AssetItem.Metadata` property. This property is not synchronized all the time, it is just consumed after deserialization, to apply metadata to the asset, and generated just before serialization, to allow the metadata to be consumed during serialization.
+
+### Overrides
+
+The prefab and archetype system introduces the possibility to override properties of an asset. Some nodes of the property tree of an asset might have a *base*. (usually all of them in case of archetype, and some specific entities that are prefab instances in case of scene). How nodes are connected together is explained later on this documentation, but from a serialization point of view, any property that is overridden will have associated yaml metadata. Then we usa a custom serializer backend, `AssetObjectSerializerBackend`, that will append a star symbol `*` at the end of the property name in Yaml.
+
+### Collections
+
+Collections need special handling to properly support override. An item of a collection that is inherited from a base can be either modified (have another value) or deleted. Also, new items that are not present in the base can have been added. This is problematic in the case of ordered collection such as `List` because adding/deleting items changes the indices of item.
+
+To solve all these issues, we introduce an object called `CollectionItemIdentifiers`. There is one instance of this object per collection that supports override. This instance is created or retrieved using the `CollectionItemIdHelper`. They are stored using `ShadowObject`, which maintain weak references from the collection to the `CollectionItemIdentifiers`. This means that it is currently not possible to have overridable items in collection that are `struct`.
+
+A collection that can't or shouldn't have overridable items should have the `NonIdentifiableCollectionItemsAttribute`.
+
+The `CollectionItemIdentifiers` associates an item of the collection to a unique id. It also keep track of deleted items, to be able to tell, when an item in an instance collection is missing comparing to the base collection, if it's because it has been removed purposely from the instance collection, or if it's because it has been added after the instance collection creation to the base collection.
+
+Items, in the `CollectionItemIdentifiers`, are represented by their key (for dictionaries) or index (list). This means that any collection operation (add, remove...) must call the proper method of this class to properly update this collection. This is automatically done as long as the collection is updated through Quantum (see below).
+
+In term of inheritance and override, the item id is what connect a given item of the base to a given item of the instance. This means that items can be re-ordered, and other items can be inserted, without loosing or messing the connection between base and instances. Also, for dictionary, keys can be renamed in the instance.
+
+At serialization, the item id is written in front of each item (so collections are transformed to dictionaries of [`ItemId`, `TValue`] and dictionary are transformed to dictionaries of [`KeyWithId<TKey>`,` TValue`], with `KeyWithId` being equivalent to a Tuple).
+Here is an example of Yaml for a base collection and an instance collection:
+
+Base collection, with one id per item:
+```
+Strings:
+    309e0b5643c5a94caa799a5ea1480617: Hello
+    e09ec493d05e0446b75358f0e1c0fbdd: World
+    9550f04dcee1d24fa8a30e41eea71a94: Example
+    1da8adce3f0ce9449a9ed0e48cd32f20: BaseClass
+```
+Derived collection. The first item is overridden, the 4th is a new item (added), and the last one express that the `BaseClass` entry has been deleted in the derived instance.
+```
+Strings:
+    309e0b5643c5a94caa799a5ea1480617*: Hi
+    e09ec493d05e0446b75358f0e1c0fbdd: World
+    9550f04dcee1d24fa8a30e41eea71a94: Example
+    cfce75d38d66e24fae426d1f40aa4f8a*: Override
+    1da8adce3f0ce9449a9ed0e48cd32f20: ~(Deleted)
+```
+
+When two assets that are connected with a base relationship are loaded, it is then possible to reconcile them:
+* any item missing in the derived collection is re-added (so the `~(Deleted)` is need to purposely delete items)
+* any item existing in the derived collection that doesn't exist in the base collection and doesn't have the star `*` is removed
+* any item that exists in both collection but have a different value is overwritten with the value of the base collection
+* overridden items (with the star `*`) are untouched
+
+## Quantum
+
+In Stride, we use an introspection framework called *Quantum*.
+
+### Type descriptors
+
+The first layer used to introspect object is in `Stride.Core.Reflection`. This assembly contains type descriptors, which are basically objects abstracting the reflection infrastructure. It is currently using .NET reflection (`System.Reflection`) but could later be implemented in a more efficient way (using `Expression`, or IL code).
+
+The `TypeDescriptorFactory` allows to retrieve introspection information on any type. `ObjectDescriptor`s contains descriptor for members which allow to access them. Collections, dictionaries and arrays are also handled (NOTE: arrays are not fully supported in Quantum itself).
+
+This assembly also provides an `AttributeRegistry` which allows to attach `Attribute`s to any class or member externally.
+
+> **TODO:** make sure all locations where we read `Attribute`s are using the `AttributeRegistry` and not the default .NET methods, so we properly support externally attached attributes.
+
+### Node graphs
+
+In order to introspect object, we build graphs on top of each object, representing their members, and referencing the graphs of other objects they reference through members or collection.
+The classes handling theses graphs are in the `Stride.Core.Quantum` assembly.
+
+#### Node containers
+
+Nodes of the graphs are created into an instance of `NodeContainer`. Usually a single instance of `NodeContainer` is enough, but we have some scenarios where we use multiple ones: for example each instance of scene editor contains its own `NodeContainer` instance to build graphs of game-side objects, which are different from asset-side (ie. UI-side) objects, have a different lifespan, and require different metadata.
+
+In the GameStudio, the `NodeContainer` class has two derivations: the `AssetNodeContainer` class, which expands the primitive types to add Stride-specific types (such as `Vector3`, `Matrix`, `Guid`...). This class is inherited to a `SessionNodeContainer`, which additionally allows plugin to register their own primitive types and metadata.
+
+#### Node builders
+
+The `NodeContainer` contains an `INodeBuilder` member and provides a default implementation for it. So far we didn't had the need to make a custom implementation, since the structure of the graphs themselves is pretty stable.
+
+However, the `INodeBuilder` interface presents an `INodeFactory` member which we override. This factory allows to customize the nodes to be constructed.
+
+The `INodeBuilder` also contains a list of types to be considered as *primitive types*, which means that even if the type contains members or is a reference type, it will be, in term of graph, considered as a primitive value and won't be expanded.
+
+#### Nodes
+
+There are 3 types of nodes in Quantum:
+
+* `ObjectNode` are node corresponding to an object that is a reference type. They can contain members (properties, fields...), and items (collection).
+* `BoxedNode` are a special case of `ObjectNode` that handles `struct`. They are able to write back the value of the struct in other nodes that reference them
+* `MemberNode` are node corresponding to the members of an object. If the value of the member is a class or a struct, the member will also contain a reference to the corresponding `ObjectNode`.
+* `ObjectNode` that are representing a collection of class/struct items will also have a collection of reference to target nodes via the `ItemReferences` property.
+
+Each node has some methods that allow to manipulate the value it's wrapping. `Retrieve` returns the current value, `Update` changes it. Collections can be manipulated with the `Add` and `Remove` methods (and a single item can be modified also with `Update`).
+
+#### Events
+
+Each node presents events that can be registered to:
+* `PrepareChange` and `FinalizeChange` are raised at the very beginning and the very end of a change of the node value. These events are internal to Quantum.
+* `MemberNode`s have the `ValueChanging` and `ValueChanged` events that are raised when the value is being modified.
+* `ObjectNode` have `ItemChanging` and `ItemChanged` events that are raised when the wrapped object is a collection, and this collection is modified.
+
+The arguments of these events all inherits from `INodeChangeEventArgs`, which allows to share the handlers between collection changes and member changes.
+
+Finally, Quantum nodes are specialized for assets, where the implementation of the support of override and base is. These specialized classes also present `OverrideChanging` and `OverrideChanged` event to handle changes in the override state.
+
+## AssetPropertyGraph
+
+### Concept
+
+We use Quantum nodes mainly to represent and save the properties of an asset. The AssetPropertyGraph is a container of all the nodes related to an asset, and describes certain rules such as which node is an object reference, etc.
+
+### Asset references
+
+When an asset needs to reference another asset, it should never contains a member that is of the type of the referenced asset. Rather, the type of the member should be the type of the *Content* corresponding to the referenced asset.
+
+### Node listener
+
+A node listener is an object that can listen to changes in a graph of node (rather than an individual nodes). The base class is `GraphNodeChangeListener`, and this class must define a visitor that can visit the graph of nodes to register, and stop at the boundaries of that graph.
+
+### Object references
+
+In many scenarios of serialization (in YAML, but also in the property grid where objects are represented by a tree rather than a graph), we need a way to represent multiple referencers of the same object such a way that the object is actually expanded at one unique location, and shown/serialized as a reference to all other locations. We introduce the concept of **Object references** to solve this issue.
+
+By design, only objects implementing the `IIdentifiable` interface can be referenced from multiple locations from the same root object. But right now they can only be referenced from the same unique root object (usually an `Asset`). Later on we might support *cross-asset references* but this would require to change how we serialize them.
+
+There are two methods to implement to define if a node must be considered as an object reference or not:
+
+* one for members of an object: `IsMemberTargetObjectReference`
+* one for items of a collection: `IsTargetItemObjectReference`
+
+## Node presenters
+
+Node presenters are objects used to present the properties of an object to a view system, such as a property grid.
+They transform a graph of nodes to a tree of nodes, and contains metadata to be consumed by the view.
+The resulting tree is slightly different from the graph. When an object A contains a member that is an object B that contains a property C, the graph will look like this:
+
+`ObjectNode A --(members)--> MemberNode B --(target)--> ObjectNode B --(members)--> MemberNode C`
+
+the corresponding tree of node presenters will be:
+
+`RootNodePresenter A --> MemberNodePresenter B --> MemberNodePresenter C`
+
+There is also a `ItemNodePresenter` for collection. On the example above, if B is instead a collection that contains a single item C, the graph would be:
+
+`ObjectNode A --(members)--> MemberNode B --(target)--> ObjectNode B --(items)--> ObjectNode C`
+
+the corresponding tree of node presenters will be:
+
+`RootNodePresenter A --> ItemNodePresenter B --> MemberNodePresenter C`
+
+Node presenter are constructed by a `INodePresenterFactory` in which `INodePresenterUpdater` can be registered. A `INodePresenterUpdater` allows to attach metadata to nodes, and re-organize the hierarchy in case it want to be presented differently from the actual structures (by inserting nodes to create category, bypassing a class object to inline its members, etc.).
+`INodePresenterUpdater` have two methods to update node:
+
+* `void UpdateNode(INodePresenter node)` is called on **each** node, after its children have been created. But it's not guaranteed that its siblings, or the siblings of its parents, will be constructed.
+* `void FinalizeTree(INodePresenter root)` is called once, at the end of the creation of the tree, and only on the root. Here it's guaranteed that every node is constructed, but you have to visit manually the tree to find the node that you want to customize.
+
+Node presenters listens to changes in the graph node they are wrapping. In case of an update, the children of the modified node are discarded and reconstructed. `UpdateNode` is called again on all new children, and `FinalizeTree` is also called again at the end on the root of the tree. Therefore, you have to be aware that an updater can run multiple time on the same nodes/trees.
+
+Metadata can be attached to node presenters via the `NodePresenterBase.AttachedProperties` property containers. These metadata are exposed to the view models as described in the section below.
+
+Commands can also be attached to node presenters. A command does special actions on a node, in order to update it. Node presenter commands implements the `INodePresenterCommand` interface. A command is divided in three steps, in order to handle multi-selection:
+* `PreExecute` and `PostExecute` are run only once, for a selection of similar node presenters, before and after `Execute` respectively.
+* `Execute` is run once per selected node presenter.
+
+### Node view models
+
+The view models are created on top of node presenters. Each node presenter has a corresponding `NodeViewModel`. In case of multi-selection, a `NodeViewModel` can actually wrap a collection of node presenters, rather than a single one.
+
+Metadata (ie. attached properties) are also exposed from the node presenter to the view via the view model, assuming they are common to all wrapped node presenter, if not, it is possible to add a `PropertyCombinerMetadata` to the property key to define the rule to combine the metadata. The default behavior for combining is to set the value to `DifferentValues` (a special object representing different values) if the values are not equals.
+
+Commands are also exposed. They are added to the view model, combined depending on their `CombineMode` property. They are transformed into WPF commands by being wrapped into a `NodePresenterCommandWrapper`.
+
+All members, attached properties, and commands of node view models are exposed as `dynamic` properties, and can therefore be used in databinding.
+
+All node view models are contained in an instance of `GraphViewModel`. A `GraphViewModelService` is passed in this object that acts as a registry for the node presenter commands and updaters that are available during the construction of the tree.
+
+### Template selector
+
+In order to be presented to the property grid, a proper template must be selected for each NodeViewModel. The `TemplateProviderSelector` object picks the proper template by finding the first registered one that accept the given node. Templates are defined in various XAML resource dictionaries, the base one being `DefaultPropertyTemplateProviders.xaml`. There is a priority mechanism that uses an `OverrideRule` enum with four values: `All`, `Most`, `Some`, `None`. One template can also explicitly override the other with the `OverriddenProviderNames` collection. The algorithm that picks the best match is in the `CompareTo` method of `TemplateProviderBase`.
+
+There is actually 3 levels of templates for each property. `PropertyHeader` and `PropertyFooter` represent the section above and the section below the expander that contains the children properties. In the default implementation (`DefaultPropertyHeaderTemplate` and most of its specializations), the header presents the left part of the property (the name, sometimes a checkbox...), and use the third template category, `PropertyEditor`, for the right side of the property grid.
+
+## Bases
+
+The base-derived concept and the override are stored in specialized Quantum nodes that implements `IAssetNode`. Properties (as well are items of collections) are automatically overridden when `Update`/`Add`/`Remove` methods are called. Some methods are also provided to manually interact with overrides, but it should not be used directly by users of Quantum.
+
+### Node linker
+
+`GraphNodeLinker` is an object that link a given node to another node. It has two main usages: it links objects that are game-side in the scene editor to their counterpart asset-side, and they also link a node to its base if it has one.
+
+The `AssetToBaseNodeLinker` is used to do that. It is invoked at initialization, as well as each time a property changes. It has a `FindTarget` method and `FindTargetReference`, which basically resolve, when visiting the derived graph, which equivalent node of the base graph corresponds to it.
+
+This linker is run from the `AssetPropertyGraph` that can then call `SetBaseNode` to actually link the nodes together.
+
+### Reconciliation with base
+
+Each time a change occurs in an asset, all nodes that have the modified nodes as base will call `ReconcileWithBase`. This method visits the graph, starting from the modified properties, and "reconcile" the change. The method is a bit long but well commented. The principle is, for each node, to detect first if something should be reconciled, and if yes, find the proper value (either cloning the value from the base, or find a corresponding existing object in the derived) and set it.
+
+`ReconcileWithBase` is also called at initialization to make sure that any desynchronization that could happen offline is fixed.
+
+## Future
+
+### Undo/redo
+
+The undo/redo system currently records only the change on the modified object, and rely on `ReconcileWithBase` to undo/redo the changes on the derived object. This is not an ideal design because there are a lot of consideration to take, and a lot of special cases.
+
+What we would like to do is:
+* record everything that changes, both in derived and in base nodes
+* disbranch totally automatic propagation during an undo/redo
+
+This design was not possible initially, and I'm not sure it is possible to do now - it's possible to hit a blocker when implementing it, or that it requires a lot of refactoring here and there before being doable.
+
+### Dynamic nodes
+
+Currently we still expose the real asset object in `AssetViewModel`, which it should never, in the editor, be modified out of Quantum node. Also, manipulating Quantum node is quite difficult sometimes due to indirection with target nodes, and access to members.
+
+```
+var partsNode = RootNode[nameof(AssetCompositeHierarchy<TAssetPartDesign, TAssetPart>.Hierarchy)].Target[nameof(AssetCompositeHierarchyData<IAssetPartDesign<IIdentifiable>, IIdentifiable>.Parts)].Target;
+partsNode.Add(newPart);
+```
+
+Ideally, we would like to use the `DynamicNode` objects (currently broken) to manipulate quantum nodes:
+
+```
+dynamic root = DynamicNode.Get(RootNode);
+root.Hierarchy.Parts.Add(newPart)
+```
+
+If this is done properly, `AssetViewModel.Asset` could be turned private, and `AssetViewModel` could just expose the root dynamic node, which would allow to seemlessly manipulate the asset through a `dynamic` object.

en/contributors/engine/build-details.md

@@ -0,0 +1,158 @@
+# 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/building-the-source.md → en/contributors/engine/building-source-linux.md

@@ -1,9 +1,8 @@
 # Building the source to Stride engine
 
 ??
-WIP: make a page that is refernced by the readme.md on Stride: https://github.com/stride3d/stride
-
-
+WIP: make a page that is refernced by the readme.md on Stride:
+https://github.com/stride3d/stride
 
 
 COPIED from readme.mdf.............

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

@@ -0,0 +1,46 @@
+# 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
+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.
+4. **[FBX SDK 2019.0 VS2015](https://www.autodesk.com/developer-network/platform-technologies/fbx-sdk-2019-0)**
+
+## 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 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)
+* Some changes might require a system reboot, try that if you haven't yet.
+* 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`.

en/contributors/engine/dependency-graph.md

@@ -0,0 +1,16 @@
+# Localization
+
+?? https://github.com/stride3d/stride/edit/master/docs/localization.md
+WIP: COPIED from link above
+
+## Translation
+
+Please help us translate by updating existing translations and/or adding new language at https://hosted.weblate.org/projects/stride/
+
+Translation are manually merged back from `weblate` branch to `master` branch.
+
+## Activate new language in Game Studio
+
+Once a new language has been added on weblate, it needs to be activated in the Game Studio during build & startup.
+
+Please check commit https://github.com/stride3d/stride/commit/c70f07f449 for an example on how to add a new language in Game Studio.

en/contributors/engine/graphics-api.md

@@ -0,0 +1,16 @@
+# Localization
+
+?? https://github.com/stride3d/stride/edit/master/docs/localization.md
+WIP: COPIED from link above
+
+## Translation
+
+Please help us translate by updating existing translations and/or adding new language at https://hosted.weblate.org/projects/stride/
+
+Translation are manually merged back from `weblate` branch to `master` branch.
+
+## Activate new language in Game Studio
+
+Once a new language has been added on weblate, it needs to be activated in the Game Studio during build & startup.
+
+Please check commit https://github.com/stride3d/stride/commit/c70f07f449 for an example on how to add a new language in Game Studio.

en/contributors/engine/localization.md

@@ -0,0 +1,158 @@
+# 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.
+
+