diff --git a/en/manual/files-and-folders/building-the-game/build-file-structure.md b/en/manual/files-and-folders/building-the-game/build-file-structure.md new file mode 100644 index 000000000..5e018d250 --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/build-file-structure.md @@ -0,0 +1,30 @@ +# Build file structure + +This page explains in detail how a built Stride game's files are structured. + +## Overview + +All builds are located in the `Bin` directory. It contains multiple sub-directories that categorize builds based on their configuration and platform. + +When building the Release version of the game, the actual published files are located in the typical build location under the directory ``publish``. + +TODO: VISUALIZATION + +## Contents of the build folder + +The build folder contains the following files: + +* **MyGame.PlatformName** - the executable. It's file extension depends on the platform (eg. `.exe` on Windows). +* **data** - folder containing asset bundles. +* **`.dll` and `.so` files** - libraries used by the game. They can be embedded in the executable itself, in order to declutter the folder. +* **`.json` files** - contain information needed to launch the game. Depending on the configuration, they might not be needed and won't be generated. + +Additionally, there are also these files, that don't need to be included with the game. + +* **createdump.exe** - application for capturing information about a crash. +* **`.pdb` files** - files containing debug information, used for attaching a debugger (using breakpoints). These files can be used by players to create mods more easily. +* **`.xml` files** - files containing the generated code API for every package in your project. + +## See also: + +* [Cleaning up](cleaning-up.md) diff --git a/en/manual/files-and-folders/building-the-game/building.md b/en/manual/files-and-folders/building-the-game/building.md new file mode 100644 index 000000000..e7f24d21b --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/building.md @@ -0,0 +1,31 @@ +# Building + +Currently, release versions of Stride games cannot be built using **Game Studio**. Instead, you can use your **IDE** or **the command line**. + +## [Visual Studio](#tab/visual-studio) + +1. Make sure to setup your game properly. For more information, visit [this page](setup.md). + +2. In the **Solution Explorer** panel, right click on the platform package you want to build and select **Publish**. + + ![](media/visual-studio-publish-context-menu.webp) + +3. In the newly opened tab, click the **Publish** button. + +4. Once the application finishes building, click the TODO: FINISH to open the folder containing your build. + +## [Command line](#tab/command-line) + +1. Make sure to setup your game properly. For more information, visit [this page](setup.md). +2. Use the `dotnet` command in order to build the game. + + ```bash + dotnet publish Path/To/Project/Package + ``` + +--- + +## See also + +* [Cleaning up](cleaning-up.md) +* [Build file structure](build-file-structure.md) diff --git a/en/manual/files-and-folders/building-the-game/cleaning-up.md b/en/manual/files-and-folders/building-the-game/cleaning-up.md new file mode 100644 index 000000000..e6092bf27 --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/cleaning-up.md @@ -0,0 +1,12 @@ +# Cleaning up + +The build process generates [additional files that aren't necessary](build-file-structure.md) for the game to work. This page explains how to clean them up in order to not clutter your game's files. + +## Files to delete + +* **`.xml` files** - contain the generated API from the code. +* **`.pdb` files** - contain information used for debugging. + +## See also + +* [Build file structure](build-file-structure.md) diff --git a/en/manual/files-and-folders/building-the-game/index.md b/en/manual/files-and-folders/building-the-game/index.md new file mode 100644 index 000000000..484543ae6 --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/index.md @@ -0,0 +1,27 @@ +# Building the game + +In order to turn the uncompiled project into an executable application, it has to be **built** first. + +For it's build system, Stride uses [MSBuild](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild). It's a powerful platform that's used by most C# projects. + +> [!NOTE] +> Currently, it's not possible to build the final version of the game using **Game Studio**. + +## Configurations + +Games can be built using one of two different configurations: +* **Debug** - used for testing and debugging, allows you to connect a debugger to create break points and inspect the game while it's running +* **Release** - used for creating the final version of the game + +When you launch the game from **Game Studio** or your **IDE**, it gets built in the **Debug** configuration. + +## What is publishing? + +**Publishing** refers to the process of creating the final version of the game made for distribution. + +## In this section + +* [Setup](setup.md) +* [Building](building.md) +* [Cleaning up](cleaning-up.md) +* [Build file structure](build-file-structure.md) diff --git a/en/manual/files-and-folders/building-the-game/media/visual-studio-csproj.webp b/en/manual/files-and-folders/building-the-game/media/visual-studio-csproj.webp new file mode 100644 index 000000000..8599f9769 --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/media/visual-studio-csproj.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f8f35c3e96dfbe16d851ba1118f10cf368c5592f6af9172af45415a366d64bc3 +size 72776 diff --git a/en/manual/files-and-folders/building-the-game/media/visual-studio-properties-assembly-name.webp b/en/manual/files-and-folders/building-the-game/media/visual-studio-properties-assembly-name.webp new file mode 100644 index 000000000..0591abba7 --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/media/visual-studio-properties-assembly-name.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c56994b7bd0841ccde7910aa9db033ede29aa76e806055afc32707fd9172dc55 +size 13508 diff --git a/en/manual/files-and-folders/building-the-game/media/visual-studio-properties-context-menu.webp b/en/manual/files-and-folders/building-the-game/media/visual-studio-properties-context-menu.webp new file mode 100644 index 000000000..cb7ea3f51 --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/media/visual-studio-properties-context-menu.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5dd597d5937c40f8ee53759836642ee18cd1ac1eecd7435bf0d6ffbc75634c4d +size 29176 diff --git a/en/manual/files-and-folders/building-the-game/media/visual-studio-properties-icon.webp b/en/manual/files-and-folders/building-the-game/media/visual-studio-properties-icon.webp new file mode 100644 index 000000000..6f59c5b29 --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/media/visual-studio-properties-icon.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2725c71f00c33c2042aebc4cbf40021143ff94d5f332f8470f4134422022261f +size 15514 diff --git a/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-context-menu.webp b/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-context-menu.webp new file mode 100644 index 000000000..d58cdeab7 --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-context-menu.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:958ad1db810c7340e1cd7b08b338fc21660d4f4398956c9ea7139da89d887f7c +size 13684 diff --git a/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-navigate.webp b/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-navigate.webp new file mode 100644 index 000000000..8775c03af --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-navigate.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0a24ffa7aec1c70cfdcb4661b832c3414201066dbddbe8356e78b7641819a31a +size 6762 diff --git a/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-self-contained.webp b/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-self-contained.webp new file mode 100644 index 000000000..d3521eb40 --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-self-contained.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f339c41085348813e7ae54d6ee02bb2a549244e30161db25f3a6f76c7acb1924 +size 15754 diff --git a/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-settings.webp b/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-settings.webp new file mode 100644 index 000000000..6990ee15c --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-settings.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:897df64259ad86c4baf0df9dd2d0d8742ae0c5ee26c391b8957d1c74d514de12 +size 14668 diff --git a/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-show-all-settings.webp b/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-show-all-settings.webp new file mode 100644 index 000000000..c2ec14ea0 --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-show-all-settings.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ac107d2280cc73b40764fb6666a5a85982edf3707d8019a5601523f9a4317d89 +size 13492 diff --git a/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-single-file.webp b/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-single-file.webp new file mode 100644 index 000000000..7f676f475 --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-single-file.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:75fb1773e8a5d1afaaf51ce907e384b96f8c24179770046ed9cbf513fb3a5ec8 +size 14084 diff --git a/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-target-location.webp b/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-target-location.webp new file mode 100644 index 000000000..a7f2b9cbf --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-target-location.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:000316639f4a084528ab9194d84635710a54045375b7a722e11b59bc2eca4463 +size 14108 diff --git a/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-wizard.webp b/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-wizard.webp new file mode 100644 index 000000000..4ab620256 --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/media/visual-studio-publish-wizard.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fb0431b5105ce463b78aaa75f598bc459f872461aa2acf38cb8d5662f94506bd +size 20504 diff --git a/en/manual/files-and-folders/building-the-game/setup.md b/en/manual/files-and-folders/building-the-game/setup.md new file mode 100644 index 000000000..7c2e102f7 --- /dev/null +++ b/en/manual/files-and-folders/building-the-game/setup.md @@ -0,0 +1,147 @@ +# Setup + +There are many configurable options that change how the game gets built. This page goes over a few of the more important ones. + +## How to change properties + +### [Visual Studio](#tab/visual-studio) + +**Visual Studio** has it's own [publishing system](https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/visual-studio-publish-profiles), which provides a graphical way of managing build settings. + +In the **Solution Explorer** panel right click on the platform package which you want to setup and select **Publish**. + +![](media/visual-studio-publish-context-menu.webp) + +This will open a new tab and a setup wizard. Select the **Folder** option, then choose **Folder** again and then optionally, specify the location where you want the build to end up. + +![](media/visual-studio-publish-wizard.webp) + +Now, you can change the settings by pressing the **Show all settings** button. + +![](media/visual-studio-publish-show-all-settings.webp) + +For some options, you might need to change the platform package's properties, which can be done by right clicking on it and selecting **Properties**. + +![](media/visual-studio-properties-context-menu.webp) + +### [Manual](#tab/manual) + +In order to change build settings, you'll have to modify the `.csproj` file of a platform package. + +--- + +## Name + +To change the name of the executable, you'll have to change the **assembly name** of the platform package. + +### [Visual Studio](#tab/visual-studio) + +In the **platform package's properties**, look for a field named **Assembly name**. + +![](media/visual-studio-properties-assembly-name.webp) + +### [Manual](#tab/manual) + +In the `.csproj` file, add `Insert name here` to the ``. + +--- + +## Icon + +The file for the application icon is located in `Resources/Icon.ico`. To change it, simply replace the file. + +If you want to, you can also change the location of the icon. + +### [Visual Studio](#tab/visual-studio) + +In the **platform package's properties**, look for a field named **Icon**. + +![](media/visual-studio-properties-icon.webp) + +### [Manual](#tab/manual) + +In the `.csproj` file, add `Insert name here` to the ``. + +--- + +## Self contained + +Making an application **self contained** removes the requirement for a user to have the **.NET runtime** installed on their machine. + +Due to how .NET applications generally work, Stride games require the runtime in order to even run. If it's not present, the game will instead show a window asking the user to install it. + +TODO: IMAGE + +> [!NOTE] +> .NET applications are fairly common, especially on **Windows**, so it's very likely that a user already has it installed. + +There are benefits and drawbacks to making a game **self contained**: +* 🟩 **Benefits**: the game will work even if a user doesn't have the runtime installed. +* 🟥 **Drawbacks**: the game's size will be larger. + +### [Visual Studio](#tab/visual-studio) + +In the profile settings, change the **Deployment mode** option to **Self-contained**. + +![](media/visual-studio-publish-self-contained.webp) + +### [Manual](#tab/manual) + +In the `.csproj` file, add `true` to the ``. + +--- + +## Single file and include native libraries + +By default, building will create a `.dll` file for every package used by the project. These files can be embeded in the application executable itself by enabling **Publish single file**. + +Despite it's name, this option **still won't make the game a single file**, as it won't embed the native libraries used by Stride. For that, you'll have to additionally enable **Include native libraries for self extract**. + +> [!NOTE] +> Even with all these options enabled, Stride will still produce an additional folder for it's assets named `data`, that needs to be included when shipping the game. + +### [Visual Studio](#tab/visual-studio) + +To enable **Include native libraries for self extract**, double click on the platform package and add `true` to the ``. + +![](media/visual-studio-csproj.webp) + +Now, to enable **publish single file**, go to the profile settings and in the **File publish options** tick the **Produce single file** checkbox. + +![](media/visual-studio-publish-single-file.webp) + +### [Manual](#tab/manual) + +In the `.csproj` file, add `true` and `true` to the ``. + +--- + +## The output directory + +There are two paths which can be configured: +* **Output path** - path to the directory that contains all build files for all builds, both Debug and Release. +* **Publish directory** - path to the directory that contains the final result when publishing a project. + +By default, the publish directory is set to `$(OutputPath)/publish`. + +### [Visual Studio](#tab/visual-studio) + +To change the **output path**, open the **platform package's properties** and look for a field named **INSERT NAME HERE**. + +TODO: IMAGE + +To change the **publish directory**, open the profile settings and modify the value of **Target location**. + +![](media/visual-studio-publish-target-location.webp) + +### [Manual](#tab/manual) + +To change the **output path**, in the `.csproj` file, add `true` and `true` to the ``. + +To change the **publish directory**, in the `.csproj` file, add `true` to the ``. + +--- + +## See also +* [Common MSBuild project properties](https://learn.microsoft.com/en-us/visualstudio/msbuild/common-msbuild-project-properties) +* [Building](building.md) diff --git a/en/manual/files-and-folders/cached-files.md b/en/manual/files-and-folders/cached-files.md index 53e791624..4779076a1 100644 --- a/en/manual/files-and-folders/cached-files.md +++ b/en/manual/files-and-folders/cached-files.md @@ -1,72 +1,46 @@ # 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). +* **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 -## 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) \ No newline at end of file +* [Version control](version-control.md) diff --git a/en/manual/files-and-folders/distribute-a-game.md b/en/manual/files-and-folders/distribute-a-game.md index 3448f2de2..699632a7b 100644 --- a/en/manual/files-and-folders/distribute-a-game.md +++ b/en/manual/files-and-folders/distribute-a-game.md @@ -1,104 +1,3 @@ -# Distribute a game - -When you're ready to publish your game, create a release build from Visual Studio, then distribute it. - -## 1. Create a release build - -1. If you've built your game in Release mode before, in your project folder (eg *MyGame/Bin/MyPlatform/Release/*), delete the *Data* folder. This folder might contain unnecessary files, such as old versions of assets, so it's simplest to build it again from scratch. - -2. Open your project in Game Studio. - -3. In the toolbar, click the drop-down menu and select **Visual Studio**. - - ![Open in VS](media/open-in-visual-studio.png) - - Your project opens in Visual Studio. - -4. In Visual Studio, from the **Solution Explorer** right click your Windows project and select **Publish** - - ![Select Publish](media/publish-project-dropdown.png) - -5. Select the **Target** **Folder** in the publish window. - -6. Select the **Specified target** **Folder** again. - -7. Confirm the output folder and Click **Finish**. - -8. You should now see the **Publish** view where you can manage the project export settings. - - ![Publish View](media/publish-view.png) - -9. Finally you can click publish and see your project in the output folder you selected at **step 6** - - Optionally you can also include the .NET runtime in your exported game to reduce a dependancy on the user. - - Select **Show all settings** -> **Deployment mode** -> **Self-contained** -> **Save** - - ![Publish Self Contained](media/publish-self-contained.png) - - > [!Note] - > - > You can only build for platforms you've added to your Stride project. For instructions about how to do this, see [Add or remove a platform](../platforms/add-or-remove-a-platform.md). - > - > To build for Android or iOS, you need Xamarin, which is included with Visual Studio licenses. For instructions about how to install Xamarin with Visual Studio 2017, see [this MSDN page](https://docs.microsoft.com/en-us/visualstudio/cross-platform/setup-and-install). - -10. Under **Build**, select **Publish Selection** and click the **Publish** button. - - ![Publish Solution](media/publish-project.png) - - Visual Studio creates a release build in your selected output folder. - -> [!Tip] -> You might want to rename the **Release** folder to something more descriptive (such as the title of your game). - -### To build using terminal instead of Visual Studio - - 1. Ensure the relevant .NET SDK is installed (Stride 4.3 is on .NET 10) - 2. Open the folder of your project where the `*.Windows.csproj` file sits. - - ![Project Folder](media/project-folder.png) - - 3. Type `cmd` in the search bar to open the folder easily in terminal. - - ![Open terminal](media/open-terminal.png) - - 4. Finally publish with the command - - ``` - dotnet publish - ``` - - or the below to include the .NET runtime with your game - - ``` - dotnet publish -r win-x64 --self-contained true -- framework net10.0-windows - ``` - - You can also append `--output ` to specify where to export to. - -## 2. Delete unnecessary files - -In the release folder in your project bin folder (eg *MyGame/Bin/MyPlatform/Release*), you can delete the following unnecessary files: - -* `.pdb` files (debug information) -* `.xml` files (API documentation) -* files that contain `vshost` in their filenames (eg `MyGame5.vshost.exe` and `MyGame5.vshost.exe.manifest`) -* folders other than the `x64`, `x86`, or `data` folders -* other unnecessary files, such as custom configuration files (ie files not created with Stride) - -## 3. Distribute your game - -After you create a release build, how you distribute it is up to you. - -To run games made with Stride on Windows, users need: - -* .NET 10 Runtime (Unless you published with **self-contained**) -* DirectX11 (included with Windows 10 and later), OpenGL, or Vulkan -* Visual C++ 2015 runtimes (x86 and/or x64, depending on what you set in your project properties in Visual Studio) - -## See also - -* [Add or remove a platform](../platforms/add-or-remove-a-platform.md) -* [Version control](version-control.md) -* [Project structure](project-structure.md) -* [Microsoft documentation](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-publish) \ No newline at end of file +--- +redirect_url: building-the-game/index.html +--- diff --git a/en/manual/files-and-folders/external-packages/index.md b/en/manual/files-and-folders/external-packages/index.md new file mode 100644 index 000000000..4e014cf6b --- /dev/null +++ b/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) diff --git a/en/manual/files-and-folders/external-packages/media/game-studio-external-package-assets.webp b/en/manual/files-and-folders/external-packages/media/game-studio-external-package-assets.webp new file mode 100644 index 000000000..4046be1c5 --- /dev/null +++ b/en/manual/files-and-folders/external-packages/media/game-studio-external-package-assets.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9a33ef11979f8ce5c581c91ecc6fc001089fdef83821dd26fb603d6c54468f7f +size 58336 diff --git a/en/manual/files-and-folders/external-packages/media/nuget-info.webp b/en/manual/files-and-folders/external-packages/media/nuget-info.webp new file mode 100644 index 000000000..006b9f5b8 --- /dev/null +++ b/en/manual/files-and-folders/external-packages/media/nuget-info.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9284e17b75a4936b666720d6ae7a1edac9fd42c0e4d46b2195bd03cf6bf6e734 +size 49862 diff --git a/en/manual/files-and-folders/external-packages/media/visual-studio-change-configuration.webp b/en/manual/files-and-folders/external-packages/media/visual-studio-change-configuration.webp new file mode 100644 index 000000000..f0f9abfd1 --- /dev/null +++ b/en/manual/files-and-folders/external-packages/media/visual-studio-change-configuration.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e082a2f097691085d333a4f14d4b3cdb7fe906a7772036c785ef7b2e0858d917 +size 25802 diff --git a/en/manual/files-and-folders/external-packages/media/visual-studio-manage-nuget-context-menu.webp b/en/manual/files-and-folders/external-packages/media/visual-studio-manage-nuget-context-menu.webp new file mode 100644 index 000000000..304ac80a2 --- /dev/null +++ b/en/manual/files-and-folders/external-packages/media/visual-studio-manage-nuget-context-menu.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8746332c5bdb8c9c12e450eec19f9cc11cbe1ebc5db8c920f567066856f7b504 +size 24726 diff --git a/en/manual/files-and-folders/external-packages/media/visual-studio-manage-nuget-prerelease.webp b/en/manual/files-and-folders/external-packages/media/visual-studio-manage-nuget-prerelease.webp new file mode 100644 index 000000000..ca08e99a5 --- /dev/null +++ b/en/manual/files-and-folders/external-packages/media/visual-studio-manage-nuget-prerelease.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c34eba094957d593b1cfbb83e5129f553ebceedbab85f7936bf3a99e84a2c88b +size 35258 diff --git a/en/manual/files-and-folders/external-packages/media/visual-studio-manage-nuget-source.webp b/en/manual/files-and-folders/external-packages/media/visual-studio-manage-nuget-source.webp new file mode 100644 index 000000000..84a29cf34 --- /dev/null +++ b/en/manual/files-and-folders/external-packages/media/visual-studio-manage-nuget-source.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ffc94f560ac06a9ce0cce7279e4742f2f8e97a25b23080fb64178462af3faaa2 +size 18220 diff --git a/en/manual/files-and-folders/external-packages/media/visual-studio-nuget-browser.webp b/en/manual/files-and-folders/external-packages/media/visual-studio-nuget-browser.webp new file mode 100644 index 000000000..235a86e5d --- /dev/null +++ b/en/manual/files-and-folders/external-packages/media/visual-studio-nuget-browser.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d340a7fefd33159706b946b7d0a2266a1e613d1c477258b57888699a076400bf +size 143572 diff --git a/en/manual/files-and-folders/external-packages/media/visual-studio-pack.webp b/en/manual/files-and-folders/external-packages/media/visual-studio-pack.webp new file mode 100644 index 000000000..36140a826 --- /dev/null +++ b/en/manual/files-and-folders/external-packages/media/visual-studio-pack.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:21691b6c49571d1ca9f1b99ec6df5a0cd8ef6fe9aeb5c7dbc8cbec7f6c6f2446 +size 18122 diff --git a/en/manual/files-and-folders/external-packages/media/visual-studio-package-properties-context-menu.webp b/en/manual/files-and-folders/external-packages/media/visual-studio-package-properties-context-menu.webp new file mode 100644 index 000000000..593ed60b8 --- /dev/null +++ b/en/manual/files-and-folders/external-packages/media/visual-studio-package-properties-context-menu.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:78066bf81ed5e76468e725209f1c17bb36210626574a2599922cac7e3be1c66f +size 40244 diff --git a/en/manual/files-and-folders/external-packages/media/visual-studio-package-properties-package-tab.webp b/en/manual/files-and-folders/external-packages/media/visual-studio-package-properties-package-tab.webp new file mode 100644 index 000000000..2366f3212 --- /dev/null +++ b/en/manual/files-and-folders/external-packages/media/visual-studio-package-properties-package-tab.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d95b52b802c217de26b6596645571557a6e88340fd8088995b4376ae2c6bf66b +size 73890 diff --git a/en/manual/files-and-folders/external-packages/publish-a-nuget-package.md b/en/manual/files-and-folders/external-packages/publish-a-nuget-package.md new file mode 100644 index 000000000..8138c9ad4 --- /dev/null +++ b/en/manual/files-and-folders/external-packages/publish-a-nuget-package.md @@ -0,0 +1,144 @@ +# Publish a Nuget package + +This is a guide on how to publish and share a Stride package. + +## Setup + +Before a package can be published, it first has to be properly setup in order to work with Stride and C#. + +### 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, fill out all the fields you need. + +![](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 + + MyGame.MyLibrary + 1.0.0 + ProfileName1,ProfileName2 + My Description + +``` + +--- + +> [!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 turn, 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, the packing process 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 + + + + + + +``` + +**Explanation** z
+The `` item tells 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 directory 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`. + +## See also + +* [Using Nuget packages](using-nuget-packages.md) diff --git a/en/manual/files-and-folders/external-packages/using-nuget-packages.md b/en/manual/files-and-folders/external-packages/using-nuget-packages.md new file mode 100644 index 000000000..a674f27f8 --- /dev/null +++ b/en/manual/files-and-folders/external-packages/using-nuget-packages.md @@ -0,0 +1,69 @@ +# Using Nuget packages + +This is a guide on how to use Nuget packages with Stride. + +## 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** tab 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.org**. +> +> ![](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 + +> [!NOTE] +> This only applies to packages that include custom Stride assets. + +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) + +> [!NOTE] +> You might need to reload the project in order to make the package to show up. diff --git a/en/manual/files-and-folders/external-packages/what-is-nuget.md b/en/manual/files-and-folders/external-packages/what-is-nuget.md new file mode 100644 index 000000000..138ac128a --- /dev/null +++ b/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). diff --git a/en/manual/files-and-folders/index.md b/en/manual/files-and-folders/index.md index dc2f8e93c..0fee85b6b 100644 --- a/en/manual/files-and-folders/index.md +++ b/en/manual/files-and-folders/index.md @@ -1,10 +1,22 @@ -# Files and folders +# Project -This section explains Stride's files and folders and the best way to organize them in development. +This section explains how a Stride project is structured, how it works and how to work with it. ## 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) +* [External packages](external-packages/index.md) + * [What is Nuget](external-packages/what-is-nuget.md) + * [Using Nuget packages](external-packages/using-nuget-packages.md) + * [Publish a Nuget package](external-packages/publish-a-nuget-package.md) * [Cached files](cached-files.md) * [Version control](version-control.md) -* [Distribute a game](distribute-a-game.md) \ No newline at end of file +* [Building the game](building-the-game/index.md) + * [Setup](building-the-game/setup.md) + * [Building](building-the-game/building.md) + * [Build file structure](building-the-game/build-file-structure.md) + * [Cleaning up](building-the-game/cleaning-up.md) diff --git a/en/manual/files-and-folders/project-packages/create-a-package.md b/en/manual/files-and-folders/project-packages/create-a-package.md new file mode 100644 index 000000000..b9cebb2b8 --- /dev/null +++ b/en/manual/files-and-folders/project-packages/create-a-package.md @@ -0,0 +1,128 @@ +# Create a package + +In this guide, we will dive into how to create custom packages. + +## Create a platform package + +TODO: IMAGE OF PLATFORM PACKAGES + +Platform packages are created when adding a platform to the project. Steps on how to do that are located on the [add or remove a platform page](../../platforms/add-or-remove-a-platform.md). + +## Create a standard package + +### [Game Studio](#tab/game-studio) + +You can create a new package in the **Solution explorer** panel by right clicking on the solution and selecting **"New project..."**. + +![](media/game-studio-new-package.webp) + +You can select from one of two templates: +* **New game** - creates a new game package along additional packages for selected platforms. +* **Code library** - a standard empty package that is meant to be used by other packages for code and assets. + +### [Visual Studio](#tab/visual-studio) + +You can create a new package in the **Solution Explorer** panel by right clicking on the solution and selecting **Add > New Project...** + +![](media/visual-studio-new-package.webp) + +You will be prompted to select one of the templates provided by Visual Studio. Select **Class Library** for the C# language. + +![](media/visual-studio-new-package-template.webp) + +Give the package a name and then continue through the steps until the package is created. + +> [!NOTE] +> Make sure to save! + +> [!WARNING] +> The created package **will be missing references to Stride libraries**. You will have to add them yourself. + +> [!WARNING] +> Creating a package through Visual Studio **won't create the `.sdpkg` file** nor the **Assets** and **Resources** folders. Make sure to create them yourself. +> +> ![](media/visual-studio-new-package-created.webp) +> +> Here is a template for the `.sdpkg` file. +> +> ```yaml +> !Package +> SerializedVersion: {Assets: 3.1.0.0} +> Meta: +> Name: MyGame.MyLibrary +> Version: 1.0.0 +> Authors: [] +> Owners: [] +> Dependencies: null +> AssetFolders: +> - Path: !dir Assets +> - Path: !dir Effects +> ResourceFolders: +> - !dir Resources +> OutputGroupDirectories: {} +> ExplicitFolders: [] +> Bundles: [] +> TemplateFolders: [] +> RootAssets: [] +> ``` + +### [Command line](#tab/command-line) + +If your IDE of choice isn't included on this page, you can create a new package from the terminal instead via the `dotnet` command. + +```bash +dotnet new classlib --name MyGame.MyLibrary +``` + +You also need to add it to your solution. + +```bash +dotnet sln add MyGame.MyLibrary +``` + +> [!WARNING] +> The created package **will be missing references to Stride libraries**. You will have to add them yourself. + +> [!WARNING] +> Creating a package through the command line **won't create the `.sdpkg` file** nor the *> *Assets** and **Resources** folders. Make sure to create them yourself. +> +> Here is a template for the `.sdpkg` file. +> +> ```yaml +> !Package +> SerializedVersion: {Assets: 3.1.0.0} +> Meta: +> Name: MyGame.MyLibrary +> Version: 1.0.0 +> Authors: [] +> Owners: [] +> Dependencies: null +> AssetFolders: +> - Path: !dir Assets +> - Path: !dir Effects +> ResourceFolders: +> - !dir Resources +> OutputGroupDirectories: {} +> ExplicitFolders: [] +> Bundles: [] +> TemplateFolders: [] +> RootAssets: [] +> ``` + +--- + +## Using your new package + +After creating a new package, it won't be possible to use it anywhere in your game, because by default, it won't be used by any other package. + +TODO: ADD VISUALISATION + +To change that, you'll have to add it as a dependency to the package(s) that you want to use it. + +For more information, visit the [dependencies page](dependencies.md#add-a-dependency). + +## See also + +* [Add or remove a platform](../../platforms/add-or-remove-a-platform.md) +* [Package properties](package-properties.md) +* [Dependencies](dependencies.md) diff --git a/en/manual/files-and-folders/project-packages/dependencies.md b/en/manual/files-and-folders/project-packages/dependencies.md new file mode 100644 index 000000000..efedddc74 --- /dev/null +++ b/en/manual/files-and-folders/project-packages/dependencies.md @@ -0,0 +1,48 @@ +# Dependencies + +Packages can depend on other packages in order to use their code and/or assets. + +TODO: VISUALISATION IMAGE + +Packages **cannot be co-dependent**: if **package A** has a dependency on **package B**, **package B** cannot have a dependency on **package A**. + +TODO: VISUALISATION IMAGE + +## Add a dependency + +### [Game Studio](#tab/game-studio) + +You can add a package as a dependency to another package by right clicking it in the **Soludion explorer** panel and selecting **Add dependency...**. + +![](media/game-studio-add-dependency.webp) + +### [Visual Studio](#tab/visual-studio) + +You can add a package as a dependency to another package by right clicking it in the **Solution Explorer** panel and selecting **Add > Project Reference...** + +![](media/visual-studio-add-dependency.webp) + +> [!NOTE] +> Make sure to save! + +### [Command line](#tab/command-line) + +If your IDE of choice isn't included in this list, you can do this from the terminal instead via the `dotnet` command. + +The below command will add **PackageA** as a dependency of **PackageB** (**PackageA** will be used by **PackageB**). + +```bash +dotnet add PackageB reference PackageA +``` + +--- + +## Unused packages + +It is possible to have packages in your project that aren't used by other packages. + +TODO: VISUALISATION IMAGE + +These packages will be ignored by the compiler and **won't be included in the build**. This is useful for creating special versions of your project that include additional libraries and content. + +TODO: VISUALISATION IMAGE diff --git a/en/manual/files-and-folders/project-packages/index.md b/en/manual/files-and-folders/project-packages/index.md new file mode 100644 index 000000000..fddb8d6ef --- /dev/null +++ b/en/manual/files-and-folders/project-packages/index.md @@ -0,0 +1,8 @@ +# Packages + +**Stride separates project files into packages**. This allows for better organization, faster compilation and splitting the game into separate parts (eg. DLC). + +## In this section +* [Create a package](create-a-package.md) +* [Package properties](package-properties.md) +* [Dependencies](dependencies.md) diff --git a/en/manual/files-and-folders/project-packages/media/game-studio-add-dependency.webp b/en/manual/files-and-folders/project-packages/media/game-studio-add-dependency.webp new file mode 100644 index 000000000..819af4002 --- /dev/null +++ b/en/manual/files-and-folders/project-packages/media/game-studio-add-dependency.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a4a7afab9314b1a592f59ed19bd7c7be653996efed09f9d7c08583e8033952fe +size 33776 diff --git a/en/manual/files-and-folders/project-packages/media/game-studio-new-package.webp b/en/manual/files-and-folders/project-packages/media/game-studio-new-package.webp new file mode 100644 index 000000000..2647fe4dd --- /dev/null +++ b/en/manual/files-and-folders/project-packages/media/game-studio-new-package.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:970fab44ba7464fbdb188895f916ebdb5c70625a1b7319807a0f9c801612dcee +size 15762 diff --git a/en/manual/files-and-folders/project-packages/media/visual-studio-add-dependency.webp b/en/manual/files-and-folders/project-packages/media/visual-studio-add-dependency.webp new file mode 100644 index 000000000..4cb8e7cdb --- /dev/null +++ b/en/manual/files-and-folders/project-packages/media/visual-studio-add-dependency.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4ee83d47a70f8beb11005b7dae83a039f096d9378296ad53d4d81a6879ab3963 +size 60022 diff --git a/en/manual/files-and-folders/project-packages/media/visual-studio-new-package-created.webp b/en/manual/files-and-folders/project-packages/media/visual-studio-new-package-created.webp new file mode 100644 index 000000000..c067d38ba --- /dev/null +++ b/en/manual/files-and-folders/project-packages/media/visual-studio-new-package-created.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b22bd8f944c95852c67ee731acd415d64769568120d822ff704e4489e21d1787 +size 20956 diff --git a/en/manual/files-and-folders/project-packages/media/visual-studio-new-package-template.webp b/en/manual/files-and-folders/project-packages/media/visual-studio-new-package-template.webp new file mode 100644 index 000000000..36e4a65a8 --- /dev/null +++ b/en/manual/files-and-folders/project-packages/media/visual-studio-new-package-template.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fc067b4b568afb555a3c9f3fc9b80d799bc227f38f12581b0dbe6c282632f202 +size 59272 diff --git a/en/manual/files-and-folders/project-packages/media/visual-studio-new-package.webp b/en/manual/files-and-folders/project-packages/media/visual-studio-new-package.webp new file mode 100644 index 000000000..2a3c73e33 --- /dev/null +++ b/en/manual/files-and-folders/project-packages/media/visual-studio-new-package.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b4efec3f10a9fbf93292b4c3187a2f02e7ec64fa1d9472ee26c888d87f29ff75 +size 37998 diff --git a/en/manual/files-and-folders/project-packages/package-properties.md b/en/manual/files-and-folders/project-packages/package-properties.md new file mode 100644 index 000000000..dbfb03c04 --- /dev/null +++ b/en/manual/files-and-folders/project-packages/package-properties.md @@ -0,0 +1,42 @@ +# Package properties + +Every package contains it's own set of properties, that can be customized. + +> [!NOTE] +> Currently there is no way to change package properties via **Game Studio** - you have to **modify the `.sdpkg` file directly**. + +| Property | Description | +| :-- | :-- | +| Meta | Package metadata (name, version, authors, etc). | +| AssetFolders | List of directory paths that contain assets. | +| ResourceFolders | List of directory paths that contain resources. | +| OutputGroupDirectories | A dictionary containing a custom output directory for each specified bundle. | +| ExplicitFolders (currently broken) | List of directory paths that are meant to always be loaded by game studio, even if they do not contain any assets. | +| Bundles | List of bundles and their metadata. For more information read [Asset Bundles](../../engine/assets/asset-bundles.md). | +| TemplateFolders | List of directory paths containing custom templates in the `.sdtpl` format. For more information read [Custom Assets](../../scripts/custom-assets.md#adding-a-section-for-the-add-asset-menu-inside-the-editor). | +| RootAssets | List of root assets (assets that will always be included with the build). | + +## Example + +Here is an example `.sdpkg` file. + +```yaml +!Package +SerializedVersion: {Assets: 3.1.0.0} +Meta: + Name: MyGame + Version: 1.0.0 + Authors: [] + Owners: [] + Dependencies: null +AssetFolders: + - Path: !dir Assets + - Path: !dir Effects +ResourceFolders: + - !dir Resources +OutputGroupDirectories: {} +ExplicitFolders: [] +Bundles: [] +TemplateFolders: [] +RootAssets: [] +``` diff --git a/en/manual/files-and-folders/project-structure.md b/en/manual/files-and-folders/project-structure.md index 5211049c6..29fec168c 100644 --- a/en/manual/files-and-folders/project-structure.md +++ b/en/manual/files-and-folders/project-structure.md @@ -1,32 +1,68 @@ -# Project structure +# File structure -Stride saves your projects as [Visual Studio solution files](https://msdn.microsoft.com/en-us/library/bb165951.aspx?f=255&MSPPError=-2147217396). You can open the projects with Stride Game Studio or any IDE such as Visual Studio. +This page explains in detail how a Stride project's files are structured. -Stride organizes project files into **packages**. Each package comprises several folders and an *.sdpkg file which describes the package. +## Overview -A project can contain one package or several. You can share packages between projects. +A Stride project is a **standard C# solution**, consisting of a single **[solution file](https://learn.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file) (`.sln`)** and multiple **[package](#packages) folders**, which contain code, assets and resources. -## Package folder structure +IMAGE OF THE FILE STRUCTURE -![Folder structure](media/folder-structure.png) +## Packages -* **Assets** contains the [asset](../game-studio/assets.md) files which represent elements in your game. +At the root, a Stride project is comprised of multiple [packages](project-packages/index.md). They are used for separating code, assets and resources. -* **Bin** contains the compiled binaries and data. Stride creates the folder when you build the project, with a subdirectory for each platform. +**For C# developers**: a Stride package is a [standard C# project](https://learn.microsoft.com/en-us/visualstudio/get-started/tutorial-projects-solutions). -* **MyGame.Game** contains the source code of your game as a cross-platform Visual Studio project (.csproj). You can add multiple projects to the same game. +By default, there are at least 2 packages in a Stride project: +* `NameOfGame` - contains most code, assets and resources for the game +* `NameOfGame.PlatformName` (eg. `NameOfGame.Windows`) - dedicated package for a given platform, contains the [**entry point**](#entry-point) and other files specific to the platform (such as the window icon). -* **MyGame.Platform** contains additional code for the platforms your project supports. Game Studio creates folders for each platform (eg *MyPackage.Windows*, *MyPackage.Linux*, etc). These folders are usually small, and only contain the entry point of the program. +Every package contains: +* **Assets** - the assets folder. Name of this folder or additional folders can be configured in the `.sdpkg` file. +* **Resources** - the resources folder. Name of this folder or additional folders can be configured in the `.sdpkg` file. +* **`.sdpkg` file** - contains configurable metadata of the package. +* **`.sdpkg.user` file** - contains user-specific data about the editor that is not meant to be shared with source control. +* **`.csprj` file** - a C# project file containing information about how it's code will be compiled. -* **obj** contains cached files. Game Studio creates this folder when you build your project. +TODO: VISUALISATION -* **Resources** is a suggested location for files such as images and audio files used by your assets. +## Entry point -## Recommended project structure +The **entry point** refers to the place in code where execution starts from. Each platform's entry point is stored in their dedicated [package](#packages). For most platforms, it's the `Program.cs` file. -For advice about the best way to organize your project, see the [Version control](version-control.md) page. +IMAGE OF WINDOWS, LINUX AND MACOS PACKAGES + +Every entry point needs to **create a game instance** and **start it**. + +```csharp +using Stride.Engine; + +using var game = new Game(); +game.Run(); +``` + +> [!NOTE] +> The file containing the **entry point** and the code needed to start the game is automatically generated when a platform is added to the project. + +## Package bin and obj folders + +Every package has a `bin` and an `obj` folders which are automatically created when opening or running the project. They store cached data used by Stride. + +> [!NOTE] +> These folders **can be safely deleted without affecting the rest of the project**. For more information, visit the [cached files page](cached-files.md). + +## Project Bin folder + +In the root of the project, there is a `Bin` folder that contains game builds for each platform. Every time the game is launched from Game Studio or from an IDE, a debug version is built and placed in that folder. + +The location of this folder can be changed by going to the `.csproj` file of a platform's package and changing the value of ``. + +> [!NOTE] +> To build the **release version** of the game, visit the [distribute a game page](distribute-a-game.md). ## See also +* [Packages](project-packages/index.md) * [Version control](version-control.md) -* [Distribute a game](distribute-a-game.md) \ No newline at end of file +* [Distribute a game](distribute-a-game.md) diff --git a/en/manual/files-and-folders/version-control.md b/en/manual/files-and-folders/version-control.md index 7b3b53c0f..3608132d1 100644 --- a/en/manual/files-and-folders/version-control.md +++ b/en/manual/files-and-folders/version-control.md @@ -1,84 +1,29 @@ -# Organize your files in version control +# Version control -We recommend you use a version control system such as Git, SVN, or Perforce Helix to save a history of changes to your project. +Version control software allows you to work on your project with multiple people at the same time and keep a history of changes that can be used for backups. -How you organize and share your files is up to you, but there are some things to keep in mind. +The most commonly used version controlled system is [Git](https://git-scm.com/). -## Files you shouldn't add to version control +## Files to ignore -### **Bin** and **obj** folders +There are certain files that version control should ignore, as they are used for caching or storing local data: +1. Package **bin** and project **Bin** folders - these folders contain the build results of your game. This includes the builds that are created when launching the game from Game Studio. +2. Package **obj** folders - these folders contain cached data used by C# and Stride. +3. **\*.user** files - these files store save data for the local user (such as the camera position in Game Studio). -We don't recommend you add the **Bin** or **obj** folders to version control. This is because: +### For Git -* Game Studio builds these folders every time you run the game, so you don't need to keep a history of them. -* You can't see if they match the source files they were generated from in a given commit. -* They take up space and slow down version control synchronization. +We recommend using the [official Github `.gitignore` for Dotnet projects](https://github.com/github/gitignore/blob/main/Dotnet.gitignore). -Visual Studio also puts **.obj** folders inside each code folder. For the same reasons, we don't recommend you add these to version control. +> [!WARNING] +> This file should be placed at the root of the Stride project, next to the `.sln` file. If your git repository isn't initialized at the root, the `.gitignore` file will still be detected. +> +> TODO: ADD PICTURE -### Resource files +## Large files -**Resource files** are files imported into Game Studio and used by assets. They include image files (eg `.png`, `.jpg`), audio files (eg `.mp3`, `.wav`), and models (eg `.fbx`). We recommend you save these files in the **Resources** folder in your project folder. - -We don't recommend you save resource files in the Assets folder. You might be used to organizing files this way if you use Unity®, as Unity® requires resource files and asset files to be in the same folder. Stride doesn't require this, and doing so has downsides. - -For example, imagine an artist has edited 10GB of textures and committed them to source control. At the same time, a designer needs to edit an asset quickly. To do this, the designer gets the latest version of the asset from source control. However, because the assets and resource files are in the same folder, the designer is forced to get the 10gb of files at the same time. If the files are in a separate folder, however, the designer only has to get the folder they need. Additionally, as asset files are much smaller than resource files, it's much faster to navigate the asset history in a dedicated asset folder. - -### Content creation files - -**Content creation files** are created with external content creation tools, such as `.psd` files (Photoshop) or `.max` files (3D Studio Max). - -We don't recommend you save content creation files in your project folder. This is because the files are often large and aren't used in the project directly. Instead, we recommend you save the files in a different version control repository - or, if your version control system supports partial checkouts (such as SVN or Perforce), a different root folder. This means team members only get the files they need. - -## Suggested directory structure - -Following these suggestions, an example folder structure might look like this: - -```cs -- MyGame - - Assets - - texture.sdtex - - Bin - - MyGame.Game - - MyGame.Platform - - obj - - Resources - - texture.png -- ContentCreationFiles - - texture.psd - ``` - -You could even create separate folders for different kinds of content creation file: - -```cs -- MyGame - - Assets - - texture.sdtex - - model.sdtex - - Bin - - MyGame.Game - - MyGame.Platform - - obj - - Resources - - texture.png - - model.fbx -- PhotoshopProjects - - texture.psd -- MayaProjects - - model.mb - ``` - -## Example - -Imagine a team with two programmers, two 2D artists, and two 3D artists. - -* The programmers check out the *MyGame* project folder containing code, assets, and resources. -* The 2D artists check out the game project and the *PhotoshopProjects* folder containing `.psd` files. -* The 3D artists check out the game project and the *MayaProjects* folder containing `.mb` (Maya project) files. - -Now imagine one of the 2D artists changes several `.psd` files and commits 2GB of changes to version control. Because only the 2D artists have the *PhotoshopProjects* folder checked out, only the other 2D artist gets this change. The other team members don't need it. This is an efficient way to share files across projects. +Some version control systems have special mechanisms for handling large files that can improve performance of those systems in large projects. In Stride, these are most commonly the resource files. For more information, visit the [project structure page](project-structure.md). ## See also * [Project structure](project-structure.md) -* [Distribute a game](distribute-a-game.md) \ No newline at end of file diff --git a/en/manual/toc.yml b/en/manual/toc.yml index 8a03d145b..e96a9fc73 100644 --- a/en/manual/toc.yml +++ b/en/manual/toc.yml @@ -115,18 +115,6 @@ items: - name: Asset introspection href: engine/asset-introspection.md - - name: Files and folders - href: files-and-folders/index.md - items: - - name: Project structure - href: files-and-folders/project-structure.md - - name: Cached files - href: files-and-folders/cached-files.md - - name: Version control - href: files-and-folders/version-control.md - - name: Distribute a game - href: files-and-folders/distribute-a-game.md - - name: Game Studio href: game-studio/index.md items: @@ -505,6 +493,45 @@ items: - name: Set the graphics platform href: platforms/set-the-graphics-platform.md + - name: Project + href: files-and-folders/index.md + items: + - name: Project file structure + href: files-and-folders/project-structure.md + - name: Packages + href: files-and-folders/project-packages/index.md + items: + - name: Create a package + href: files-and-folders/project-packages/create-a-package.md + - name: Package properties + href: files-and-folders/project-packages/package-properties.md + - name: Dependencies + href: files-and-folders/project-packages/dependencies.md + - name: External packages + href: files-and-folders/external-packages/index.md + items: + - name: What is Nuget + href: files-and-folders/external-packages/what-is-nuget.md + - name: Using Nuget packages + href: files-and-folders/external-packages/using-nuget-packages.md + - name: Publish a Nuget package + href: files-and-folders/external-packages/publish-a-nuget-package.md + - name: Version control + href: files-and-folders/version-control.md + - name: Cached files + href: files-and-folders/cached-files.md + - name: Building the game + href: files-and-folders/building-the-game/index.md + items: + - name: Setup + href: files-and-folders/building-the-game/setup.md + - name: Building + href: files-and-folders/building-the-game/building.md + - name: Build file structure + href: files-and-folders/building-the-game/build-file-structure.md + - name: Cleaning up + href: files-and-folders/building-the-game/cleaning-up.md + - name: Scripts href: scripts/index.md items: @@ -594,20 +621,6 @@ items: - name: VR sickness href: virtual-reality/vr-sickness.md - - name: NuGet - href: nuget/index.md - items: - - name: Consume Packages - href: nuget/consume-packages.md - - name: Create Packages - href: nuget/create-packages.md - - - name: Extensibility - href: extensibility/index.md - items: - - name: C# Libraries - href: extensibility/csharp-libraries.md - - name: Troubleshooting href: troubleshooting/index.md items: