Rewrite of the files and folders section

en/manual/files-and-folders/cached-files.md

@@ -1,72 +1,48 @@
 # Cached files
 
-When you build your project, Stride caches the assets and code in folders inside the project.
+Stride caches assets and code in folders inside of your project:
+* **~/Bin** - contains the built game executables, including the one used when launching the game from Game Studio.
+* **~/PackageName/bin** - contains build files for the specific package.
+* **~/PackageName/obj** - contains cached data for that package.
 
-You might want to clean the cache if:
+Additionally, Stride also uses these files:
+* **\*.sdpkg.user** - file containing user-specific information used by the editor (like camera position and rotation).
+* **Asset cache** - contains every asset that was ever loaded by any project. By default, it's located in **%temp%/Stride**, which can be changed in Game Studio in **Edit > Settings > Environment > Build cache directory**.
+* **Settings cache** - contains Game Studio's settings. It's located in **%AppData%/Stride**.
 
+You might want to clean the cache if:
 * the cache is taking up too much space on disk
-
 * assets don't update in-game after you edit or delete them
+* Game Studio is in a bad state.
 
-## Clean the cache from Visual Studio
-
-1. To clean the code cache, under **Build**, select **Clean Solution**.
-
-    ![Clean solution](media/clean-solution.png)
-
-2. If you have the [Stride Visual Studio extension](../get-started/visual-studio-extension.md) installed, you can also clean the asset cache. **Using Visual Studio**: To do this, under Extensions > **Stride**, select **Clean intermediate assets for Solution**.
-
-    ![Clean solution](media/clean-assets.png)
-
-3. Rebuild the project to rebuild the cache from scratch.
-
-## Clean the cache manually
-
-If cleaning the cache from Visual Studio doesn't work, try deleting the files manually.
-
-1. Delete the following folders:
-
-    * the binary cache: *~/MyGame/MyGame/Bin*
-
-    * the asset cache: *~/MyGame/MyGame/Cache*
-
-    * the **obj** folders in the platform folders for your game (eg *~/MyGame.iOS/obj*)
-
-2. If you're developing for iOS, on your Mac, also delete: *~/Library/Caches/Xamarin/mtbs/builds/MyGame*
-
-3. Rebuild the project to rebuild the cache from scratch.
-
-## Clear the Game Studio caches
-
-In addition to the caches Stride creates for your project, Game Studio keeps caches for the editor.
-
-### Asset cache
+Cleaning the cache **won't affect your project**.
 
-To speed up asset loading in the editor, Game Studio saves a cache of asset references. It contains data about every asset ever loaded in every project. This means it can grow very large over time.
+## Cleaning the project cache
 
-By default, the folder is in: *%temp%/Stride*
+Look for a way to clean the solution in your IDE.
 
->[!Tip]
->To check or change where Game Studio saves the cache, see **Edit > Settings > Environment > Build cache directory.**
->![Settings](media/settings-window.png)
+### [Visual Studio](#tab/clean-solution-visual-studio)
 
-To clean the cache, delete the folder and run Game Studio again.
+1. To clean the code cache, select **Build > Clean Solution**.
+2. If you have the [Stride Extension for Visual Studio](../get-started/visual-studio-extension.md), to clean the asset cache, select **Extensions > Stride > Clean intermediate assets for Solution**.
 
-### Settings cache
+### [Command line](#tab/clean-solution-command-line)
 
-Game Studio saves editor information (such as window positions and recently-opened projects) in: *%AppData%/Stride*
+The cache can be cleaned by using the `dotnet` command.
 
-Game Studio also saves information about open tabs and the editor camera position in the `.sdpkg.user` file in the project folder (eg *~/MyGame/MyGame/MyGame.sdpkg.user*).
+```bash
+dotnet clean
+```
 
-These files are small, but you might want to delete them if you get Game Studio into a bad state. Deleting them doesn't affect anything in your project.
+### [Manual](#tab/clean-solution-manual)
 
-After you delete cache files, when you start Game Studio, it builds a new cache using the default settings.
+To clean the cache:
+1. Delete `bin` and `obj` directories in all packages.
+2. Delete the `Bin` directory in the project root.
 
->[!Tip]
->You can also reset the Game Studio layout without clearing the cache in **Edit > Settings > Interface > Reset Game Studio layout**.
->![Reset Game Studio layout](media/game-studio-layout-reset-button.png)
+---
 
 ## See also
 
 * [Project structure](project-structure.md)
-* [Version control](version-control.md)
+* [Version control](version-control.md)

