diff --git a/.github/release.yml b/.github/release.yml index 4e1c52fb5..cf1ade31a 100644 --- a/.github/release.yml +++ b/.github/release.yml @@ -2,6 +2,7 @@ changelog: exclude: labels: - ignore-for-release + - deployment authors: - dependabot categories: diff --git a/.github/workflows/stride-docs-github.yml b/.github/workflows/stride-docs-github.yml index 106bf1cd2..6cafc4f84 100644 --- a/.github/workflows/stride-docs-github.yml +++ b/.github/workflows/stride-docs-github.yml @@ -47,7 +47,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.76.0 + run: dotnet tool update -g docfx --version 2.77.0 - name: Build documentation run: ./build-all.bat diff --git a/.github/workflows/stride-docs-release-azure.yml b/.github/workflows/stride-docs-release-azure.yml index 7db216955..5fbffac91 100644 --- a/.github/workflows/stride-docs-release-azure.yml +++ b/.github/workflows/stride-docs-release-azure.yml @@ -60,7 +60,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.76.0 + run: dotnet tool update -g docfx --version 2.77.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 7d98c0b12..1003f1eb4 100644 --- a/.github/workflows/stride-docs-release-fast-track-azure.yml +++ b/.github/workflows/stride-docs-release-fast-track-azure.yml @@ -54,7 +54,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.76.0 + run: dotnet tool update -g docfx --version 2.77.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 c38d80a64..36aeb2e83 100644 --- a/.github/workflows/stride-docs-staging-azure.yml +++ b/.github/workflows/stride-docs-staging-azure.yml @@ -63,12 +63,13 @@ jobs: token: ${{ secrets.GITHUB_TOKEN }} path: stride lfs: true + ref: master - name: Install DocFX # 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.76.0 + run: dotnet tool update -g docfx --version 2.77.0 - name: Build documentation run: ./build-all.bat @@ -111,4 +112,4 @@ jobs: app-name: 'stride-doc' slot-name: 'staging' publish-profile: ${{ secrets.AZUREAPPSERVICE_PUBLISHPROFILE_32FCD402B970463A9143B24C9B225749 }} - package: ./${{ env.DOCS_PATH }}/_site \ No newline at end of file + package: ./${{ env.DOCS_PATH }}/_site diff --git a/.github/workflows/stride-docs-staging-fast-track-azure.yml b/.github/workflows/stride-docs-staging-fast-track-azure.yml index 573c28b80..c73503de3 100644 --- a/.github/workflows/stride-docs-staging-fast-track-azure.yml +++ b/.github/workflows/stride-docs-staging-fast-track-azure.yml @@ -54,7 +54,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.76.0 + run: dotnet tool update -g docfx --version 2.77.0 - name: Build documentation run: ./build-all.bat diff --git a/BuildDocs.ps1 b/BuildDocs.ps1 index fad4b8151..053492f4d 100644 --- a/BuildDocs.ps1 +++ b/BuildDocs.ps1 @@ -15,12 +15,16 @@ Switch parameter. If provided, the script will build documentation in all available languages and include API documentation. .PARAMETER Version The Version to build the Docs, the default is the latest version +.PARAMETER SkipPdfBuilding + Switch parameter. If provided, It skips Pdf generation step. .EXAMPLE .\BuildDocs.ps1 -BuildAll In this example, the script will build the documentation in all available languages and include API documentation. Use this in GitHub Actions. .EXAMPLE .\BuildDocs.ps1 In this example, the script will prompt the user to select an operation and an optional language. If the user chooses to build the documentation, the script will also ask if they want to include API documentation. +.EXAMPLE + .\BuildDocs.ps1 -SkipPdfBuilding #> param ( @@ -30,6 +34,7 @@ param ( param([string] $CommandName,[string] $ParameterName,[string] $WordToComplete,[System.Management.Automation.Language.CommandAst] $CommandAst,[System.Collections.IDictionary] $FakeBoundParameters) return (Get-Content $PSScriptRoot\versions.json -Encoding UTF8 | ConvertFrom-Json).versions })] + [switch]$SkipPdfBuilding, $Version = $((Get-Content $PSScriptRoot\versions.json -Encoding UTF8 | ConvertFrom-Json).versions | Sort-Object -Descending | Select-Object -First 1) ) @@ -189,12 +194,23 @@ 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 + Build-EnglishPdf -SkipBuilding $SkipPdfBuilding return $LastExitCode } +function Build-EnglishPdf +{ + param ( + $SkipBuilding + ) + if(!$SkipBuilding) + { + # Build pdf files + docfx pdf en/docfx.json -o $outputDirectory | Write-Host + } +} + function Build-NonEnglishDoc { param ( $SelectedLanguage @@ -219,12 +235,12 @@ function Build-NonEnglishDoc { # Copy all files from en folder to the selected language folder, this way we can keep en files that are not translated Copy-Item en/* -Recurse $langFolder -Force - # Get all translated files from the selected language folder + # Get all previously copied en files from the selected language folder $files = Get-ChildItem "$langFolder/$($Settings.ManualFolderName)/*.md" -Recurse -Force Write-Host "Start write files:" - # Mark files as not translated if they are not in the toc.md file + # Mark files as not translated if they are not a toc.md file foreach ($file in $files) { if($file.ToString().Contains("toc.md")) { diff --git a/en/community-resources/physics.md b/en/community-resources/physics.md index eb3fc16b4..535a0427c 100644 --- a/en/community-resources/physics.md +++ b/en/community-resources/physics.md @@ -3,4 +3,3 @@ * [Bepu physics integration](https://github.com/Nicogo1705/BepuPhysicIntegrationTest/tree/master) * [Trigger Example](https://github.com/profan/XenkoByteSized#xenkobytesizedtriggerscene---doorscript) * [Vehicle Script](https://github.com/profan/XenkoByteSized#xenkobytesizedvehiclescene---vehiclescript) -* [XenkoRotatingSun](https://github.com/SuavePirate/Xenko.RotatingSun) - Rotating Sun diff --git a/en/contributors/core-team.md b/en/contributors/core-team.md new file mode 100644 index 000000000..b3b4ca22a --- /dev/null +++ b/en/contributors/core-team.md @@ -0,0 +1,165 @@ +# Core Team + +The core team is a small group of volunteer developers, each with expertise in different areas of development. There are no full-time developers solely dedicated to Stride's advancement; instead, the engine progresses through voluntary contributions from both the core team and the [wider community](https://github.com/stride3d/stride?tab=readme-ov-file#contributors-). These individuals dedicate their spare time to enhancing and expanding the engine, driven by personal interest, passion for the project, and their specialized knowledge. + +The core team is composed of members who make frequent contributions to the project, whether in code, documentation, or community management. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DiscordGitHubLocationFocus / Expertise
+ xen2 +
Lead developer of Stride +
(Original & Current) +
xen2Japan +
    +
  • Build
  • +
  • Release
  • +
  • Most engine areas
  • +
      +
    • Asset pipeline
    • +
    • Render pipelne
    • +
    • Shader system
    • +
    +
+
tebjantebjanGermany +
    +
  • C# in general
  • +
  • Render pipeline
  • +
  • Graphics
  • +
  • Shaders
  • +
+
EiderenEiderenBelgium +
    +
  • C# in general
  • +
  • Shaders
  • +
  • Physics
  • +
  • Multithreading
  • +
  • Input/Gameplay
  • +
  • Math
  • +
+
Manio143Manio143Ireland +
    +
  • Asset system
  • +
  • Porting Editor to Avalonia
  • +
  • Plugin system
  • +
+
VašoVaclavEliasUnited Kingdom +
    +
  • Website
  • +
  • Documenation
  • +
  • Stride Community Toolkit
  • +
  • C#
  • +
+
SimbaDoprezCanada +
    +
  • Video Tutorials
  • +
  • C#
  • +
