diff --git a/.github/workflows/stride-docs-github.yml b/.github/workflows/stride-docs-github.yml new file mode 100644 index 000000000..93b7b9857 --- /dev/null +++ b/.github/workflows/stride-docs-github.yml @@ -0,0 +1,44 @@ +# More GitHub Actions for Azure: https://github.com/Azure/actions + +name: Build Stride Docs for GitHub Staging + +on: + workflow_dispatch: + +jobs: + publish-docs: + runs-on: windows-2022 + + steps: + - name: Dotnet Setup + uses: actions/setup-dotnet@v3 + with: + dotnet-version: 8.x + + - name: Checkout Stride Docs + uses: actions/checkout@v3 + with: + path: stride-docs + lfs: true + + - name: Checkout Stride (note the LFS) + uses: actions/checkout@v3 + with: + repository: stride3d/stride + token: ${{ secrets.GITHUB_TOKEN }} + path: stride + lfs: true + + - name: Install DocFX + run: dotnet tool update -g docfx --version 2.74.0 + + - name: Build documentation + run: ./build-all.bat + working-directory: stride-docs + + - name: Deploy + uses: peaceiris/actions-gh-pages@v3.9.2 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: stride-docs/_site + publish_branch: gh-pages \ No newline at end of file diff --git a/.github/workflows/stride-docs-release-azure.yml b/.github/workflows/stride-docs-release-azure.yml index a9a3a7f01..63905c355 100644 --- a/.github/workflows/stride-docs-release-azure.yml +++ b/.github/workflows/stride-docs-release-azure.yml @@ -27,7 +27,7 @@ jobs: - name: Dotnet Setup uses: actions/setup-dotnet@v3 with: - dotnet-version: 6.x + dotnet-version: 8.x # Checkout the Stride Docs repository from the branch that triggered the workflow - name: Checkout Stride Docs @@ -49,7 +49,7 @@ jobs: # This installs the latest version of DocFX and may introduce breaking changes # run: dotnet tool update -g docfx # This installs a specific, tested version of DocFX. - run: dotnet tool update -g docfx --version 2.71.0 + run: dotnet tool update -g docfx --version 2.74.0 - name: Build documentation run: ./build-all.bat diff --git a/.github/workflows/stride-docs-release-fast-track-azure.yml b/.github/workflows/stride-docs-release-fast-track-azure.yml index e256e15c6..9bf4bc61c 100644 --- a/.github/workflows/stride-docs-release-fast-track-azure.yml +++ b/.github/workflows/stride-docs-release-fast-track-azure.yml @@ -20,7 +20,7 @@ jobs: - name: Dotnet Setup uses: actions/setup-dotnet@v3 with: - dotnet-version: 6.x + dotnet-version: 8.x # Checkout the Stride Docs repository from the branch that triggered the workflow - name: Checkout Stride Docs @@ -42,7 +42,7 @@ jobs: # This installs the latest version of DocFX and may introduce breaking changes # run: dotnet tool update -g docfx # This installs a specific, tested version of DocFX. - run: dotnet tool update -g docfx --version 2.71.0 + run: dotnet tool update -g docfx --version 2.74.0 - name: Build documentation run: ./build-all.bat diff --git a/.github/workflows/stride-docs-staging-azure.yml b/.github/workflows/stride-docs-staging-azure.yml index 891b0cd5e..d6232f340 100644 --- a/.github/workflows/stride-docs-staging-azure.yml +++ b/.github/workflows/stride-docs-staging-azure.yml @@ -27,7 +27,7 @@ jobs: - name: Dotnet Setup uses: actions/setup-dotnet@v3 with: - dotnet-version: 6.x + dotnet-version: 8.x # Checkout the Stride Docs repository from the branch that triggered the workflow - name: Checkout Stride Docs @@ -49,7 +49,7 @@ jobs: # This installs the latest version of DocFX and may introduce breaking changes. # run: dotnet tool update -g docfx # This installs a specific, tested version of DocFX. - run: dotnet tool update -g docfx --version 2.71.0 + run: dotnet tool update -g docfx --version 2.74.0 - name: Build documentation run: ./build-all.bat diff --git a/.github/workflows/stride-docs-staging-fast-track-azure.yml b/.github/workflows/stride-docs-staging-fast-track-azure.yml index 7f858be77..49d5b7c74 100644 --- a/.github/workflows/stride-docs-staging-fast-track-azure.yml +++ b/.github/workflows/stride-docs-staging-fast-track-azure.yml @@ -20,7 +20,7 @@ jobs: - name: Dotnet Setup uses: actions/setup-dotnet@v3 with: - dotnet-version: 6.x + dotnet-version: 8.x # Checkout the Stride Docs repository from the branch that triggered the workflow - name: Checkout Stride Docs @@ -42,7 +42,7 @@ jobs: # This installs the latest version of DocFX and may introduce breaking changes # run: dotnet tool update -g docfx # This installs a specific, tested version of DocFX. - run: dotnet tool update -g docfx --version 2.71.0 + run: dotnet tool update -g docfx --version 2.74.0 - name: Build documentation run: ./build-all.bat diff --git a/BuildDocs.ps1 b/BuildDocs.ps1 index dabb9c77a..fad4b8151 100644 --- a/BuildDocs.ps1 +++ b/BuildDocs.ps1 @@ -189,6 +189,9 @@ function Build-EnglishDoc { # Output to both build.log and console docfx build en/docfx.json -o $outputDirectory | Write-Host + # Build pdf files + docfx pdf en/docfx.json -o $outputDirectory | Write-Host + return $LastExitCode } diff --git a/Stride.Docs.sln b/Stride.Docs.sln index 9ac84ac50..9f9de9c1d 100644 --- a/Stride.Docs.sln +++ b/Stride.Docs.sln @@ -7,6 +7,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Stride.Docs", "Stride.Docs. EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{85103FBF-C9A6-4722-B36B-89A58F55C1DF}" ProjectSection(SolutionItems) = preProject + .github\workflows\stride-docs-github.yml = .github\workflows\stride-docs-github.yml .github\workflows\stride-docs-release-azure.yml = .github\workflows\stride-docs-release-azure.yml .github\workflows\stride-docs-release-fast-track-azure.yml = .github\workflows\stride-docs-release-fast-track-azure.yml .github\workflows\stride-docs-staging-azure.yml = .github\workflows\stride-docs-staging-azure.yml diff --git a/en/ReleaseNotes/ReleaseNotes-4.1.md b/en/ReleaseNotes/ReleaseNotes-4.1.md new file mode 100644 index 000000000..1288a9cf4 --- /dev/null +++ b/en/ReleaseNotes/ReleaseNotes-4.1.md @@ -0,0 +1,150 @@ +# Stride 4.1 Release Notes + +July 16th, 2022 + +Stride contributors are proud to announce a new release now running on **.NET 6** supporting the latest **C# 10**. That means you can now head to the download page and start developing your games using the latest .NET technologies. + +## Improvements Summary + +Here's a non-exhaustive list of new improvements: + +- .NET 6 support and [VS 2022 plugin](https://github.com/stride3d/stride/pull/1221) + - Stride 4.1 leverages the power of .NET 6 + - Support for C# 10 +- [Dithered shadows for semi-transparent materials](https://github.com/stride3d/stride/pull/1256) +- [Physics constraints](https://github.com/stride3d/stride/pull/1114) + - Bullet constraints wrapped around in easy to use functionality + - Editor gizmos for physics constraints +- [Physics performance optimization](https://github.com/stride3d/stride/pull/1100) +- [ACES tonemaping](https://github.com/stride3d/stride/pull/1037) +- [Fog image effect](https://github.com/stride3d/stride/pull/1039) +- [Outline image effect](https://github.com/stride3d/stride/pull/1038) +- [Improved editor gizmos](https://github.com/stride3d/stride/pull/1083) +- [C# Intermediate tutorials project](https://github.com/stride3d/stride/pull/1401) + - This Open Collective sub-project was [successfully funded](https://opencollective.com/stride3d/projects/stride-intermediate-tutorials) by the community. All related video recordings are available on Stride's [Youtube channel](https://www.youtube.com/c/Stride3D) and the [tutorials page](https://doc.stride3d.net/latest/en/tutorials/index.html) in the documentation will also be update to reflect the new project. +- Many more minor fixes and quality of life improvements + - [Fixed sample game](https://github.com/stride3d/stride/pull/1217) + - [Simpler Procedural Model creation](https://github.com/stride3d/stride/pull/1285) + - New math signatures ([1122](https://github.com/stride3d/stride/pull/1122), [1121](https://github.com/stride3d/stride/pull/1121), [1090](https://github.com/stride3d/stride/pull/1090)) + - Dispatcher/threadpool improvements + - Ambient Occlusion quality improvement + - And many other fixes + +## Dithered shadows for semi-transparent materials + +Produces semi-transparent shadows by poking more and more holes in the shadow map based on the transparency of the object, shadow map filtering will blur those holes with their neighbor which will result in those partially opaque pixels. + +![Dithered shadow settings](https://i.imgur.com/xFzuNbl.png) + +![Dithered shadow effect comparison](https://i.imgur.com/kHvSy8a.png) + + +## Physics constraints + +Stride's physics system Bullet comes with a set of constraints for you to use in your projects. These constraints are now all visible inside the editor, previewing the constraints using various editor gizmo. + +![preview(to be removed)](https://i.imgur.com/qiaBBpm.png) + +For more information on all the types of constraints, you can read up about them in the [Stride documentation](https://doc.stride3d.net/latest/en/manual/physics/constraints.html) or watch the video below. + +> [!Video https://www.youtube.com/embed/uMZMYpMD3Wg] + +## Physics optimizations + +Retrieving collision and contact information was previously done by re-testing all components for collisions, which, as one might expect, led to awful performance for physics heavy scenes (could take up to and above 90% of the frame). + +Contacts are now lazily evaluated to reduce overhead when nothing ends up reading them. +Users can now read and iterate over all collisions through Simulation.CurrentCollisions. + +## Improved editor gizmos + +The old gizmos weren't very nice to look at, so this feature makes them look better and more user-friendly. It also changes how the rotation gizmo works and adds scale planes to the scale gizmo. + +![New gizmos](https://i.imgur.com/8siM2Lc.png) + +This feature also updates the text on the CameraOrientationGizmo to be XYZ instead of right/left. Still prefer the old text instead of the XYZ coordinate? Don't worry, there's a setting under the viewport settings that swaps it back to the old text. + +![Rotation](https://i.imgur.com/W4zIf7J.png =400x160) + + +## Intermediate tutorials + +One of the first Open Collective sub-projects is the [intermediate C# tutorials project](https://opencollective.com/stride3d/projects/stride-intermediate-tutorials). After discussion in community meetings and with various contributors donating directly to this project, the amount for this project to be included in Stride quickly became a realization. + +![Intermediate tutorials intro screen](https://i.imgur.com/7GVEiSR.jpg) + +With Stride 4.1, you will be able to select the C# intermediate tutorials project as a new template project. The template project contains (at the moment of writing) 11 topics that every developer will want to have a look at. +1. UI basics +1. Collision triggers +1. Raycasting +1. Projecting and Unprojecting +1. Async(hronous) scripts +1. Scene loading +1. Animation basics +1. Audio +1. First person camera +1. Third person camera +1. Navigation + +Each tutorial has a video tutorial accompanying it, which can be found on Stride's [Youtube channel](https://www.youtube.com/c/Stride3D). Below you can find the full playlist. + + + > [!Video https://www.youtube.com/embed/videoseries?list=PLRZx2y7uC8mOE6_L0ZiFxNBE7HmzU2dP7] + +## Known Issues + +### Integrated C# Editor + +The transition to .NET6 unfortunately broke the help tooltips and the code completion of integrated C# code editor. But we decided to accept it for now, as everyone is using a proper C# editor anyways, such as Visual Studio, Rider or Visual Studio Code. + +The reason for the error is that [RoslynPad](https://github.com/roslynpad/roslynpad), the underlaying library, also needs an update or fix. We'll adress this in one of the upcoming minor version releases. + +![](https://i.imgur.com/Gn2i6Js.png) + + +## A little help + +We, contributors, believe that Stride can help .NET game developers make the games they want with ease using their favorite languages. We want to make sure Stride offers the most comfortable environment for developing games, and this takes time and effort. + +Since the free and open-source release of Stride, the community has been growing slowly, so we have decided to open a fund to reward developers for any contribution they make to Stride. We set up an [Open Collective page](https://opencollective.com/stride3d) to manage our funds and allocate money for features that the community would like to see implemented. + +We have various bounties for [bug fixes and features](https://opencollective.com/stride3d/projects) (Vulkan support, decals, morph targets, and many others). If you have or know someone with the skills to tackle those bounties, please reach out to us through the [respective GitHub tickets](https://github.com/stride3d/stride/labels/bounty). You can also contact us through our discord server or on GitHub to propose new bounties. + +## Contributors + +Many thanks to [all the contributors](https://github.com/stride3d/stride/graphs/contributors?from=2021-02-01&to=2022-06-10&type=c) who have donated their time and skill by adding features, fixing bugs, managing the build pipelines, adding documentation, and reviewing PRs. + +### Financial contributors + +Also, a huge thanks to the individuals and companies who contributed financially to our [Open Collective](https://opencollective.com/stride3d)! + +* [ORE System](https://ore-system.com) with a diamond sponsorship +* [xen2](https://opencollective.com/xen2) Core contributor that donated a large portion of the previous Patreon back through Open collective +* [vvvv](https://visualprogramming.net) A visual live-programming environment for easy prototyping and development. It is designed to facilitate the handling of large media environments with physical interfaces, real-time motion graphics, audio and video that can interact with many users simultaneously. vvvv uses Stride +* [Vašo](https://opencollective.com/vaclav) +* [Mitchel Albertz](https://opencollective.com/mitchel-albertz) +* [Bill](https://opencollective.com/bill2) +* [Ideonella](https://opencollective.com/ideonella) +* [Soul Rider](https://opencollective.com/soul-rider) +* [najak3d](https://opencollective.com/guest-ce7ccb03) +* [Eideren](https://opencollective.com/eideren) +* [Jorn Aggror](https://opencollective.com/jorn-theunissen) +* [Marian Dziubiak](https://marian.dziubiak.pl) +* [Youness KAFIA](https://opencollective.com/guest-7253cc41) +* [David Thunderclown](https://www.disruptionworks.co.uk) +* [Christian Clavet](https://opencollective.com/christian-clavet) +* [Marko Viitanen](https://opencollective.com/fador) +* [Aaron Disibio](https://opencollective.com/guest-2f41a631) +* [z16](https://opencollective.com/z16) +* [Incognito](https://opencollective.com/guest-5635aca5) +* [Walter Hulsebos](https://opencollective.com/guest-2170ad46) +* [TheKeyblader](https://opencollective.com/thekeyblader) +* [James Rinker](https://opencollective.com/james-rinker) +* [ztl](https://opencollective.com/guest-6653841d) +* [Bruno Garcia](https://brunogarcia.com) +* [BanditRevolver](https://opencollective.com/banditrevolver) +* [EmmX](https://opencollective.com/emmx) +* [SeleDreams](https://opencollective.com/seledreams) +* [Vignette](https://vignetteapp.org) +* [Longplay Games](https://opencollective.com/guest-a5fa78c8) +* [Redberd36](https://opencollective.com/guest-3fc8bf91) diff --git a/en/ReleaseNotes/ReleaseNotes.md b/en/ReleaseNotes/ReleaseNotes.md index ab49857ca..3001fc74a 100644 --- a/en/ReleaseNotes/ReleaseNotes.md +++ b/en/ReleaseNotes/ReleaseNotes.md @@ -1,150 +1,191 @@ -# Stride 4.1 Release Notes - -July 16th, 2022 - -Stride contributors are proud to announce a new release now running on **.NET 6** supporting the latest **C# 10**. That means you can now head to the download page and start developing your games using the latest .NET technologies. - -## Improvements Summary - -Here's a non-exhaustive list of new improvements: - -- .NET 6 support and [VS 2022 plugin](https://github.com/stride3d/stride/pull/1221) - - Stride 4.1 leverages the power of .NET 6 - - Support for C# 10 -- [Dithered shadows for semi-transparent materials](https://github.com/stride3d/stride/pull/1256) -- [Physics constraints](https://github.com/stride3d/stride/pull/1114) - - Bullet constraints wrapped around in easy to use functionality - - Editor gizmos for physics constraints -- [Physics performance optimization](https://github.com/stride3d/stride/pull/1100) -- [ACES tonemaping](https://github.com/stride3d/stride/pull/1037) -- [Fog image effect](https://github.com/stride3d/stride/pull/1039) -- [Outline image effect](https://github.com/stride3d/stride/pull/1038) -- [Improved editor gizmos](https://github.com/stride3d/stride/pull/1083) -- [C# Intermediate tutorials project](https://github.com/stride3d/stride/pull/1401) - - This Open Collective sub-project was [successfully funded](https://opencollective.com/stride3d/projects/stride-intermediate-tutorials) by the community. All related video recordings are available on Stride's [Youtube channel](https://www.youtube.com/c/Stride3D) and the [tutorials page](https://doc.stride3d.net/latest/en/tutorials/index.html) in the documentation will also be update to reflect the new project. -- Many more minor fixes and quality of life improvements - - [Fixed sample game](https://github.com/stride3d/stride/pull/1217) - - [Simpler Procedural Model creation](https://github.com/stride3d/stride/pull/1285) - - New math signatures ([1122](https://github.com/stride3d/stride/pull/1122), [1121](https://github.com/stride3d/stride/pull/1121), [1090](https://github.com/stride3d/stride/pull/1090)) - - Dispatcher/threadpool improvements - - Ambient Occlusion quality improvement - - And many other fixes - -## Dithered shadows for semi-transparent materials - -Produces semi-transparent shadows by poking more and more holes in the shadow map based on the transparency of the object, shadow map filtering will blur those holes with their neighbor which will result in those partially opaque pixels. - -![Dithered shadow settings](https://i.imgur.com/xFzuNbl.png) - -![Dithered shadow effect comparison](https://i.imgur.com/kHvSy8a.png) - - -## Physics constraints - -Stride's physics system Bullet comes with a set of constraints for you to use in your projects. These constraints are now all visible inside the editor, previewing the constraints using various editor gizmo. - -![preview(to be removed)](https://i.imgur.com/qiaBBpm.png) - -For more information on all the types of constraints, you can read up about them in the [Stride documentation](https://doc.stride3d.net/latest/en/manual/physics/constraints.html) or watch the video below. - -> [!Video https://www.youtube.com/embed/uMZMYpMD3Wg] - -## Physics optimizations - -Retrieving collision and contact information was previously done by re-testing all components for collisions, which, as one might expect, led to awful performance for physics heavy scenes (could take up to and above 90% of the frame). - -Contacts are now lazily evaluated to reduce overhead when nothing ends up reading them. -Users can now read and iterate over all collisions through Simulation.CurrentCollisions. - -## Improved editor gizmos - -The old gizmos weren't very nice to look at, so this feature makes them look better and more user-friendly. It also changes how the rotation gizmo works and adds scale planes to the scale gizmo. - -![New gizmos](https://i.imgur.com/8siM2Lc.png) - -This feature also updates the text on the CameraOrientationGizmo to be XYZ instead of right/left. Still prefer the old text instead of the XYZ coordinate? Don't worry, there's a setting under the viewport settings that swaps it back to the old text. - -![Rotation](https://i.imgur.com/W4zIf7J.png =400x160) - - -## Intermediate tutorials - -One of the first Open Collective sub-projects is the [intermediate C# tutorials project](https://opencollective.com/stride3d/projects/stride-intermediate-tutorials). After discussion in community meetings and with various contributors donating directly to this project, the amount for this project to be included in Stride quickly became a realization. - -![Intermediate tutorials intro screen](https://i.imgur.com/7GVEiSR.jpg) - -With Stride 4.1, you will be able to select the C# intermediate tutorials project as a new template project. The template project contains (at the moment of writing) 11 topics that every developer will want to have a look at. -1. UI basics -1. Collision triggers -1. Raycasting -1. Projecting and Unprojecting -1. Async(hronous) scripts -1. Scene loading -1. Animation basics -1. Audio -1. First person camera -1. Third person camera -1. Navigation - -Each tutorial has a video tutorial accompanying it, which can be found on Stride's [Youtube channel](https://www.youtube.com/c/Stride3D). Below you can find the full playlist. - - - > [!Video https://www.youtube.com/embed/videoseries?list=PLRZx2y7uC8mOE6_L0ZiFxNBE7HmzU2dP7] - -## Known Issues - -### Integrated C# Editor - -The transition to .NET6 unfortunately broke the help tooltips and the code completion of integrated C# code editor. But we decided to accept it for now, as everyone is using a proper C# editor anyways, such as Visual Studio, Rider or Visual Studio Code. - -The reason for the error is that [RoslynPad](https://github.com/roslynpad/roslynpad), the underlaying library, also needs an update or fix. We'll adress this in one of the upcoming minor version releases. - -![](https://i.imgur.com/Gn2i6Js.png) - - -## A little help - -We, contributors, believe that Stride can help .NET game developers make the games they want with ease using their favorite languages. We want to make sure Stride offers the most comfortable environment for developing games, and this takes time and effort. - -Since the free and open-source release of Stride, the community has been growing slowly, so we have decided to open a fund to reward developers for any contribution they make to Stride. We set up an [Open Collective page](https://opencollective.com/stride3d) to manage our funds and allocate money for features that the community would like to see implemented. - -We have various bounties for [bug fixes and features](https://opencollective.com/stride3d/projects) (Vulkan support, decals, morph targets, and many others). If you have or know someone with the skills to tackle those bounties, please reach out to us through the [respective Github tickets](https://github.com/stride3d/stride/labels/bounty). You can also contact us through our discord server or on Github to propose new bounties. - -## Contributors - -Many thanks to [all the contributors](https://github.com/stride3d/stride/graphs/contributors?from=2021-02-01&to=2022-06-10&type=c) who have donated their time and skill by adding features, fixing bugs, managing the build pipelines, adding documentation, and reviewing PRs. - -### Financial contributors - -Also, a huge thanks to the individuals and companies who contributed financially to our [Open Collective](https://opencollective.com/stride3d)! - -* [ORE System](https://ore-system.com) with a diamond sponsorship -* [xen2](https://opencollective.com/xen2) Core contributor that donated a large portion of the previous Patreon back through Open collective -* [vvvv](https://visualprogramming.net) A visual live-programming environment for easy prototyping and development. It is designed to facilitate the handling of large media environments with physical interfaces, real-time motion graphics, audio and video that can interact with many users simultaneously. vvvv uses Stride -* [Vašo](https://opencollective.com/vaclav) -* [Mitchel Albertz](https://opencollective.com/mitchel-albertz) -* [Bill](https://opencollective.com/bill2) -* [Ideonella](https://opencollective.com/ideonella) -* [Soul Rider](https://opencollective.com/soul-rider) -* [najak3d](https://opencollective.com/guest-ce7ccb03) -* [Eideren](https://opencollective.com/eideren) -* [Jorn Aggror](https://opencollective.com/jorn-theunissen) -* [Marian Dziubiak](https://marian.dziubiak.pl) -* [Youness KAFIA](https://opencollective.com/guest-7253cc41) -* [David Thunderclown](https://www.disruptionworks.co.uk) -* [Christian Clavet](https://opencollective.com/christian-clavet) -* [Marko Viitanen](https://opencollective.com/fador) -* [Aaron Disibio](https://opencollective.com/guest-2f41a631) -* [z16](https://opencollective.com/z16) -* [Incognito](https://opencollective.com/guest-5635aca5) -* [Walter Hulsebos](https://opencollective.com/guest-2170ad46) -* [TheKeyblader](https://opencollective.com/thekeyblader) -* [James Rinker](https://opencollective.com/james-rinker) -* [ztl](https://opencollective.com/guest-6653841d) -* [Bruno Garcia](https://brunogarcia.com) -* [BanditRevolver](https://opencollective.com/banditrevolver) -* [EmmX](https://opencollective.com/emmx) -* [SeleDreams](https://opencollective.com/seledreams) -* [Vignette](https://vignetteapp.org) -* [Longplay Games](https://opencollective.com/guest-a5fa78c8) -* [Redberd36](https://opencollective.com/guest-3fc8bf91) +# Stride 4.2 Release Notes + +January 5th, 2024 + +Stride contributors are thrilled to announce the release of Stride 4.2, now fully compatible with .NET 8 and leveraging the latest enhancements in C# 12. This release brings significant improvements in performance, stability, and developer experience. + +A massive thank you to the open-source Stride community for your dedicated contributions. This release saw X contributions from over Y amazing contributors, each playing a crucial role in making Stride 4.2 a reality. + +## What's new in Stride 4.2 +Stride 4.2 includes numerous enhancements and improvements. + +- **[.NET 8 Integration](https://devblogs.microsoft.com/dotnet/announcing-dotnet-8/)**: Experience the power and efficiency of the latest .NET version in your game development. + - Full compatibility with .NET 8, taking advantage of [improved runtime performance](https://devblogs.microsoft.com/dotnet/performance-improvements-in-net-8/) + - **[C# 12 features](https://devblogs.microsoft.com/dotnet/announcing-csharp-12/)**: Utilize cutting-edge language features to write more concise and maintainable code, enhancing coding efficiency and reducing boilerplate code +- **[Changed Assimp binding to Silk.Net.Assimp](https://github.com/stride3d/stride/pull/1158)** + - This change allows us to remove much of the C++/CLR code used by the asset compiler and brings us one step closer to running the asset compiler on non-windows systems. +- [Migration NET6+ and more gettextnet#2](https://github.com/stride3d/gettextnet/pull/2) + - Updated all of gettext.NET to the latest stable version of NET +- [Enable multiple profiler consumers and add a timeline/tracing profiler #1788](https://github.com/stride3d/stride/pull/1788) + - This feature adds a profiler outputting data in chrome://tracing format and changes Profiler to make that possible. +- [Feature: Add Support for F# and VB Project Types #1821](https://github.com/stride3d/stride/pull/1821) + - Currently only for code-only projects + - [F# examples](https://stride3d.github.io/stride-community-toolkit/manual/code-only/examples/basic-examples-fs.html) + - [Visual Basic examples](https://stride3d.github.io/stride-community-toolkit/manual/code-only/examples/basic-examples-vb.html) +- [Stride Diagnostics Analyzer #1864](https://github.com/stride3d/stride/pull/1864) + - Implements a code analyzer to show helpful warnings in your IDE and at compilation when any of your members or structures are incompatible with the serialization system. +- [OpenVR Handle custom resolution specified by the user through VR settings #2000](https://github.com/stride3d/stride/pull/2000) +- [Editor - Add dynamic snapping for selected objects #1801](https://github.com/stride3d/stride/pull/1801) + - Implements a dynamic snapping used while holding down a key (default: Left Shift) on manipulating (rotating/moving/scaling) an object/entity. + - Adds a new Hotkey Setting for dynamic snapping + - Adds a Method to handle dynamic snapping +- [Editor - Let the user pick which animation stack to import in an fbx #1977](https://github.com/stride3d/stride/pull/1977) + - This change introduces a field that users can edit to control which animation the engine should import from the source FBX. +- [Editor - Added the ability to copy imported assets automatically to the Resources dir #1827](https://github.com/stride3d/stride/pull/1827) + - We recommend storing assets within your project's resource directory to avoid issues that may arise when sharing the project or moving files around. + - Whenever users import assets that are located outside of the resource directory, they will now be presented with a dialog box asking them whether the file should be copied to that directory. + +## What's Changed in Details + +* Fixed Exception Caused By Privacy Policy URL in Crash Reporter by @MeharDT in https://github.com/stride3d/stride/pull/1878 +* docs: add acastrodev as a contributor for code by @allcontributors in https://github.com/stride3d/stride/pull/1886 +* docs: add SVNMLR as a contributor for design by @allcontributors in https://github.com/stride3d/stride/pull/1887 +* docs: add JeromyWalsh as a contributor for code by @allcontributors in https://github.com/stride3d/stride/pull/1888 +* docs: add parhamgholami as a contributor for design by @allcontributors in https://github.com/stride3d/stride/pull/1889 +* Fix missing OpenGLES texture formats. by @Basewq in https://github.com/stride3d/stride/pull/1898 +* field typo by @IXLLEGACYIXL in https://github.com/stride3d/stride/pull/1900 +* [Editor] Improve Cameracontrol in Editor by @SVNMLR in https://github.com/stride3d/stride/pull/1879 +* [XML Comment] Minor updates on EFlags in CollisionFilterGroups.cs by @VaclavElias in https://github.com/stride3d/stride/pull/1910 +* Fixes the issue where projects were disappearing from the launcher by @acastrodev in https://github.com/stride3d/stride/pull/1880 +* Fix typo in translations generation by @Ethereal77 in https://github.com/stride3d/stride/pull/1916 +* Handle importing meshes with duplicate material names by @adrsch in https://github.com/stride3d/stride/pull/1920 +* [Native] - Implement some existing C++ methods in C# by @Jklawreszuk in https://github.com/stride3d/stride/pull/1896 +* [Launcher] Prevent launcher automatically closing when offline by @Eideren in https://github.com/stride3d/stride/pull/1912 +* Small refactoring changes in Stride.GameStudio by @Jklawreszuk in https://github.com/stride3d/stride/pull/1741 +* Remove MSBuild.Extras from project by @Jklawreszuk in https://github.com/stride3d/stride/pull/1895 +* [Editor] Allow drag and drop of EntityComponent by @Eideren in https://github.com/stride3d/stride/pull/1921 +* Add editor settings for the camera speed increase/decrease hotkeys by @adrsch in https://github.com/stride3d/stride/pull/1927 +* docs: add adrsch as a contributor for code by @allcontributors in https://github.com/stride3d/stride/pull/1930 +* Let the user set the default Bullet gravity vector in PhysicsSettings by @adrsch in https://github.com/stride3d/stride/pull/1928 +* Migrate Irony.GrammarExplorer to net 6.0 by @Jklawreszuk in https://github.com/stride3d/stride/pull/1932 +* [Core] Enable multiple profiler consumers and add a timeline/tracing profiler by @froce in https://github.com/stride3d/stride/pull/1788 +* [Build] Fixed an errors in the build pipeline associated with having a space in the user name by @Fydar in https://github.com/stride3d/stride/pull/1941 +* fix(graphics): Stop FastTextRenderer VB clobbering by @froce in https://github.com/stride3d/stride/pull/1954 +* Update SSH.NET to 2023.0.0 by @WojciechNagorski in https://github.com/stride3d/stride/pull/1951 +* [Build] Fix Android build error by @froce in https://github.com/stride3d/stride/pull/1949 +* [Docs] Use XML documentation lists by @Fydar in https://github.com/stride3d/stride/pull/1948 +* [Editor] Remove some windows dependencies in editor libraries by @Kryptos-FR in https://github.com/stride3d/stride/pull/1908 +* parse numbers in NumericTextBox using CurrentCulture by @Schossi in https://github.com/stride3d/stride/pull/1811 +* Xml comments fixing 1 by @VaclavElias in https://github.com/stride3d/stride/pull/1918 +* [Presentation] Reduce allocations when parsing number in NumericTextBox by @Kryptos-FR in https://github.com/stride3d/stride/pull/1955 +* [Sample] Replace deprecated GetServiceAs calls by @Eideren in https://github.com/stride3d/stride/pull/1943 +* Fix compiling assets in Android build by @Basewq in https://github.com/stride3d/stride/pull/1905 +* Removed all references to $(SolutionDir) from build artifacts by @JeromyWalsh in https://github.com/stride3d/stride/pull/1894 +* [Serialization] Fix diverging rules for editor and runtime serialization of fields and properties by @Eideren in https://github.com/stride3d/stride/pull/1875 +* feat(extension): Rename launcher buttons for clarity by @acastrodev in https://github.com/stride3d/stride/pull/1872 +* Stride Diagnostics Analyzer by @IXLLEGACYIXL in https://github.com/stride3d/stride/pull/1864 +* Fix Building by @MaximilianEmel in https://github.com/stride3d/stride/pull/1956 +* [Math] Add a couple of helpers for Vectors by @ch3mbot in https://github.com/stride3d/stride/pull/1769 +* Fix #1769 and introduce an optional argument to specify a different r… by @Kryptos-FR in https://github.com/stride3d/stride/pull/1964 +* [Github] Update pull request template to ensure users tried out their changes by @Eideren in https://github.com/stride3d/stride/pull/1965 +* Fixed small xml docs mistake by @Doprez in https://github.com/stride3d/stride/pull/1976 +* Revert "[Editor] Remove some windows dependencies in editor libraries (#1908)" by @Eideren in https://github.com/stride3d/stride/pull/1980 +* [AssemblyProcessor] Fixed packing path. by @Basewq in https://github.com/stride3d/stride/pull/1987 +* [Core] Make object id more performant by @IXLLEGACYIXL in https://github.com/stride3d/stride/pull/1957 +* [Docs] Move bounty paragraph to a more prominent spot by @Eideren in https://github.com/stride3d/stride/pull/1984 +* [Readme] Some additional info for building Stride from source by @tebjan in https://github.com/stride3d/stride/pull/1988 +* [Docs] Update PropertiesDemo.cs by @Eideren in https://github.com/stride3d/stride/pull/1991 +* Fix failing to load data/db/index file on non-Win desktop platforms by @Jklawreszuk in https://github.com/stride3d/stride/pull/1995 +* [Shaders] Fixes `EffectValueDescription.DefaultValue` for negative values by @azeno in https://github.com/stride3d/stride/pull/1990 +* [Editor] Re-introduce workaround for missing input while navigating by @Eideren in https://github.com/stride3d/stride/pull/1897 +* [Build] Fix native library loading picking up invalid files by @Basewq in https://github.com/stride3d/stride/pull/1999 +* Fixes OpenXR by @MaximilianEmel in https://github.com/stride3d/stride/pull/1911 +* [Breaking] Scoping generic extension methods by @Fydar in https://github.com/stride3d/stride/pull/1959 +* Add information about Irony.GrammarExplorer project by @Jklawreszuk in https://github.com/stride3d/stride/pull/2007 +* [VR] Remove framecap from VR sample by @Eideren in https://github.com/stride3d/stride/pull/2002 +* Bump Newtonsoft.Json from 12.0.3 to 13.0.1 in /sources/metrics/Stride.Metrics by @dependabot in https://github.com/stride3d/stride/pull/1539 +* [OpenVR] Handle custom resolution specified by the user through VR settings by @Eideren in https://github.com/stride3d/stride/pull/2000 +* Update NuGet libraries to 6.4.2 by @manio143 in https://github.com/stride3d/stride/pull/2017 +* Let the user pick which animation stack to import in an fbx by @adrsch in https://github.com/stride3d/stride/pull/1977 +* Fixes OpenGL by @MaximilianEmel in https://github.com/stride3d/stride/pull/2023 +* Update dotnet 8 by @Doprez in https://github.com/stride3d/stride/pull/1616 + +## New Contributors +* @adrsch made their first contribution in https://github.com/stride3d/stride/pull/1920 +* @froce made their first contribution in https://github.com/stride3d/stride/pull/1788 +* @Fydar made their first contribution in https://github.com/stride3d/stride/pull/1941 +* @WojciechNagorski made their first contribution in https://github.com/stride3d/stride/pull/1951 +* @Schossi made their first contribution in https://github.com/stride3d/stride/pull/1811 +* @MaximilianEmel made their first contribution in https://github.com/stride3d/stride/pull/1956 +* @ch3mbot made their first contribution in https://github.com/stride3d/stride/pull/1769 + +## Stride 4.2 Feature Overview + +### F# and Visual Basic Integration + +A pivotal PR has enabled **F#** and **Visual Basic** support for game development in Stride. This feature is currently limited to a code-only approach. Detailed insights and tutorials will be provided in upcoming blog posts. + +We will use the [Stride Community Toolkit [WIP]](https://stride3d.github.io/stride-community-toolkit/), with further details to be covered in a separate post. + +Below is a simple example of rendering a capsule using F#: + +```fsharp +open Stride.CommunityToolkit.Engine; +open Stride.CommunityToolkit.ProceduralModels; +open Stride.Core.Mathematics; +open Stride.Engine; + +let game = new Game() + +let Start rootScene = + game.SetupBase3DScene() + game.AddProfiler() |> ignore + + let firstBox = game.CreatePrimitive(PrimitiveModelType.Capsule); + firstBox.Transform.Position <- new Vector3(0f, 2.5f, 0f) + firstBox.Scene <- rootScene + +[] +let main argv = + game.Run(start = Start) + 0 +``` + +![Example basic 3d scene with a capsule](media/ReleaseNotes-4.2/stride-game-engine-example01-basic-3d-scene.webp) + +The equivalent Visual Basic example: + +```vb +Imports Stride.CommunityToolkit.Engine +Imports Stride.CommunityToolkit.ProceduralModels +Imports Stride.Core.Mathematics +Imports Stride.Engine + +Module Program + Private game As New Game() + + Sub Main() + GameExtensions.Run(game, Nothing, AddressOf StartGame) + End Sub + + Private Sub StartGame(rootScene As Scene) + game.SetupBase3DScene() + game.AddProfiler() + + Dim entity = game.CreatePrimitive(PrimitiveModelType.Capsule) + entity.Transform.Position = New Vector3(0, 8, 0) + entity.Scene = rootScene + End Sub +End Module + +``` + +These examples showcase how F# and Visual Basic can be utilized in Stride. The Stride Community Toolkit provides a set of helpers and extensions designed to enhance your experience with the Stride Game Engine. + +## Fixes +Although there have been [many fixes](https://github.com/stride3d/stride/pulls?page=2&q=is%3Apr+merged%3A%3E2023-10-10), we like to point out some of them out: +- [Runtime rasterized fonts are broken #1750](https://github.com/stride3d/stride/issues/1750) +- [Game Studio doesnt reload sub projects after changes #1703](https://github.com/stride3d/stride/issues/1703) +- [Changing the comparison project related and not UPath related #1704](https://github.com/stride3d/stride/pull/1704) +- [Translations fix #1717](https://github.com/stride3d/stride/pull/1717) +- [C# Beginner Tutorial Build Errors #1652](https://github.com/stride3d/stride/issues/1652) +- [Can not create "C# Beginner" project #1650](https://github.com/stride3d/stride/issues/1650) + +## Also good to know +Although not directly tied to Release 4.2, we have made some other big changes. For instance to our website and documentation. We also had another community meeting to address all those new members. +- [Website and documentation revamped and build process updated](https://www.stride3d.net/blog/announcing-website-update/) +- [Contributor section moved to docs](https://doc.stride3d.net/latest/en/contributors/index.html) +- [Community meeting October 2023](https://www.stride3d.net/blog/community-meeting-october-2023/) + +## Acknowledgements +We extend our heartfelt gratitude for all the hard work and donations that have been made. Your generous contributions significantly aid in the continuous development and enhancement of the Stride community and projects. Thank you for your support and belief in our collective efforts. \ No newline at end of file diff --git a/en/ReleaseNotes/media/ReleaseNotes-4.2/stride-game-engine-example01-basic-3d-scene.webp b/en/ReleaseNotes/media/ReleaseNotes-4.2/stride-game-engine-example01-basic-3d-scene.webp new file mode 100644 index 000000000..ee151bb18 --- /dev/null +++ b/en/ReleaseNotes/media/ReleaseNotes-4.2/stride-game-engine-example01-basic-3d-scene.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4766ad01ca6ef73b69f45ea63df99ebacde1ddb49f2bb010a18bdd1c6e505bb6 +size 36000 diff --git a/en/ReleaseNotes/toc.yml b/en/ReleaseNotes/toc.yml index becc95afa..0e34021d3 100644 --- a/en/ReleaseNotes/toc.yml +++ b/en/ReleaseNotes/toc.yml @@ -1,5 +1,7 @@ -- name: 4.1 release notes +- name: 4.2 release notes href: ReleaseNotes.md +- name: 4.1 release notes + href: ReleaseNotes-4.1.md - name: 4.0 release notes href: ReleaseNotes-4.0.md - name: 3.1 release notes diff --git a/en/contributors/contribution-workflow.md b/en/contributors/contribution-workflow.md new file mode 100644 index 000000000..f47efbeb8 --- /dev/null +++ b/en/contributors/contribution-workflow.md @@ -0,0 +1,55 @@ +# Contribution Workflow for Stride Projects + +This guide outlines the fundamental workflow for contributing to various Stride projects, including the Stride Engine, Stride website, and Stride documentation. Whether you're a seasoned contributor or new to the project, this workflow ensures your contributions are effectively integrated. + +## Overview + +The contribution process involves several key steps, from forking the repository to having your changes merged into the main project. This workflow is applicable to contributions to the Stride Engine, Stride website, and Stride documentation. + +``` mermaid +%% Define styles + +%% Main Graph +graph TB + +%% Nodes + Start[Start] + A[Fork the Repository] + B[Create Branch 'X'] + C[Make Updates on Branch 'X'] + D{Has the Upstream Changed?} + E[Sync/Merge Upstream to Forked Main Branch] + F[Sync/Merge Forked Main Branch to Branch 'X'] + G[Test your updates] + H["Create a Pull Request (PR)"] + I[Wait for the PR to be Merged] + J[Address PR Feedback] + K[Sync/Merge Upstream to Your Forked Main Branch] + L{Do You Want to Make More Updates?} + Z[End] + +%% Edges + Start --> A --> B --> C --> D + D -->|Yes| E + D -->|No| G + E --> F --> G + G --> H --> I --> J --> K --> L + L -->|Yes| B + L -->|No| Z +``` + +## Detailed Steps + +1. **Fork the Repository**: Start by forking the repository of the project you wish to contribute to +1. **Create a Branch**: Name your branch appropriately and start making your changes +1. **Make and Test Updates**: Implement your changes and test them within your branch +1. **Review and Create a PR**: Review your updates and create a Pull Request to the main repository +1. **Address Feedback**: If there is any feedback on your PR, address it to improve your contribution +1. **Final Merging**: Once your PR is approved, it will be merged into the main project + +## Best Practices +1. Ensure your updates align with the project goals and guidelines +1. Keep your fork synchronized with the main repository to avoid conflicts +1. Engage with the Stride community for support and collaboration + +For more specific guidelines related to each project, refer to their respective contribution documentation. \ No newline at end of file diff --git a/en/contributors/documentation/content.md b/en/contributors/documentation/content.md index cdbb0f217..b59e89c1f 100644 --- a/en/contributors/documentation/content.md +++ b/en/contributors/documentation/content.md @@ -1,21 +1,6 @@ # Documentation content -- [Content Updates](#content-updates) - - [Small Updates](#small-updates) - - [Major Updates](#major-updates) -- [Manual](#manual) - - [Creating New Page](#creating-new-manual-page) -- [Tutorial](#tutorial) - - [Creating New Tutorial](#creating-new-tutorial-page) -- [Shortcodes and Includes](#shortcodes-and-includes) - - [Alert](#alert) - - [Video](#video) -- [Web Assets](#web-assets) -- [Styling](#styling) - - [Bootstrap Customization](#bootstrap-customization) - - [CSS Guidelines](#css-guidelines) -- [Submitting your Changes](#submitting-your-changes) - -# Content Updates + +## Content Updates If you want to contribute and update the website, please follow the instructions below. @@ -23,201 +8,129 @@ Small updates can be done directly in the GitHub web interface, for bigger updat You can use any text editor to make changes. If you are using **Visual Studio**, you can open `Stride.Docs.sln` solution file in the root of the repository and start making your updates directly from this IDE. -You are always welcome to create an issue to discuss your changes before you start working on them. +You are always welcome to [create an issue](https://github.com/stride3d/stride-docs/issues) to discuss your changes before you start working on them. -## Small Updates +### Small Updates Creating an issue is not required for small updates, but it is recommended to let others know what you are working on. If you are not sure whether your update is small or not, please create an issue first. -### What is a small update? +#### What is a small update? We can define small updates as changes to the content of the website: -- Update the content of an existing page (manual, tutorial or release note) -- Add a [new manual](#creating-new-manual-page) or [tutorial](#creating-new-tutorial-page) +- Update the content of an existing page (manual, tutorial or release note, ..) +- Add a [new manual](#creating-new-manual-page) or [tutorial](#creating-new-tutorial-page) or any new content - Fix a typo -### Steps +#### Steps + +> [!NOTE] +> This guide assumes that you are already familiar with updating files on GitHub. -**Note:** This guide assumes you are already familiar with updating files in GitHub. +For the following instructions, use the [Stride Docs GitHub repository](https://github.com/stride3d/stride-docs): -1. Go to the [Stride Docs GitHub](https://github.com/stride3d/stride-docs) repository. -1. Locate the file you wish to edit. -1. Click the `Edit this file` (pencil) icon in the top right corner. -1. If prompted, fork the repository by clicking `Fork this repository`. -1. Make your changes to the file, then write a brief commit message describing the changes. -1. Click on the `Propose changes` button. -1. On the next screen, click the `Create pull request` button. -1. Provide a title and description for your pull request, and click on `Create pull request` again. -1. Wait for the review and merge. +[!INCLUDE [small-updates](../../includes/small-update-instructions.md)] -## Major Updates +### Major Updates [Creating an issue](https://github.com/stride3d/stride-docs/issues) is **required** for major updates, so that others can comment on your changes and provide feedback. -We can define bigger updates as changes to the design of the website, where you would like to see the impact of your changes beforehand to assess the desired result: +Major updates can be defined as significant changes to the website's design, where it's beneficial to preview the impact of your changes to ensure they achieve the desired result. This may include: -- Update docfx version -- Update layouts +- Update Docfx version +- Modifying layouts +- Revamping design elements -You would start with the local development environment, which is described in the [Installation](installation.md) section. +Start by setting up your local development environment, as described in the [Installation](installation.md) section. After making and testing your changes locally, you should create a pull request to merge your changes into the `master` branch. -Then you would make your changes and test them locally. Once you are happy with the result, you can create a pull request to merge your changes into the `master` branch. +When submitting a pull request, especially for substantial changes, it's recommended to include **screenshots** or a link to your local deployment. This approach helps maintainers visualize and assess your proposed changes more effectively. If you prefer to use GitHub infrastructure for your demonstrations, refer to our [Deployment to GitHub Pages guide](deployment-azure.md#deployment-to-github-pages) for instructions on deploying via GitHub Actions. -# Manual +## Manual These pages contain information about how to use Stride, an open-source C# game engine. -## Creating New Manual Page +> [!IMPORTANT] +> **SEO Note:** Ensure that the file name includes essential keywords related to the content of the article. This is crucial because the file name dictates the URL of the content page, which plays a significant role in search engine optimization (SEO). + +### Creating New Manual Page 1. Create a new file in the `manual` folder, in the already existing folders (e.g. animation, audio, ..) or create a new folder in the `manual` folder. - - If you created a new folder, make sue that you create also index.md file in this folder. + - If you created a new folder, make sue that you create also `index.md` file in this folder. 1. Use any existing page as a template for the new page. -1. Update `toc.md` file in the `manual` folder to include the new page or folder. The `toc.md` file contains the table of contents for the manual pages, which is displayed on the left side of the manual pages. +1. Update `toc.yml` (or `toc.md`) file in the `manual` folder to include the new page or folder. The `toc.yml` file contains the table of contents for the manual pages, which is displayed on the left side of the manual pages. These pages are also included in the optionally generated PDF file. -## Naming Convention +### Naming Convention Observe existing pages and folders for the naming convention. -## Media +### Media You can observe that existing folders might have a `media` folder. This folder contains images and videos used in the manual pages. You can use this folder or create a new one in your folder. If possible make sure that images are `.webp` format and videos are `.mp4` format. -# Tutorial +## Tutorial These pages contain tutorials on how to use Stride, an open-source C# game engine. -## Creating New Tutorial Page +### Creating New Tutorial Page 1. Create a new tutorial folder in the `tutorial` folder. -1. Create a new index.md file in this folder. Observe existing tutorials for the content of this file. +1. Create a new `index.md` file in this folder. Observe existing tutorials for the content of this file. 1. Create markdown files for each step of the tutorial. Observe existing tutorials structure for the content of these files. -1. Update `toc.md` file in the `tutorial` folder to include the new tutorial folder. The `toc.md` file contains the table of contents for the tutorial pages, which is displayed on the left side of the tutorial pages. +1. Update `toc.yml` file in the `tutorial` folder to include the new tutorial folder. The `toc.yml` file contains the table of contents for the tutorial pages, which is displayed on the left side of the tutorial pages. -## Naming Convention +### Naming Convention Observe existing pages and folders for the naming convention. -## Media +### Media You can observe that existing tutorials have a `media` folder. This folder contains images. If possible make sure that images are `.webp` format. The videos should be uploaded to YouTube and embedded in the tutorial pages. -# Shortcodes and Includes - -Read docfx documentation about [shortcodes and inludes](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet). Some of them are briefly described below. - -## Alert - -```liquid -> [!NOTE] -> Information the user should notice even if skimming. - -> [!TIP] -> Optional information to help a user be more successful. - -> [!IMPORTANT] -> Essential information required for user success. - -> [!CAUTION] -> Negative potential consequences of an action. - -> [!WARNING] -> Dangerous certain consequences of an action. -``` - -## Video - -We should consider hosting our videos on YouTube whenever possible. - -You can embed a video by using the following Markdown syntax: - -`> [!Video embed_link]` +## Other Sections -Replace `embed_link` with the YouTube video link. This shortcode renders as: +In addition to the Manual and Tutorial sections mentioned above, the same principles apply to both existing and new sections. Follow the established formats and conventions to ensure consistency and clarity throughout the documentation. -Example: -```md -> [!Video https://www.youtube.com/embed/-IXw64hZAqg] -``` +## Shortcodes and Includes -To embed a video hosted elsewhere, use the following shortcode: +Docfx supports additional markdown syntax to enrich content. These syntaxes are specific to Docfx and **may not render** correctly on other platforms, like GitHub. -### Hosting our own videos +For more information, read the Docfx documentation on [markdown, shortcodes and includes](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet). Some commonly used features include: -`{% video 'url' %}` +- **Alert**: These are block quotes that render with distinct colors and icons, highlighting the importance or nature of the content +- **Video**: Embed video content directly into your documentation +- **Image**: Insert images to enhance the visual aspect of the documentation +- **Math Expressions**: Integrate mathematical notations and expressions +- **Mermaid Diagrams**: Embed [mermaid diagrams](https://mermaid.js.org/) for flowcharts and other graphical representations +- **Include Markdown Files**: Include content from other markdown files seamlessly +- **Code Snippet**: Insert code snippets for better clarity and demonstration +- **Tabs**: Organize content into tabbed sections for improved readability -Replace `url` with the video URL (e.g., .mp4 file). Make sure you have a matching .jpg file with the same name as the .mp4 file for the poster attribute. This shortcode renders as: +## Web Assets -```html - -
-``` +Our main web assets include: -### How to encode videos +- `template/partials/affix.tmpl.partial` - Currently not functioning +- `template/partials/footer.tmpl.partial` - Currently not functioning +- `template/public/main.css` - Contains minor Bootstrap CSS overrides +- `template/public/main.js`: + - Sets the top navigation icons, such as GitHub, Discord, Twitter + - Injects the Stride Docs version selection above the filter in the side navigation + - Injects the Stride Docs language selection into the top navigation +- `docfx.json` - The HTML footer is included in the `_appFooter` section -Videos can be generated by many software in various formats & size, so they might end up being incompatible with web browsers or mobile, or simply be way too large. -It is better to stick to a format with low requirements such as H264 baseline profile (works almost everywhere). +## Styling -To do so, process the file using [fmpeg](https://ffmpeg.org/download.html): +### Bootstrap Customization -``` -ffmpeg -i myvideo_original.mp4 -profile:v baseline -level 3.0 -an myvideo.mp4 -``` +We utilize the `modern` template provided by Docfx, which employs the [Bootstrap](https://getbootstrap.com/) framework, version **5.3**. This includes the dark theme, enabled by Docfx. -Also, generate a static thumbnail so that people can preview it before downloading the video (very important on mobile): - -ToDo: Check if webp can be generated from ffmpeg - -``` -ffmpeg -i myvideo.mp4 -vframes 1 -f image2 -y myvideo.jpg -``` - -ToDo: Maybe we could provide a simple tool to do that without using command line. - - - -# Web Assets - -Our main web assets are: - -- `css/custom-bootstrap.scss` - Slightly modified Bootstrap theme - - Some Bootstrap variables are overridden - - Some Bootstrap parts are disabled so they don't bloat the website (e.g. button-group, breadcrumb, ..) -- `css/styles.scss` - Main stylesheet - - Styles also Dark Mode -- `css/syntax-highlighting.scss` - Imported prismjs styling, Light and Dark Mode -- `assets/search.liquid` - Script for search -- `assets/site.liquid` - Not used -- `assets/theme-selector.liquid` - Script for Ligth and Dark Mode selection -- `search.liquid` - Renders as `search.json` contains search meta - - -# Styling - -## Bootstrap Customization - -Our website uses the [Bootstrap](https://getbootstrap.com/) framework, version **5.3**. - -Prioritize using Bootstrap styling before introducing any custom styles. - -## CSS Guidelines - -We aim to write minimum CSS code to keep the website lightweight and use the Bootstrap framework as much as possible. - -Further, we are using also [FontAwesome](https://fontawesome.com/) free icons. The icons are loaded in the `src/_includes/css/main.css` file. - -# Submitting your Changes +> [!IMPORTANT] +> Prioritize the use of Bootstrap's inherent styling before integrating any custom styles. You should be familiar with [Bootstrap Utilities](https://getbootstrap.com/docs/5.3/utilities/api/) which help you to achieve most of the styling requirements. -Assuming you have made all necessary changes and tested them on the development server, you can submit a pull request to the `master` branch. The pull request will be reviewed and merged by the website maintainers. +### CSS Guidelines -Steps to contribute your updates: +Our goal is to write minimal CSS code to keep the website lightweight, leveraging the Bootstrap framework to the fullest extent possible. -1. Commit your changes to your forked repository: - - Commit the changes with a meaningful message - - Push the changes to your forked repository -1. Create a pull request to the main repository: - - You can create a pull request from your forked repository by navigating to Pull requests page and click **New pull request** button - - Select the **master** branch as the base branch and your branch as the compare branch - - Click **Create pull request** button +## Submitting your Changes -Once your pull request has been reviewed and approved, your changes will be merged into the main repository and deployed to the website. \ No newline at end of file +[!INCLUDE [submitting-changes](../../includes/submitting-changes.md)] \ No newline at end of file diff --git a/en/contributors/documentation/deployment-azure.md b/en/contributors/documentation/deployment-azure.md index 98b4ec6d3..933cdff73 100644 --- a/en/contributors/documentation/deployment-azure.md +++ b/en/contributors/documentation/deployment-azure.md @@ -1,16 +1,19 @@ -# Deployment in Azure -- [Step-by-Step Guide to Deploying Azure Web Apps (Windows) with IIS](#step-by-step-guide-to-deploying-azure-web-apps-windows-with-iis) - - [Setting up a new Azure Web App (Windows) with IIS](#setting-up-a-new-azure-web-app-windows-with-iis) - - [Adjusting the Web App Configuration](#adjusting-the-web-app-configuration) - - [Modifying the GitHub Action](#modifying-the-github-action) +# Deployment -# Step-by-Step Guide to Deploying Azure Web Apps (Windows) with IIS +Our team has explored various deployment options, ultimately selecting the method detailed in this guide for its efficacy. Additionally, for demonstration purposes, you can refer to the [Deployment to GitHub Pages](deployment-azure.md#deployment-to-github-pages) section for alternative deployment strategies you can use to showcase your updates. -This guide assumes you already have permission to access the Azure subscription. +## Deploying to Azure Web Apps (Windows) with IIS -## Setting up a new Azure Web App (Windows) with IIS +This guide is crafted for individuals who already have access to the Azure subscription. It provides step-by-step instructions for setting up a new Azure Web App, specifically tailored for staging environments. Note that the process for setting up a production environment is similar, but requires a distinct web app name. -These instructions pertain to the staging environment. For the production environment, follow the same steps, but with a different web app name. +Deployments to Azure Web Apps are automated through GitHub Actions, forming an integral part of our Continuous Integration/Continuous Deployment (CI/CD) process. The CI/CD pipeline is configured to automatically trigger deployments upon merging changes into either the `staging` or `release` branches. + +> [!NOTE] +> The deployment process outlined here is already established and running, hosted on Azure and sponsored by the .NET Foundation. This guide serves primarily as a reference for maintainers in the event that a new deployment setup is required. + +### Setting up a new Azure Web App + +Follow these instructions carefully to establish your Azure Web App in a staging environment. For deploying in a production environment, replicate these steps with an alternate web app name for differentiation. 1. Navigate to the [Azure Portal](https://portal.azure.com/) 1. Select **Create a resource** @@ -18,7 +21,7 @@ These instructions pertain to the staging environment. For the production enviro 1. In the Basic Tab - Choose your existing subscription and resource group - Under Instance Details, enter: - - Name: **stride-website-staging** + - Name: **stride-docs-staging** - Publish: **Code** - Runtime stack: **ASP.NET V4.8** - OS: **Windows** @@ -27,7 +30,7 @@ These instructions pertain to the staging environment. For the production enviro - Click **Next** 1. In the Deployment Tab - This step can be completed later if preferred. - Enable Continuous deployment - - Select account, organisation `Stride`, repository `stride-website` and branch `staging-next` + - Select account, organisation `Stride`, repository `stride-docs` and branch `staging` - Click **Next** 1. In the Monitoring Tab - Leave all settings as default @@ -43,30 +46,76 @@ These instructions pertain to the staging environment. For the production enviro - Click **Create** - The GitHub Action will be added to the repository and run automatically. It will fail at this stage, but this will be resolved in the subsequent steps. -## Adjusting the Web App Configuration +> [!CAUTION] +> If you have completed the **Deployment Tab** process, ensure that the deployment profile includes the **DeleteExistingFiles** property. This property may need to be set to `False` or `True` depending on the specific requirements of your deployment. For instance, Stride Docs deployment retains files from previous deployments, allowing multiple versions like `4.2`, `4.1`, etc., to be maintained. Adjust this setting based on your deployment needs. + +### Adjusting the Web App Configuration 1. Proceed to the newly created Web App 1. Click on **Configuration** 1. Select **General Settings** -1. Change the Http Version to **2.0** +1. Change the `Http version` to **2.0** +1. Change `Ftp state` to **FTPS only** +1. Change `HTTPS Only` to **On** 1. Click **Save** to apply the changes -## Modifying the GitHub Action +### Modifying the GitHub Action -The previous step will have added a GitHub Action to the repository, which will fail at this point. You need to modify the GitHub Action to correct the issue. +The previous step will have added a GitHub Action to your repository, which might fail initially. To address this, you need to modify the GitHub Action: 1. Navigate to the repository -1. Select Actions +1. Select **Actions** 1. You have the option to stop the currently running action -1. Locate the new GitHub Action *(within this folder Stride Website -> staging-next repo -> .github -> workflows)* which was automatically generated by the Azure Portal. We will need to reference the properties app-name and publish-profile and disable the push trigger. +1. Locate the new GitHub Action file *(stride-docs/blob/master/.github/workflows/some-file-name.yml)* that was automatically generated by Azure Portal. We need to extract the `app-name` and `publish-profile` values from it and disable the push trigger. - To disable the push trigger, retain only **workflow_dispatch** (manual trigger) as shown below: ``` on: # push: # branches: - # - staging-next + # - staging workflow_dispatch: ``` -1. Open the `stride-website-staging-azure.yml` workflow and update it with the properties from the previous step. Save your changes. -1. This workflow may also need to be added to the production branch master if it is not already there. -1. Execute the workflow stride-website-staging-azure.yml. Ensure you select the correct branch staging-next and click **Run workflow**. This action will deploy the website to the Azure Web App. +1. Open the `stride-docs-staging-azure.yml` workflow and update it with the values obtained in the previous step. Save your changes. +1. This workflow might also need to be added to the `master` branch if it is not already present. +1. Execute the workflow `stride-docs-staging-azure.yml`. Ensure you select the correct branch `staging` and click **Run workflow**. This action will deploy the website to the Azure Web App. + +### GitHub Actions + +- `stride-website-github.yml`: Enables manual deployment to GitHub Pages in a forked repository, primarily for showcasing updates. +- `stride-docs-release-azure.yml`: Automates deployment to production upon merging changes into the `release` branch, with a manual trigger option also available. +- `stride-docs-release-fast-track-azure.yml`: Provides manual deployment to production, bypassing the creation of artifacts. +- `stride-docs-staging-azure.yml`: Facilitates automatic deployment to [staging](https://stride-doc-staging.azurewebsites.net/latest/en/index.html) when changes are merged into the `staging` branch, and includes a manual trigger option. +- `stride-docs-staging-fast-track-azure.yml`: Allows for manual deployment to staging, skipping the creation of artifacts. +- `stride-website-wiki.yml`: Automatically deploys to the GitHub Wiki when changes are pushed to the `wiki` folder in the `master` branch, also includes a manual trigger feature + +## Deployment to GitHub Pages + +To showcase your updates, especially helpful for design changes pending review, you can deploy the docs website either to your infrastructure or to GitHub Pages, a free hosting service. Once deployed, share the link with us for review. + +### Prerequisites + +In your `stride-docs` repository: + +1. Navigate to **Settings** → **Actions** → **General** → **Workflow Permissions** + - Choose **Read and write permissions** + +### Run GitHub Action + +1. Go to **Actions**, select **Build Stride Docs for GitHub Staging** + - Click **Run workflow**; you may optionally select a branch +2. Monitor the build logs while the action is in progress +3. Upon successful build, a `gh-pages` branch will be created +4. Navigate to **Settings** → **Pages** → **Branch** section + - Choose the `gh-pages` branch with the root option and click **Save** +5. After saving, an internal GitHub Action **pages build and deployment** is automatically created and triggered, deploying the content to the GitHub Pages website +6. The website will be accessible at `https://[your-username].github.io/stride-docs/4.2/en` + - Change the version in the URL accordingly. You might see some JS errors, related to file expected in the root level. + +### Add Custom Domain + +Optionally, you can add also a custom domain. This should resolve JS url related errors. + +1. Go to **Settings** → **Pages** → **Custom domain** + - Enter your custom domain and follow the instructions for verification +1. Upon saving, the **pages build and deployment** action is triggered again, adding a `CNAME` file containing your custom domain name to the `gh-pages` branch +1. Your website should now be fully operational on your custom domain, for example, `https://stride-docs.vaclavelias.com/4.2/en/` is hosted on GitHub Pages \ No newline at end of file diff --git a/en/contributors/documentation/deployment.md b/en/contributors/documentation/deployment.md deleted file mode 100644 index b74f1452b..000000000 --- a/en/contributors/documentation/deployment.md +++ /dev/null @@ -1,54 +0,0 @@ -# Deployment -We tested five different deployment methods and chose Azure Web Apps IIS ASP.NET 4.8. - -- [GitHub Pages](#github-pages) -- [Azure Web Apps](#azure-web-apps) - - [Deploying with .NET Framework](#deploying-with-net-framework) - -# GitHub Pages - -GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files directly from a repository on GitHub, optionally processes the files through a build process, and publishes a website. It is an excellent way to host a website for free and serves as an effective method for testing a website before deploying it to a paid hosting service. - -We use GitHub Pages to test our website. Any content pushed to the `staging` branch of the `stride-website` repository is automatically deployed to the `gh-pages` branch, from which GitHub Pages builds and publishes the website. - -To manage the build and deployment process, we use the GitHub action `stride-web-staging-github.yml`. This action is triggered when: - -1. A push is made to the staging branch -1. The action is manually triggered - -You can manually trigger the action by navigating to the **Actions** tab and clicking the **Run workflow** button. - -The `gh-pages` branch is a special branch used by GitHub Pages to host the website and should not be edited directly. Any changes made to the `gh-pages` branch will be overwritten by the subsequent `staging` branch deployment. - -The GitHub action `stride-web-staging-github.yml` works as follows: - -1. The action is triggered when: - - A push is made to the staging branch - - The action is manually triggered -1. `paths-ignore` is used to ignore specific changes to the `staging` branch - - Current exclusions: `README.md`, `wiki/**`, `.github/**` -1. The remaining steps in the action are self-explanatory - -# Azure Web Apps - -## Deploying with .NET Framework - -The .NET Framework uses IIS to host the website, which serves any static files. - -The `web.config` file is used to configure IIS, including: - -- Mime types for static files -- Redirects -- Gzip compression -- Static file caching -- Custom Headers -- Custom 404 - -The GitHub action `stride-website-staging-azure` builds the website and deploys it to Azure Web Apps. - -[Step-by-Step Deployment Guide for Azure Web Apps (Windows) with IIS and Stride Website](deployment-azure.md). - -**Recommendation** - -1. **ASP.NET 4.8 with IIS** for Staging -2. **ASP.NET 4.8 with IIS** for Release \ No newline at end of file diff --git a/en/contributors/documentation/docfx.md b/en/contributors/documentation/docfx.md index f899385e3..4412821e4 100644 --- a/en/contributors/documentation/docfx.md +++ b/en/contributors/documentation/docfx.md @@ -1,140 +1,85 @@ -# DocFX -[docfx](https://www.11ty.dev/) is a static site generator that uses JavaScript as its templating language. It is a very powerful tool that allows us to create a website with a lot of flexibility and customization. It is also very easy to use and learn. This section will cover the basics of Eleventy configuration on the Stride website. Creating and updating the content is described in our [Content](content.md) section. - -We used to use **Jekyll** as our static site generator, but we decided to switch to Eleventy because of its flexibility and ease of use. We also wanted to use a tool that is more widely used and supported, which is why we decided to switch to Eleventy. - -# Table of Contents -- [Packages and Dependencies](#packages-and-dependencies) -- [Configuration](#configuration) -- [Global Data](#global-data) -- [Folder Structure](#folder-structure) -- [Layouts](#layouts) -- [Includes](#includes) -- [Advanced Topics](#advanced-topics) - - [Creating Custom Shortcodes and Includes](#creating-custom-shortcodes-and-includes) - -# Packages and Dependencies -Eleventy is a **Node.js** application. Please follow our [installation](installation.md) guide to install Node.js and all the required dependencies. - -Packages we currently use: - -- Dev Dependencies - - `@11ty/eleventy` v2.0 - Main package for the static site generator - - `@11ty/eleventy-plugin-rss` - RSS feed plugin - - `@11ty/eleventy-plugin-syntaxhighlight` - Syntax highlighting plugin (dark and light theme in `/css/syntax-highlighting.scss`) -- Dependencies - - `@11ty/eleventy-fetch` - Fetch plugin - - `@fortawesome/fontawesome-free` - Font Awesome with a variety of awesome icons 😃🤩 - - `bootstrap` - Bootstrap 5.3 - - `lunr` - Lunr search plugin that consumes local `search.json (/search.liquid)` and remote `index.json` from the docs website; the script is in `/assets/scripts/search.liquid` - - `markdown-it-anchor` - Anchor plugin for markdown-it - - `markdown-it-table-of-contents` - Table of contents plugin for markdown-it, used mainly in blog posts as `[[TOC]]` - - `sass` - Sass compiler for our `/css/*.scss` files +# Docfx -# Configuration -The Eleventy configuration is located in the `.eleventy.js` file at the root of the project. This file contains all the configuration settings for the Eleventy build process. As it is a JavaScript file, you can utilize all JavaScript features and syntax within it. +[Docfx](https://dotnet.github.io/docfx/index.html) is a static site generator that uses C# as its templating language. It is an exceptionally powerful tool, offering immense flexibility and customization options for creating a documentation website. Moreover, Docfx is user-friendly and easy to learn. This section covers the basics of Docfx configuration for the Stride Docs website, while the creation and updating of content are detailed in our [Content](content.md) section. -**What do you find in this file?** +After reviewing various static site generator options, we decided to continue using Docfx, particularly in light of the release of the new `modern` Docfx template. This template leverages Bootstrap 5.3 and has recently introduced a dark theme feature. -- plugins configuration - All the plugins we use -- pass through files - Files that are copied to the output folder without any processing -- custom collections - Custom collections used in the templates like `tagList` and `yearList` -- filters - Custom filters used in the templates -- custom shortcodes - Custom [shortcodes](content.md#shortcodes-and-includes) used in the templates, pages or blog posts. +## Packages and Dependencies -The file is well-commented and should be self-explanatory. If you need to add a new configuration, please follow the existing structure and include a comment to explain the new configuration. +Currently, we are not utilizing any additional packages. -# Global Data +## Configuration -Global data is located in the `/_data` folder. It contains all the global data that is accessible in all the templates. Currently, we have these JSON files: +The configuration for Docfx is located in the `en\docfx.json` file. This file contains all the necessary settings for the Docfx build process. -- `site.json` - Contains all the global data for the website, used in the templates and shortcodes. -- `features.json` - Contains all the data for the features page and its features sections. -- `sponsors.json` - Contains sponsor information used in multiple places on the website. +Contents of the Configuration File: -Our `site.json` file contains these main properties, with only some listed below: +- **API Sources**: Specifies the Stride path and selected projects for API documentation generation +- **Global Metadata**: Contains global configuration settings for the documentation build +- **File Metadata**: Defines folder sections to be processed for documentation generation, such as Manuals, Tutorials, etc. +- **Resource - Pass Through Files**: Lists files that are copied directly to the output folder without processing +- **Other Configuration**: Explore the file for additional configuration options -- `dark-mode` - Dark mode toggle `true|false` -- `alert-banner` - Global banner below navigation `true|false` -- `docs-search` - Includes docs website content in the search `true|false` -- `links` - Contains all the main links used across the website (social media, docs, GitHub, etc.) -- `authors` - Contains all the authors used in the blog posts -- repeated data - like `csharp-version`, `dotnet-version`, `download-version` which are used in multiple places on the website and are updated with every release +For more details on configuration options, visit the [Docfx Configuration Documentation](https://dotnet.github.io/docfx/docs/config.html). -# Folder Structure +## Global Data -The folder structure is crucial for Eleventy, as it determines the output of the build process. The folder structure is organized as follows: +Docfx currently does not support global data like 11ty. At present, *Mustache* can only be used in templates. -**Folders** +## Folder Structure -- `/_data` - Global data -- `/_drafts` - Draft blog posts (excluded from the build process) -- `/_includes` - Reusable code snippets that can be included in multiple pages -- `/_layouts` - Main layout pages (`container`, `page`, `post`) using the primary layout page `default` -- `/_site` - Output build folder (excluded in `.gitignore` and used for deployment) -- `/assets` - Additional assets, such as scripts -- `/blog` - Blog content page -- `/css` - Website stylesheets -- `/files` - Stride installer files -- `/images` - Images and MP4 files used on the website -- `/legal` - Content page -- `/posts` - Blog posts -- `/posts/2014-2021` - Old blog posts which are merged to the same output folder as `/posts` - - this folder is only for convenience to easily access new posts +The folder structure plays a vital role in the documentation generation process, as it determines the output of the build. The structure is organized as follows: -**Files** +### Folders -- `/posts/posts.json` - Blog post defaults so they don't have to be repeated in the front matter -- `*.html` - HTML content pages -- `*.liquid` - Liquid content pages -- `*.md` - Markdown content pages -- `*.njk` - Nunjucks content pages -- `.eleventy.js` - Eleventy configuration file -- `.eleventyignore` - Lists files and folders not to be processed by Eleventy -- `package.json` - Eleventy project metadata used by `npm` +- `.github`: Contains GitHub Action workflows +- `_site`: The output build folder (excluded in `.gitignore` and used for deployment) +- `en`: Contains the English language documentation +- `en\api`: Automatically generated folder from the Stride API +- `en\contributors`: Documentation for contributors +- `en\diagnostics`: Diagnostic pages referenced by Stride solution warnings in the IDE +- `en\examples`: Additional content for C# XML comments, which are merged into API documentation and linked by **uids** +- `en\includes`: Markdown files whose content can be included in multiple `.md` files across the documentation. +- `en\manual`: Documentation for the manual +- `en\media`: Main media assets +- `en\ReleaseNotes`: Documentation for release notes +- `en\template`: Docfx assets for minor template customization, including CSS and JS files +- `en\tutorials`: Documentation for tutorials +- `jp`: Japanese language documentation, translated from the English version (currently not updated) +- `wiki`: GitHub wiki content - Excluded from the build process and used only for wiki deployment. This section will be decommissioned as the content has been moved to Stride Docs. -**Non Eleventy files:** +### Files -- `.nojekyll` - Special file for GitHub Pages -- `CNAME` - Custom domain for GitHub Pages -- `appsettings.json` - ASP.NET Core configuration file -- `appsettings.Development.json` - ASP.NET Core configuration file -- `Program.cs` - ASP.NET Core startup file -- `Stride.Web.csproj` - ASP.NET Core project file -- `Stride.Web.sln` - ASP.NET Core solution file -- `Stride.Web.csproj.user` - ASP.NET Core project file -- `web.config` - Configuration file for IIS deployment -- `web.Release.config` - Configuration file for Windows ASP.NET Core deployment +- `en\*.md`: Markdown content pages +- `en\*.yml`: Table of content files +- `en\.nojekyll`: A flag file for GitHub Actions +- `en\docfx.json`: Docfx configuration file +- `en\filterConfig.yml`: Rules for API exclusion +- `en\languages.json`: Configuration file for languages +### Non Docfx Files -**Note:** This project includes ASP.NET Core solution and files, as they can be used seamlessly with Eleventy. Read more about this in our [Installation](installation.md#asp-net-core.md) section. +- `appsettings.json`: Configuration file for ASP.NET Core. +- `appsettings.Development.json`: Development-specific configuration file for ASP.NET Core. +- `build-all.bat`: Batch file used in GitHub Actions CI/CD to build all documentation using `BuildDocs.ps1`. +- `BuildDocs.ps1`: PowerShell script responsible for building documentation. Refer to [pipeline](documentation-generation-pipeline.md) for details. +- `OldDocsFix.ps1`: Temporary PowerShell script for fixing old documentation. +- `Program.cs`: Startup file for ASP.NET Core. +- `run.bat`: Batch file to run `BuildDocs.ps1` in interactive mode. +- `run-fix.bat`: Temporary batch file to run `OldDocsFix.ps1`. +- `Stride.Docs.csproj`: ASP.NET Core project file. +- `Stride.Docs.sln`: ASP.NET Core solution file. +- `Stride.Docs.csproj.user`: User-specific ASP.NET Core project file. +- `versions.json`: Configuration file managing versions of Stride documentation. +- `web.config`: Configuration file for IIS deployment. +> [!NOTE] +> This project includes the Visual Studio solution `Stride.Docs.sln`, allowing you to edit the files using the Visual Studio IDE. -# Layouts +## Layouts -All the layouts are located in the `/_layouts` folder. The `default` layout is the main layout page and is used by all the other layouts. +We utilize the default layout provided by the `modern` template, as specified in `docfx.json`. -- `default` - Main layout page -- `container` - Used by some pages -- `page` - Used by most of the pages -- `post` - Used by blog posts +## Includes -# Includes - -All the includes are located in the `/_includes` folder. The includes are reusable code snippets that can be included in multiple pages. - -Some includes are used solely by the layouts, while others are used by the content pages. - -# Advanced Topics - -## Creating Custom Shortcodes and Includes - -If you need to create a custom shortcode or include, please follow the existing structure and [include a comment](content.md#shortcodes-and-includes) to explain the new shortcode or include. - -The shortcodes are defined in the `.eleventy.js` file, while the includes are located in the `/_includes` folder. - -You can explore the existing shortcodes and includes to get a better understanding of how they work and how to create new ones. - -## Performance Optimization - -ToDo: Remove this section if not needed +All includes are located in the `/_includes` folder. These are reusable markdown snippets that can be incorporated into multiple pages. \ No newline at end of file diff --git a/en/contributors/documentation/documentation-generation-pipeline.md b/en/contributors/documentation/documentation-generation-pipeline.md index 2376ff837..3cf6e98cc 100644 --- a/en/contributors/documentation/documentation-generation-pipeline.md +++ b/en/contributors/documentation/documentation-generation-pipeline.md @@ -1,42 +1,39 @@ -# Documentation generation pipeline -- [Introduction](#introduction) -- [A Simplified Overview](#a-simplified-overview) -- [Docs Build Workflow](#docs-build-workflow) -- [Workflow Diagram](#workflow-diagram) +# Generation Pipeline -# Introduction -As of now, **DocFX** does not natively support the generation of multi-language and multi-version documentation. To address this limitation, the Stride team has developed a PowerShell script. Initially, separate scripts were created for each language; however, these have since been consolidated into a single script named [`BuildDocs.ps1`](https://github.com/stride3d/stride-docs/blob/staging/BuildDocs.ps1). This unified script is capable of generating documentation in all supported languages. +## Introduction + +As of now, **Docfx** does not natively support the generation of multi-language and multi-version documentation. To address this limitation, the Stride team has developed a PowerShell script. Initially, separate scripts were created for each language; however, these have since been consolidated into a single script named [`BuildDocs.ps1`](https://github.com/stride3d/stride-docs/blob/staging/BuildDocs.ps1). This unified script is capable of generating documentation in all supported languages. The script serves two main purposes: - It features a non-interactive mode, utilized by the Continuous Integration/Continuous Deployment (CI/CD) pipeline to automatically generate documentation for all languages and the most recent version, eliminating the need for user intervention. - It also offers an interactive command-line UI, allowing users to select which languages they wish to generate documentation for. -# A Simplified Overview +## A Simplified Overview Here's a straightforward explanation of how the documentation generation process works. -The `/en` folder serves as the repository for the primary documentation files. When documentation for another language (e.g., Japanese) is built, the files from `/en` are copied over to a temporary folder, for example, `/jp-tmp`. This ensures that the non-English versions will contain all the files present in the `/en` folder. Files that have been translated (found in folders like `/jp`) will overwrite their English counterparts in the temp folder. +The `/en` folder serves as the repository for the primary documentation files. When documentation for another language (e.g., Japanese) is built, the files from `/en` are copied over to a temporary folder, for example, `/jp-tmp`. This ensures that the non-English versions will contain all the files present in the `/en` folder. Files that have been translated (found in folders like `/jp`) will overwrite their English counterparts in the temp folder `/jp-tmp`. -DocFX is invoked multiple times, once for each language, to create the documentation. The generated documents are stored in the `_site` folder, organized according to the latest version information obtained from `version.json`. For example: +Docfx is invoked multiple times, once for each language, to create the documentation. The generated documents are stored in the `_site` folder, organized according to the latest version information obtained from `version.json`. For example: ``` /_site/4.1/en /_site/4.1/jp ``` -## DocFX Files Processed +### Docfx Files Processed -This section outlines the file processing carried out by DocFX during the documentation generation: +This section outlines the file processing carried out by Docfx during the documentation generation: -- **Table of Contents (TOC) Files:** 4 files processed -- **Assets:** 1607 items (images, videos, etc.) included -- **Conceptual Files:** 304 files processed, resulting in 304 HTML files +- **Table of Contents (TOC) Files:** 7 files processed +- **Assets:** 1620 items (images, videos, etc.) included +- **Conceptual Files:** 358 files processed, resulting in 304 HTML files - **Warnings (No API Metadata):** 44 instances encountered - **Warnings (API Metadata):** 200 instances of missing or incorrect references -- **API Files:** 2821 files processed, resulting in 2133 HTML files +- **API Files:** 2825 files processed, resulting in 2133 HTML files -# Docs Build Workflow +## Docs Build Workflow In this part, we elaborate on the individual steps involved in the documentation build workflow for the Stride Docs project. @@ -77,7 +74,7 @@ In this part, we elaborate on the individual steps involved in the documentation - **PostProcessing-DocFxDocUrl** - Adjusts HTML tags and GitHub links, removing any `_tmp` suffixes. Also updates GitHub links to English if the translation is unavailable. -# Workflow Diagram +## Workflow Diagram ``` mermaid @@ -135,7 +132,8 @@ graph TB R -->|No| T S --> T T --> X{{docfx build}} - X --> Y + X --> X1{{docfx pdf}} + X1 --> Y Y --> Z end ``` \ No newline at end of file diff --git a/en/contributors/documentation/index.md b/en/contributors/documentation/index.md index 19d1925a4..7fc5557e0 100644 --- a/en/contributors/documentation/index.md +++ b/en/contributors/documentation/index.md @@ -1,4 +1,5 @@ -# Contributing to documentation +# Contributing to documentation + This documentation serves as a comprehensive guide to help you navigate and contribute to the **Stride Docs** website. If you're looking to make minor changes, such as adding or updating a manual, tutorial or page, or fixing a typo, feel free to jump straight to the [Content Updates](content.md#content-updates) section. @@ -7,57 +8,27 @@ For more extensive updates 🤯🤦‍♂️ or for a deeper understanding of th Here are the technologies we use to build our website: -- [docfx](https://dotnet.github.io/docfx/index.html) (static site generator) +- [Docfx](https://dotnet.github.io/docfx/index.html) (static site generator) + - A specific version of Docfx is utilized in GitHub Actions, one that has been thoroughly tested. Should you wish to upgrade this version, please ensure it is properly tested before implementation. - Markdown -- [Mustache](https://mustache.github.io/) template engine (docfx dropped Liquid template engine support) +- [Mustache](https://mustache.github.io/) template engine (Docfx dropped Liquid template engine support) - Bootstrap - Emojis (because why not? 😎) - HTML, JavaScript, CSS, JSON - PowerShell scripts -- GitHub Actions (CI/CD) - Don't worry, this is already set up, you don't need to worry about it. - -## Table of Contents - -- [Understanding the Stride Documentation Generation Pipeline](documentation-generation-pipeline.md) - - [Introduction](documentation-generation-pipeline.md#introduction) - - [A Simplified Overview](documentation-generation-pipeline.md#a-simplified-overview) - - [Docs Build Workflow](documentation-generation-pipeline.md#docs-build-workflow) - - [Workflow Diagram](documentation-generation-pipeline.md#workflow-diagram) -- [Installation](installation.md) - - [Prerequisites](installation.md#prerequisites) - - [Installation Steps](installation.md#installation-steps) - - [Running the Development Server](installation.md#running-the-development-server) -- [Content Updates](content.md#content-updates) - - [Small Updates](content.md#small-updates) - - [Major Updates](content.md#major-updates) - - [Manual](content.md#manual) - - [Creating New Page](content.md#creating-new-manual-page) - - [Tutorial](content.md#tutorial) - - [Creating New Tutorial](content.md#creating-new-tutorial-page) - - [Shortcodes and Includes](content.md#shortcodes-and-includes) - - [Alert](content.md#alert) - - [Video](content.md#video) - - [Web Assets](content.md#web-assets) - - [Styling](content.md#styling) - - [Bootstrap Customization](content.md#bootstrap-customization) - - [CSS Guidelines](content.md#css-guidelines) - - [Submitting your Changes](content.md#submitting-your-changes) -- [New Language](new-language.md) - - [Adding a New Language](new-language.md#adding-a-new-language) -- [Roadmap](roadmap.md) -- [DocFX](docfx.md) - - [Packages and Dependencies](docfx.md#packages-and-dependencies) - - [Configuration](docfx.md#configuration) - - [Global Data](docfx.md#global-data) - - [Folder Structure](docfx.md#folder-structure) - - [Layouts](docfx.md#layouts) - - [Includes](docfx.md#includes) - - [Advanced Topics](docfx.md#advanced-topics) - - [Creating Custom Shortcodes and Includes](docfx.md#creating-custom-shortcodes-and-includes) -- [Deployment](deployment.md) - - [GitHub Pages](deployment.md#github-pages) - - [Azure Web Apps](deployment.md#azure-web-apps) -- [Troubleshooting and FAQ](troubleshooting-and-faq.md) - - [Known Issues](troubleshooting-and-faq.md#known-issues) - - [Common Issues and Solutions](troubleshooting-and-faq.md#common-issues-and-solutions) - - [Frequently Asked Questions](troubleshooting-and-faq.md#frequently-asked-questions) \ No newline at end of file +- GitHub Actions (CI/CD) + - Our [GitHub Actions](https://github.com/stride3d/stride-docs/tree/master/.github/workflows) are already configured for deploying to both staging and release environments. + - For personal testing or demonstration purposes, you may need to set up your own GitHub Actions. This is especially useful for showcasing proposed changes to maintainers for their approval. For guidance on this, refer to our [Deployment to GitHub Pages guide](deployment-azure.md#deployment-to-github-pages). + +## Dependencies + +Various Stride systems rely on content fetched and processed from either the Stride website or the Stride Docs website. It's crucial to ensure that the following links remain active and accessible. Please refrain from removing or altering these links unless the dependent systems have been updated accordingly to accommodate any changes. + +1. https://doc.stride3d.net/latest/en/index.json + - This JSON file is crucial for integrating the Stride Docs search functionality with the Stride Website. It ensures that search results are comprehensive, including relevant information from both the Stride website and Stride Docs. +1. https://doc.stride3d.net/latest/en/ReleaseNotes/ReleaseNotes.md + - The **Stride Launcher** utilizes this file when you click a release notes button. +1. https://doc.stride3d.net/latest/en/diagnostics/index.html + - Diagnostic warnings in the Stride IDE reference pages in the Stride Docs - Diagnostics section. This ensures that users can quickly find detailed explanations and potential solutions for any issues encountered. +1. https://doc.stride3d.net/latest/en/studio_getting_started_links.txt + - The **Stride Launcher** is using this file in `Urls.Designer.cs`. \ No newline at end of file diff --git a/en/contributors/documentation/installation.md b/en/contributors/documentation/installation.md index 0c9d31e2f..2aa4c2638 100644 --- a/en/contributors/documentation/installation.md +++ b/en/contributors/documentation/installation.md @@ -1,27 +1,17 @@ # Local installation This guide will walk you through the steps to install the Stride Docs website on your local machine for development purposes. Although we use the Windows operating system for development, the steps should be similar for other operating systems. -[Minor updates](content.md#small-updates) can be made directly on GitHub. However, for [more significant updates](content.md#major-updates) that affect multiple pages, we recommend using a local development environment so you can see the impact of your changes beforehand. This is because we use the **docfx** static site generator, and in some cases, all pages need to be regenerated. This approach helps you assess your changes before submitting a pull request. +[Minor updates](content.md#small-updates) can be made directly on GitHub. However, for [more significant updates](content.md#major-updates) that affect multiple pages, we recommend using a local development environment so you can see the impact of your changes beforehand. This is because we use the [Docfx](https://dotnet.github.io/docfx/index.html) static site generator, and in some cases, all pages need to be regenerated. This approach helps you assess your changes before submitting a pull request. This guide assumes you have a basic understanding of the technologies used in the Stride docs website. -# Table of Contents - -- [Prerequisites](#prerequisites) -- [Installation Steps](#installation-steps) -- [Running the Development Server](#running-the-development-server) - -# Prerequisites +## Prerequisites Before updating the Stride Docs, ensure you are familiar with the following prerequisites: -1. Familiarity with the command line -1. **.NET SDK 6.0 or higher:** You can download the installer from the [.NET SDK website](https://dotnet.microsoft.com/en-us/download) - - If .NET SDK is already installed, ensure you have version 6.0 or higher. You can check your version by running `dotnet --info` in a terminal. -1. **Git installed:** You will need Git for version control. If you don't have Git installed, you can download it from the [Git website](https://git-scm.com/downloads) -1. **Development IDE of choice:** Choose an Integrated Development Environment (IDE) that you're comfortable with for development. Although there are various popular choices, such as Visual Studio, Visual Studio Code, and others, this guide will focus on using **Visual Studio**, as it is the primary IDE for the Stride project, and as of writing, we use **Visual Studio 2022**. You can download the free Community edition from the [Visual Studio website](https://visualstudio.microsoft.com/downloads/) +[!INCLUDE [docs-prerequisites](../../includes/docs-prerequisites.md)] -# Installation Steps +## Installation Steps 1. ❓You might want to create an issue so we can track your contribution and avoid duplicate work. If you're unsure whether your contribution is needed, feel free to create an issue and ask 1. 🍴 Fork the repository by navigating to the [Stride Docs repository](https://github.com/stride3d/stride-docs) and clicking the **Fork** button in the top-right corner @@ -30,7 +20,7 @@ Before updating the Stride Docs, ensure you are familiar with the following prer 1. Make sure you have also Stride repo cloned on **the same level** as stride-docs, read more about it [here](https://github.com/stride3d/stride) - This repo is needed for API documentation generation 1. 📁 Go to the project folder `cd stride-docs` -1. 🚀 Let's start with the **docfx** +1. 🚀 Let's start with the **Docfx** Enter the following command to install the latest docfx @@ -38,7 +28,7 @@ Enter the following command to install the latest docfx dotnet tool install -g docfx ``` -Or check the inslalled version is at least `2.67.0` +Or check the installed version is at least `2.74.1` ``` docfx --version @@ -46,26 +36,25 @@ docfx --version **Other options** -Update to the latest docfx +Update to the latest Docfx ``` dotnet tool update -g docfx ``` -Install a specific version of docfx +Install a specific version of Docfx ``` -dotnet tool update -g docfx --version 2.67.0 +dotnet tool update -g docfx --version 2.74.1 ``` -Uninstall docfx if you need to downgrade - +Uninstall Docfx if you need to downgrade ``` dotnet tool uninstall -g docfx ``` -# Running the Development Server +## Running the Development Server We've created a PowerShell script [BuildDocs.ps1](https://github.com/stride3d/stride-docs/blob/master/BuildDocs.ps1) with a context menu where you can select the language, include the API build, and run the development server. diff --git a/en/contributors/documentation/major-release-workflow.md b/en/contributors/documentation/major-release-workflow.md new file mode 100644 index 000000000..b2c8d627b --- /dev/null +++ b/en/contributors/documentation/major-release-workflow.md @@ -0,0 +1,27 @@ +# Major Release Workflow + +Assuming the transition is from version `4.1` to `4.2`, and that the Stride source code has been updated to the corresponding .NET version, follow these steps. Note that some steps can be executed at a later stage if needed. + +1. Duplicate `ReleaseNotes\ReleaseNotes.md` and rename the copy to `ReleaseNotes-4.1.md` +1. Update `ReleaseNotes.md`: + - Change the content title to `4.2` + - Replace the content with the new release notes for version `4.2` + - [GitHub Release](https://github.com/stride3d/stride/releases) can be used to generate a list **What's Changed**, once the new tag was added +1. Modify `ReleaseNotes\toc.yml` + - `name: 4.2 release notes` with `href: ReleaseNotes.md` + - `name: 4.1 release notes` with `href: ReleaseNotes-4.1.md` +1. In `en\docfx.json` + - `_appFooter`: Increase the version number + - Change `TargetFramework`in two locations to the current framework version being used. Ensure to test this step locally +1. Edit `versions.json` + - Under `versions`, add the new version `4.2` +1. For GitHub Actions deployment update `*.yml` files in the `.github\workflows\` folder + - `dotnet-version:` Update to the related .NET version + +The `BuildDocs.ps1` script will manage the deployment to the `4.2` folder while maintaining accessibility to previous versions. Note, that the deployment profile must be set to not delete existing items. + +## Other locations to update + +1. Update [README.md](https://github.com/stride3d/stride/blob/master/README.md) in the Stride repo, Building from source - Prerequisites section, bump .NET version +1. Modify `contributors\documentation\installation.md` + - Update SDK version \ No newline at end of file diff --git a/en/contributors/documentation/roadmap.md b/en/contributors/documentation/roadmap.md index bd3719ff9..704274f83 100644 --- a/en/contributors/documentation/roadmap.md +++ b/en/contributors/documentation/roadmap.md @@ -1,11 +1,8 @@ -# Documentation roadmap -This is a proposal for our website roadmap and ongoing website development plan. +# Documentation Roadmap -- Tackle existing issues listed in the [Issues](https://github.com/stride3d/stride-website/issues) -- Convert images to WebP for better performance -- Streamline the website by decoupling media from the site - - Host videos on YouTube - - Host images in Azure Blob Storage or another location -- Optimize the website for possible deployment on Azure Static Web Apps - +This document outlines a proposed roadmap and an ongoing development plan for our Stride Docs website. +- **Address Existing Issues**: Prioritize resolving issues listed in the [Issues](https://github.com/stride3d/stride-docs/issues) section on GitHub. +- **Image Optimization**: Convert existing images to the WebP format to enhance website performance. +- **Content Enhancement**: Implement improvements across all sections of the documentation to ensure clarity, accuracy, and comprehensiveness. +- **Guidance for Contributors**: Provide clear instructions for contributors on writing XML comments in C#, which play a crucial role in enhancing the API documentation. \ No newline at end of file diff --git a/en/contributors/documentation/troubleshooting-and-faq.md b/en/contributors/documentation/troubleshooting-and-faq.md index c4f6a0328..2dcfe5d15 100644 --- a/en/contributors/documentation/troubleshooting-and-faq.md +++ b/en/contributors/documentation/troubleshooting-and-faq.md @@ -5,17 +5,14 @@ # Known Issues -1. **Sponsor Page - Widget Incompatibility with dark theme:** Widgets on the Sponsor Page currently do not support the dark theme. As a workaround, we can either fetch data from https://opencollective.com/stride3d/members/all.json and render it before deployment or make it dynamic. Both options would give us more control over the content and design, and allow for better compatibility with the dark theme in the future. -1. **Search Page - Lack of pagination:** At present, the Search Page does not have pagination, which limits the maximum number of search results displayed to 100. To resolve this issue, we can implement a pager in JavaScript. This would enable users to navigate through multiple pages of search results, providing a more comprehensive view of the available content. +ToDo: Add any known issues # Common Issues and Solutions -Any issue should be added to Stride Website [GitHub issues](https://github.com/stride3d/stride-website/issues) so it can be tracked and elaborated by the community. +Any issue should be added to Stride Docs [GitHub issues](https://github.com/stride3d/stride-docs/issues) so it can be tracked and elaborated by the community. # Frequently Asked Questions **Q:** I just want to fix a typo in a post. Do I need to follow your installation steps? -**A:** *No, you can fix the typo directly on the GitHub website. However, you will still need to fork the repo, make your update on the main branch or a new branch, and then create a pull request. You can follow this guide for [minor updates](content.md#small-updates).* - - +**A:** *No, you can fix the typo directly on the GitHub website. However, you will still need to fork the repo, make your update on the main branch or a new branch, and then create a pull request. You can follow this guide for [minor updates](content.md#small-updates).* \ No newline at end of file diff --git a/en/contributors/donate.md b/en/contributors/donate.md index 40a5e7082..7363cf919 100644 --- a/en/contributors/donate.md +++ b/en/contributors/donate.md @@ -5,4 +5,6 @@ In order to support our contributors or if we want to finance a specific feature We gather funding through a website called [OpenCollective](https://opencollective.com/stride3d). This website displays where all the money is coming from and where it is going to: 100% transparency guaranteed. ## Projects -Stride's Open Collective hosts different '[Projects](https://opencollective.com/stride3d/projects)' — think of them as funding goals for specific features or contributions. Each project typically has a related GitHub ticket for more details on what's required for its development. If you're interested in working on or contributing to a particular feature, please reply in the thread and mention @stride3d/stride-contributors. +Stride's Open Collective hosts different '[Projects](https://opencollective.com/stride3d/projects)' — think of them as funding goals for specific features or contributions. Each project typically has a related GitHub ticket for more details on what's required for its development. If you're interested in working on or contributing to a particular feature, you can let us know by either replying: + - In each projects related GitHub thread and mention @stride3d/stride-contributors + - In the Stride [Contributors channel on Discord](https://discord.gg/bDhMhGVHvD) diff --git a/en/contributors/engine/architecture/asset-introspection.md b/en/contributors/engine/architecture/asset-introspection.md index 8a9ed2fdc..9ea23f2ed 100644 --- a/en/contributors/engine/architecture/asset-introspection.md +++ b/en/contributors/engine/architecture/asset-introspection.md @@ -1,11 +1,5 @@ # 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 diff --git a/en/contributors/engine/architecture/build-details.md b/en/contributors/engine/architecture/build-details.md index d6cdfb27a..955fc713a 100644 --- a/en/contributors/engine/architecture/build-details.md +++ b/en/contributors/engine/architecture/build-details.md @@ -1,8 +1,8 @@ -# Build details +# Build details This is a technical description what happens in our build and how it is organized. This covers mostly the build architecture of Stride itself. * [Targets](../Targets) contains the MSBuild target files used by Games -* [sources/common/targets](../sources/common/targets) (generic) and [sources/targets](../sources/targets) (Stride-specific) contains the MSBuild target files used to build Stride itself. +* [sources/common/targets](../sources/common/targets) (generic) and [sources/targets](https://github.com/stride3d/stride/tree/master/sources/targets) (Stride-specific) contains the MSBuild target files used to build Stride itself. Since 3.1, we switched from our custom build system to the new csproj system with one nuget package per assembly. @@ -11,15 +11,14 @@ We use `TargetFrameworks` to properly compile the different platforms using a si Also, we use `RuntimeIdentifiers` to select graphics platform. [MSBuild.Sdk.Extras](https://github.com/onovotny/MSBuildSdkExtras) is used to properly build NuGet packages with multiple `RuntimeIdentifiers` (not supported out of the box). ### Limitations - * Dependencies are per `TargetFramework` and can't be done per `RuntimeIdentifier` (tracked in [NuGet#1660](https://github.com/NuGet/Home/issues/1660)). -* FastUpToDate check doesn't work with multiple `TargetFrameworks` (tracked in [project-system#2487](https://github.com/dotnet/project-system/issues/2487)). + ## NuGet resolver Since we want to package tools (i.e. GameStudio, ConnectionRouter, CompilerApp) with a package that contains only the executable with proper dependencies to other NuGet runtime packages, we use NuGet API to resolve assemblies at runtime. -The code responsible for this is located in [Stride.NuGetResolver](../../../sources/shared/Stride.NuGetResolver). +The code responsible for this is located in [Stride.NuGetResolver](https://github.com/stride3d/stride/tree/master/sources/shared/Stride.NuGetResolver). Later, we might want to take advantage of .NET Core dependency resolving to do that natively. Also, we might want to use actual project information/dependencies to resolve to different runtime assemblies and better support plugins. diff --git a/en/contributors/ways-to-contribute.md b/en/contributors/index.md similarity index 100% rename from en/contributors/ways-to-contribute.md rename to en/contributors/index.md diff --git a/en/contributors/toc.yml b/en/contributors/toc.yml index 55c919195..b988fb465 100644 --- a/en/contributors/toc.yml +++ b/en/contributors/toc.yml @@ -1,8 +1,13 @@ +pdf: true +pdfFileName: contributing-in-stride.pdf +items: - name: 🌟 Ways to Contribute - href: ways-to-contribute.md + href: index.md expanded: true - name: 💸 Donate href: donate.md +- name: 🤝 Contribution Workflow + href: contribution-workflow.md - name: 🛠️ Contribute to the engine expanded: false href: engine/index.md @@ -21,8 +26,8 @@ href: engine/source-debugging.md - name: Visual Studio plugin href: engine/visual-studio-plugin.md - - name: 🏗️️ Architecture - expanded: false + - name: 🏗️ Architecture + expanded: true href: engine/architecture/index.md items: - name: Build pipeline @@ -34,27 +39,29 @@ - name: Dependency graph href: engine/architecture/dependency-graph.md - name: Asset introspection - href: engine/architecture/build-pipeline.md -- name: 🎓 Contribute to the documentation + href: engine/architecture/asset-introspection.md +- name: 📖 Contribute to the documentation expanded: false href: documentation/index.md items: - - name: Documentation generation pipeline - href: Documentation/documentation-generation-pipeline.md + - name: Generation Pipeline + href: documentation/documentation-generation-pipeline.md - name: Installation - href: Documentation/installation.md + href: documentation/installation.md - name: Content - href: Documentation/content.md + href: documentation/content.md # - name: New language -# href: Documentation/new-language.md +# href: documentation/new-language.md - name: Roadmap - href: Documentation/roadmap.md - - name: DocFX - href: Documentation/docfx.md + href: documentation/roadmap.md + - name: Docfx + href: documentation/docfx.md - name: Deployment - href: Documentation/deployment-azure.md + href: documentation/deployment-azure.md + - name: Major Release Workflow + href: documentation/major-release-workflow.md - name: Troubleshooting and FAQ - href: Documentation/troubleshooting-and-faq.md + href: documentation/troubleshooting-and-faq.md - name: 🌐️ Contribute to the website expanded: false href: website/index.md @@ -63,11 +70,18 @@ href: website/installation.md - name: Website Content href: website/content.md + items: + - name: Shortcodes and Includes + href: website/content-shortcodes-and-includes.md + - name: Figma Designs + href: website/figma.md - name: Roadmap href: website/roadmap.md - name: Eleventy href: website/eleventy.md - name: Deployment href: website/deployment-azure.md + - name: Major Release Workflow + href: website/major-release-workflow.md - name: Troubleshooting and FAQ href: website/troubleshooting-and-faq.md \ No newline at end of file diff --git a/en/contributors/website/content-shortcodes-and-includes.md b/en/contributors/website/content-shortcodes-and-includes.md new file mode 100644 index 000000000..0240693d0 --- /dev/null +++ b/en/contributors/website/content-shortcodes-and-includes.md @@ -0,0 +1,140 @@ +# Shortcodes and Includes + +You can see examples here https://www.stride3d.net/blog/examples/. + +## Alert + +To add an alert, use the following `include`, where: + +- `type` is one of the following: `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark`. Using these types will automatically include a relevant icon +- `icon` is a Font Awesome icon, which is optional. You can use any free icon, e.g., fa-check. +- `title` is the title of the alert + +```liquid +# This will render as a green box without the icon +{% include _alert.html type:'success' icon:'' title:'No icon: Stride contributors are proud to announce a new release now running on .NET 6 supporting the latest C# 10.' %} + +# This will render as a green box with a check icon +{% include _alert.html type:'success' title:'No icon: Stride contributors are proud to announce a new release now running on .NET 6 supporting the latest C# 10.' %} + +# This will render as a green box with a custom icon +{% include _alert.html type:'success' icon:'fa-face-smile' title:'No icon: Stride contributors are proud to announce a new release now running on .NET 6 supporting the latest C# 10.' %} +``` + +### Examples + +See the examples [here](https://www.stride3d.net/blog/examples/#alert). + +![Alert examples in the Stride website](media/alert-examples.jpg) + +## Alert Banner + +A global alert banner can be used for promotional purposes. The banner can be activated in `site.json`. It will show up on every single page. + +```json +"alert-banner": true +``` + +The HTML can be updated in the `/_includes/alert-banner.html` file. + +![Alert Banner examples in the Stride website](media/alert-banner-example.jpg) + +## Image + +Add responsive images using shortcodes. Be sure to include a descriptive title, as it will improve your post's search engine visibility. Also, if possible, use the **webp** format for images, which can also be used for transparent images. This will improve the performance of your site. + +### img + +To add a responsive image, use the following shortcode: + +`{% img 'title' 'url' %}` + +Replace `title` with a descriptive title for the image and `url` with the image URL. This shortcode renders as: + +```html +title +``` + +### img-click + +To add a responsive image with a clickable link that opens the image in full size, use the following shortcode: + +`{% img-click 'title' 'url' %}` + +Replace `title` with a descriptive title for the image and `url` with the image URL. This shortcode renders as: + +```html +title +``` + +To add a responsive image with a clickable link that directs users to a custom destination, use the following shortcode: + +`{% img-click 'title' 'url' 'destinationUrl' %}` + +Replace `title` with a descriptive title for the image, `url` with the image URL, and `destinationUrl` with the target URL when the image is clicked. This shortcode renders as: + +```html +title +``` + +## Video + +We should consider hosting our videos on YouTube whenever possible. + +### youtube + +To embed a **YouTube video**, use the following shortcode: + +`{% youtube 'id' %}` + +Replace `id` with the YouTube video ID. This shortcode renders as: + +```html +
+``` + +### youtube-playlist + +To embed a **YouTube playlist**, use the following shortcode: + +`{% youtube-playlist 'id' %}` + +Replace `id` with the YouTube playlist ID. This shortcode renders as: + +```html +
+``` + +To embed a video hosted elsewhere, use the following shortcode: + +### Hosting our own videos + +`{% video 'url' %}` + +Replace `url` with the video URL (e.g., .mp4 file). Make sure you have a matching .jpg file with the same name as the .mp4 file for the poster attribute. This shortcode renders as: + +```html + +
+``` + +### How to encode videos + +Videos can be generated by many software in various formats & size, so they might end up being incompatible with web browsers or mobile, or simply be way too large. +It is better to stick to a format with low requirements such as H264 baseline profile (works almost everywhere). + +To do so, process the file using [fmpeg](https://ffmpeg.org/download.html): + +``` +ffmpeg -i myvideo_original.mp4 -profile:v baseline -level 3.0 -an myvideo.mp4 +``` + +Also, generate a static thumbnail so that people can preview it before downloading the video (very important on mobile): + +ToDo: Check if webp can be generated from ffmpeg + +``` +ffmpeg -i myvideo.mp4 -vframes 1 -f image2 -y myvideo.jpg +``` + +ToDo: Maybe we could provide a simple tool to do that without using command line. \ No newline at end of file diff --git a/en/contributors/website/content.md b/en/contributors/website/content.md index d5a01991c..c00b84c45 100644 --- a/en/contributors/website/content.md +++ b/en/contributors/website/content.md @@ -1,26 +1,6 @@ # Website Content -- [Content Updates](#content-updates) - - [Small Updates](#small-updates) - - [Major Updates](#major-updates) -- [Creating New Post](#creating-new-post) - - [Post Naming Convention](#post-naming-convention) - - [Post Front Matter](#post-front-matter) - - [Post Content](#post-content) - - [Excerpt](#excerpt) -- [Creating New Page](#creating-new-page) - - [Page Front Matter](#page-front-matter) -- [Shortcodes and Includes](#shortcodes-and-includes) - - [Alert](#alert) - - [Alert Banner](#alert-banner) - - [Image](#image) - - [Video](#video) -- [Web Assets](#web-assets) -- [Styling](#styling) - - [Bootstrap Customization](#bootstrap-customization) - - [CSS Guidelines](#css-guidelines) -- [Submitting your Changes](#submitting-your-changes) - -# Content Updates + +## Content Updates If you want to contribute and update the website, please follow the instructions below. @@ -28,13 +8,13 @@ Small updates can be done directly in the GitHub web interface, for bigger updat You can use any text editor to make changes. If you are using **Visual Studio**, you can open `Stride.Web.sln` solution file in the root of the repository and start making your updates directly from this IDE. -You are always welcome to create an issue to discuss your changes before you start working on them. +You are always welcome to [create an issue](https://github.com/stride3d/stride-website) to discuss your changes before you start working on them. -## Small Updates +### Small Updates Creating an issue is not required for small updates, but it is recommended to let others know what you are working on. If you are not sure whether your update is small or not, please create an issue first. -### What is a small update? +#### What is a small update? We can define small updates as changes to the content of the website: @@ -45,35 +25,31 @@ We can define small updates as changes to the content of the website: - Minor navigation or footer update - This will update all pages containing the navigation or footer -### Steps +#### Steps + +> [!NOTE] +> This guide assumes that you are already familiar with updating files on GitHub. -**Note:** This guide assumes you are already familiar with updating files in GitHub. +For the following instructions, use the [Stride Website GitHub repository](https://github.com/stride3d/stride-website): -1. Go to the [Stride Website GitHub](https://github.com/stride3d/stride-website) repository -1. Locate the file you wish to edit -1. Click the `Edit this file` (pencil) icon in the top right corner -1. If prompted, fork the repository by clicking `Fork this repository` -1. Make your changes to the file, then write a brief commit message describing the changes -1. Click on the `Propose changes` button -1. On the next screen, click the `Create pull request` button -1. Provide a title and description for your pull request, and click on `Create pull request` again -1. Wait for the review and merge +[!INCLUDE [small-updates](../../includes/small-update-instructions.md)] -## Major Updates +### Major Updates [Creating an issue](https://github.com/stride3d/stride-website/issues) is **required** for major updates, so that others can comment on your changes and provide feedback. -We can define bigger updates as changes to the design of the website, where you would like to see the impact of your changes beforehand to assess the desired result: +Major updates can be defined as significant changes to the website's design, where it's beneficial to preview the impact of your changes to ensure they achieve the desired result. This may include: -- Add new Eleventy shortcodes and Liquid includes -- Update Bootstrap library or other libraries -- Update layouts +- Adding new Eleventy shortcodes and Liquid includes +- Updating the Bootstrap library or other libraries +- Modifying layouts +- Revamping design elements -You would start with the local development environment, which is described in the [Installation](installation.md) section. +Start by setting up your local development environment, as described in the [Installation](installation.md) section. After making and testing your changes locally, you should create a pull request to merge your changes into the `master` branch. -Then you would make your changes and test them locally. Once you are happy with the result, you can create a pull request to merge your changes into the `master` branch. +When submitting a pull request, especially for substantial changes, it's recommended to include **screenshots** or a link to your local deployment. This approach helps maintainers visualize and assess your proposed changes more effectively. If you prefer to use GitHub infrastructure for your demonstrations, refer to our [Deployment to GitHub Pages guide](deployment-azure.md#deployment-to-github-pages) for instructions on deploying via GitHub Actions. -# Creating New Post +## Creating New Post To create a new blog post, you can follow one of these methods: @@ -82,15 +58,16 @@ To create a new blog post, you can follow one of these methods: Either method will allow you to create a new blog post, so choose the one that best suits your needs. -## Post Naming Convention +### Post Naming Convention `YYYY-MM-DD-post-title.md` Replace `YYYY-MM-DD` with the date of the post and `post-title` with the title of the post. -⚠️**Important SEO Note:** Ensure the file title includes essential keywords related to your post's content. This is crucial as the file title dictates the URL of the post, which plays a significant role in search engine optimization (SEO). +> [!IMPORTANT] +> **SEO Note:** Ensure the file title includes essential keywords related to your post's content. This is crucial as the file title dictates the URL of the post, which plays a significant role in search engine optimization (SEO). -## Post Front Matter +### Post Front Matter The file should start with the following front matter: @@ -140,16 +117,16 @@ Default front matter, which is used for all posts, can be found in the `posts/po } ``` -### Image +#### Image The image specified in the front matter serves dual purposes: It appears in the blog listing at [Stride Blog](https://www.stride3d.net/blog/) and is used as the **og:image** meta tag for social sharing. Here are three ways to specify this image: - Not including an image in the front matter will use the default image - Including an image in the front matter will override the default image. The size of the image should be minimum **1200 x 600px** e.g. `image: /images/blog/2023-04/new-home-page.webp` - External image URL e.g. `image: https://i.imgur.com/7GVEiSR.jpg` -- If you are looking for Stride specific logo's or icons, have a look at the [Figma](figma.md) options. +- If you are looking for Stride specific logo's or icons, have a look at the [Figma](figma.md) options -## Post Content +### Post Content Check the previous posts for an example of the post content. Ideally you should use the same format as the previous posts to preserve the consistency of the blog. @@ -157,9 +134,10 @@ You can use shortcodes and includes which are described in the [Shortcodes and I You can also use majority of the Bootstrap classes in your content if you combine HTML and Markdown. -💡**Tip:** We have a folder called `_drafts` where you can store your drafts. These files are not published. Once you are ready to publish your post, you can move it to the `posts` folder. +> [!TIP] +> We have a folder called `_drafts` where you can store your drafts. These files are not published. Once you are ready to publish your post, you can move it to the `posts` folder. -## Excerpt +### Excerpt The excerpt is the first paragraph of the post. Separated from the rest of the content by three dashes `---`. The excerpt is used in the blog post list, meta description and in the RSS feed. @@ -180,11 +158,11 @@ Additional content goes here... ``` -# Creating New Page +## Creating New Page -To create a new page, create a new file in the root folder or create a new folder and add an `index.md` file to it. You can use any templating language supported by Eleventy. We use Markup, html, nunjacks. +To create a new page, create a new file in the root folder or create a new folder and add an `index.md` file to it. You can use any templating language supported by Eleventy. We use Markup, HTML, Nunjucks. -## Page Front Matter +### Page Front Matter The page front matter works the same way as the post front matter. The only difference is that the `layout` property is required. @@ -200,133 +178,11 @@ permalink: /my-features/ # otherwise it would be /features/ --- ``` -# Shortcodes and Includes - -You can see examples here https://www.stride3d.net/blog/examples/. - -## Alert - -To add an alert, use the following include, where: - -- `type` is one of the following: `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark`. Using these types will automatically include a relevant icon -- `icon` is a Font Awesome icon, which is optional. You can use any free icon, e.g., fa-check. -- `title` is the title of the alert - -```liquid -# This will render as a green box without the icon -{% include _alert.html type:'success' icon:'' title:'No icon: Stride contributors are proud to announce a new release now running on .NET 6 supporting the latest C# 10.' %} - -# This will render as a green box with a check icon -{% include _alert.html type:'success' title:'No icon: Stride contributors are proud to announce a new release now running on .NET 6 supporting the latest C# 10.' %} - -# This will render as a green box with a custom icon -{% include _alert.html type:'success' icon:'fa-face-smile' title:'No icon: Stride contributors are proud to announce a new release now running on .NET 6 supporting the latest C# 10.' %} -``` - -## Alert Banner - -A global alert banner can be used for promotional purposes. The banner can be activated in `site.json`. - -```json -"alert-banner": true -``` - -The HTML can be updated in the `/_includes/alert-banner.html` file. - -## Image - -Add responsive images using shortcodes. Be sure to include a descriptive title, as it will improve your post's search engine visibility. Also, if possible, use the **webp** format for images, which can also be used for transparent images. This will improve the performance of your site. - -To add a responsive image, use the following shortcode: - -`{% img 'title' 'url' %}` - -Replace `title` with a descriptive title for the image and `url` with the image URL. This shortcode renders as: - -```html -title -``` - -To add a responsive image with a clickable link that opens the image in full size, use the following shortcode: - -`{% img-click 'title' 'url' %}` - -Replace `title` with a descriptive title for the image and `url` with the image URL. This shortcode renders as: - -```html -title -``` - -To add a responsive image with a clickable link that directs users to a custom destination, use the following shortcode: - -`{% img-click 'title' 'url' 'destinationUrl' %}` - -Replace `title` with a descriptive title for the image, `url` with the image URL, and `destinationUrl` with the target URL when the image is clicked. This shortcode renders as: - -```html -title -``` - -## Video - -We should consider hosting our videos on YouTube whenever possible. - -To embed a **YouTube video**, use the following shortcode: - -`{% youtube 'id' %}` - -Replace `id` with the YouTube video ID. This shortcode renders as: - -```html -
-``` - -To embed a **YouTube playlist**, use the following shortcode: - -`{% youtube-playlist 'id' %}` +## Shortcodes and Includes -Replace `id` with the YouTube playlist ID. This shortcode renders as: - -```html -
-``` - -To embed a video hosted elsewhere, use the following shortcode: - -### Hosting our own videos - -`{% video 'url' %}` - -Replace `url` with the video URL (e.g., .mp4 file). Make sure you have a matching .jpg file with the same name as the .mp4 file for the poster attribute. This shortcode renders as: - -```html - -
-``` +To enhance the quality and functionality of the content, both pages and posts can incorporate [shortcodes and includes](content-shortcodes-and-includes.md). These tools offer a versatile way to enrich the presentation and interactivity of the content on the Stride website. -### How to encode videos - -Videos can be generated by many software in various formats & size, so they might end up being incompatible with web browsers or mobile, or simply be way too large. -It is better to stick to a format with low requirements such as H264 baseline profile (works almost everywhere). - -To do so, process the file using [fmpeg](https://ffmpeg.org/download.html): - -``` -ffmpeg -i myvideo_original.mp4 -profile:v baseline -level 3.0 -an myvideo.mp4 -``` - -Also, generate a static thumbnail so that people can preview it before downloading the video (very important on mobile): - -ToDo: Check if webp can be generated from ffmpeg - -``` -ffmpeg -i myvideo.mp4 -vframes 1 -f image2 -y myvideo.jpg -``` - -ToDo: Maybe we could provide a simple tool to do that without using command line. - - -# Web Assets +## Web Assets Our main web assets are: @@ -342,32 +198,21 @@ Our main web assets are: - `search.liquid` - Renders as `search.json` contains search meta -# Styling +## Styling -## Bootstrap Customization +### Bootstrap Customization Our website uses the [Bootstrap](https://getbootstrap.com/) framework, version **5.3**. -⚠️**Important:** Prioritize the use of Bootstrap's inherent styling before integrating any custom styles. You should be familiar with [Bootstrap Utilities](https://getbootstrap.com/docs/5.3/utilities/api/) which help you to achieve most of the styling requirements. +> [!IMPORTANT] +> Prioritize the use of Bootstrap's inherent styling before integrating any custom styles. You should be familiar with [Bootstrap Utilities](https://getbootstrap.com/docs/5.3/utilities/api/) which help you to achieve most of the styling requirements. -## CSS Guidelines +### CSS Guidelines Our goal is to write as little CSS as possible to ensure the website remains lightweight. We maximize the utilization of the Bootstrap framework to achieve this. Further, we are using also [FontAwesome](https://fontawesome.com/) free icons. The icons are loaded in the `src/_includes/css/main.css` file. -# Submitting your Changes - -Assuming you have made all necessary changes and tested them on the development server, you can submit a pull request to the `master` branch. The pull request will be reviewed and merged by the website maintainers. - -Steps to contribute your updates: - -1. Commit your changes to your forked repository: - - Commit the changes with a meaningful message - - Push the changes to your forked repository -1. Create a pull request to the main repository: - - You can create a pull request from your forked repository by navigating to Pull requests page and click **New pull request** button - - Select the **master** branch as the base branch and your branch as the compare branch - - Click **Create pull request** button +## Submitting your Changes -Once your pull request has been reviewed and approved, your changes will be merged into the main repository and deployed to the website. \ No newline at end of file +[!INCLUDE [submitting-changes](../../includes/submitting-changes.md)] \ No newline at end of file diff --git a/en/contributors/website/deployment-azure.md b/en/contributors/website/deployment-azure.md index 354578af7..4700d5188 100644 --- a/en/contributors/website/deployment-azure.md +++ b/en/contributors/website/deployment-azure.md @@ -1,16 +1,19 @@ -# Deployment Azure -- [Step-by-Step Guide to Deploying Azure Web Apps (Windows) with IIS](#step-by-step-guide-to-deploying-azure-web-apps-windows-with-iis) - - [Setting up a new Azure Web App (Windows) with IIS](#setting-up-a-new-azure-web-app-windows-with-iis) - - [Adjusting the Web App Configuration](#adjusting-the-web-app-configuration) - - [Modifying the GitHub Action](#modifying-the-github-action) +# Deployment -# Step-by-Step Guide to Deploying Azure Web Apps (Windows) with IIS +Our team has explored various deployment options, ultimately selecting the method detailed in this guide for its efficacy. Additionally, for demonstration purposes, you can refer to the [Deployment to GitHub Pages](deployment-azure.md#deployment-to-github-pages) section for alternative deployment strategies you can use to showcase your updates. -This guide assumes you already have permission to access the Azure subscription. +## Deploying to Azure Web Apps (Windows) with IIS -## Setting up a new Azure Web App (Windows) with IIS +This guide is crafted for individuals who already have access to the Azure subscription. It provides step-by-step instructions for setting up a new Azure Web App, specifically tailored for staging environments. Note that the process for setting up a production environment is similar, but requires a distinct web app name. -These instructions pertain to the staging environment. For the production environment, follow the same steps, but with a different web app name. +Deployments to Azure Web Apps are automated through GitHub Actions, forming an integral part of our Continuous Integration/Continuous Deployment (CI/CD) process. The CI/CD pipeline is configured to automatically trigger deployments upon merging changes into either the `staging` or `release` branches. + +> [!NOTE] +> The deployment process outlined here is already established and running, hosted on Azure and sponsored by the .NET Foundation. This guide serves primarily as a reference for maintainers in the event that a new deployment setup is required. + +### Setting up a new Azure Web App + +Follow these instructions carefully to establish your Azure Web App in a staging environment. For deploying in a production environment, replicate these steps with an alternate web app name for differentiation. 1. Navigate to the [Azure Portal](https://portal.azure.com/) 1. Select **Create a resource** @@ -27,7 +30,7 @@ These instructions pertain to the staging environment. For the production enviro - Click **Next** 1. In the Deployment Tab - This step can be completed later if preferred. - Enable Continuous deployment - - Select account, organisation `Stride`, repository `stride-website` and branch `staging-next` + - Select account, organisation `Stride`, repository `stride-website` and branch `staging` - Click **Next** 1. In the Monitoring Tab - Leave all settings as default @@ -43,30 +46,72 @@ These instructions pertain to the staging environment. For the production enviro - Click **Create** - The GitHub Action will be added to the repository and run automatically. It will fail at this stage, but this will be resolved in the subsequent steps. -## Adjusting the Web App Configuration +> [!CAUTION] +> If you have completed the **Deployment Tab** process, ensure that the deployment profile includes the **DeleteExistingFiles** property. This property may need to be set to `False` or `True` depending on the specific requirements of your deployment. For instance, Stride Docs deployment retains files from previous deployments, allowing multiple versions like `4.2`, `4.1`, etc., to be maintained. Adjust this setting based on your deployment needs. + +### Adjusting the Web App Configuration 1. Proceed to the newly created Web App 1. Click on **Configuration** 1. Select **General Settings** -1. Change the Http Version to **2.0** +1. Change the `Http version` to **2.0** +1. Change `Ftp state` to **FTPS only** +1. Change `HTTPS Only` to **On** 1. Click **Save** to apply the changes -## Modifying the GitHub Action +### Modifying the GitHub Action -The previous step will have added a GitHub Action to the repository, which will fail at this point. You need to modify the GitHub Action to correct the issue. +The previous step will have added a GitHub Action to your repository, which might fail initially. To address this, you need to modify the GitHub Action: 1. Navigate to the repository -1. Select Actions +1. Select **Actions** 1. You have the option to stop the currently running action -1. Locate the new GitHub Action *(within this folder Stride Website -> staging-next repo -> .github -> workflows)* which was automatically generated by the Azure Portal. We will need to reference the properties app-name and publish-profile and disable the push trigger. +1. Locate the new GitHub Action file *(stride-website/blob/master/.github/workflows/some-file-name.yml)* that was automatically generated by Azure Portal. We need to extract the `app-name` and `publish-profile` values from it and disable the push trigger. - To disable the push trigger, retain only **workflow_dispatch** (manual trigger) as shown below: ``` on: # push: # branches: - # - staging-next + # - staging workflow_dispatch: ``` -1. Open the `stride-website-staging-azure.yml` workflow and update it with the properties from the previous step. Save your changes. -1. This workflow may also need to be added to the production branch master if it is not already there. -1. Execute the workflow stride-website-staging-azure.yml. Ensure you select the correct branch staging-next and click **Run workflow**. This action will deploy the website to the Azure Web App. +1. Open the `stride-website-staging-azure.yml` workflow and update it with the values obtained in the previous step. Save your changes. +1. This workflow might also need to be added to the `master` branch if it is not already present. +1. Execute the workflow `stride-website-staging-azure.yml`. Ensure you select the correct branch `staging` and click **Run workflow**. This action will deploy the website to the Azure Web App. + +### GitHub Actions + +- `stride-website-github.yml`: Facilitates manual deployment to GitHub Pages in the forked repository, primarily used for showcasing updates +- `stride-website-release-azure.yml`: Automates deployment to production upon merging changes into `release` branch, with a manual trigger option also available +- `stride-website-staging-azure.yml`: Enables automatic deployment to [staging](https://stride-website-staging.azurewebsites.net/) upon merging changes into `staging` branch, along with an option for manual triggering +- `stride-website-wiki.yml`: Automatically deploys to the GitHub Wiki when changes are pushed to the `wiki` folder in the `master` branch, also includes a manual trigger feature + +## Deployment to GitHub Pages + +To showcase your updates, especially helpful for design changes pending review, you can deploy the website either to your infrastructure or to GitHub Pages, a free hosting service. Once deployed, share the link with us for review. + +### Prerequisites + +In your `stride-website` repository: + +1. Navigate to **Settings** → **Actions** → **General** → **Workflow Permissions** + - Choose **Read and write permissions** + +### Run GitHub Action + +1. Go to **Actions**, select **Build Stride Web for GitHub Staging** + - Click **Run workflow**; you may optionally select a branch +2. Monitor the build logs while the action is in progress +3. Upon successful build, a `gh-pages` branch will be created +4. Navigate to **Settings** → **Pages** + - Choose the `gh-pages` branch with the root option and click **Save** +5. After saving, an internal GitHub Action **pages build and deployment** is automatically created and triggered, deploying the content to the GitHub Pages website +6. Initially, the website will be accessible at `https://[your-username].github.io/stride-website` but with broken styling + +### Add Custom Domain + +1. To resolve styling issues, deploy the site to a custom domain. This is necessary because the site isn't deployed at the root directory on GitHub Pages +2. Go to **Settings** → **Pages** → **Custom domain** + - Enter your custom domain and follow the instructions for verification +3. Upon saving, the **pages build and deployment** action is triggered again, adding a `CNAME` file containing your custom domain name to the `gh-pages` branch +4. Your website should now be fully operational on your custom domain, for example, `https://stride-website.vaclavelias.com/` is hosted on GitHub Pages \ No newline at end of file diff --git a/en/contributors/website/eleventy.md b/en/contributors/website/eleventy.md index 6a6d1632d..c96bcd6ac 100644 --- a/en/contributors/website/eleventy.md +++ b/en/contributors/website/eleventy.md @@ -2,19 +2,8 @@ [Eleventy](https://www.11ty.dev/) is a static site generator that uses JavaScript as its templating language. It is a very powerful tool that allows us to create a website with a lot of flexibility and customization. It is also very easy to use and learn. This section will cover the basics of Eleventy configuration on the Stride website. Creating and updating the content is described in our [Content](content.md) section. We used to use **Jekyll** as our static site generator, but we decided to switch to Eleventy because of its flexibility and ease of use. We also wanted to use a tool that is more widely used and supported, which is why we decided to switch to Eleventy. - -# Table of Contents - -- [Packages and Dependencies](#packages-and-dependencies) -- [Configuration](#configuration) -- [Global Data](#global-data) -- [Folder Structure](#folder-structure) -- [Layouts](#layouts) -- [Includes](#includes) -- [Advanced Topics](#advanced-topics) - - [Creating Custom Shortcodes and Includes](#creating-custom-shortcodes-and-includes) - -# Packages and Dependencies + +## Packages and Dependencies Eleventy is a **Node.js** application. Please follow our [Installation](installation.md) guide to install Node.js and all the required dependencies. @@ -33,7 +22,7 @@ Packages we currently use: - `markdown-it-table-of-contents` - Table of contents plugin for markdown-it, used mainly in blog posts as `[[TOC]]` - `sass` - Sass compiler for our `/css/*.scss` files -# Configuration +## Configuration The Eleventy configuration is located in the `.eleventy.js` file at the root of the project. This file contains all the configuration settings for the Eleventy build process. As it is a JavaScript file, you can utilize all JavaScript features and syntax within it. @@ -43,13 +32,13 @@ The Eleventy configuration is located in the `.eleventy.js` file at the root of - pass through files - Files that are copied to the output folder without any processing - custom collections - Custom collections used in the templates like `tagList` and `yearList` - filters - Custom filters used in the templates -- custom shortcodes - Custom [shortcodes](content.md#shortcodes-and-includes) used in the templates, pages or blog posts. +- custom shortcodes - Custom [shortcodes](content-shortcodes-and-includes.md) used in the templates, pages or blog posts. The file is well-commented and should be self-explanatory. If you need to add a new configuration, please follow the existing structure and include a comment to explain the new configuration. -# Global Data +## Global Data -Global data is located in the `/_data` folder. It contains all the global data that is accessible in all the templates. Currently, we have these JSON files: +Global data is located in the `_data` folder. It contains all the global data that is accessible in all the templates. Currently, we have these JSON files: - `site.json` - Contains all the global data for the website, used in the templates and shortcodes. - `features.json` - Contains all the data for the features page and its features sections. @@ -64,31 +53,31 @@ Our `site.json` file contains these main properties, with only some listed below - `authors` - Contains all the authors used in the blog posts - repeated data - like `csharp-version`, `dotnet-version`, `download-version` which are used in multiple places on the website and are updated with every release -# Folder Structure +## Folder Structure The folder structure is crucial for Eleventy, as it determines the output of the build process. The folder structure is organized as follows: -**Folders** - -- `/_data` - Global data -- `/_drafts` - Draft blog posts (excluded from the build process) -- `/_includes` - Reusable code snippets that can be included in multiple pages -- `/_layouts` - Main layout pages (`container`, `page`, `post`) using the primary layout page `default` -- `/_site` - Output build folder (excluded in `.gitignore` and used for deployment) -- `/assets` - Additional assets, such as scripts -- `/blog` - Blog content page -- `/css` - Website stylesheets -- `/files` - Stride installer files -- `/images` - Images and MP4 files used on the website -- `/legal` - Content page -- `/posts` - Blog posts -- `/posts/2014-2021` - Old blog posts which are merged to the same output folder as `/posts` +### Folders + +- `_data` - Global data +- `_drafts` - Draft blog posts (excluded from the build process) +- `_includes` - Reusable code snippets that can be included in multiple pages +- `_layouts` - Main layout pages (`container`, `page`, `post`) using the primary layout page `default` +- `_site` - Output build folder (excluded in `.gitignore` and used for deployment) +- `assets` - Additional assets, such as scripts +- `blog` - Blog content page +- `css` - Website stylesheets +- `files` - Stride installer files +- `images` - Images and MP4 files used on the website +- `legal` - Content page +- `posts` - Blog posts +- `posts/2014-2021` - Old blog posts which are merged to the same output folder as `/posts` - this folder is only for convenience to easily access new posts -- `/wiki` - Excluded from build process, used only for wiki deployment +- `wiki` - GitHub wiki content - Excluded from build process, used only for wiki deployment. This will be decommissioned because the content was moved to Stride Docs -**Files** +### Files -- `/posts/posts.json` - Blog post defaults so they don't have to be repeated in the front matter +- `posts/posts.json` - Blog post defaults so they don't have to be repeated in the front matter - `*.html` - HTML content pages - `*.liquid` - Liquid content pages - `*.md` - Markdown content pages @@ -97,7 +86,7 @@ The folder structure is crucial for Eleventy, as it determines the output of the - `.eleventyignore` - Lists files and folders not to be processed by Eleventy - `package.json` - Eleventy project metadata used by `npm` -**Non Eleventy files:** +### Non Eleventy files - `.nojekyll` - Special file for GitHub Pages - `CNAME` - Custom domain for GitHub Pages @@ -110,35 +99,34 @@ The folder structure is crucial for Eleventy, as it determines the output of the - `web.config` - Configuration file for IIS deployment - `web.Release.config` - Configuration file for Windows ASP.NET Core deployment +> [!NOTE] +> This project includes ASP.NET Core solution and files, as they can be used seamlessly with Eleventy. Read more about this in our [Installation](installation.md#aspnet-core) section. -**Note:** This project includes ASP.NET Core solution and files, as they can be used seamlessly with Eleventy. Read more about this in our [Installation](installation.md#aspnet-core) section. - - -# Layouts +## Layouts -All the layouts are located in the `/_layouts` folder. The `default` layout is the main layout page and is used by all the other layouts. +All the layouts are located in the `_layouts` folder. The `default` layout is the main layout page and is used by all the other layouts. - `default` - Main layout page - `container` - Used by some pages - `page` - Used by most of the pages - `post` - Used by blog posts -# Includes +## Includes -All the includes are located in the `/_includes` folder. The includes are reusable code snippets that can be included in multiple pages. +All the includes are located in the `_includes` folder. The includes are reusable code snippets that can be included in multiple pages. Some includes are used solely by the layouts, while others are used by the content pages. -# Advanced Topics +## Advanced Topics -## Creating Custom Shortcodes and Includes +### Creating Custom Shortcodes and Includes -If you need to create a custom shortcode or include, please follow the existing structure and [include a comment](content.md#shortcodes-and-includes) to explain the new shortcode or include. +If you need to create a custom shortcode or include, please follow the existing structure and [include a comment](content-shortcodes-and-includes.md) to explain the new shortcode or include. -The shortcodes are defined in the `.eleventy.js` file, while the includes are located in the `/_includes` folder. +The shortcodes are defined in the `.eleventy.js` file, while the includes are located in the `_includes` folder. You can explore the existing shortcodes and includes to get a better understanding of how they work and how to create new ones. -## Performance Optimization +### Performance Optimization ToDo: Remove this section if not needed \ No newline at end of file diff --git a/en/contributors/website/figma.md b/en/contributors/website/figma.md index 3bf256aab..9ecdb5ffd 100644 --- a/en/contributors/website/figma.md +++ b/en/contributors/website/figma.md @@ -1,11 +1,13 @@ -# Figma -For Stride we have official logo's for various solutions and occasions. +# Figma Designs -You can find the official [Figma designs here](https://www.figma.com/file/LwUrbnxR1hVkO53R3yqpQT/STRIDE3D?type=design&node-id=126-192&mode=design) +Stride boasts a range of official logos tailored for various applications and occasions. -We have logo's for the following scenarios -* Stride logo -* Stride icons -* Stride website mockups -* Stride tutorial thumbnails -* Stride splash screens \ No newline at end of file +Access the official [Stride Figma designs](https://www.figma.com/file/LwUrbnxR1hVkO53R3yqpQT/STRIDE3D?type=design&node-id=126-192&mode=design) to explore and utilize these creative resources. + +Our Figma design collection encompasses: + +- **Stride Logo**: The core visual representation of the Stride brand +- **Stride Icons**: A variety of icons reflecting Stride's identity and functionality +- **Stride Website Mockups**: Conceptual designs and layouts for the Stride website +- **Stride Tutorial Thumbnails**: Engaging and informative thumbnails for Stride tutorials +- **Stride Splash Screens**: Visually striking splash screens for Stride software and applications \ No newline at end of file diff --git a/en/contributors/website/index.md b/en/contributors/website/index.md index b39c5fd6e..ffbde74bc 100644 --- a/en/contributors/website/index.md +++ b/en/contributors/website/index.md @@ -1,4 +1,5 @@ -# Contributing to the Stride website +# Contributing to the Stride website + This documentation serves as a comprehensive guide to help you navigate and contribute to the **Stride website**. If you're looking to make minor changes, such as adding or updating a post or page, or fixing a typo, you can jump straight to the [Content Updates](content.md#content-updates) section. @@ -13,58 +14,17 @@ Technologies we use to build our website: - Bootstrap - Font Awesome - HTML, JavaScript, CSS, SCSS, and JSON -- GitHub Actions (CI/CD) - Don't worry, this is already set up, you don't need to worry about it. - -## Important Links +- GitHub Actions (CI/CD) + - Our [GitHub Actions](https://github.com/stride3d/stride-website/tree/master/.github/workflows) are already configured for deploying to both staging and release environments. + - For personal testing or demonstration purposes, you may need to set up your own GitHub Actions. This is especially useful for showcasing proposed changes to maintainers for their approval. For guidance on this, refer to our [Deployment to GitHub Pages guide](deployment-azure.md#deployment-to-github-pages). -- https://www.stride3d.net/legal/privacy-policy/ - - This links is used in the Stride Installer -- https://www.stride3d.net/feed.xml - - This feed is loaded in the Stride Launcher +## Dependencies -## Table of Contents +Various Stride systems rely on content fetched and processed from either the Stride website or the Stride Docs website. It's crucial to ensure that the following links remain active and accessible. Please refrain from removing or altering these links unless the dependent systems have been updated accordingly to accommodate any changes. -- [Installation](installation.md) - - [Prerequisites](installation.md#prerequisites) - - [Installation Steps](installation.md#installation-steps) - - [Running the Development Server](installation.md#running-the-development-server) - - [ASP.NET Core](installation.md#aspnet-core) -- [Content](content.md) - - [Content Updates](content.md#content-updates) - - [Small Updates](content.md#small-updates) - - [Major Updates](content.md#major-updates) - - [Creating New Post](content.md#creating-new-post) - - [Post Naming Convention](content.md#post-naming-convention) - - [Post Front Matter](content.md#post-front-matter) - - [Post Content](content.md#post-content) - - [Excerpt](content.md#excerpt) - - [Creating New Page](content.md#creating-new-page) - - [Page Front Matter](content.md#page-front-matter) - - [Shortcodes and Includes](content.md#shortcodes-and-includes) - - [Alert](content.md#alert) - - [Alert Banner](content.md#alert-banner) - - [Image](content.md#image) - - [Video](content.md#video) - - [Web Assets](content.md#web-assets) - - [Styling](content.md#styling) - - [Bootstrap Customization](content.md#bootstrap-customization) - - [CSS Guidelines](content.md#css-guidelines) - - [Submitting your Changes](content.md#submitting-your-changes) -- [Roadmap](roadmap.md) -- [Eleventy](eleventy.md) - - [Packages and Dependencies](eleventy.md#packages-and-dependencies) - - [Configuration](eleventy.md#configuration) - - [Global Data](eleventy.md#global-data) - - [Folder Structure](eleventy.md#folder-structure) - - [Layouts](eleventy.md#layouts) - - [Includes](eleventy.md#includes) - - [Advanced Topics](eleventy.md#advanced-topics) - - [Creating Custom Shortcodes and Includes](eleventy.md#creating-custom-shortcodes-and-includes) -- [Deployment](deployment.md) - - [Azure Web Apps](deployment.md#azure-web-apps) - - [Deploying with .NET Framework](deployment.md#deploying-with-net-framework) - - [Deployment To Wiki](deployment.md#deployment-to-wiki) -- [Troubleshooting and FAQ](troubleshooting-and-faq.md) - - [Known Issues](troubleshooting-and-faq.md#known-issues) - - [Common Issues and Solutions](troubleshooting-and-faq.md#common-issues-and-solutions) - - [Frequently Asked Questions](troubleshooting-and-faq.md#frequently-asked-questions) \ No newline at end of file +1. https://www.stride3d.net/legal/privacy-policy/ + - This link is integral to the **Stride Installer**. It provides users with transparent information about data handling and privacy considerations associated with using Stride. +2. https://www.stride3d.net/feed.xml + - The **Stride Launcher** utilizes this feed to keep users updated with the latest news, updates, and announcements from the Stride community. +3. https://doc.stride3d.net/latest/en/index.json + - This JSON file is crucial for integrating the Stride Website's search functionality with the Stride Documentation. It ensures that search results are comprehensive, including relevant information from both the Stride website and Stride Docs. \ No newline at end of file diff --git a/en/contributors/website/installation.md b/en/contributors/website/installation.md index 4c24dbed1..52a712e92 100644 --- a/en/contributors/website/installation.md +++ b/en/contributors/website/installation.md @@ -1,27 +1,18 @@ # Local installation + This guide will walk you through the steps to install the Stride website on your local machine for development purposes. Although we use the Windows operating system for development, the steps should be similar for other operating systems. -[Minor updates](content.md#small-updates) can be made directly on GitHub. However, for [more significant updates](content.md#major-updates) that affect multiple pages, we recommend using a local development environment so you can see the impact of your changes beforehand. This is because we use the **Eleventy** static site generator, and in some cases, all pages need to be regenerated. This approach helps you assess your changes before submitting a pull request. +[Minor updates](content.md#small-updates) can be made directly on GitHub. However, for [more significant updates](content.md#major-updates) that affect multiple pages, we recommend using a local development environment so you can see the impact of your changes beforehand. This is because we use the [Eleventy](https://www.11ty.dev/docs/) static site generator, and in some cases, all pages need to be regenerated. This approach helps you assess your changes before submitting a pull request. This guide assumes you have a basic understanding of the technologies used in the Stride website. -# Table of Contents - -- [Prerequisites](#prerequisites) -- [Installation Steps](#installation-steps) -- [Running the Development Server](#running-the-development-server) -- [ASP.NET Core](#aspnet-core) - -# Prerequisites +## Prerequisites Before updating the Stride website, ensure you are familiar with the following prerequisites: -1. **Node.js 16+ (including npm) installed:** You can download the installer from the [Node.js website](https://nodejs.org/en/download) - - If Node.js is already installed, ensure you have version 16 or higher. You can check your version by running `node -v` in a terminal. Note that `npm`, the package manager for Node.js, is included with the installation -1. **Git installed:** You will need Git for version control. If you don't have Git installed, you can download it from the [Git website](https://git-scm.com/downloads) -1. **Development IDE of choice:** Choose an Integrated Development Environment (IDE) that you're comfortable with for development. Although there are various popular choices, such as Visual Studio, Visual Studio Code, and others, this guide will focus on using **Visual Studio**, as it is the primary IDE for the Stride project, and as of writing, we use **Visual Studio 2022**. You can download the free Community edition from the [Visual Studio website](https://visualstudio.microsoft.com/downloads/) +[!INCLUDE [docs-prerequisites](../../includes/docs-prerequisites.md)] -# Installation Steps +## Installation Steps 1. ❓You might want to create an issue so we can track your contribution and avoid duplicate work. If you're unsure whether your contribution is needed, feel free to create an issue and ask 1. 🍴 Fork the repository by navigating to the [Stride website repository](https://github.com/stride3d/stride-website) and clicking the **Fork** button in the top-right corner @@ -30,7 +21,7 @@ Before updating the Stride website, ensure you are familiar with the following p 1. 📁 Go to the project folder `cd stride-website` 1. 🚀 Run `npm install` to install all dependencies -# Running the Development Server +## Running the Development Server 1. 🚀 Run `npm start` (`npx @11ty/eleventy --serve`) in the command line to start the development server 1. 📋 You should see many logs in the command line, indicating the progress and displaying any errors @@ -44,7 +35,7 @@ Before updating the Stride website, ensure you are familiar with the following p Let's [update the content](content.md) now! -# ASP.NET Core +## ASP.NET Core This static website can also be hosted using ASP.NET Core. diff --git a/en/contributors/website/major-release-workflow.md b/en/contributors/website/major-release-workflow.md new file mode 100644 index 000000000..7395c4904 --- /dev/null +++ b/en/contributors/website/major-release-workflow.md @@ -0,0 +1,13 @@ +# Major Release Workflow + +1. **Create a Release Blog Post** + - Place the post inside the `_drafts` folder, which is not deployed, or directly in the `posts` folder for testing in the `staging` environment. Note: If you need to deploy updates to the `release` branch, remember to move the post back to the `_drafts` folder. +2. **Update `_data\site.json` with the following settings**, which are used in multiple places on the website: + - `version`: Increase the version number + - This helps refresh the cached CSS file + - `download-version`: Update the version number for downloads + - Used on the home page + - `csharp-version`: Update to the current C# version being used + - Used on the home page and features page + - `dotnet-version`: Update to the current .NET version being used + - Used on the home page and features page \ No newline at end of file diff --git a/en/contributors/website/media/alert-banner-example.jpg b/en/contributors/website/media/alert-banner-example.jpg new file mode 100644 index 000000000..77e34fe29 --- /dev/null +++ b/en/contributors/website/media/alert-banner-example.jpg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5a652157b376de3e8880469ea5434cd26936fbfda358d5cd25c040c7f7e4c26f +size 74911 diff --git a/en/contributors/website/media/alert-examples.jpg b/en/contributors/website/media/alert-examples.jpg new file mode 100644 index 000000000..e6c4526bd --- /dev/null +++ b/en/contributors/website/media/alert-examples.jpg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9ca887d6a33d7cce6716964f3fd785c3adc17325948666df4560eecee891f401 +size 120834 diff --git a/en/contributors/website/roadmap.md b/en/contributors/website/roadmap.md index c7262be2d..7fd8df866 100644 --- a/en/contributors/website/roadmap.md +++ b/en/contributors/website/roadmap.md @@ -1,11 +1,9 @@ # Website roadmap -This is a proposal for our website roadmap and ongoing website development plan. -- Tackle existing issues listed in the [Issues](https://github.com/stride3d/stride-website/issues) -- Convert images to WebP for better performance -- Streamline the website by decoupling media from the site - - Host videos on YouTube - - Host images in Azure Blob Storage or another location -- Optimize the website for possible deployment on Azure Static Web Apps - +This document outlines a proposed roadmap and an ongoing development plan for our Stride website. +- **Address Existing Issues**: Prioritize resolving issues listed in the [Issues](https://github.com/stride3d/stride-website/issues) section on GitHub. +- **Image Optimization**: Convert existing images to the WebP format to enhance website performance. +- **Decoupling Media**: Streamline the website by decoupling media from the site + - Consider hosting videos on YouTube + - Consider hosting images in Azure Blob Storage or another location \ No newline at end of file diff --git a/en/contributors/website/troubleshooting-and-faq.md b/en/contributors/website/troubleshooting-and-faq.md index c4f6a0328..768f69823 100644 --- a/en/contributors/website/troubleshooting-and-faq.md +++ b/en/contributors/website/troubleshooting-and-faq.md @@ -1,21 +1,16 @@ # Troubleshooting and FAQ -- [Known Issues](#known-issues) -- [Common Issues and Solutions](#common-issues-and-solutions) -- [Frequently Asked Questions](#frequently-asked-questions) -# Known Issues +## Known Issues 1. **Sponsor Page - Widget Incompatibility with dark theme:** Widgets on the Sponsor Page currently do not support the dark theme. As a workaround, we can either fetch data from https://opencollective.com/stride3d/members/all.json and render it before deployment or make it dynamic. Both options would give us more control over the content and design, and allow for better compatibility with the dark theme in the future. 1. **Search Page - Lack of pagination:** At present, the Search Page does not have pagination, which limits the maximum number of search results displayed to 100. To resolve this issue, we can implement a pager in JavaScript. This would enable users to navigate through multiple pages of search results, providing a more comprehensive view of the available content. -# Common Issues and Solutions +## Common Issues and Solutions Any issue should be added to Stride Website [GitHub issues](https://github.com/stride3d/stride-website/issues) so it can be tracked and elaborated by the community. -# Frequently Asked Questions +## Frequently Asked Questions **Q:** I just want to fix a typo in a post. Do I need to follow your installation steps? -**A:** *No, you can fix the typo directly on the GitHub website. However, you will still need to fork the repo, make your update on the main branch or a new branch, and then create a pull request. You can follow this guide for [minor updates](content.md#small-updates).* - - +**A:** *No, you can fix the typo directly on the GitHub website. However, you will still need to fork the repo, make your update on the main branch or a new branch, and then create a pull request. You can follow this guide for [minor updates](content.md#small-updates).* \ No newline at end of file diff --git a/en/diagnostics/STRDIAG002.md b/en/diagnostics/STRDIAG002.md index 55c8cae43..8de924411 100644 --- a/en/diagnostics/STRDIAG002.md +++ b/en/diagnostics/STRDIAG002.md @@ -6,7 +6,7 @@ ## Explanation The [DataMemberMode.Content](xref:Stride.Core.DataMemberMode) mutates the object which is currently in the member. -As this is not possible with the current serializers, only mutable types are supported for `DataMemberMode.Content`. Immutable types in this context are none reference types and string. +As this is not possible with the current serializers, only mutable types are supported for `DataMemberMode.Content`. Immutable types in this context are not reference types and strings. ## Example diff --git a/en/diagnostics/STRDIAG004.md b/en/diagnostics/STRDIAG004.md index 7ebdb10e8..ef804ab0a 100644 --- a/en/diagnostics/STRDIAG004.md +++ b/en/diagnostics/STRDIAG004.md @@ -34,11 +34,10 @@ public class STRDIAG004 ``` > [!WARNING] -> There is an edge case with `internal`/`internal protected`, it will count as non visible when the @Stride.Core.DataMemberAttribute isn't applied. +> There is an edge case with `internal`/`internal protected`, it will count as non visible when the @Stride.Core.DataMemberAttribute isn't applied. > But when the attribute is applied then the getter counts as visible and therefore is correct. ```csharp -// STRDIAG000.cs using Stride.Core; public class STRDIAG004 diff --git a/en/diagnostics/STRDIAG009.md b/en/diagnostics/STRDIAG009.md index 655acdf48..3c42288cc 100644 --- a/en/diagnostics/STRDIAG009.md +++ b/en/diagnostics/STRDIAG009.md @@ -28,7 +28,7 @@ public class STRDIAG009 ## Solution -To resolve the warning, remove the @Stride.Core.DataMemberAttribute. Or change the key of the `IDictionary` to a supported type. Add a pragma Suppression in the IDE if it is a valid type. +To resolve the warning, remove the @Stride.Core.DataMemberAttribute or add @Stride.Core.DataMemberIgnoreAttribute. Or change the key of the `IDictionary` to a supported type. Add a pragma Suppression in the IDE if it is a valid type. ## References diff --git a/en/docfx.json b/en/docfx.json index e4c5696f2..0da66bf99 100644 --- a/en/docfx.json +++ b/en/docfx.json @@ -25,7 +25,7 @@ ], "src": "../../stride", "properties": { - "TargetFramework": "net6.0", + "TargetFramework": "net8.0", "StrideBuildDoc": "true" } }, @@ -36,7 +36,7 @@ ], "src": "../../stride", "properties": { - "TargetFramework": "net6.0-windows7.0", + "TargetFramework": "net8.0-windows7.0", "StrideBuildDoc": "true" } } @@ -58,7 +58,7 @@ "_enableSearch": true, "_appLogoPath": "media/stride-logo-red.svg", "_appLogoUrl": "https://www.stride3d.net/", - "_appFooter": "