en/manual/files-and-folders/external-packages/index.md

@@ -0,0 +1,10 @@
+# External packages
+
+In Stride it is possible to use external [Nuget](https://www.nuget.org/) packages in your projects. These packages can contain not only code, but also their own **assets and resources**.
+
+This system allows you to create and share your own packages for Stride with other people, as well as get access to those made by others.
+
+## In this section
+* [What is Nuget](what-is-nuget.md)
+* [Using Nuget packages](using-nuget-packages.md)
+* [Publish a Nuget package](publish-a-nuget-package.md)

en/manual/files-and-folders/external-packages/publish-a-nuget-package.md

@@ -0,0 +1,140 @@
+# Publish a Nuget package
+
+This is a guide on how to publish a Stride package and share it.
+
+## Setup
+
+Before a package can be published, it first has to be properly setup in order to work with Stride.
+
+### Changing metadata
+
+You'll need to change the package's metadata in order to publish it on the internet.
+
+#### [Visual Studio](#tab/metadata-visual-studio)
+
+In the **Solution Explorer** panel, right click on your package and select **Properties**.
+
+![](media/visual-studio-package-properties-context-menu.webp)
+
+In the **Package** tab and edit the id, version, authors, etc.
+
+![](media/visual-studio-package-properties-package-tab.webp)
+
+#### [Manual](#tab/metadata-manual)
+
+You can change the metadata manually, by editing the `.csproj` file of the package you are trying to publish.
+
+```xml
+<PropertyGroup>
+  <PackageId>MyGame.MyLibrary</PackageId>
+  <Version>1.0.0</Version>
+  <Authors>ProfileName1,ProfileName2</Authors>
+  <Description>My Description</Description>
+</PropertyGroup>
+```
+
+---
+
+> [!WARNING]
+> The **package id** needs to be the same as the `.csproj` file's name in order to avoid complications.
+
+For more information about how to **correctly** fill out metadata, visit [the Microsoft documentation](https://learn.microsoft.com/en-us/nuget/create-packages/package-authoring-best-practices).
+
+### Add the module initializer
+
+> [!NOTE]
+> If your package **doesn't include Stride code**, you can skip this step.
+
+To ensure that Stride loads your custom [data contracts](../../scripts/serialization.md#datacontractattribute), you'll have to add a **module initializer** in order to manually register them.
+
+To do this, create a `Module.cs` file in the root of your package and add the below code to it:
+
+```csharp
+using Stride.Core.Reflection;
+using Stride.Core;
+using System.Reflection;
+
+namespace MyNamespaceHere;
+
+internal class Module
+{
+    [ModuleInitializer]
+    public static void Initialize()
+    {
+        AssemblyRegistry.Register(typeof(Module).GetTypeInfo().Assembly, AssemblyCommonCategories.Assets);
+    }
+}
+```
+
+### Check the `.sdpkg` file
+
+> [!NOTE]
+> If your package **doesn't have a `.sdpkg` file** and it **only includes code**, you can skip this step.
+
+The `.sdpkg` file's name **has to exactly match the package id and the `.csproj` file's name**. If it's incorrect, the engine won't load it and in turns, it will prevent it's assets from loading.
+
+### Including assets and resources
+
+> [!NOTE]
+> If your package **doesn't have a `.sdpkg` file** and it **only includes code**, you can skip this step.
+
+Without proper setup, Nuget packages will ignore any non-code content.
+
+To make Nuget include stride files in the package, you'll have to modify the `.csproj` file of the package and include these lines:
+
+```xml
+<ItemGroup>
+    <None Include="*.sdpkg" Pack="true" PackagePath="stride"/>
+    <None Include="Assets/*.*" Pack="true" PackagePath="stride/Assets"/>
+    <None Include="Resources/*.*" Pack="true" PackagePath="stride/Resources"/>
+    <None Include="Effects/*.*" Pack="true" PackagePath="stride/Effects"/>
+</ItemGroup>
+```
+
+**Explanation** z<br/>
+The `<None>` property tell C# to not treat the specified files in `Include` as code, which is what it already did, except that now, we can set additional parameters. This includes setting `Pack` to `true` in order to include these files in the package as standard files and specifying the `PackagePath` to make sure they are placed in the correct spot in the package.
+
+> [!NOTE]
+> If your package includes more directories outside of `Assets`, `Resources` and `Effects`, make sure to create separate entries for them.
+
+## Packing
+
+Once you've setup your package correctly, you can **pack it** to create a `.nupkg` file, that can be easily shared with other people.
+
+### [Visual Studio](#tab/packing-visual-studio)
+
+Before starting, change the configuration of your project to **Release mode**.
+
+![](media/visual-studio-change-configuration.webp)
+
+After that, right click the package in the **Solution Explorer** panel and select **Pack**.
+
+![](media/visual-studio-pack.webp)
+
+Once the process is done, the `.nupkg` file will be created in `/packageLocation/bin/Release`.
+
+### [Command line](#tab/packing-command-line)
+
+In order to pack a package using the command line, use the `dotnet` command.
+
+```bash
+dotnet pack path/to/the/package
+```
+
+This will create the `.nupkg` file under `/path/to/the/package/bin/Release`.
+
+---
+
+## Checking the package contents
+
+You can check to see if the package's contents were generated correctly by using [nuget.info](https://nuget.info). It's a website that let's you open a `.nupkg` file and inspect it.
+
+![](media/nuget-info.webp)
+
+Things to look out for:
+1. Make sure everything related to Stride is located in the `stride` folder.
+2. Make sure the `.sdpkg` file is located in **~/stride** and that it's name matches the package id.
+
+## Publishing your package
+
+You can publish your package on [nuget.org](https://nuget.org) directly from the website, or by using commands like `dotnet` or `nuget`.

en/manual/files-and-folders/external-packages/using-nuget-packages.md

@@ -0,0 +1,63 @@
+# Using Nuget packages
+
+Nuget packages
+
+## The idea
+
+Nuget packages can be added to a project **as a dependency of another project package**. 
+
+This is most often the **package named after your project**, which contains the majority of the code and assets.
+
+TODO: VISUALIZATION HERE
+
+## Finding Nuget packages
+
+Nuget packages are hosted on [nuget.org](https://nuget.org). **You can use this website in order to search for a Nuget package**.
+
+Alternatively, check if your IDE of choice has a built-in browser of it's own.
+
+## Adding a Nuget package as a dependency
+
+> [!NOTE]
+> Currently, you cannot do this using Game Studio.
+
+### [Visual Studio](#tab/add-visual-studio)
+
+In the **Solution Explorer** panel, right click on the project package you want to add the Nuget package to and select **Manage Nuget packages...**
+
+![](media/visual-studio-manage-nuget-context-menu.webp)
+
+Select the **Browser** category and search for the package you want to add.
+
+![](media/visual-studio-nuget-browser.webp)
+
+> [!NOTE]
+> If no packages are showing up, make sure that the **package source** is set to **Nuget**.
+> 
+> ![](media/visual-studio-manage-nuget-source.webp)
+
+> [!NOTE]
+> If the package you are looking for isn't showing up, try clicking the **include prerelease** checkbox.
+> 
+> ![](media/visual-studio-manage-nuget-prerelease.webp)
+
+After selecting the package, click the **install** button on the right.
+
+> [!NOTE]
+> Make sure to save!
+
+### [Command line](#tab/add-command-line)
+
+If your IDE doesn't have a way of adding Nuget packages, you can use the `dotnet` command in the terminal.
+
+```bash
+dotnet add Path/To/Project/Package package NameOfNugetPackage
+```
+
+---
+
+## Using assets in Game Studio
+
+In Game Studio, in the **Solution explorer** panel, expand **External packages** and look for the package you have just added.
+
+![](media/game-studio-external-package-assets.webp)

en/manual/files-and-folders/external-packages/what-is-nuget.md

@@ -0,0 +1,7 @@
+# What is Nuget?
+
+Nuget is a package manager used for distributing packages for .NET projects (which includes C#). It's used by Stride to manage engine libraries and it can be used for using extra ones.
+
+**Nuget isn't exclusive to Stride**. It's used in a lot of other C# and .NET projects that have nothing to do with the engine. You can easily take advantage of that to use any publicly available library in your project.
+
+For more information on Nuget, check out [Nuget for Beginners](https://github.com/lukepadiachy/nuget-for-beginners/blob/main/README.md).

en/manual/files-and-folders/index.md

@@ -5,6 +5,10 @@ This section explains Stride's files and folders and the best way to organize th
 ## In this section
 
 * [Project structure](project-structure.md)
+* [Packages](project-packages/index.md)
+  * [Create a package](project-packages/create-a-package.md)
+  * [Package properties](project-packages/package-properties.md)
+  * [Dependencies](project-packages/dependencies.md)
 * [Cached files](cached-files.md)
 * [Version control](version-control.md)
-* [Distribute a game](distribute-a-game.md)
+* [Distribute a game](distribute-a-game.md)