+
JoreykIXLLEGACYIXLGermany +
    +
  • Yaml Serializer Source Generator
  • +
  • Stride Diagnostics Analyzer
  • +
  • Overall source generators
  • +
+
YounessYouness KAFIAFrance +
    +
  • Shader system
  • +
  • ECS
  • +
+
AggrorAggrorNetherlands +
    +
  • Official video tutorials
  • +
  • Community meetings
  • +
  • Documentation
  • +
  • C#
  • +
+
JkaojklawreszukPoland +
    +
  • Asset compiler
  • +
  • Metrics
  • +
+
+ kryptosfr +
Original developer of Stride +
Kryptos-FRFrance +
    +
  • Game Studio
  • +
  • C#
  • +
+
+ diff --git a/en/contributors/engine/architecture/build-details.md b/en/contributors/engine/architecture/build-details.md index 955fc713a..789451214 100644 --- a/en/contributors/engine/architecture/build-details.md +++ b/en/contributors/engine/architecture/build-details.md @@ -1,8 +1,7 @@ # 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](https://github.com/stride3d/stride/tree/master/sources/targets) (Stride-specific) contains the MSBuild target files used to build Stride itself. +* [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. diff --git a/en/contributors/index.md b/en/contributors/index.md index a91855bde..e44fe66ea 100644 --- a/en/contributors/index.md +++ b/en/contributors/index.md @@ -1,31 +1,40 @@ # Ways to contribute Stride is a non-profit, community-driven, free and open source project. -There are no full-time developers dedicated solely to Stride's advancement; instead, the engine progresses through the voluntary contributions of both the core team and the broader community. + +There are no full-time developers dedicated solely to Stride's advancement; instead, the engine progresses through the voluntary contributions of both the [core team](core-team.md) and the broader community. In order to thrive, Stride requires the help from other community members. There are various ways you can help: ### [Community activity](https://discord.gg/f6aerfE)🤝 + To make Stride better, just use it and tell others about it in your blogs, videos, and events. Get involved in discussions on [Discord](https://discord.gg/f6aerfE) and [GitHub Discussion](https://github.com/stride3d/stride/discussions). Being a user and spreading the word is vital for our engine, as we don't have a big marketing budget and rely on the community to grow. ### [Make games](https://github.com/stride3d/stride/wiki/Community-Projects) 🕹️ + The best way to promote Stride is by creating a cool demo or, even better, a full game. Having people see and play an actual game made with Stride is the most effective form of advertisement. ### [Donate](donate.md) 💸 + We utilize Open Collective for fundraising. The funds collected are allocated towards bug bounties and compensating individuals contracted for paid work. ### [Submit bug reports](https://github.com/stride3d/stride/issues) 🐛 + Making Stride more stable greatly improves usability and user satisfaction. So if you encounter a bug during development, please contribute by reporting it on [GitHub](https://github.com/stride3d/stride/issues). ### [PR reviews](https://github.com/stride3d/stride/pulls) 🔭 + Contributing to Pull Requests (PRs) is excellent as it enables active participation without local builds. Reviewing and offering feedback in this collaborative process enhances code quality and maintains project standards, fostering a sense of community and knowledge sharing. ### [Contribute code](engine/index.md) 🤖 + If you're passionate about C# and want to contribute by building features or fixing bugs in Stride, dive into the source code and get involved! Have a look at the GitHub issues label [Good first issue](https://github.com/stride3d/stride/labels/good%20first%20issue) or funded [Open Collective projects](https://opencollective.com/stride3d/projects) ### [Contribute to Documentation](documentation/index.md) 🪶 + Enhance the official documentation and tutorials by expanding the manual or creating textual/video guides. Your contributions will greatly improve accessibility and understanding for users. ### [Contribute to Website](website/index.md) 🌐 + Enhance the official Stride website. Is design more your thing, or do you have an interesting blog post? It will all help us spread the word of Stride. \ No newline at end of file diff --git a/en/contributors/roadmap.md b/en/contributors/roadmap.md index 3192cd70a..161665bc7 100644 --- a/en/contributors/roadmap.md +++ b/en/contributors/roadmap.md @@ -1,5 +1,5 @@ # Roadmap -The Stride game engine (MIT) is a collaborative endeavor managed by a small group of core volunteer developers, each with expertise in different areas of development. There are no full-time developers dedicated solely to Stride's advancement; instead, the engine progresses through the voluntary contributions of both the core team and the broader community. These individuals dedicate their spare time to enhance and expand the engine, motivated by personal interest, passion for the project, or their areas of expertise. +The Stride game engine (MIT) is a collaborative endeavor managed by a small group of core volunteer developers, each with expertise in different areas of development. There are no full-time developers dedicated solely to Stride's advancement; instead, the engine progresses through the voluntary contributions of both the [core team](core-team.md) and the broader community. These individuals dedicate their spare time to enhance and expand the engine, motivated by personal interest, passion for the project, or their areas of expertise. ## Contributors Contributions to Stride come in various forms. Some contributors focus on resolving existing issues, fostering the engine's stability and usability. Others venture into new territories, introducing improvements and features they deem beneficial, are personally intrigued by, or hold expertise in. @@ -9,28 +9,30 @@ The community has highlighted a range of feature requests, some of which are qui Given the voluntary nature of contributions, the pace of progress hinges largely on the personal commitments and availability of our contributors. However, to catalyze action around certain desired features, Stride has established bounties through the [Open Collective](https://opencollective.com/stride3d). These bounties serve as a rallying call, incentivizing efforts towards tackling specific requests. -- Migrate Gamestudio to Avalonia (Being worked on) - - Github https://github.com/stride3d/stride/issues/1629 - - Open Collective project https://opencollective.com/stride3d/projects/editor-rewrite-avalonia +- Bepu Physics integration In Progress + - GitHub: https://github.com/stride3d/stride/pull/2131 +- Migrate Game Studio to Avalonia In Progress + - GitHub: https://github.com/stride3d/stride/issues/1629 + - Open collective project: https://opencollective.com/stride3d/projects/editor-rewrite-avalonia - Linux/MacOS https://github.com/stride3d/stride/issues/70 -- Improving asset pipeline - - https://opencollective.com/stride3d/projects/fbx-import-cpp-to-c-sharp - - https://opencollective.com/stride3d/projects/multiple-animations-per-model -- Morph targets (Being worked on) - - Github: https://github.com/stride3d/stride/issues/339 - - pen Collective project https://opencollective.com/stride3d/projects/morph-targets +- Improving asset pipeline Done + - Open collective project: https://opencollective.com/stride3d/projects/fbx-import-cpp-to-c-sharp + - Open collective project: https://opencollective.com/stride3d/projects/multiple-animations-per-model +- Morph targets On Hold + - GitHub: https://github.com/stride3d/stride/issues/339 + - Open collective project: https://opencollective.com/stride3d/projects/morph-targets - Decals https://opencollective.com/stride3d/projects/decals -- Open XR support (Being worked on) - - Github: https://github.com/stride3d/stride/discussions/1848 - - Open Collective project https://opencollective.com/stride3d/projects/openxr-support +- Open XR support On Hold + - GitHub: https://github.com/stride3d/stride/discussions/1848 + - Open collective project: https://opencollective.com/stride3d/projects/openxr-support - Embed into UI frameworks - - Github: https://github.com/stride3d/stride/pull/1315 - - Open collective Project https://opencollective.com/stride3d/projects/embed-stride-ui-frameworks + - GitHub: https://github.com/stride3d/stride/pull/1315 + - Open collective project: https://opencollective.com/stride3d/projects/embed-stride-ui-frameworks - Silk.NET integration - - Github: https://github.com/stride3d/stride/pull/ - - Open collective Project https://opencollective.com/stride3d/projects/stride3d-silknet + - GitHub: https://github.com/stride3d/stride/pull/ + - Open collective project: https://opencollective.com/stride3d/projects/stride3d-silknet -Other areas were contributors have been active +Other areas where contributors have been active - Plugins: https://github.com/stride3d/stride/issues/1120 - Improving Docs - Improving Website diff --git a/en/contributors/toc.yml b/en/contributors/toc.yml index 657861296..7289b206c 100644 --- a/en/contributors/toc.yml +++ b/en/contributors/toc.yml @@ -18,6 +18,8 @@ items: href: contribution-workflow/xml-comments-and-docs.md - name: ⚙️ Major Release Workflow href: major-release-workflow.md +- name: 🧑‍💻 Core Team + href: core-team.md - name: 🛠️ Contribute to the engine expanded: false href: engine/index.md diff --git a/en/diagnostics/STRDIAG010.md b/en/diagnostics/STRDIAG010.md new file mode 100644 index 000000000..68d09fe0c --- /dev/null +++ b/en/diagnostics/STRDIAG010.md @@ -0,0 +1,50 @@ +# Diagnostics Warning STRDIAG010 + +> The Type '{0}' doesn't have a public parameterless constructor, which is needed for Serialization. + +## Explanation + +By default, Stride serializers only support types that have a parameterless constructor. If no constructor is defined then the default constructor counts as parameterless constructor. Primary Constructors with parameters count as non parameterless constructor. Structs have per default a parameterless constructor so this warning will never appear on a struct. + +## Example + +The following example generates STRDIAG010: + +```csharp +using Stride.Core; + +[DataContract] +public class InvalidSTRDIAG010 +{ + // no parameterless constructor available so it will throw STRDIAG010 + public InvalidSTRDIAG010(int x, int y) + { + + } +} +``` + +The following example doesn't generate STRDIAG010: + +```csharp +public class ValidSTRDIAG010 +{ + // will be ignored by the serializers + public ValidSTRDIAG010(int x, int y) + { + } + // this parameterless constructor will be used by the serializers + public ValidSTRDIAG010() + { + + } +} +``` + +## Solution + +To resolve the warning, add a parameterless constructor that can be used by the serializers. Or remove the @Stride.Core.DataContractAttribute so the class gets entirely ignored by the serialization system. + +## References + +- [Serialisation](../manual/scripts/serialization.md) \ No newline at end of file diff --git a/en/examples/Stride.Utilities-examples.md b/en/examples/Stride.Utilities-examples.md index 7bb5884c2..e60b97fcf 100644 --- a/en/examples/Stride.Utilities-examples.md +++ b/en/examples/Stride.Utilities-examples.md @@ -1,57 +1,15 @@ --- -uid: Stride.Utilities.Test +uid: Stride.Utilities example: [*content] --- ```csharp -using System; -using System.IO; -using System.Text; +// This example demonstrates how to add C# code snippets to API documentation from external files, though it's unrelated to the subject matter. -class Test -{ - - public static void Main() - { - string path = @"c:\temp\MyTest.txt"; - - // Delete the file if it exists. - if (File.Exists(path)) - { - File.Delete(path); - } - - //Create the file. - using (FileStream fs = File.Create(path)) - { - AddText(fs, "This is some text"); - AddText(fs, "This is some more text,"); - AddText(fs, "\r\nand this is on a new line"); - AddText(fs, "\r\n\r\nThe following is a subset of characters:\r\n"); +var trigger = Entity.Get(); - for (int i=1;i < 120;i++) - { - AddText(fs, Convert.ToChar(i).ToString()); - } - } - - //Open the stream and read it back. - using (FileStream fs = File.OpenRead(path)) - { - byte[] b = new byte[1024]; - UTF8Encoding temp = new UTF8Encoding(true); - int readLen; - while ((readLen = fs.Read(b,0,b.Length)) > 0) - { - Console.WriteLine(temp.GetString(b,0,readLen)); - } - } - } - - private static void AddText(FileStream fs, string value) - { - byte[] info = new UTF8Encoding(true).GetBytes(value); - fs.Write(info, 0, info.Length); - } +foreach (var collision in trigger.Collisions) +{ + //do something with the collision } ``` \ No newline at end of file diff --git a/en/examples/Stride.Utilities-remarks.md b/en/examples/Stride.Utilities-remarks.md index 0736de539..0dc67c409 100644 --- a/en/examples/Stride.Utilities-remarks.md +++ b/en/examples/Stride.Utilities-remarks.md @@ -1,16 +1,14 @@ --- -uid: Stride.Utilities.Test +uid: Stride.Utilities remarks: *content --- -Use the FileStream class to read from, write to, open, and close files on a file system, and to manipulate other file-related operating system handles, including pipes, standard input, and standard output. You can use the Read, Write, CopyTo, and Flush methods to perform synchronous operations, or the ReadAsync, WriteAsync, CopyToAsync, and FlushAsync methods to perform asynchronous operations. Use the asynchronous methods to perform resource-intensive file operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. FileStream buffers input and output for better performance. +This remark serves as a demonstration of how to use overwrite files in API documentation. Overwrite files allow us to add a remarks section to the API docs seamlessly. > [!NOTE] -> This type implements the IDisposable interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its Dispose method in a `try/catch block`. To dispose of it indirectly, use a language construct such as `using` (in C#) or Using (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the IDisposable interface topic. - -The IsAsync property detects whether the file handle was opened asynchronously. You specify this value when you create an instance of the FileStream class using a constructor that has an isAsync, useAsync, or options parameter. When the property is true, the stream utilizes overlapped I/O to perform file operations asynchronously. However, the IsAsync property does not have to be true to call the ReadAsync, WriteAsync, or CopyToAsync method. When the IsAsync property is false and you call the asynchronous read and write operations, the UI thread is still not blocked, but the actual I/O operation is performed synchronously. - -The Seek method supports random access to files. Seek allows the read/write position to be moved to any position within the file. This is done with byte offset reference point parameters. The byte offset is relative to the seek reference point, which can be the beginning, the current position, or the end of the underlying file, as represented by the three members of the SeekOrigin enumeration. +> This text is an example of how to incorporate notes within the documentation. Notes are useful for providing additional information about the subject. You can also use ticks ` for code snippets. > [!CAUTION] -> Disk files always support random access. At the time of construction, the CanSeek property value is set to true or false depending on the underlying file type. If the underlying file type is FILE_TYPE_DISK, as defined in winbase.h, the CanSeek property value is true. Otherwise, the CanSeek property value is false. \ No newline at end of file +> This text is an example of how to incorporate caution notes within the documentation to highlight important information or warnings. + +