Supported by the .NET Foundation

Made with docfx

Stride Docs Website v.2.0.0.7

© .NET Foundation and Contributors

", + "_appFooter": "

Supported by the .NET Foundation

Made with docfx

Stride Docs Website v.2.0.0.8

© .NET Foundation and Contributors

", "_gitContribute": { "repo": "https://github.com/stride3d/stride-docs", "branch": "master" @@ -97,8 +97,6 @@ }, { "files": [ - "articles/**.md", - "articles/**/toc.yml", "toc.yml", "*.md" ] @@ -149,4 +147,4 @@ "keepFileLink": false, "disableGitFeatures": false } -} +} \ No newline at end of file diff --git a/en/includes/docs-prerequisites.md b/en/includes/docs-prerequisites.md new file mode 100644 index 000000000..c12538c58 --- /dev/null +++ b/en/includes/docs-prerequisites.md @@ -0,0 +1,5 @@ +1. Familiarity with the command line +1. **.NET SDK 8.0 or higher:** You can download the installer from the [.NET SDK website](https://dotnet.microsoft.com/en-us/download) + - If .NET SDK is already installed, ensure you have version 8.0 or higher. You can check your version by running `dotnet --info` in a terminal. +1. **Git installed:** You will need Git for version control. If you don't have Git installed, you can download it from the [Git website](https://git-scm.com/downloads) +1. **Development IDE of choice:** Choose an Integrated Development Environment (IDE) that you're comfortable with for development. Although there are various popular choices, such as Visual Studio, Visual Studio Code, and others, this guide will focus on using **Visual Studio**, as it is the primary IDE for the Stride project, and as of writing, we use **Visual Studio 2022**. You can download the free Community edition from the [Visual Studio website](https://visualstudio.microsoft.com/downloads/) \ No newline at end of file diff --git a/en/includes/small-update-instructions.md b/en/includes/small-update-instructions.md new file mode 100644 index 000000000..31d40f731 --- /dev/null +++ b/en/includes/small-update-instructions.md @@ -0,0 +1,9 @@ +1. Go to the repository +1. Locate the file you wish to edit +1. Click the `Edit this file` (pencil) icon in the top right corner +1. If prompted, fork the repository by clicking `Fork this repository` +1. Make your changes to the file, then write a brief commit message describing the changes +1. Click on the `Propose changes` button +1. On the next screen, click the `Create pull request` button +1. Provide a title and description for your pull request, and click on `Create pull request` again +1. Wait for the review and merge \ No newline at end of file diff --git a/en/includes/submitting-changes.md b/en/includes/submitting-changes.md new file mode 100644 index 000000000..b360f5054 --- /dev/null +++ b/en/includes/submitting-changes.md @@ -0,0 +1,13 @@ +Assuming you have made all necessary changes and tested them on the development server, you can submit a pull request to the `master` branch. The pull request will be reviewed and merged by the website maintainers. + +Steps to contribute your updates: + +1. Commit your changes to your forked repository: + - Commit the changes with a meaningful message + - Push the changes to your forked repository +1. Create a pull request to the main repository: + - You can create a pull request from your forked repository by navigating to Pull requests page and click **New pull request** button + - Select the **master** branch as the base branch and your branch as the compare branch + - Click **Create pull request** button + +Once your pull request has been reviewed and approved, your changes will be merged into the main repository and deployed to the website. \ No newline at end of file diff --git a/en/index.md b/en/index.md index 60c4d7b19..818c9621f 100644 --- a/en/index.md +++ b/en/index.md @@ -34,9 +34,9 @@ Welcome to the Stride documentation, specifically designed for game developers,