Html support is also available in the remarks section.

diff --git a/en/manual/audio/custom-audio-data.md b/en/manual/audio/custom-audio-data.md index 27246d7e6..7d8dc34fe 100644 --- a/en/manual/audio/custom-audio-data.md +++ b/en/manual/audio/custom-audio-data.md @@ -4,7 +4,7 @@ Programmer You can generate audio using your own mechanism. To do this, create a subclass of [DynamicSoundSource](xref:Stride.Audio.DynamicSoundSource). -For an example of how to implement this, see the [CompressedSoundSource` source code](https://github.com/SiliconStudio/stride/blob/master-1.8/sources/engine/Stride.Audio/CompressedSoundSource.cs). +For an example of how to implement this, see the [CompressedSoundSource` source code](https://github.com/Stride3d/stride/blob/master/sources/engine/Stride.Audio/CompressedSoundSource.cs). ## Example code @@ -23,4 +23,4 @@ myCustomInstance.Play(); ``` ## See also -* [Global audio settings](global-audio-settings.md) \ No newline at end of file +* [Global audio settings](global-audio-settings.md) diff --git a/en/manual/engine/entity-component-system/flexible-processing.md b/en/manual/engine/entity-component-system/flexible-processing.md new file mode 100644 index 000000000..235446cd3 --- /dev/null +++ b/en/manual/engine/entity-component-system/flexible-processing.md @@ -0,0 +1,94 @@ +# Flexible Processing + +This document expects the reader to be familiar with ECS, please take a look at [usage](usage.md) first. + +Handling components through [`EntityProcessor`](xref:Stride.Engine.EntityProcessor) may be too rigid in some cases, when the components +you're trying to process cannot share the same base implementation for example. + +[`Stride.Engine.FlexibleProcessing.IComponent`](xref:Stride.Engine.FlexibleProcessing.IComponent`2) +provides similar features to [`EntityProcessor`](xref:Stride.Engine.EntityProcessor) while being more flexible on the component type, +this document covers some of the usage of this particular interface. + +The `IComponent` interface requires to type parameters, +- `TProcessor` which is your processor's type. +- And `TThis` which is your component's type. + +While that last type may seem redundant, it is required to ensure your processor and +your implemented type are compatible. + +A summarised example satisfying those type constraint would look like so: +```cs +public class MyComponent : StartupScript, IComponent +{ + public class MyProcessor : IProcessor + { + public List Components = new(); + + public void SystemAdded(IServiceRegistry registryParam) { } + public void SystemRemoved() { } + + public void OnComponentAdded(MyComponent item) => Components.Add(item); + public void OnComponentRemoved(MyComponent item) => Components.Remove(item); + } +} +``` + +The main difference compared to [`EntityProcessor`](xref:Stride.Engine.EntityProcessor) +is that [`IComponent`](xref:Stride.Engine.FlexibleProcessing.IComponent`2) is not limited to concrete types, your processor may operate on interfaces as well; +```cs +// Here, declaring the interface, which will be the type received by the processor +public interface IInteractable : IComponent +{ + void Interact(); + public class InteractableProcessor : IProcessor + { + // Process each IInteractable here + // Omitted method implementation for brievety + } +} + +// Now any component implementing IInteractable will be processed by the InteractableProcessor +public class Button : StartupScript, IInteractable +{ + public void Interact(){} +} +public class Character : SyncScript, IInteractable +{ + public void Interact(){} + public override void Update(){} +} +``` + +## Updating Processors +[`Processors`](xref:Stride.Engine.FlexibleProcessing.IComponent`2) do not receive any updates by default, you have to implement the [`IUpdateProcessor`](xref:Stride.Engine.FlexibleProcessing.IUpdateProcessor) or [`IDrawProcessor`](xref:Stride.Engine.FlexibleProcessing.IDrawProcessor) +interface to receive them: +```cs +public interface ISpecialTick : IComponent +{ + void Tick(); + + public class Processor : IProcessor, IUpdateProcessor + { + public List Components = new(); + + public void SystemAdded(IServiceRegistry registryParam) { } + public void SystemRemoved() { } + + public void OnComponentAdded(ISpecialTick item) => Components.Add(item); + public void OnComponentRemoved(ISpecialTick item) => Components.Remove(item); + + // The execution order of this Update, smaller values execute first compared to other IComponent Processors + public int Order => 0; + + public void Update(GameTime gameTime) + { + foreach (var comp in Components) + comp.Tick(); + } + } +} +``` + +## Performance +While it is more flexible, processing components as interfaces instead of concrete class may introduce some overhead. +If the system you're writing is performance critical you should look into strategies to elide or reduce virtual calls in your hot path. diff --git a/en/manual/engine/file-system.md b/en/manual/engine/file-system.md index b268bf28d..4fc0d4743 100644 --- a/en/manual/engine/file-system.md +++ b/en/manual/engine/file-system.md @@ -19,11 +19,11 @@ var gamesave2 = VirtualFileSystem.ApplicationRoaming.OpenStream("gamesave001.dat ## Default mount points -| Mount point | Description | Writable | Cloud | Notes | PC | Android | iOS | Windows Phone 8.1 -| ----------- | -------------| -------- | ----- | -------| ---- | -------- | ------- | -- -| data | Application data, deployed by package | ✗ | ✗ | | Output directory/data | APK itself | Deployed package directory | InstalledLocation.Path -| binary | Application binaries, deployed by package | ✗ | ✗ | Usually the same as *app_data* (except on Android) | Assembly directory | Assembly directory | Assembly directory | Assembly directory -| roaming | User specific data (roaming) | ✓ | ✓ | Backup | Output directory/roaming, *%APPDATA%* | *$(Context.getFilesDir)/roaming* | Library/roaming | Roaming -| local | User application data | ✓ | ✓ | Backup | Output directory/local | $(Context.getFilesDir)local | Library/local | Local -| cache | Application cache | ✓ | ✗ | DLC, etc. Might be deleted manually by user (restore, clear data, etc...) | Output directory/cache, with do-not-back-up flags | *$(Context.getFilesDir)/cache* | Library/caches | LocalCache -| tmp | Application temporary data | ✓ | ✗ | Might be deleted without notice by OS | Output directory/temp, *%TEMP%/%APPNAME%* | *$(Context.getCacheDir)* | tmp | Temporary \ No newline at end of file +| Mount point | Description | Writable | Cloud | Notes | PC | Android | iOS | +|-------------|-------------------------------------------|----------|-------|---------------------------------------------------------------------------|---------------------------------------------------|----------------------------------|----------------------------| +| data | Application data, deployed by package | ✗ | ✗ | | Output directory/data | APK itself | Deployed package directory | +| binary | Application binaries, deployed by package | ✗ | ✗ | Usually the same as *app_data* (except on Android) | Assembly directory | Assembly directory | Assembly directory | +| roaming | User specific data (roaming) | ✓ | ✓ | Backup | Output directory/roaming, *%APPDATA%* | *$(Context.getFilesDir)/roaming* | Library/roaming | +| local | User application data | ✓ | ✓ | Backup | Output directory/local | $(Context.getFilesDir)local | Library/local | +| cache | Application cache | ✓ | ✗ | DLC, etc. Might be deleted manually by user (restore, clear data, etc...) | Output directory/cache, with do-not-back-up flags | *$(Context.getFilesDir)/cache* | Library/caches | +| tmp | Application temporary data | ✓ | ✗ | Might be deleted without notice by OS | Output directory/temp, *%TEMP%/%APPNAME%* | *$(Context.getCacheDir)* | tmp | \ No newline at end of file diff --git a/en/manual/files-and-folders/distribute-a-game.md b/en/manual/files-and-folders/distribute-a-game.md index 9195c9a23..2a3525f9d 100644 --- a/en/manual/files-and-folders/distribute-a-game.md +++ b/en/manual/files-and-folders/distribute-a-game.md @@ -65,7 +65,7 @@ After you create a release build, how you distribute it is up to you. To run games made with Stride on Windows, users need: -* .NET 4.6.1 +* .NET 8 SDK * DirectX11 (included with Windows 10 and later), OpenGL, or Vulkan diff --git a/en/manual/game-studio/index.md b/en/manual/game-studio/index.md index c1d07fc5b..b7b61f617 100644 --- a/en/manual/game-studio/index.md +++ b/en/manual/game-studio/index.md @@ -15,7 +15,7 @@ Game Studio is also integrated with your Visual Studio projects, so you can seam ![Game Studio](../get-started/media/game-studio-main-interface.png) -The **asset editor** (A) is used to edit assets and scenes. Some asset types, such as scenes [scenes](create-a-scene.md), have dedicated editors where you can make complex changes to the asset. To open a dedicated editor (when available), double-click the asset or right-click it and select **Edit asset**. +The **asset editor** (A) is used to edit assets and scenes. Some asset types, such as [scenes](create-a-scene.md), have dedicated editors where you can make complex changes to the asset. To open a dedicated editor (when available), double-click the asset or right-click it and select **Edit asset**. The **Property Grid** (B) displays the properties of the asset or entity you select. You can edit the properties here. @@ -47,4 +47,4 @@ You can show and hide different parts of the Game Studio in the View menu. You c * [Edit prefabs](prefabs/edit-prefabs.md) * [Nested prefabs](prefabs/nested-prefabs.md) * [Override prefab properties](prefabs/override-prefab-properties.md) -* [World units](world-units.md) \ No newline at end of file +* [World units](world-units.md) diff --git a/en/manual/get-started/launch-stride.md b/en/manual/get-started/launch-stride.md index 26377b758..62875e59a 100644 --- a/en/manual/get-started/launch-stride.md +++ b/en/manual/get-started/launch-stride.md @@ -16,7 +16,7 @@ If you choose to install the latest version, the Stride Launcher asks if you wan ![Install Visual Studio integration](media/install-VS-plug-in-prompt.webp) -The Stride Visual Studio extension adds syntax highlighting, live code validation, error checking, and navigation. It also lets you you [edit shaders directly from Visual Studio](../graphics/effects-and-shaders/custom-shaders.md). You don't need to install the extension to use Stride, but we recommend it, especially for programmers. +The Stride Visual Studio extension lets you you [edit shaders directly from Visual Studio](../graphics/effects-and-shaders/custom-shaders.md). You don't need to install the extension to use Stride, but we recommend it, especially for programmers. ## Manage different versions of Stride diff --git a/en/manual/get-started/visual-studio-extension.md b/en/manual/get-started/visual-studio-extension.md index 04e6eba85..a8c559ba7 100644 --- a/en/manual/get-started/visual-studio-extension.md +++ b/en/manual/get-started/visual-studio-extension.md @@ -2,7 +2,7 @@ Beginner -The **Stride Visual Studio extension** adds syntax highlighting, live code validation, error checking, and navigation. It also lets you you [edit shaders directly from Visual Studio](../graphics/effects-and-shaders/custom-shaders.md). +The **Stride Visual Studio extension** lets you [edit shaders directly from Visual Studio](../graphics/effects-and-shaders/custom-shaders.md). You don't need to install the extension to use Stride, but we recommend it, especially for programmers. diff --git a/en/manual/graphics/materials/shading-attributes.md b/en/manual/graphics/materials/shading-attributes.md index 7f2c21330..8ccabffa6 100644 --- a/en/manual/graphics/materials/shading-attributes.md +++ b/en/manual/graphics/materials/shading-attributes.md @@ -20,7 +20,6 @@ The **diffuse** is the basic color of the material. A pure diffuse material is c The final diffuse contribution is calculated like this: - the **diffuse** defines the color used by the diffuse model - - the **diffuse model** defines which shading model is used for rendering the diffuse component (see below) Currently, the diffuse attribute supports only a **diffuse map**. @@ -42,7 +41,7 @@ Under the Lambert model, light is reflected equally in all directions with an in | Property | Description | ------------- | ----------- -| Diffuse map | The diffuse map color provider +| Diffuse map | The diffuse map color provider | Diffuse model | The shading model for diffuse lighting ## Specular @@ -62,10 +61,8 @@ By taking into into account the fact that almost all materials always have some The final specular color is calculated by mixing a fixed low-reflection color and the diffuse color. - With the metalness color at `0.0`, the effective specular color is equal to `0.02`, while the diffuse color is unchanged. The material is not metal but exhibits some reflectance and is sensitive to the Fresnel effect. - - With the metalness color at `1.0`, the effective specular color is equal to the diffuse color, and the diffuse color is set to `0`. The material is considered a pure metal. - - ![media/material-attributes-26.png](media/material-attributes-26.png) + ![media/material-attributes-26.png](media/material-attributes-26.png) The screenshots below show the result of the metalness factor on a material with the following attributes: @@ -100,15 +97,9 @@ The microfacet is defined by the following formula, where Rs is the resulting sp | Property | Description | ------------------- | ------- -| Fresnel | Defines the amount of light that is reflected and transmitted. The models supported are:

**Schlick**: An approximation of the Fresnel effect (default)

**Thin glass**: A simulation of light passing through glass

**None**: The material as-is with no Fresnel effect
-| Visibility | Defines the visibility between of the microfacets between (0, 1). Also known as the geometry attenuation - Shadowing and Masking - in the original Cook-Torrance. Stride simplifies the formula to use the visibility term instead:

![media/material-attributes-35.png](media/material-attributes-35.png)

and

![media/material-attributes-36.png](media/material-attributes-36.png)

**Schlick GGX** (default)

**Implicit**: The microsurface is always visible and generates no shadowing or masking

**Cook-Torrance**

**Kelemen**

**Neumann**

**Smith-Beckmann**

**Smith-GGX correlated**

**Schlick-Beckmann**
-| Normal Distribution |

Defines how the normal is distributed. The gloss attribute is used by this part of the function to modify the distribution of the normal.

**GGX** (default)

**Beckmann**

**Blinn-Phong**
-| Fresnel | Defines the amount of light that is reflected and transmitted. The models supported are:

**Schlick**: An approximation of the Fresnel effect (default)

**Thin glass**: A simulation of light passing through glass

**None**: The material as-is with no Fresnel effect
-| Visibility | Defines the visibility between of the microfacets between (0, 1). Also known as the geometry attenuation - Shadowing and Masking - in the original Cook-Torrance. Stride simplifies the formula to use the visibility term instead:

![media/material-attributes-35.png](media/material-attributes-35.png)

and

![media/material-attributes-36.png](media/material-attributes-36.png)

**Schlick GGX** (default)

**Implicit**: The microsurface is always visible and generates no shadowing or masking

**Cook-Torrance**

**Kelemen**

**Neumann**

**Smith-Beckmann**

**Smith-GGX correlated**

**Schlick-Beckmann**
-| Normal Distribution |

Defines how the normal is distributed. The gloss attribute is used by this part of the function to modify the distribution of the normal.

**GGX** (default)

**Beckmann**

**Blinn-Phong**
-| Fresnel | Defines the amount of light that is reflected and transmitted. The models supported are:


**Schlick**: An approximation of the Fresnel effect (default)



**Thin glass**: A simulation of light passing through glass



**None**: The material as-is with no Fresnel effect


-| Visibility | Defines the visibility between of the microfacets between (0, 1). Also known as the geometry attenuation - Shadowing and Masking - in the original Cook-Torrance. Stride simplifies the formula to use the visibility term instead:


![media/material-attributes-35.png](media/material-attributes-35.png)



and


![media/material-attributes-36.png](media/material-attributes-36.png)



**Schlick GGX** (default)



**Implicit**: The microsurface is always visible and generates no shadowing or masking



**Cook-Torrance**



**Kelemen**



**Neumann**



**Smith-Beckmann**



**Smith-GGX correlated**



**Schlick-Beckmann**


-| Normal Distribution |


Defines how the normal is distributed. The gloss attribute is used by this part of the function to modify the distribution of the normal.



**GGX** (default)



**Beckmann**



**Blinn-Phong**


+| Fresnel | Defines the amount of light that is reflected and transmitted. The models supported are:
**Schlick**: An approximation of the Fresnel effect (default)
**Thin glass**: A simulation of light passing through glass
**None**: The material as-is with no Fresnel effect +| Visibility | Defines the visibility between of the microfacets between (0, 1). Also known as the geometry attenuation - Shadowing and Masking - in the original Cook-Torrance. Stride simplifies the formula to use the visibility term instead:
![media/material-attributes-35.png](media/material-attributes-35.png)
and
![media/material-attributes-36.png](media/material-attributes-36.png)
**Schlick GGX** (default)
**Implicit**: The microsurface is always visible and generates no shadowing or masking
**Cook-Torrance**
**Kelemen**
**Neumann**
**Smith-Beckmann**
**Smith-GGX correlated**
**Schlick-Beckmann** +| Normal Distribution | Defines how the normal is distributed. The gloss attribute is used by this part of the function to modify the distribution of the normal.
**GGX** (default)
**Beckmann**
**Blinn-Phong** ## Emissive diff --git a/en/manual/graphics/textures/index.md b/en/manual/graphics/textures/index.md index 30ab71323..a235aba62 100644 --- a/en/manual/graphics/textures/index.md +++ b/en/manual/graphics/textures/index.md @@ -63,8 +63,6 @@ The following properties are common to all textures. | Width | The width of the texture in-game | Height | The height of the texture in-game | Use percentages | Use percentages for width and height instead of actual pixel size -| Width | The width of the texture in-game -| Height | The height of the texture in-game | Type | Use **Color** for textures you want to display as images, **Normal map** for normal maps, and **Grayscale** to provide values for other things (eg specular maps, metalness maps, roughness maps). Color textures and normal maps have additional properties (see below). | Generate mipmaps | Generate different versions of the texture at different resolutions to be displayed at different distances. Improves performance, removes visual artifacts, and reduces pop-in when using **streaming**, but uses more memory. Unnecessary for textures always at the same distance from the camera (such as UIs). | Compress | Compress the final texture to a format based on the target platform and usage. The final texture is a multiple of 4. For more information, see [Texture compression](compression.md). diff --git a/en/manual/graphics/textures/skyboxes-and-backgrounds.md b/en/manual/graphics/textures/skyboxes-and-backgrounds.md index 248ce650b..28d81b137 100644 --- a/en/manual/graphics/textures/skyboxes-and-backgrounds.md +++ b/en/manual/graphics/textures/skyboxes-and-backgrounds.md @@ -54,6 +54,7 @@ Instead of using a cubemap, you can use a **360° panoramic texture** as a 3D ba | 360° panorama | Appearance in game |----------------|------------- | ![Panorama texture](media/MyPanorama.jpg) | ![Panorama in game](media/panorama-in-game.jpg) + *Image courtesy of [Texturify](http://texturify.com)* >[!Note] diff --git a/en/manual/index.md b/en/manual/index.md index 5a0b0a4f0..9e74b235d 100644 --- a/en/manual/index.md +++ b/en/manual/index.md @@ -10,6 +10,16 @@ These pages contain information about how to use Stride, an open-source C# game ## Latest documentation ### Recent updates + +#### Contributors + +- New [Contributing - Core Team](../contributors/core-team.md) - The Stride core team +- Updated [Contributing - Roadmap](../contributors/roadmap.md) - Status added + +#### Manual +- Updated [Scripts - Types of script](scripts/types-of-script.md) - Asynchronous script example improved +- New [Scripts - Gizmos](scripts/gizmos.md) - Description and example of the Flexible Processing system +- New [ECS - Flexible Processing](engine/entity-component-system/flexible-processing.md) - Description and example of the Flexible Processing system - Updated [Linux - Setup and requirements](platforms/linux/setup-and-requirements.md) - Fedora OS option added - New [Scripts - Serialization](scripts/serialization.md) - Explanation of serialization - Updated [Scripts - Public properties and fields](scripts/public-properties-and-fields.md) - Content improvements and additions diff --git a/en/manual/nuget/create-packages.md b/en/manual/nuget/create-packages.md index 4ac2f3ff6..4e6ec4a69 100644 --- a/en/manual/nuget/create-packages.md +++ b/en/manual/nuget/create-packages.md @@ -5,9 +5,6 @@ ## Open your project in Visual Studio -> [!Note] -> Game Studio will later support creating NuGet packages directly. - First of all, after saving all your changes, open your project with Visual Studio. You can easily do this by clicking the appropriate button on the toolbar: ![Open project in Visual Studio](../game-studio/media/open-project-in-visual-studio.png) diff --git a/en/manual/physics/fix-physics-jitter.md b/en/manual/physics/fix-physics-jitter.md index 72a931613..be4371321 100644 --- a/en/manual/physics/fix-physics-jitter.md +++ b/en/manual/physics/fix-physics-jitter.md @@ -8,7 +8,7 @@ In Stride, there is no default smoothing applied to entities that are attached t In this tutorial, we will explore how to add smoothing to an entity using a SyncScript. > [!Note] -> You can also decrease the `Fixed Time Step` in the physics settings configuration to achieve more accurate physics simulations. For example, changing it from `0.016667` to `0.008` will increase accuracy but at the cost of higher CPU usage. +> You can also decrease the `FixedTimeStep` in the physics settings configuration to achieve more accurate physics simulations. For example, changing it from `0.016667` to `0.008` will increase accuracy but at the cost of higher CPU usage. ## Code to handle smoothing between two entities The following code is all that's needed to smoothly attach two entities. Ensure that you unparent the entity you are trying to smooth, otherwise the transform processor will override this script. @@ -42,7 +42,7 @@ public class SmoothFollowAndRotate : SyncScript ## Example Usage -This example demonstrates modifications to the **First Person Shooter** Template to integrate smooth camera movement. +This example demonstrates modifications to the **First Person Shooter** template to integrate smooth camera movement. 1. Detach the camera from the physics entity. 2. Remove the FPS camera script from the camera. @@ -84,29 +84,32 @@ var inverseView = Matrix.Invert(camera.ViewMatrix); ``` to -`var inverseView = camera.Transform.WorldMatrix;` + +```cs +var inverseView = camera.Transform.WorldMatrix; +``` ### FpsCamera.cs Remove ```cs - /// - /// Gets the camera component used to visualized the scene. - /// - private Entity Component; +/// +/// Gets the camera component used to visualized the scene. +/// +private Entity Component; ``` and change ```cs - private void UpdateViewMatrix() - { - var camera = Component; - if (camera == null) return; - var rotation = Quaternion.RotationYawPitchRoll(Yaw, Pitch, 0); - - Entity.Transform.Rotation = rotation; - } +private void UpdateViewMatrix() +{ + var camera = Component; + if (camera == null) return; + var rotation = Quaternion.RotationYawPitchRoll(Yaw, Pitch0); + + Entity.Transform.Rotation = rotation; +} ``` to diff --git a/en/manual/platforms/index.md b/en/manual/platforms/index.md index 7c939e0c7..b950dbf5a 100644 --- a/en/manual/platforms/index.md +++ b/en/manual/platforms/index.md @@ -6,9 +6,9 @@ Stride is cross-platform game engine. This means you can create your game once, ## Supported platforms -* Windows Desktop 7, 8, 10 -* Windows Universal (UWP) -* [Linux (Ubuntu)](linux/index.md) +* Windows 7, 8, 10 +* Windows Universal Platform (UWP) +* [Linux](linux/index.md) * Android 2.3 and later * [iOS 8.0 and later](ios.md) diff --git a/en/manual/platforms/linux/setup-and-requirements.md b/en/manual/platforms/linux/setup-and-requirements.md index e08738b75..d9fdcee96 100644 --- a/en/manual/platforms/linux/setup-and-requirements.md +++ b/en/manual/platforms/linux/setup-and-requirements.md @@ -13,7 +13,7 @@ You need the following packages: * [FreeType](#freetype) * [OpenAL](#openal) * [SDL2](#sdl2) -* [Latest .NET](https://dotnet.microsoft.com/en-us/download) +* [FreeImage](#freeimage) ## FreeType @@ -87,16 +87,31 @@ sudo pacman -S sdl2 --- -## .NET +## FreeImage -For information about how to install .NET, see the [.NET instructions for Linux](https://docs.microsoft.com/en-us/dotnet/core/linux-prerequisites). +[FreeImage](https://freeimage.sourceforge.io/) is battle-tested library for loading and saving popular image file formats like BMP, PNG, JPEG etc. The minimum required version is 3.18 and can be installed via: -We recommend to install .NET 8. To check which version you have installed, type: +### [Debian / Ubuntu](#tab/freeimage-ubuntu) + +```bash +sudo apt install libfreeimage-dev ``` -dotnet --info + +### [Fedora](#tab/freeimage-fedora) + +```bash +sudo dnf install freeimage-devel ``` +### [Arch](#tab/freeimage-arch) + +```bash +sudo pacman -S freeimage +``` + +--- + ## See also * [Create a Linux game](create-a-linux-game.md) diff --git a/en/manual/requirements/index.md b/en/manual/requirements/index.md index af5f336ba..5df7c1ede 100644 --- a/en/manual/requirements/index.md +++ b/en/manual/requirements/index.md @@ -11,13 +11,15 @@ To develop projects with Stride, you need: | CPU | x64 | GPU | Direct3D 10+ compatible GPU | RAM | 4GB (minimum), 8GB (recommended) [see (2)] +| .NET SDK | 8+ [see (3)] | (1) Earlier versions of Windows _may_ work but are untested. (2) RAM requirements vary depending on your project: * Developing simple 2D applications doesn't require much RAM. * Developing 3D games with lots of assets requires larger amounts of RAM. - + +(3) .NET SDK is being downloaded with the Stride installer. ## Mobile development requirements @@ -25,10 +27,10 @@ To develop for mobile platforms, you also need: | Platform | Requirements |----------|------- -| Android | Xamarin [see (3)] -| iOS | Mac computer, Xamarin [see (3)] +| Android | Xamarin [see (4)] +| iOS | Mac computer, Xamarin [see (4)] -(3) Xamarin is included with Visual Studio installations. For instructions about how to install Xamarin with Visual Studio, see [this MSDN page](https://docs.microsoft.com/en-us/visualstudio/cross-platform/setup-and-install). +(4) Xamarin is included with Visual Studio installations. For instructions on installing Xamarin with Visual Studio, see [this MSDN page](https://docs.microsoft.com/en-us/visualstudio/cross-platform/setup-and-install). ## Running Stride Games diff --git a/en/manual/scripts/gizmos.md b/en/manual/scripts/gizmos.md new file mode 100644 index 000000000..be60d4c8a --- /dev/null +++ b/en/manual/scripts/gizmos.md @@ -0,0 +1,172 @@ +# Gizmos + +Intermediate +Programmer + +**Gizmos** are a tool which you can implement over your components to provide visual assistance for designers when manipulating component values. + +Here's an exhaustive example one could implement: +```cs +using Stride.Core; +using Stride.Core.Mathematics; +using Stride.Engine; +using Stride.Engine.Gizmos; +using Stride.Graphics; +using Stride.Graphics.GeometricPrimitives; +using Stride.Rendering; +using Stride.Rendering.Materials; +using Stride.Rendering.Materials.ComputeColors; + +// We will be implementing a Gizmo for the following class +public class MyScript : StartupScript +{ + +} + +// This attribute specifies to the engine that the following gizmo class is bound to 'MyScript', +// the game studio will pick that up and spawn an instance of that class for each 'MyScript' in the scene +[GizmoComponent(typeof(MyScript), isMainGizmo:false/*When true, only the first gizmo on an entity with true is visible, false means that it is always visible*/)] +public class Gizmo : IEntityGizmo +{ + private bool _selected, _enabled; + private MyScript _component; + private ModelComponent _model; + private Material _material, _materialOnSelect; + + // This property is set based on whether the gizmo is globally turned on or off in the editor's view settings + public bool IsEnabled + { + get + { + return _enabled; + } + set + { + _enabled = value; + _model.Enabled = _enabled; + } + } + + // The size slider value in the view settings pane + public float SizeFactor { get; set; } + + // The editor will set this property whenever the entity the component is on is selected + public bool IsSelected + { + get + { + return _selected; + } + set + { + _selected = value; + _model.Materials[0] = _selected ? _materialOnSelect : _material; + // The logic below shows gizmos for all components when they are on in the gizmo settings, and when off, only shows the one from the selected entity + // Removing the line hides gizmos even when selected when the gizmo settings is off + _model.Enabled = _selected || _enabled; + } + } + + // This constructor is called by the editor, + // A gizmo class MUST contain a constructor with a single parameter of the component's type + public Gizmo(MyScript component) + { + _component = component; + } + + public bool HandlesComponentId(OpaqueComponentId pickedComponentId, out Entity? selection) + { + // This function is called when scene picking/mouse clicking in the scene on a gizmo + // The engine calls this function on each gizmos, gizmos in term notify the engine + // when the given component comes from them by returning true, and provide the editor with the corresponding entity this gizmo represents + if (pickedComponentId.Match(_model)) + { + selection = _component.Entity; + return true; + } + selection = null; + return false; + } + + public void Initialize(IServiceRegistry services, Scene editorScene) + { + // As part of initialization, we create a model in the editor scene to visualize the gizmo + var graphicsDevice = services.GetSafeServiceAs().GraphicsDevice; + + // In our case we'll just rely on the GeometricPrimitive API to create a sphere for us + // You don't have to create one right away, you can delay it until the component is in the appropriate state + // You can also dynamically create and update one in the Update() function further below + var sphere = GeometricPrimitive.Sphere.New(graphicsDevice); + + var vertexBuffer = sphere.VertexBuffer; + var indexBuffer = sphere.IndexBuffer; + var vertexBufferBinding = new VertexBufferBinding(vertexBuffer, new VertexPositionNormalTexture().GetLayout(), vertexBuffer.ElementCount); + var indexBufferBinding = new IndexBufferBinding(indexBuffer, sphere.IsIndex32Bits, indexBuffer.ElementCount); + + _material = Material.New(graphicsDevice, new MaterialDescriptor + { + Attributes = + { + Emissive = new MaterialEmissiveMapFeature(new ComputeColor(new Color4(0.25f,0.75f,0.25f,0.05f).ToColorSpace(graphicsDevice.ColorSpace))) { UseAlpha = true }, + Transparency = new MaterialTransparencyBlendFeature() + }, + }); + _materialOnSelect = Material.New(graphicsDevice, new MaterialDescriptor + { + Attributes = + { + Emissive = new MaterialEmissiveMapFeature(new ComputeColor(new Color4(0.25f,0.75f,0.25f,0.5f).ToColorSpace(graphicsDevice.ColorSpace))) { UseAlpha = true }, + Transparency = new MaterialTransparencyBlendFeature() + }, + }); + + _model = new ModelComponent + { + Model = new Model + { + (_selected ? _materialOnSelect : _material), + new Mesh + { + Draw = new MeshDraw + { + StartLocation = 0, + // You can swap to LineList or LineStrip to show the model in wireframe mode, you'll have to adapt your index buffer to that new type though + PrimitiveType = PrimitiveType.TriangleList, + VertexBuffers = new[] { vertexBufferBinding }, + IndexBuffer = indexBufferBinding, + DrawCount = indexBuffer.ElementCount, + } + } + }, + RenderGroup = IEntityGizmo.PickingRenderGroup, // This RenderGroup allows scene picking/selection, use a different one if you don't want selection + Enabled = _selected || _enabled + }; + + var entity = new Entity($"{nameof(Gizmo)} for {_component.Entity.Name}"){ _model }; + entity.Transform.UseTRS = false; // We're controlling the matrix directly in this case + entity.Scene = editorScene; + + vertexBuffer.DisposeBy(entity); + indexBuffer.DisposeBy(entity); // Attach buffers to the entity for manual disposal later + } + + public void Dispose() + { + _model.Entity.Scene = null; + _model.Entity.Dispose(); // Clear the two buffers we attached above + } + + public void Update() + { + // This is where you'll update how the gizmo looks based on MyScript's state + // Here we'll just ensure the gizmo follows the entity it is representing whenever that entity moves, + // note that UseTRS is disabled above to improve performance and ensure that there are no world space issues + _model.Entity.Transform.LocalMatrix = _component.Entity.Transform.WorldMatrix; + } +} +``` +And the result: + +![Green sphere gizmo](media/gizmo.png) + +Do note that you may have to restart the editor if it was open while you introduced this new gizmo. \ No newline at end of file diff --git a/en/manual/scripts/index.md b/en/manual/scripts/index.md index 3cc081fbc..96aa06820 100644 --- a/en/manual/scripts/index.md +++ b/en/manual/scripts/index.md @@ -39,4 +39,5 @@ You can still use standard C# classes in Stride, but these aren't called scripts * [Events](events.md) * [Debugging](debugging.md) * [Preprocessor variables](preprocessor-variables.md) -* [Create a model from code](create-a-model-from-code.md) \ No newline at end of file +* [Create a model from code](create-a-model-from-code.md) +* [Create Gizmos for you components](gizmos.md) \ No newline at end of file diff --git a/en/manual/scripts/media/gizmo.png b/en/manual/scripts/media/gizmo.png new file mode 100644 index 000000000..bc199a16e --- /dev/null +++ b/en/manual/scripts/media/gizmo.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0a62f0db688ba96190cb147747afcb9c43818717b62eb334f86ca6a0dceb0c86 +size 92679 diff --git a/en/manual/scripts/types-of-script.md b/en/manual/scripts/types-of-script.md index c40162fd7..1efae7183 100644 --- a/en/manual/scripts/types-of-script.md +++ b/en/manual/scripts/types-of-script.md @@ -16,10 +16,10 @@ Example: ```cs public class StartUpScriptExample : StartupScript { - public override void Start() - { - // Do some stuff during initialization - } + public override void Start() + { + // Do some stuff during initialization + } } ``` @@ -36,10 +36,10 @@ The following script performs updates every frame, no matter what: ```cs public class SampleSyncScript : SyncScript { - public override void Update() - { - // Performs the update on the entity — this code is executed every frame - } + public override void Update() + { + // Performs the update on the entity — this code is executed every frame + } } ``` @@ -48,7 +48,6 @@ public class SampleSyncScript : SyncScript Asynchronous scripts are initialized only once, then canceled when removed from the scene. * Asynchronous code goes in the [Execute](xref:Stride.Engine.AsyncScript.Execute) function. - * Code performing the cancellation goes in the [Cancel](xref:Stride.Engine.ScriptComponent.Cancel) method. The following script performs actions that depend on events and triggers: @@ -56,22 +55,38 @@ The following script performs actions that depend on events and triggers: ```cs public class SampleAsyncScript : AsyncScript { - public override async Task Execute() - { - // The initialization code should come here, if necessary - - while (Game.IsRunning) // loop until the game ends (optional depending on the script) - { - await MyEvent; - - // Do some stuff - - await Script.NextFrame(); // wait for the next frame (optional depending on the script) - } - } + public override async Task Execute() + { + // The initialization code should come here, if necessary + // This method starts running on the main thread + + while (Game.IsRunning) // loop until the game ends (optionalpendingon the script) + { + // We're still on the main thread + + // Task.Run will pause the execution of this method until the task is completed, + // while that's going on, the game will continue running, it will display new frames and process inputs appropriately + var lobbies = await Task.Run(() => GetMultiplayerLobbies()); + + // After awaiting a task, the thread the method runs on will have changed, + // this method now runs on a thread pool thread instead of the main thread + // You can manipulate the data returned by the task here if needed + // But if you want to interact with the engine safely, you have to make sure the method runs on the main thread + + // await Script.NextFrame() yields execution of this method to the main thread, + // meaning that this method is paused, and once the main thread processes the next frame, + // it will pick that method up and run it + await Script.NextFrame(); + // So after this call, this method is back on the main thread + + // You can now safely interact with the engine's systems by displaying the lobbies retrieved above in a UI for example + } + } } ``` +Check out an example from our [Async scripts tutorial](../../tutorials/csharpintermediate/async-scripts.md). + ## See also * [Create a script](create-a-script.md) @@ -80,4 +95,4 @@ public class SampleAsyncScript : AsyncScript * [Scheduling and priorities](scheduling-and-priorities.md) * [Events](events.md) * [Debugging](debugging.md) -* [Preprocessor variables](preprocessor-variables.md) \ No newline at end of file +* [Preprocessor variables](preprocessor-variables.md) diff --git a/en/manual/toc.yml b/en/manual/toc.yml index 0d9a02fb3..3b89b3431 100644 --- a/en/manual/toc.yml +++ b/en/manual/toc.yml @@ -118,6 +118,8 @@ items: href: engine/entity-component-system/usage.md - name: Manage entities href: engine/entity-component-system/managing-entities.md + - name: Flexible processing + href: engine/entity-component-system/flexible-processing.md - name: File system href: engine/file-system.md - name: Build pipeline @@ -496,6 +498,8 @@ items: href: scripts/preprocessor-variables.md - name: Create a model from code href: scripts/create-a-model-from-code.md + - name: Create Gizmos for you components + href: scripts/gizmos.md - name: Sprites href: sprites/index.md diff --git a/en/manual/troubleshooting/stride-doesnt-run.md b/en/manual/troubleshooting/stride-doesnt-run.md index dfb20a46b..3e2d6eafc 100644 --- a/en/manual/troubleshooting/stride-doesnt-run.md +++ b/en/manual/troubleshooting/stride-doesnt-run.md @@ -43,7 +43,7 @@ If you have Visual Studio 2022 (or later) installed, you need to have the follow * **.NET desktop development** with **Development tools for .NET** optional component enabled. > [!Note] -> Earlier versions might work with older version of Stride. However, for Stride 4.2 and later you need to have .NET 8 support. +> Earlier versions might work with older version of Stride. However, for Stride 4.2 and later you only need to have .NET 8 SDK installed. ### Build Tools for Visual Studio 2022 (optional) diff --git a/en/toc.yml b/en/toc.yml index 6508c1dbc..c4c808ee8 100644 --- a/en/toc.yml +++ b/en/toc.yml @@ -23,6 +23,6 @@ # - name: 🔍 Diagnostics # href: diagnostics/ # homepage: diagnostics/index.md -- name: 🏋🏽 Community resources ⭐New +- name: 🏋🏽 Community resources href: community-resources/ homepage: community-resources/index.md \ No newline at end of file diff --git a/en/tutorials/toc.yml b/en/tutorials/toc.yml index 55a98778f..9b43fd3c2 100644 --- a/en/tutorials/toc.yml +++ b/en/tutorials/toc.yml @@ -76,7 +76,7 @@ items: href: csharpintermediate/ui-basics.md - name: Collision triggers href: csharpintermediate/collision-triggers.md - - name: Racyasting + - name: Raycasting href: csharpintermediate/raycasting.md - name: Project and Unproject href: csharpintermediate/project-and-unproject.md diff --git a/jp/manual/files-and-folders/distribute-a-game.md b/jp/manual/files-and-folders/distribute-a-game.md index 738550fc7..5a55dae4a 100644 --- a/jp/manual/files-and-folders/distribute-a-game.md +++ b/jp/manual/files-and-folders/distribute-a-game.md @@ -57,7 +57,7 @@ Stride で作成されたゲームを Windows で実行するには、次のものが必要です。 -* .NET 4.6.1 +* .NET 8 SDK * DirectX11 (Windows 10 以降に含まれます)、OpenGL、または Vulkan diff --git a/jp/manual/graphics/textures/skyboxes-and-backgrounds.md b/jp/manual/graphics/textures/skyboxes-and-backgrounds.md index 2aaaec5c6..aad855ffd 100644 --- a/jp/manual/graphics/textures/skyboxes-and-backgrounds.md +++ b/jp/manual/graphics/textures/skyboxes-and-backgrounds.md @@ -124,6 +124,7 @@ Instead of using a cubemap, you can use a **360° panoramic texture** as a 3D ba | 360° パノラマ | ゲームでの見た目 |----------------|------------- | ![Panorama texture](media/MyPanorama.jpg) | ![Panorama in game](media/panorama-in-game.jpg) + *画像提供: [Texturify](http://texturify.com)*