🌟 Contributors

-

Learn how you can contribute to Stride's development.

+

Join our vibrant community of creators and contribute to Stride's growth. Whether you're enhancing the engine, documentation, or the website, your contributions shape the future of Stride.

-

Start contributing to Stride

+

Start contributing to Stride

@@ -48,7 +48,24 @@ Welcome to the Stride documentation, specifically designed for game developers,

View Stride API Reference

+
+
+
+

🔍 Diagnostics

+

In the world of game development, unexpected behavior is a common challenge. Stride's diagnostic tools are designed to help you quickly and effectively diagnose and resolve these issues.

+
+

Explore Diagnostics

+
+
+## 📥 Download PDF Versions + +You can download PDF versions of various Stride documentation sections: + +- [Stride Manual](manual/stride-manual.pdf): (File size: 82MB) +- [Stride Tutorials](tutorials/stride-tutorials.pdf): (File size: 13MB) +- [Contributing to Stride](contributors/contributing-in-stride.pdf): (File size: 8MB) + > [!NOTE] > Please note that while our English documentation is actively updated, translations may not always be current. We recommend English-literate users to refer to the original for the latest information. To help with translations or report discrepancies, please see our GitHub or community forums. Your input is invaluable! \ No newline at end of file diff --git a/en/manual/animation/additive-animation.md b/en/manual/animation/additive-animation.md index 7ac095923..cd1e33937 100644 --- a/en/manual/animation/additive-animation.md +++ b/en/manual/animation/additive-animation.md @@ -7,7 +7,7 @@ ![Additive animations](media/animations-additive-sample.gif) -In the example above, the leftmost animation is the *Walk* animation. The rightmost animation is the *Idle* animation. The two animations in the center are the *Walk* and *Idle* animations respectively, but have the *Reload* animation added to them. +In the example above, the leftmost animation is the *Walk* animation. The rightmost animation is the *Idle* animation. The two animations in the center are the *Walk* and *Idle* animations respectively, but have the *Reload* animation added to them. This means we only had to create three animations: *Walk*, *Idle*, and *Reload*. Additionally, we can add the *Reload* animation to other suitable animations (eg *Crouch*, *Strafe* or *Run*). This helps keep the memory budget and number of animations low. @@ -22,7 +22,7 @@ Stride calculates the difference between the source and reference clips to creat We can use use the difference clip to blend the source and reference animations. We can also use the same difference clip to blend the source animation with **other** animations. If the animation you add it to is sufficiently similar to the original reference clip, then the animations blend effectively. For example, you could use it to add the reload animation to any animation that doesn't use the arms, such as crouching. >[!Note] ->Additive animations should use the same skinned mesh and skeleton. +>Additive animations should use the same skinned mesh and skeleton. ### Create a difference clip @@ -30,7 +30,7 @@ We can use use the difference clip to blend the source and reference animations. 2. As we don't need a source for this animation, click **Cancel**. - Game Studio asks if you want to create an animation without a source file. + Game Studio asks if you want to create an animation without a source file. ![Create animation without source file](media/create-animation-without-source-file.png) diff --git a/en/manual/animation/custom-blend-trees.md b/en/manual/animation/custom-blend-trees.md index 4a9f4c520..8a114215d 100644 --- a/en/manual/animation/custom-blend-trees.md +++ b/en/manual/animation/custom-blend-trees.md @@ -3,7 +3,7 @@ Advanced Programmer -The [AnimationComponent](xref:Stride.Engine.AnimationComponent) has the property [AnimationComponent.BlendTreeBuilder](xref:Stride.Engine.AnimationComponent#Stride_Engine_AnimationComponent_BlendTreeBuilder). If you want absolute control over which animations are played, how are they blended and what weights they have, you can create a script which inherits from `IBlendTreeBuilder` and assign it to the BlendTreeBuilder under your animation component. +The [AnimationComponent](xref:Stride.Engine.AnimationComponent) has the property [AnimationComponent.BlendTreeBuilder](xref:Stride.Engine.AnimationComponent#Stride_Engine_AnimationComponent_BlendTreeBuilder). If you want absolute control over which animations are played, how are they blended and what weights they have, you can create a script which implements from `IBlendTreeBuilder` and assign it to the BlendTreeBuilder under your animation component. When the animation component is updated, it calls `void BuildBlendTree(FastList animationList)` on your script instead of updating the animations itself. This allows you to choose any combination of animation clips, speeds and blends, but is also more difficult, as all the heavy lifting is now on the script side. diff --git a/en/manual/animation/import-animations.md b/en/manual/animation/import-animations.md index befb8df20..4cd573452 100644 --- a/en/manual/animation/import-animations.md +++ b/en/manual/animation/import-animations.md @@ -9,7 +9,7 @@ To animate a model, you need to use three kinds of assets together: * skeletons * animations -You can import these assets from 3D model files. Stride supports the following model file types: ``.3ds``, ``.blend``, ``.dae``, ``.dxf``, ``.fbx``, ``.md2``, ``.md3``, ``.obj``, ``.x`` +Stride supports the following model file types: `.3ds`, `.blend`, `.dae`,`dxf`, `.fbx`, `.glb`, `.gltf`, `.md2`, `.md3`, `.obj`, `.ply`, `.stl`,`.stp`, `.x`. ## Import a model, skeleton, or animation from a model file diff --git a/en/manual/audio/audio-listeners.md b/en/manual/audio/audio-listeners.md index 1ee066eb5..91a5294a5 100644 --- a/en/manual/audio/audio-listeners.md +++ b/en/manual/audio/audio-listeners.md @@ -19,7 +19,7 @@ To create an audio listener, attach an **audio listener component** to an entity 2. In the **Property Grid**, click _Add Component_ and select [Audio listener component](xref:Stride.Audio.AudioListener): - ![Add AudioListener Component](media/audio-add-audiolistener-component.png) + ![Add AudioListener component](media/audio-add-audiolistener-component.png) The entity is now an audio listener. diff --git a/en/manual/audio/hrtf.md b/en/manual/audio/hrtf.md index 3a86485ac..40fbf8e65 100644 --- a/en/manual/audio/hrtf.md +++ b/en/manual/audio/hrtf.md @@ -21,7 +21,7 @@ To use HRTF, first enable it globally in the **Game Settings** asset, then enabl ### 1. Enable HRTF globally -1. In the **Solution Explorer** (the bottom-left pane by default), select the **Assets folder**. +1. In **Solution explorer** (the bottom-left pane by default), select the **Assets folder**. ![Select Assets folder asset](../game-studio/media/select-asset-folder.png) diff --git a/en/manual/audio/import-audio.md b/en/manual/audio/import-audio.md index 467bc5040..a64068f15 100644 --- a/en/manual/audio/import-audio.md +++ b/en/manual/audio/import-audio.md @@ -21,7 +21,7 @@ You can import audio files to use as **audio assets** in your project. You can i * **Sound effect**: Recommended for smaller files that you want to play directly from memory. - * **Spatialized sound**: Process the audio asset as [spatialized audio](spatialized-audio.md). Note that Stride processes audio files as mono (single-channel) audio. The source file is unaffected. + * **Spatialized audio*: Process the audio asset as [spatialized audio](spatialized-audio.md). Note that Stride processes audio files as mono (single-channel) audio. The source file is unaffected. * **Music**: Recommended for larger files that you want to stream from disk to save memory. @@ -31,7 +31,7 @@ After you import an audio file, you can select it as an asset in the **Asset Vie You can also import a [video](../video/index.md) file and choose to import only the audio tracks from it. -1. In the **Asset View**, click **Add assett** and select **Media > Video**. +1. In the **Asset View**, click **Add asset** and select **Media > Video**. ![Add video asset](../video/media/add-video-asset.png) diff --git a/en/manual/audio/non-spatialized-audio.md b/en/manual/audio/non-spatialized-audio.md index 0fc280241..8ad3a8e88 100644 --- a/en/manual/audio/non-spatialized-audio.md +++ b/en/manual/audio/non-spatialized-audio.md @@ -27,14 +27,14 @@ To play non-spatialized audio at runtime, create an instance of it and define it The [SoundInstance](xref:Stride.Audio.SoundInstance) controls audio at runtime with the following properties: -| Property | Function | -|------- |-------| -| [IsLooping](xref:Stride.Audio.SoundInstance.IsLooping) | Gets or sets looping of the audio. | -| [Pan](xref:Stride.Audio.SoundInstance.Pan) | Sets the balance between left and right speakers. By default, each speaker a value of 0.5. | -| [Pitch](xref:Stride.Audio.SoundInstance.Pitch) | Gets or sets the audio pitch (frequency). | -| [PlayState](xref:Stride.Audio.SoundInstance.PlayState) | Gets the state of the [SoundInstance](xref:Stride.Audio.SoundInstance). | -| [Position](xref:Stride.Audio.SoundInstance.Position) | Gets the current play position of the audio. | -| [Volume](xref:Stride.Audio.SoundInstance.Volume) | Sets the audio volume. | +| Property | Function | +|--------------------------------------------------------|------------------------------------------------------------------------------------------| +| [IsLooping](xref:Stride.Audio.SoundInstance.IsLooping) | Gets or sets looping of the audio. | +| [Pan](xref:Stride.Audio.SoundInstance.Pan) | Sets the balance between left and right speakers. By default, each speaker a value of 0. | +| [Pitch](xref:Stride.Audio.SoundInstance.Pitch) | Gets or sets the audio pitch (frequency). | +| [PlayState](xref:Stride.Audio.SoundInstance.PlayState) | Gets the state of the [SoundInstance](xref:Stride.Audio.SoundInstance). | +| [Position](xref:Stride.Audio.SoundInstance.Position) | Gets the current play position of the audio. | +| [Volume](xref:Stride.Audio.SoundInstance.Volume) | Sets the audio volume. | For more details, see the [SoundInstance API documentation](xref:Stride.Audio.SoundInstance). diff --git a/en/manual/audio/play-a-range-within-an-audio-file.md b/en/manual/audio/play-a-range-within-an-audio-file.md index 65ccf7032..1774914f9 100644 --- a/en/manual/audio/play-a-range-within-an-audio-file.md +++ b/en/manual/audio/play-a-range-within-an-audio-file.md @@ -9,17 +9,17 @@ You can have Stride play only certain portions of an audio asset. This means, fo You can use the following properties, methods, and structures: -| Property, method, or structure | Function | -|---------|-----------| -| [TotalLength](xref:Stride.Audio.SoundBase.TotalLength) | The total length of the [sound](xref:Stride.Audio.Sound). | -| [SoundInstance.SetRange(PlayRange)](xref:Stride.Audio.SoundInstance.SetRange(Stride.Media.PlayRange)) | Sets the time range to play within the audio asset. | -| [PlayRange](xref:Stride.Media.PlayRange) | Time information, including the range's starting point and length. | -| [SoundInstance.Position](xref:Stride.Audio.SoundInstance.Position) | Gets the current play position as **TimeSpan**. | +| Property, method, or structure | Function | +|-------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------| +| [TotalLength](xref:Stride.Audio.SoundBase.TotalLength) | The total length of the [sound](xref:Stride.Audio.Sound). | +| [SoundInstance.SetRange(PlayRange)](xref:Stride.Audio.SoundInstance.SetRange(Stride.Media.PlayRange)) | Sets the time range to play within the audio asset. | +| [PlayRange](xref:Stride.Media.PlayRange) | Time information, including the range's starting point and length. | +| [SoundInstance.Position](xref:Stride.Audio.SoundInstance.Position) | Gets the current play position as **TimeSpan**. | For example: ```cs -//Assume sample length is 5 seconds. +//Assume sample length is 4 seconds. var length = mySound.TotalLength; var begin = TimeSpan.FromSeconds(2); var duration = TimeSpan.FromSeconds(2); diff --git a/en/manual/engine/entity-component-model/index.md b/en/manual/engine/entity-component-system/index.md similarity index 98% rename from en/manual/engine/entity-component-model/index.md rename to en/manual/engine/entity-component-system/index.md index dd3336430..b8b052213 100644 --- a/en/manual/engine/entity-component-model/index.md +++ b/en/manual/engine/entity-component-system/index.md @@ -2,7 +2,7 @@ # Problem -> `Dog` is a subclasses of `Animal`. +> `Dog` is a subclass of `Animal`. This example is often used as an example of inheritance in introductions to programming. However, when things get more complex, diff --git a/en/manual/engine/entity-component-model/managing-entities.md b/en/manual/engine/entity-component-system/managing-entities.md similarity index 100% rename from en/manual/engine/entity-component-model/managing-entities.md rename to en/manual/engine/entity-component-system/managing-entities.md diff --git a/en/manual/engine/entity-component-model/media/7438984.png b/en/manual/engine/entity-component-system/media/7438984.png similarity index 100% rename from en/manual/engine/entity-component-model/media/7438984.png rename to en/manual/engine/entity-component-system/media/7438984.png diff --git a/en/manual/engine/entity-component-model/media/ecs-choice.jpg b/en/manual/engine/entity-component-system/media/ecs-choice.jpg similarity index 100% rename from en/manual/engine/entity-component-model/media/ecs-choice.jpg rename to en/manual/engine/entity-component-system/media/ecs-choice.jpg diff --git a/en/manual/engine/entity-component-model/usage.md b/en/manual/engine/entity-component-system/usage.md similarity index 100% rename from en/manual/engine/entity-component-model/usage.md rename to en/manual/engine/entity-component-system/usage.md diff --git a/en/manual/engine/index.md b/en/manual/engine/index.md index 7bc6599d6..026addd0a 100644 --- a/en/manual/engine/index.md +++ b/en/manual/engine/index.md @@ -4,7 +4,7 @@ >This section is out of date. For now, you should only use it for reference. - [Asset](assets/index.md) -- [Entity-component model](entity-component-model/index.md) +- [Entity-component system](entity-component-system/index.md) - [File system](file-system.md) # See also diff --git a/en/manual/engine/resources.md b/en/manual/engine/resources.md index 1707065c3..6376b47f1 100644 --- a/en/manual/engine/resources.md +++ b/en/manual/engine/resources.md @@ -2,6 +2,6 @@ [!INCLUDE [stride-studio-note](../../includes/under-construction-note.md)] -Resources are images, texture ([```.dds```](https://en.wikipedia.org/wiki/DirectDraw_Surface) files and entity images used in your game. Resources are stored in the **Resources** folder of a game application. +Resources are images, texture [```.dds```](https://en.wikipedia.org/wiki/DirectDraw_Surface) files and entity images used in your game. Resources are stored in the **Resources** folder of a game application. ->**Note:** As a best practice, all data resources should be placed inside the **Resources** folder to enable easy movement of your project. If resources are placed outside the project, moving the project breaks the links and compiler issues can occur. \ No newline at end of file +>**Note:** As a best practice, all data resources should be placed inside the **Resources** folder to enable easy movement of your project. If resources are placed outside the project, moving the project breaks the links and compiler issues can occur. diff --git a/en/manual/files-and-folders/cached-files.md b/en/manual/files-and-folders/cached-files.md index 8da951e50..6856a987e 100644 --- a/en/manual/files-and-folders/cached-files.md +++ b/en/manual/files-and-folders/cached-files.md @@ -14,7 +14,7 @@ You might want to clean the cache if: ![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. To do this, under **Stride**, select **Clean intermediate assets for Solution**. +2. If you have the [Stride Visual Studio extension](../get-started/visual-studio-extension.md) installed, you can also clean the asset cache. **Using VS 2022**: To do this, under Extensions > **Stride**, select **Clean intermediate assets for Solution**. ![Clean solution](media/clean-assets.png) diff --git a/en/manual/files-and-folders/distribute-a-game.md b/en/manual/files-and-folders/distribute-a-game.md index 759b2c7b6..9195c9a23 100644 --- a/en/manual/files-and-folders/distribute-a-game.md +++ b/en/manual/files-and-folders/distribute-a-game.md @@ -53,7 +53,7 @@ In the release folder in your project bin folder (eg *MyGame/Bin/MyPlatform/Rele * `.xml` files (API documentation) -* files that contain `vshost` in their filenames (eg `MyGame.vshost.exe` and `MyGame5.vshost.exe.manifest`) +* 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 diff --git a/en/manual/game-studio/use-assets.md b/en/manual/game-studio/use-assets.md index 36ea2ddc7..e0faa3d79 100644 --- a/en/manual/game-studio/use-assets.md +++ b/en/manual/game-studio/use-assets.md @@ -85,7 +85,7 @@ SceneSystem.SceneInstance.RootScene.Entities.Add(entity); When loading content from code, you should unload content when you don't need them any more. If you don't, content stays in memory, wasting GPU. -To do unload an asset, use ``Content.Unload(myAsset)``. +To unload an asset, use ``Content.Unload(myAsset)``. ## Load assets from code using UrlReference diff --git a/en/manual/graphics/lights-and-shadows/voxel-cone-tracing-gi.md b/en/manual/graphics/lights-and-shadows/voxel-cone-tracing-gi.md index 94f53c308..497a77b8b 100644 --- a/en/manual/graphics/lights-and-shadows/voxel-cone-tracing-gi.md +++ b/en/manual/graphics/lights-and-shadows/voxel-cone-tracing-gi.md @@ -1,10 +1,13 @@ # Voxel Cone Tracing Global Illumination -## Howto: setup existing project with Voxel Cone Tracing GI +## How to set up an existing project with Voxel Cone Tracing GI -### Reference Stride.Voxels -Since Stride is modular based, we need to add a reference to `Stride.Voxels` plugin: + +### Prerequesites: +VoxelGI requires Graphics Profile Level 11 or Higher (Direct3D 11.0 / OpenGL ES 3.1). This can be set in the Game Settings asset under the Rendering category. + +Since Stride is modular, we need to add a reference to the `Stride.Voxels` plugin: 1. In the **Solution Explorer**, right-click on the user project @@ -14,7 +17,7 @@ Since Stride is modular based, we need to add a reference to `Stride.Voxels` plu 3. Select `Stride.Voxels` in the list and press `OK` -4. You might be asked if you want to reload project, choose whichever option, both are OK. +4. Close and re-open the project. ### Graphics Compositor diff --git a/en/manual/graphics/low-level-api/spritebatch.md b/en/manual/graphics/low-level-api/spritebatch.md index 483661450..5718c2d83 100644 --- a/en/manual/graphics/low-level-api/spritebatch.md +++ b/en/manual/graphics/low-level-api/spritebatch.md @@ -10,7 +10,7 @@ A sprite batch is a collection of sprites (2D textured planes). ## Create a sprite batch -Stride offers a easy way to deal will batches of sprites through the @'Stride.Graphics.SpriteBatch' class. You can use this class to regroup, update, and display sprites efficiently. +Stride offers a easy way to deal with batches of sprites through the @'Stride.Graphics.SpriteBatch' class. You can use this class to regroup, update, and display sprites efficiently. **Code:** Creating a sprite batch @@ -36,7 +36,7 @@ The @'Stride.Graphics.SpriteBatch' class has multiple draw methods to set variou ```cs // begin the sprite batch operations -spriteBatch.Begin(GraphicsContext, SpriteSortMode.Immediate); +spriteBatch.Begin(Game.GraphicsContext, SpriteSortMode.Immediate); // draw the sprite immediately spriteBatch.Draw(myTexture, new Vector2(10, 20)); @@ -48,7 +48,7 @@ spriteBatch.End(); There are five modes to draw a sprite batch. They are enumerated in the @'Stride.Graphics.SpriteSortMode' enum: - Deferred (default mode): the sprites are drawn at the same time at the end to reduce the drawcall overhead -- Immediate: the sprites are draw after each each @'Stride.Graphics.SpriteBatch.Draw' call +- Immediate: the sprites are drawn after each @'Stride.Graphics.SpriteBatch.Draw' call - Texture: Deferred mode but sprites are sorted based on their texture to reduce effect parameters update - BackToFront: Deferred mode with a sort based on the z-order of the sprites - FrontToBack: Deferred mode with a sort based on the z-order of the sprites @@ -59,7 +59,7 @@ To set the mode, specify it in the @'Stride.Graphics.SpriteBatch.Begin' method. ```cs // begin the sprite batch operations -spriteBatch.Begin(GraphicsContext); // same as spriteBatch.Begin(GraphicsContext, SpriteSortMode.Deferred); +spriteBatch.Begin(Game.GraphicsContext); // same as spriteBatch.Begin(GraphicsContext, SpriteSortMode.Deferred); // store the modification of the sprite spriteBatch.Draw(myTexture, new Vector2(10, 20)); @@ -103,4 +103,4 @@ spriteBatch.End(); ## See also -* [SpriteFont](spritefont.md) \ No newline at end of file +* [SpriteFont](spritefont.md) diff --git a/en/manual/index.md b/en/manual/index.md index 85f666ce0..0703423f9 100644 --- a/en/manual/index.md +++ b/en/manual/index.md @@ -5,7 +5,7 @@ These pages contain information about how to use Stride, an open-source C# game engine. > [!Note] -> The Stride manual is under construction and updated regularly with new content. Follow [Stride on Twitter](https://twitter.com/stridedotnet?lang=en) for documentation updates. +> The Stride manual is under construction and updated regularly with new content. Follow [Stride on X](https://x.com/stridedotnet?s=20) for documentation updates. ## Latest documentation @@ -13,8 +13,8 @@ These pages contain information about how to use Stride, an open-source C# game - Updated [Linux - Setup and requirements](platforms/linux/setup-and-requirements.md) - Fedora OS option added - New [Scripts - Serialization](scripts/serialization.md) - Serialization explained - Updated [Scripts - Public properties and fields](scripts/public-properties-and-fields.md) - Content improvements and additions -- New [Engine - Entity Component model - Usage](engine/entity-component-model/usage.md) - ECS usage explained -- Updated [Engine - Entity Component model](engine/entity-component-model/index.md) - Content improvements +- New [Engine - Entity Component model - Usage](engine/entity-component-system/usage.md) - ECS usage explained +- Updated [Engine - Entity Component model](engine/entity-component-system/index.md) - Content improvements - Updated [Stride for Unity® developers](stride-for-unity-developers/index.md) - Content improvements ### Previous updates diff --git a/en/manual/scripts/preprocessor-variables.md b/en/manual/scripts/preprocessor-variables.md index 91d607e15..9d361ba61 100644 --- a/en/manual/scripts/preprocessor-variables.md +++ b/en/manual/scripts/preprocessor-variables.md @@ -14,8 +14,6 @@ If you're developing for multiple platforms, you often need to write custom code | -------------------------------------- | ------------------------------ | | STRIDE_PLATFORM_WINDOWS | Windows (standard and RT) | | STRIDE_PLATFORM_WINDOWS_DESKTOP | Windows (non-RT) | -| STRIDE_PLATFORM_WINDOWS_RT | Windows RT | -| STRIDE_PLATFORM_WINDOWS_PHONE | Windows Phone | | STRIDE_PLATFORM_MONO_MOBILE | Xamarin.iOS or Xamarin.Android | | STRIDE_PLATFORM_ANDROID | Xamarin.Android | | STRIDE_PLATFORM_IOS | Xamarin.iOS | diff --git a/en/manual/stride-for-unity-developers/index.md b/en/manual/stride-for-unity-developers/index.md index e8ecf6d6a..2c8475a18 100644 --- a/en/manual/stride-for-unity-developers/index.md +++ b/en/manual/stride-for-unity-developers/index.md @@ -801,7 +801,7 @@ System.Diagnostics.Debug.WriteLine("hello"); | `[SerializeField]` | `[DataMember]` | | `[HideInInspector]` | `[DataMemberIgnore]` | | `[Range]` | `[DataMemberRange]` | -| `[Header]` | `[Display]` | +| `[Header("My Header")]` | `[Display(category: "My Header")]` | | `[Tooltip("My tooltip")]` | `/// My tooltip` | >[!Note] diff --git a/en/manual/toc.md b/en/manual/toc.md deleted file mode 100644 index 7e1ce3004..000000000 --- a/en/manual/toc.md +++ /dev/null @@ -1,270 +0,0 @@ -# [Manual](index.md) - -# [Requirements](requirements/index.md) - -# [Stride for Unity® developers](stride-for-unity-developers/index.md) - - -# [Stride Launcher](stride-launcher/index.md) - -# [Get started](get-started/index.md) -## [Install Stride](get-started/install-stride.md) -## [Visual Studio extension](get-started/visual-studio-extension.md) -## [Launch Stride](get-started/launch-stride.md) -## [Create a project](get-started/create-a-project.md) -## [Game Studio](game-studio/index.md) -## [Assets](game-studio/assets.md) -### [Create assets](game-studio/create-assets.md) -### [Use assets](game-studio/use-assets.md) -## [Scenes](game-studio/scenes.md) -### [Create a scene](game-studio/create-a-scene.md) -### [Add entities](game-studio/add-entities.md) -### [Manage entities](game-studio/manage-entities.md) -### [Navigate in the Scene Editor](game-studio/navigate-in-the-scene-editor.md) -## [Launch a game](get-started/launch-a-game.md) - -# [Animation](animation/index.md) -## [Import animations](animation/import-animations.md) -## [Animation properties](animation/animation-properties.md) -## [Set up animations](animation/set-up-animations.md) -## [Preview animations](animation/preview-animations.md) -## [Animation scripts](animation/animation-scripts.md) -## [Additive animation](animation/additive-animation.md) -## [Procedural animation](animation/procedural-animation.md) -## [Custom blend trees](animation/custom-blend-trees.md) -## [Model node links](animation/model-node-links.md) -## [Custom attributes](animation/custom-attributes.md) - -# [Audio](audio/index.md) -## [Import audio](audio/import-audio.md) -## [Audio asset properties](audio/audio-asset-properties.md) -## [Non-spatialized audio](audio/non-spatialized-audio.md) -## [Spatialized audio](audio/spatialized-audio.md) -### [Audio emitters](audio/audio-emitters.md) -### [Audio listeners](audio/audio-listeners.md) -### [HRTF](audio/hrtf.md) -## [Stream audio](audio/stream-audio.md) -## [Global audio settings](audio/global-audio-settings.md) -## [Play a range within an audio file](audio/play-a-range-within-an-audio-file.md) -## [Custom audio data](audio/custom-audio-data.md) -## [Set an audio device](audio/set-an-audio-device.md) - -# [Engine](engine/index.md) -## [Assets](engine/assets/index.md) -### [Asset bundles](engine/assets/asset-bundles.md) -### [Asset control](engine/assets/asset-control.md) -## [Entity component model](engine/entity-component-model/index.md) -### [Usage](engine/entity-component-model/usage.md) -### [Manage entities](engine/entity-component-model/managing-entities.md) -## [File system](engine/file-system.md) - -# [Files and folders](files-and-folders/index.md) -## [Project structure](files-and-folders/project-structure.md) -## [Cached files](files-and-folders/cached-files.md) -## [Version control](files-and-folders/version-control.md) -## [Distribute a game](files-and-folders/distribute-a-game.md) - -# [Game Studio](game-studio/index.md) -## [Scenes](game-studio/scenes.md) -### [Create and open a scene](game-studio/create-a-scene.md) -### [Navigate in the Scene Editor](game-studio/navigate-in-the-scene-editor.md) -### [Manage scenes](game-studio/manage-scenes.md) -### [Load scenes](game-studio/load-scenes.md) -### [Add entities](game-studio/add-entities.md) -### [Manage entities](game-studio/manage-entities.md) -## [Assets](game-studio/assets.md) -### [Create assets](game-studio/create-assets.md) -### [Manage assets](game-studio/manage-assets.md) -### [Use assets](game-studio/use-assets.md) -### [Archetypes](game-studio/archetypes.md) -## [Prefabs](game-studio/prefabs/index.md) -### [Create a prefab](game-studio/prefabs/create-a-prefab.md) -### [Use prefabs](game-studio/prefabs/use-prefabs.md) -### [Edit prefabs](game-studio/prefabs/edit-prefabs.md) -### [Nested prefabs](game-studio/prefabs/nested-prefabs.md) -### [Override prefab properties](game-studio/prefabs/override-prefab-properties.md) -### [Prefab models](game-studio/prefabs/prefab-models.md) -## [Game settings](game-studio/game-settings.md) -### [Splash screen](game-studio/splash-screen.md) -## [World units](game-studio/world-units.md) - -# [Graphics](graphics/index.md) -## [Cameras](graphics/cameras/index.md) -### [Camera slots](graphics/cameras/camera-slots.md) -### [Animate a camera with a model file](graphics/cameras/animate-a-camera-with-a-model-file.md) -## [Materials](graphics/materials/index.md) -### [Material maps](graphics/materials/material-maps.md) -### [Attributes](graphics/materials/material-attributes.md) -#### [Geometry attributes](graphics/materials/geometry-attributes.md) -#### [Shading attributes](graphics/materials/shading-attributes.md) -#### [Misc attributes](graphics/materials/misc-attributes.md) -#### [Clear-coat shading](graphics/materials/clear-coat-shading.md) -### [Layers](graphics/materials/material-layers.md) -### [Slots](graphics/materials/material-slots.md) -### [Materials for developers](graphics/materials/materials-for-developers.md) -## [Textures](graphics/textures/index.md) -### [Normal maps](graphics/textures/normal-maps.md) -### [Compression](graphics/textures/compression.md) -### [Streaming](graphics/textures/streaming.md) -### [Skyboxes and backgrounds](graphics/textures/skyboxes-and-backgrounds.md) -## [Lights and shadows](graphics/lights-and-shadows/index.md) -### [Add a light](graphics/lights-and-shadows/add-a-light.md) -### [Point lights](graphics/lights-and-shadows/point-lights.md) -### [Ambient lights](graphics/lights-and-shadows/ambient-lights.md) -### [Directional lights](graphics/lights-and-shadows/directional-lights.md) -### [Skybox lights](graphics/lights-and-shadows/skybox-lights.md) -### [Spot lights](graphics/lights-and-shadows/spot-lights.md) -### [Light probes](graphics/lights-and-shadows/light-probes.md) -### [Light shafts](graphics/lights-and-shadows/light-shafts.md) -### [Shadows](graphics/lights-and-shadows/shadows.md) -### [Voxel Cone Tracing GI](graphics/lights-and-shadows/voxel-cone-tracing-gi.md) -## [Post effects](graphics/post-effects/index.md) -### [Anti-aliasing](graphics/post-effects/anti-aliasing.md) -### [Ambient occlusion](graphics/post-effects/ambient-occlusion.md) -### [Bloom](graphics/post-effects/bloom.md) -### [Bright filter](graphics/post-effects/bright-filter.md) -### [Color transforms](graphics/post-effects/color-transforms/index.md) -#### [Film grain](graphics/post-effects/color-transforms/film-grain.md) -#### [Gamma correction](graphics/post-effects/color-transforms/gamma-correction.md) -#### [ToneMap](graphics/post-effects/color-transforms/tonemap.md) -#### [Vignetting](graphics/post-effects/color-transforms/vignetting.md) -#### [Custom color transforms](graphics/post-effects/color-transforms/custom-color-transforms.md) -### [Depth of field](graphics/post-effects/depth-of-field.md) -### [Lens flare](graphics/post-effects/lens-flare.md) -### [Light streaks](graphics/post-effects/light-streaks.md) -### [Local reflections](graphics/post-effects/local-reflections.md) -## [Graphics compositor](graphics/graphics-compositor/index.md) -### [Scene renderers](graphics/graphics-compositor/scene-renderers.md) -#### [Custom scene renderers](graphics/graphics-compositor/custom-scene-renderers.md) -### [Debug renderers](graphics/graphics-compositor/debug-renderers.md) -### [Render textures](graphics/graphics-compositor/render-textures.md) -### [Render group and masks](graphics/graphics-compositor/render-groups-and-masks.md) -## [Effects and shaders](graphics/effects-and-shaders/index.md) -### [Effect language](graphics/effects-and-shaders/effect-language.md) -### [Shading language](graphics/effects-and-shaders/shading-language/index.md) -#### [Classes, mixins and inheritance](graphics/effects-and-shaders/shading-language/shader-classes-mixins-and-inheritance.md) -#### [Composition](graphics/effects-and-shaders/shading-language/composition.md) -#### [Templates](graphics/effects-and-shaders/shading-language/templates.md) -#### [Automatic shader stage input/output](graphics/effects-and-shaders/shading-language/automatic-shader-stage-input-output.md) -#### [Shader stages](graphics/effects-and-shaders/shading-language/shader-stages.md) -### [Custom shaders](graphics/effects-and-shaders/custom-shaders.md) -### [Compile shaders](graphics/effects-and-shaders/compile-shaders.md) -## [Low-level API](graphics/low-level-api/index.md) -### [Textures and render textures](graphics/low-level-api/textures-and-render-textures.md) -### [Pipeline state](graphics/low-level-api/pipeline-state.md) -### [Resource binding](graphics/low-level-api/resources.md) -### [Draw vertices](graphics/low-level-api/draw-vertices.md) -### [SpriteBatch](graphics/low-level-api/spritebatch.md) -### [SpriteFont](graphics/low-level-api/spritefont.md) -## [Rendering pipeline](graphics/rendering-pipeline/index.md) -### [Render features](graphics/rendering-pipeline/render-features.md) -### [Render stages](graphics/rendering-pipeline/render-stages.md) -## [Sprite fonts](graphics/sprite-fonts.md) - -# [Input](input/index.md) -## [Gamepads](input/gamepads.md) -## [Gestures](input/gestures.md) -## [Keyboards](input/keyboards.md) -## [Mouse](input/mouse.md) -## [Pointers](input/pointers.md) -## [Sensors](input/sensors.md) -## [Virtual buttons](input/virtual-buttons.md) - -# [Navigation](navigation/index.md) -## [Navigation groups](navigation/navigation-groups.md) -## [Navigation meshes](navigation/navigation-meshes.md) -## [Navigation bounding boxes](navigation/navigation-bounding-boxes.md) -## [Navigation components](navigation/navigation-components.md) -## [Dynamic navigation](navigation/dynamic-navigation.md) - -# [Particles](particles/index.md) -## [Create particles](particles/create-particles.md) -## [Emitters](particles/emitters.md) -### [Shapes](particles/shapes.md) -#### [Ribbons and trails](particles/ribbons-and-trails.md) -### [Materials](particles/materials.md) -### [Spawners](particles/spawners.md) -### [Initializers](particles/initializers.md) -### [Updaters](particles/updaters.md) -## [Tutorials](particles/tutorials/index.md) -### [Particle materials](particles/tutorials/particle-materials.md) -### [Inheritance](particles/tutorials/inheritance.md) -### [Lasers and lightning](particles/tutorials/lasers-and-lightning.md) -### [Create a trail](particles/tutorials/create-a-trail.md) -### [Custom particles](particles/tutorials/custom-particles.md) - -# [Physics](physics/index.md) -## [Colliders](physics/colliders.md) -### [Static colliders](physics/static-colliders.md) -### [Rigidbodies](physics/rigid-bodies.md) -### [Kinematic rigidbodies](physics/kinematic-rigid-bodies.md) -### [Characters](physics/characters.md) -### [Collider shapes](physics/collider-shapes.md) -### [Triggers](physics/triggers.md) -### [Constraints](physics/constraints.md) -## [Raycasting](physics/raycasting.md) -## [Simulation](physics/simulation.md) -## [Tutorials](physics/tutorials.md) -### [Create a bouncing ball](physics/create-a-bouncing-ball.md) -### [Script a trigger](physics/script-a-trigger.md) - -# [Platforms](platforms/index.md) -## [Linux](platforms/linux/index.md) -### [Setup and requirements](platforms/linux/setup-and-requirements.md) -### [Create a Linux game](platforms/linux/create-a-linux-game.md) -## [UWP](platforms/uwp/index.md) -### [Xbox Live](platforms/uwp/xbox-live.md) -## [iOS](platforms/ios.md) -## [Add or remove a platform](platforms/add-or-remove-a-platform.md) -## [Set the graphics platform](platforms/set-the-graphics-platform.md) - -# [Scripts](scripts/index.md) -## [Types of script](scripts/types-of-script.md) -## [Create a script](scripts/create-a-script.md) -## [Use a script](scripts/use-a-script.md) -## [Public properties and fields](scripts/public-properties-and-fields.md) -## [Serialization](scripts/serialization.md) -## [Scheduling and priorities](scripts/scheduling-and-priorities.md) -## [Events](scripts/events.md) -## [Debugging](scripts/debugging.md) -## [Preprocessor variables](scripts/preprocessor-variables.md) -## [Create a model from code](scripts/create-a-model-from-code.md) - -# [Sprites](sprites/index.md) -## [Import sprite sheets](sprites/import-sprite-sheets.md) -## [Edit sprites](sprites/edit-sprites.md) -### [Set sprite borders](sprites/set-sprite-borders.md) -## [Use sprites](sprites/use-sprites.md) - -# [UI](ui/index.md) -## [Pages](ui/ui-pages.md) -## [Libraries](ui/ui-libraries.md) -## [Editor](ui/ui-editor.md) -## [Add a UI to a scene](ui/add-a-ui-to-a-scene.md) -## [Layout system](ui/layout-system.md) - -# [Video](video/index.md) -## [Set up a video](video/set-up-a-video.md) -## [Video properties](video/video-properties.md) -## [Use a video as a skybox](video/use-a-video-as-a-skybox.md) - -# [Virtual reality](virtual-reality/index.md) -## [Enable VR](virtual-reality/enable-vr.md) -## [Preview a scene in VR](virtual-reality/preview-a-scene-in-vr.md) -## [Overlays](virtual-reality/overlays.md) -### [Display a UI in an overlay](virtual-reality/display-a-UI-in-an-overlay.md) -## [VR sickness](virtual-reality/vr-sickness.md) - -# [NuGet](nuget/index.md) -## [Consume Packages](nuget/consume-packages.md) -## [Create Packages](nuget/create-packages.md) - -# [Troubleshooting](troubleshooting/index.md) -## [Logging](troubleshooting/logging.md) -## [Debug text](troubleshooting/debug-text.md) -## [Profiling](troubleshooting/profiling.md) -## [Stride doesn't run](troubleshooting/stride-doesnt-run.md) -## [Default value changes ignored at runtime](troubleshooting/default-value-changes-ignored-at-runtime.md) -## [Lights don't cast shadows](troubleshooting/lights-dont-cast-shadows.md) -## [Full call stack not available](troubleshooting/full-call-stack-not-available.md) -## [Error: "A SceneCameraRenderer in use has no camera assigned to its [Slot]. Make sure a camera is enabled and assigned to the [Slot]"](troubleshooting/error-a-scenecamerarenderer-in-use-has-no-camera-set.md) diff --git a/en/manual/toc.yml b/en/manual/toc.yml new file mode 100644 index 000000000..d86e204be --- /dev/null +++ b/en/manual/toc.yml @@ -0,0 +1,568 @@ +pdf: true +pdfFileName: stride-manual.pdf +items: + - name: Manual + href: index.md + - name: Requirements + href: requirements/index.md + - name: Stride for Unity® developers + href: stride-for-unity-developers/index.md + # - name: Stride for Godot developers + # href: stride-for-godot-developers/index.md + - name: Stride Launcher + href: stride-launcher/index.md + + - name: Get started + href: get-started/index.md + items: + - name: Install Stride + href: get-started/install-stride.md + - name: Visual Studio extension + href: get-started/visual-studio-extension.md + - name: Launch Stride + href: get-started/launch-stride.md + - name: Create a project + href: get-started/create-a-project.md + - name: Game Studio + href: game-studio/index.md + - name: Assets + href: game-studio/assets.md + items: + - name: Create assets + href: game-studio/create-assets.md + - name: Use assets + href: game-studio/use-assets.md + - name: Scenes + href: game-studio/scenes.md + items: + - name: Create a scene + href: game-studio/create-a-scene.md + - name: Add entities + href: game-studio/add-entities.md + - name: Manage entities + href: game-studio/manage-entities.md + - name: Navigate in the Scene Editor + href: game-studio/navigate-in-the-scene-editor.md + - name: Launch a game + href: get-started/launch-a-game.md + + - name: Animation + href: animation/index.md + items: + - name: Import animations + href: animation/import-animations.md + - name: Animation properties + href: animation/animation-properties.md + - name: Set up animations + href: animation/set-up-animations.md + - name: Preview animations + href: animation/preview-animations.md + - name: Animation scripts + href: animation/animation-scripts.md + - name: Additive animation + href: animation/additive-animation.md + - name: Procedural animation + href: animation/procedural-animation.md + - name: Custom blend trees + href: animation/custom-blend-trees.md + - name: Model node links + href: animation/model-node-links.md + - name: Custom attributes + href: animation/custom-attributes.md + + - name: Audio + href: audio/index.md + items: + - name: Import audio + href: audio/import-audio.md + - name: Audio asset properties + href: audio/audio-asset-properties.md + - name: Non-spatialized audio + href: audio/non-spatialized-audio.md + - name: Spatialized audio + href: audio/spatialized-audio.md + items: + - name: Audio emitters + href: audio/audio-emitters.md + - name: Audio listeners + href: audio/audio-listeners.md + - name: HRTF + href: audio/hrtf.md + - name: Stream audio + href: audio/stream-audio.md + - name: Global audio settings + href: audio/global-audio-settings.md + - name: Play a range within an audio file + href: audio/play-a-range-within-an-audio-file.md + - name: Custom audio data + href: audio/custom-audio-data.md + - name: Set an audio device + href: audio/set-an-audio-device.md + + - name: Engine + href: engine/index.md + items: + - name: Assets + href: engine/assets/index.md + items: + - name: Asset bundles + href: engine/assets/asset-bundles.md + - name: Asset control + href: engine/assets/asset-control.md + - name: ECS (Entity Component System) + href: engine/entity-component-system/index.md + items: + - name: Usage + href: engine/entity-component-system/usage.md + - name: Manage entities + href: engine/entity-component-system/managing-entities.md + - name: File system + href: engine/file-system.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: + - name: Scenes + href: game-studio/scenes.md + items: + - name: Create and open a scene + href: game-studio/create-a-scene.md + - name: Navigate in the Scene Editor + href: game-studio/navigate-in-the-scene-editor.md + - name: Manage scenes + href: game-studio/manage-scenes.md + - name: Load scenes + href: game-studio/load-scenes.md + - name: Add entities + href: game-studio/add-entities.md + - name: Manage entities + href: game-studio/manage-entities.md + - name: Assets + href: game-studio/assets.md + items: + - name: Create assets + href: game-studio/create-assets.md + - name: Manage assets + href: game-studio/manage-assets.md + - name: Use assets + href: game-studio/use-assets.md + - name: Archetypes + href: game-studio/archetypes.md + - name: Prefabs + href: game-studio/prefabs/index.md + items: + - name: Create a prefab + href: game-studio/prefabs/create-a-prefab.md + - name: Use prefabs + href: game-studio/prefabs/use-prefabs.md + - name: Edit prefabs + href: game-studio/prefabs/edit-prefabs.md + - name: Nested prefabs + href: game-studio/prefabs/nested-prefabs.md + - name: Override prefab properties + href: game-studio/prefabs/override-prefab-properties.md + - name: Prefab models + href: game-studio/prefabs/prefab-models.md + - name: Game settings + href: game-studio/game-settings.md + items: + - name: Splash screen + href: game-studio/splash-screen.md + - name: World units + href: game-studio/world-units.md + + - name: Graphics + href: graphics/index.md + items: + - name: Cameras + href: graphics/cameras/index.md + items: + - name: Camera slots + href: graphics/cameras/camera-slots.md + - name: Animate a camera with a model file + href: graphics/cameras/animate-a-camera-with-a-model-file.md + - name: Materials + href: graphics/materials/index.md + items: + - name: Material maps + href: graphics/materials/material-maps.md + - name: Attributes + href: graphics/materials/material-attributes.md + items: + - name: Geometry attributes + href: graphics/materials/geometry-attributes.md + - name: Shading attributes + href: graphics/materials/shading-attributes.md + - name: Misc attributes + href: graphics/materials/misc-attributes.md + - name: Clear-coat shading + href: graphics/materials/clear-coat-shading.md + - name: Layers + href: graphics/materials/material-layers.md + - name: Slots + href: graphics/materials/material-slots.md + - name: Materials for developers + href: graphics/materials/materials-for-developers.md + - name: Textures + href: graphics/textures/index.md + items: + - name: Normal maps + href: graphics/textures/normal-maps.md + - name: Compression + href: graphics/textures/compression.md + - name: Streaming + href: graphics/textures/streaming.md + - name: Skyboxes and backgrounds + href: graphics/textures/skyboxes-and-backgrounds.md + - name: Lights and shadows + href: graphics/lights-and-shadows/index.md + items: + - name: Add a light + href: graphics/lights-and-shadows/add-a-light.md + - name: Point lights + href: graphics/lights-and-shadows/point-lights.md + - name: Ambient lights + href: graphics/lights-and-shadows/ambient-lights.md + - name: Directional lights + href: graphics/lights-and-shadows/directional-lights.md + - name: Skybox lights + href: graphics/lights-and-shadows/skybox-lights.md + - name: Spot lights + href: graphics/lights-and-shadows/spot-lights.md + - name: Light probes + href: graphics/lights-and-shadows/light-probes.md + - name: Light shafts + href: graphics/lights-and-shadows/light-shafts.md + - name: Shadows + href: graphics/lights-and-shadows/shadows.md + - name: Voxel Cone Tracing GI + href: graphics/lights-and-shadows/voxel-cone-tracing-gi.md + - name: Post effects + href: graphics/post-effects/index.md + items: + - name: Anti-aliasing + href: graphics/post-effects/anti-aliasing.md + - name: Ambient occlusion + href: graphics/post-effects/ambient-occlusion.md + - name: Bloom + href: graphics/post-effects/bloom.md + - name: Bright filter + href: graphics/post-effects/bright-filter.md + - name: Color transforms + href: graphics/post-effects/color-transforms/index.md + items: + - name: Film grain + href: graphics/post-effects/color-transforms/film-grain.md + - name: Gamma correction + href: graphics/post-effects/color-transforms/gamma-correction.md + - name: ToneMap + href: graphics/post-effects/color-transforms/tonemap.md + - name: Vignetting + href: graphics/post-effects/color-transforms/vignetting.md + - name: Custom color transforms + href: graphics/post-effects/color-transforms/custom-color-transforms.md + - name: Depth of field + href: graphics/post-effects/depth-of-field.md + - name: Lens flare + href: graphics/post-effects/lens-flare.md + - name: Light streaks + href: graphics/post-effects/light-streaks.md + - name: Local reflections + href: graphics/post-effects/local-reflections.md + - name: Graphics compositor + href: graphics/graphics-compositor/index.md + items: + - name: Scene renderers + href: graphics/graphics-compositor/scene-renderers.md + items: + - name: Custom scene renderers + href: graphics/graphics-compositor/custom-scene-renderers.md + - name: Debug renderers + href: graphics/graphics-compositor/debug-renderers.md + - name: Render textures + href: graphics/graphics-compositor/render-textures.md + - name: Render group and masks + href: graphics/graphics-compositor/render-groups-and-masks.md + - name: Effects and shaders + href: graphics/effects-and-shaders/index.md + items: + - name: Effect language + href: graphics/effects-and-shaders/effect-language.md + - name: Shading language + href: graphics/effects-and-shaders/shading-language/index.md + items: + - name: Classes, mixins and inheritance + href: graphics/effects-and-shaders/shading-language/shader-classes-mixins-and-inheritance.md + - name: Composition + href: graphics/effects-and-shaders/shading-language/composition.md + - name: Templates + href: graphics/effects-and-shaders/shading-language/templates.md + - name: Automatic shader stage input/output + href: graphics/effects-and-shaders/shading-language/automatic-shader-stage-input-output.md + - name: Shader stages + href: graphics/effects-and-shaders/shading-language/shader-stages.md + - name: Custom shaders + href: graphics/effects-and-shaders/custom-shaders.md + - name: Compile shaders + href: graphics/effects-and-shaders/compile-shaders.md + - name: Low-level API + href: graphics/low-level-api/index.md + items: + - name: Textures and render textures + href: graphics/low-level-api/textures-and-render-textures.md + - name: Pipeline state + href: graphics/low-level-api/pipeline-state.md + - name: Resource binding + href: graphics/low-level-api/resources.md + - name: Draw vertices + href: graphics/low-level-api/draw-vertices.md + - name: SpriteBatch + href: graphics/low-level-api/spritebatch.md + - name: SpriteFont + href: graphics/low-level-api/spritefont.md + - name: Rendering pipeline + href: graphics/rendering-pipeline/index.md + items: + - name: Render features + href: graphics/rendering-pipeline/render-features.md + - name: Render stages + href: graphics/rendering-pipeline/render-stages.md + - name: Sprite fonts + href: graphics/sprite-fonts.md + + - name: Input + href: input/index.md + items: + - name: Gamepads + href: input/gamepads.md + - name: Gestures + href: input/gestures.md + - name: Keyboards + href: input/keyboards.md + - name: Mouse + href: input/mouse.md + - name: Pointers + href: input/pointers.md + - name: Sensors + href: input/sensors.md + - name: Virtual buttons + href: input/virtual-buttons.md + + - name: Navigation + href: navigation/index.md + items: + - name: Navigation groups + href: navigation/navigation-groups.md + - name: Navigation meshes + href: navigation/navigation-meshes.md + - name: Navigation bounding boxes + href: navigation/navigation-bounding-boxes.md + - name: Navigation components + href: navigation/navigation-components.md + - name: Dynamic navigation + href: navigation/dynamic-navigation.md + + - name: Particles + href: particles/index.md + items: + - name: Create particles + href: particles/create-particles.md + - name: Emitters + href: particles/emitters.md + items: + - name: Shapes + href: particles/shapes.md + items: + - name: Ribbons and trails + href: particles/ribbons-and-trails.md + - name: Materials + href: particles/materials.md + - name: Spawners + href: particles/spawners.md + - name: Initializers + href: particles/initializers.md + - name: Updaters + href: particles/updaters.md + - name: Tutorials + href: particles/tutorials/index.md + items: + - name: Particle materials + href: particles/tutorials/particle-materials.md + - name: Inheritance + href: particles/tutorials/inheritance.md + - name: Lasers and lightning + href: particles/tutorials/lasers-and-lightning.md + - name: Create a trail + href: particles/tutorials/create-a-trail.md + - name: Custom particles + href: particles/tutorials/custom-particles.md + + - name: Physics + href: physics/index.md + items: + - name: Colliders + href: physics/colliders.md + items: + - name: Static colliders + href: physics/static-colliders.md + - name: Rigidbodies + href: physics/rigid-bodies.md + - name: Kinematic rigidbodies + href: physics/kinematic-rigid-bodies.md + - name: Characters + href: physics/characters.md + - name: Collider shapes + href: physics/collider-shapes.md + - name: Triggers + href: physics/triggers.md + - name: Constraints + href: physics/constraints.md + - name: Raycasting + href: physics/raycasting.md + - name: Simulation + href: physics/simulation.md + - name: Tutorials + href: physics/tutorials.md + items: + - name: Create a bouncing ball + href: physics/create-a-bouncing-ball.md + - name: Script a trigger + href: physics/script-a-trigger.md + + - name: Platforms + href: platforms/index.md + items: + - name: Linux + href: platforms/linux/index.md + items: + - name: Setup and requirements + href: platforms/linux/setup-and-requirements.md + - name: Create a Linux game + href: platforms/linux/create-a-linux-game.md + - name: UWP + href: platforms/uwp/index.md + items: + - name: Xbox Live + href: platforms/uwp/xbox-live.md + - name: iOS + href: platforms/ios.md + - name: Add or remove a platform + href: platforms/add-or-remove-a-platform.md + - name: Set the graphics platform + href: platforms/set-the-graphics-platform.md + + - name: Scripts + href: scripts/index.md + items: + - name: Types of script + href: scripts/types-of-script.md + - name: Create a script + href: scripts/create-a-script.md + - name: Use a script + href: scripts/use-a-script.md + - name: Public properties and fields + href: scripts/public-properties-and-fields.md + - name: Serialization + href: scripts/serialization.md + - name: Scheduling and priorities + href: scripts/scheduling-and-priorities.md + - name: Events + href: scripts/events.md + - name: Debugging + href: scripts/debugging.md + - name: Preprocessor variables + href: scripts/preprocessor-variables.md + - name: Create a model from code + href: scripts/create-a-model-from-code.md + + - name: Sprites + href: sprites/index.md + items: + - name: Import sprite sheets + href: sprites/import-sprite-sheets.md + - name: Edit sprites + href: sprites/edit-sprites.md + items: + - name: Set sprite borders + href: sprites/set-sprite-borders.md + - name: Use sprites + href: sprites/use-sprites.md + + - name: UI + href: ui/index.md + items: + - name: Pages + href: ui/ui-pages.md + - name: Libraries + href: ui/ui-libraries.md + - name: Editor + href: ui/ui-editor.md + - name: Add a UI to a scene + href: ui/add-a-ui-to-a-scene.md + - name: Layout system + href: ui/layout-system.md + + - name: Video + href: video/index.md + items: + - name: Set up a video + href: video/set-up-a-video.md + - name: Video properties + href: video/video-properties.md + - name: Use a video as a skybox + href: video/use-a-video-as-a-skybox.md + + - name: Virtual reality + href: virtual-reality/index.md + items: + - name: Enable VR + href: virtual-reality/enable-vr.md + - name: Preview a scene in VR + href: virtual-reality/preview-a-scene-in-vr.md + - name: Overlays + href: virtual-reality/overlays.md + items: + - name: Display a UI in an overlay + href: virtual-reality/display-a-UI-in-an-overlay.md + - 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: Troubleshooting + href: troubleshooting/index.md + items: + - name: Logging + href: troubleshooting/logging.md + - name: Debug text + href: troubleshooting/debug-text.md + - name: Profiling + href: troubleshooting/profiling.md + - name: Stride doesn't run + href: troubleshooting/stride-doesnt-run.md + - name: Default value changes ignored at runtime + href: troubleshooting/default-value-changes-ignored-at-runtime.md + - name: Lights don't cast shadows + href: troubleshooting/lights-dont-cast-shadows.md + - name: Full call stack not available + href: troubleshooting/full-call-stack-not-available.md + - name: "Error: A SceneCameraRenderer in use has no camera assigned to its [Slot]. Make sure a camera is enabled and assigned to the [Slot]" + href: troubleshooting/error-a-scenecamerarenderer-in-use-has-no-camera-set.md diff --git a/en/template/public/main.css b/en/template/public/main.css index e0998592e..90cda5be0 100644 --- a/en/template/public/main.css +++ b/en/template/public/main.css @@ -36,6 +36,11 @@ --bs-link-hover-color-rgb: 247, 149, 149 !important; } +.link-secondary { + padding-left: 10px; + display: block; +} + footer .link-danger { color: var(--stride-red-web); -} +} \ No newline at end of file diff --git a/en/template/public/main.js b/en/template/public/main.js index 75d682643..cb76a9d21 100644 --- a/en/template/public/main.js +++ b/en/template/public/main.js @@ -237,15 +237,12 @@ const app = { }, start: function () { - // Call the function to start waiting for the navbar element this.waitForNavbarAndAddLanguageNavigation(); - this.addVersionNavigation(); this.loadVersions(); } }; -export default app; +app.start = app.start.bind(app); -// Start the app when the DOM content is loaded -document.addEventListener("DOMContentLoaded", () => app.start()); \ No newline at end of file +export default app; \ No newline at end of file diff --git a/en/toc.yml b/en/toc.yml index ec349b4a4..4c2594c3a 100644 --- a/en/toc.yml +++ b/en/toc.yml @@ -14,9 +14,9 @@ # href: tutorials/csharpintermediate/index.md - name: 📝 Release Notes href: ReleaseNotes/ReleaseNotes.md -- name: 🌟 Contributing +- name: 🌟 Contributing href: contributors/ - homepage: contributors/ways-to-contribute.md + homepage: contributors/index.md - name: 🔧 API href: api/ homepage: api/index.md diff --git a/en/tutorials/index.html b/en/tutorials/index.html deleted file mode 100644 index cd60ce5fa..000000000 --- a/en/tutorials/index.html +++ /dev/null @@ -1,38 +0,0 @@ -
-
-
- Game studio tutorials -
-
Game Studio
-

The Stride engine comes with an editor called Game Studio.

-

Read about Stride launcher, main inteface, scene management, transforming entities, asset pipelines and more.

-
-

Jump to the Game Studio tutorials.

-
-
-
-
- C# beginner tutorials -
-
C# Beginner
-

These tutorials cover the beginner principles of using C# when working with the Stride game engine.

-

Read about entities, transform positions, editor properties, components, delta time, cloning, keyboar and mouse input and more.

-
-

Jump to the C# beginner tutorials.

-
-
-
-
-
-
- C# intermediate tutorials -
-
C# Intermediate
-

These tutorials cover various intermediate principles of using C# when working with the Stride game engine.

-

Read more about UI basics, collision triggers, raycasting, async scripts, scenes, animations, audio, camera and navigation.

-

New

-
-

Jump to the C# intermediate tutorials.

-
-
-
\ No newline at end of file diff --git a/en/tutorials/toc.yml b/en/tutorials/toc.yml index 782627a29..9b69d6ce5 100644 --- a/en/tutorials/toc.yml +++ b/en/tutorials/toc.yml @@ -1,3 +1,6 @@ +pdf: true +pdfFileName: stride-tutorials.pdf +items: - name: 🎓 Tutorials href: index.md - name: 🛠️ Game studio diff --git a/versions.json b/versions.json index 867ffffda..a509e9c1e 100644 --- a/versions.json +++ b/versions.json @@ -1,5 +1,6 @@ { "versions": [ + "4.2", "4.1", "4.0", "3.1", diff --git a/web.config b/web.config index 11b818eb6..f458b3497 100644 --- a/web.config +++ b/web.config @@ -1,4 +1,4 @@ - + @@ -19,6 +19,7 @@ + @@ -27,6 +28,7 @@ +