Upgrade to Stride 4.4.0 and streamline build workflows

.github/copilot-instructions.md

@@ -58,6 +58,17 @@ These repository instructions guide GitHub Copilot (and similar AI assistants) t
 - Physics: Prefer Bepu components; keep Bullet only for transition/testing. Avoid mixing both on the same entity.
 - Core components commonly manipulated: Transform (position, rotation, scale), Camera, Rigidbody, Script logic.
 
+### Bepu transform ownership (frequent source of confusion)
+
+- The transform sync is **one-way: physics → `TransformComponent`**. Assigning `Entity.Transform.Position` on an entity that has an attached body moves the mesh only; the body stays where the simulation put it.
+- To move a body deliberately: `Teleport(...)` jumps it without checking collisions, while scripted motion that should collide belongs on a body with `Kinematic = true`.
+- Prefer setting `LinearVelocity` on a kinematic body over calling `SetTargetPose(...)` from a per-frame `Update`. `SetTargetPose` derives its velocity from `(target - position) / FixedTimeStep`, which assumes exactly one physics tick per call. When the frame rate falls below the physics rate two ticks run on that velocity, the body overshoots the target, the next correction overshoots further, and it diverges to `NaN` within seconds. `SetTargetPose` is safe when the caller runs once per physics tick (`ISimulationUpdate.SimulationUpdate`) or when the frame rate is pinned to the physics rate; otherwise integrate a velocity you compute yourself, and add a small proportional pull towards the ideal position to stop drift.
+- Setting `LinearVelocity` does **not** wake a sleeping body — set `Awake = true` as well, or the motion silently stops once the body sleeps.
+- `ISimulationUpdate.SimulationUpdate` can run **before** `StartupScript.Start` / `SyncScript.Start`. The component is registered with the simulation as soon as it enters the scene, while `Start` waits its turn in the script system. Resolve component references lazily inside `SimulationUpdate` (`_body ??= Entity.Get<BodyComponent>()`) rather than caching them in `Start`.
+- Only **awake** bodies are synced back to their transform. A dynamic body that settles and falls asleep stops overwriting the transform, so direct transform writes suddenly appear to work while the collider is left behind. A "moving mesh with no collisions" almost always means this.
+- `Bepu3DPhysicsOptions.IncludeCollider = false` still attaches a `BodyComponent`, but a `CompoundCollider` with no shapes never attaches to the simulation, leaving an inert component. For a purely visual entity use the non-physics `Create3DPrimitive` overload by passing `Primitive3DEntityOptions` instead.
+- `Create3DPrimitive` has both a Bepu overload (`Bepu3DPhysicsOptions`) and a plain one (`Primitive3DEntityOptions`). Passing an explicitly typed options object selects the intended overload and avoids `CS0121` ambiguity when both namespaces are imported.
+
 ## Toolkit patterns
 ### Extension method pattern
 
@@ -158,6 +169,67 @@ game.Run(start: (Scene rootScene) =>
 });
 ```
 
+## Running & debugging examples (AI assistants)
+
+Code-only examples are GUI applications that run until the window is closed, so a plain `dotnet run` cannot be waited on and read back. Use this loop instead: build, launch the built executable with redirected output, wait, terminate, then read the captured log. Verify engine behaviour this way rather than reasoning about it — assumptions about Stride internals are frequently wrong.
+
+### Run an example and capture its console output
+
+```powershell
+$out = "$env:TEMP\example-run.txt"
+dotnet build examples\code-only\Example02_GiveMeACube\Example02_GiveMeACube.csproj -v q --nologo
+$exe = "examples\code-only\Example02_GiveMeACube\bin\Debug\net10.0\Example02_GiveMeACube.exe"
+$process = Start-Process $exe -PassThru -RedirectStandardOutput $out -WorkingDirectory (Split-Path $exe)
+Start-Sleep -Seconds 12
+if (-not $process.HasExited) { Stop-Process -Id $process.Id -Force }
+Get-Content $out | Select-String "DIAG"
+```
+
+### Where temporary diagnostics actually surface
+
+- **Top-level statements and the `game.Run(start:/update:)` callbacks**: `Console.WriteLine` reaches the redirected stream.
+- **Inside a `SyncScript` / `AsyncScript` / `StartupScript`**: `Console.WriteLine` does *not* reach it. Use the script's own logger (`Log.Info`, `Log.Warning`).
+- **Inside a render feature or game system**: use `GlobalLogger.GetLogger("Name")`.
+- Stride writes log lines to both the console and the redirected stream, so captured output shows each line twice. Expect the duplicates or pipe through `Select-Object -Unique`.
+
+### Making per-frame diagnostics readable
+
+Gate on a frame counter to keep the log short, but always include the first few frames:
+
+```csharp
+_frames++;
+if (_frames > 3 && _frames % 120 != 0) return;
+
+Log.Warning($"DIAG position={Entity.Transform.Position}");
+```
+
+Gating on `% N` alone can produce no output at all when the run is short or the frame rate is low, which is easily misread as "the code never ran". Prefix diagnostic lines with a unique token such as `DIAG` so they can be filtered out of Stride's own logging.
+
+### Screenshots
+
+Useful for confirming a visual change, and the resulting PNG can be read back directly.
+
+```powershell
+Add-Type -AssemblyName System.Windows.Forms, System.Drawing
+$bitmap = New-Object System.Drawing.Bitmap 1200, 900
+$graphics = [System.Drawing.Graphics]::FromImage($bitmap)
+$graphics.CopyFromScreen(0, 0, 0, 0, $bitmap.Size)
+$bitmap.Save("$env:TEMP\shot.png", [System.Drawing.Imaging.ImageFormat]::Png)
+$graphics.Dispose(); $bitmap.Dispose()
+```
+
+- Prefer positioning the window from the example itself (`game.Window.Position`, `game.Window.AllowUserResizing`) over forcing it with a `SetWindowPos` P/Invoke. Forcing a resize leaves Stride's `Window.ClientBounds` out of sync with the captured region, which can make correctly rendered UI look as though it is missing.
+- Capture two screenshots a few seconds apart to confirm that animation or physics is actually progressing.
+
+### Build warnings are a debugging tool
+
+- Real defects hide in the warning list. A Stride 4.4 regression that silently broke the ImGui.NET integration was found only through a single `warning CS9193` among 66 warnings.
+- Filter with `Select-String ": error|warning CS"`. Filtering by project path also matches unrelated `NU1903` NuGet advisories.
+
+### Always clean up
+
+- Remove every temporary diagnostic, then confirm with `git status` before reporting the work as complete.
+
 ## AI assistance guidance
 
 - Inspect the existing implementation before proposing changes; do not invent APIs or patterns that are not present in the repository.

.github/workflows/bump-stride-nuget-packages.yml

@@ -9,10 +9,10 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Setup .NET
-        uses: actions/setup-dotnet@v5
+        uses: actions/setup-dotnet@v6
         with:
           dotnet-version: '10.0.x'
 
@@ -51,4 +51,4 @@ jobs:
 
             Auto-generated by the Update NuGet Packages workflow.
           branch: package-updates
-          base: main
+          base: main

.github/workflows/dotnet-build-test.yml

@@ -19,10 +19,10 @@ jobs:
 
     steps:
     - name: Checkout Stride Community Toolkit
-      uses: actions/checkout@v6
+      uses: actions/checkout@v7
 
     - name: .NET Setup
-      uses: actions/setup-dotnet@v5
+      uses: actions/setup-dotnet@v6
       with:
         dotnet-version: 10.0.x
 
@@ -34,4 +34,4 @@ jobs:
           dotnet restore "$project"
           dotnet build "$project" --no-restore
         done
-      shell: bash
+      shell: bash

.github/workflows/dotnet-nuget.yml

@@ -4,14 +4,18 @@ permissions:
   contents: write  # required to create releases/tags
 
 env:
-  PROJECT_PATH_CORE: src/Stride.CommunityToolkit/Stride.CommunityToolkit.csproj
-  PROJECT_PATH_BEPU: src/Stride.CommunityToolkit.Bepu/Stride.CommunityToolkit.Bepu.csproj
-  PROJECT_PATH_BULLET: src/Stride.CommunityToolkit.Bullet/Stride.CommunityToolkit.Bullet.csproj
-  PROJECT_PATH_DEBUG: src/Stride.CommunityToolkit.DebugShapes/Stride.CommunityToolkit.DebugShapes.csproj
-  PROJECT_PATH_IMGUI: src/Stride.CommunityToolkit.ImGui/Stride.CommunityToolkit.ImGui.csproj
-  PROJECT_PATH_SKYBOX: src/Stride.CommunityToolkit.Skyboxes/Stride.CommunityToolkit.Skyboxes.csproj
-  PROJECT_PATH_WINDOWS: src/Stride.CommunityToolkit.Windows/Stride.CommunityToolkit.Windows.csproj
-  PROJECT_PATH_LINUX: src/Stride.CommunityToolkit.Linux/Stride.CommunityToolkit.Linux.csproj
+  # One entry per package, in publish order. Optional "|extra-restore-args" suffix
+  # is appended to the `dotnet restore` call for that project only.
+  PACK_PROJECTS: |
+    src/Stride.CommunityToolkit/Stride.CommunityToolkit.csproj
+    src/Stride.CommunityToolkit.Windows/Stride.CommunityToolkit.Windows.csproj|--runtime win-x64
+    src/Stride.CommunityToolkit.Linux/Stride.CommunityToolkit.Linux.csproj
+    src/Stride.CommunityToolkit.Skyboxes/Stride.CommunityToolkit.Skyboxes.csproj
+    src/Stride.CommunityToolkit.Bepu/Stride.CommunityToolkit.Bepu.csproj
+    src/Stride.CommunityToolkit.Bullet/Stride.CommunityToolkit.Bullet.csproj
+    src/Stride.CommunityToolkit.DebugShapes/Stride.CommunityToolkit.DebugShapes.csproj
+    src/Stride.CommunityToolkit.ImGui/Stride.CommunityToolkit.ImGui.csproj
+  TEST_PROJECT: tests/Stride.CommunityToolkit.Tests/Stride.CommunityToolkit.Tests.csproj
   COMMON_SETTINGS_PATH: src/CommonSettings.props
   VERSION: "1.0.0.0-preview.${{ github.run_number }}"
   NUGET_SOURCE: "https://api.nuget.org/v3/index.json"
@@ -26,10 +30,10 @@ jobs:
 
     steps:
     - name: Checkout Stride Community Toolkit
-      uses: actions/checkout@v6
+      uses: actions/checkout@v7
 
     - name: .NET Setup
-      uses: actions/setup-dotnet@v5
+      uses: actions/setup-dotnet@v6
       with:
         dotnet-version: 10.0.x
 
@@ -44,134 +48,45 @@ jobs:
     #   run: New-Item -ItemType Directory -Force -Path D:\.sarif
     #   shell: pwsh
 
-    # Stride.CommunityToolkit
-    - name: Restore dependencies - Stride.CommunityToolkit
-      run: dotnet restore ${{ env.PROJECT_PATH_CORE }}
+    # Run the tests before anything is packed, so a failure costs nothing
+    - name: Test
+      run: dotnet test ${{ env.TEST_PROJECT }} -c Release --verbosity normal
 
-    - name: Build - Stride.CommunityToolkit
-      run: dotnet build ${{ env.PROJECT_PATH_CORE }} --no-restore -c Release
-
-    - name: Test - Stride.CommunityToolkit
-      run: dotnet test ${{ env.PROJECT_PATH_CORE }} --no-build --verbosity normal
-
-    - name: Pack - Stride.CommunityToolkit
-      run: dotnet pack ${{ env.PROJECT_PATH_CORE }} --no-build -c Release -o "${{ env.NUPKG_ROOT }}\core"
-
-    - name: Publish - Stride.CommunityToolkit
-      run: dotnet nuget push "${{ env.NUPKG_ROOT }}\core\*.nupkg" --source "${{ env.NUGET_SOURCE }}" --api-key "${{ secrets.NUGET_API_KEY }}" --skip-duplicate
-
-    # Stride.CommunityToolkit.Windows
-    - name: Restore dependencies - Stride.CommunityToolkit.Windows
-      run: dotnet restore ${{ env.PROJECT_PATH_WINDOWS }} --runtime win-x64
-
-    - name: Build - Stride.CommunityToolkit.Windows
-      run: dotnet build ${{ env.PROJECT_PATH_WINDOWS }} --no-restore -c Release
-
-    - name: Test - Stride.CommunityToolkit.Windows
-      run: dotnet test ${{ env.PROJECT_PATH_WINDOWS }} --no-build --verbosity normal
-
-    - name: Pack - Stride.CommunityToolkit.Windows
-      run: dotnet pack ${{ env.PROJECT_PATH_WINDOWS }} --no-build -c Release -o "${{ env.NUPKG_ROOT }}\windows"
-
-    - name: Publish - Stride.CommunityToolkit.Windows
-      run: dotnet nuget push "${{ env.NUPKG_ROOT }}\windows\*.nupkg" --source "${{ env.NUGET_SOURCE }}" --api-key "${{ secrets.NUGET_API_KEY }}" --skip-duplicate
-
-    # Stride.CommunityToolkit.Linux
-    - name: Restore dependencies - Stride.CommunityToolkit.Linux
-      run: dotnet restore ${{ env.PROJECT_PATH_LINUX }}
-
-    - name: Build - Stride.CommunityToolkit.Linux
-      run: dotnet build ${{ env.PROJECT_PATH_LINUX }} --no-restore -c Release
-
-    - name: Pack - Stride.CommunityToolkit.Linux
-      run: dotnet pack ${{ env.PROJECT_PATH_LINUX }} --no-build -c Release -o "${{ env.NUPKG_ROOT }}\linux"
-
-    - name: Publish - Stride.CommunityToolkit.Linux
-      run: dotnet nuget push "${{ env.NUPKG_ROOT }}\linux\*.nupkg" --source "${{ env.NUGET_SOURCE }}" --api-key "${{ secrets.NUGET_API_KEY }}" --skip-duplicate
-
-    # Stride.CommunityToolkit.Skyboxes
-    - name: Restore dependencies - Stride.CommunityToolkit.Skyboxes
-      run: dotnet restore ${{ env.PROJECT_PATH_SKYBOX }}
-
-    - name: Build - Stride.CommunityToolkit.Skyboxes
-      run: dotnet build ${{ env.PROJECT_PATH_SKYBOX }} --no-restore -c Release
-
-    - name: Test - Stride.CommunityToolkit.Skyboxes
-      run: dotnet test ${{ env.PROJECT_PATH_SKYBOX }} --no-build --verbosity normal
-
-    - name: Pack - Stride.CommunityToolkit.Skyboxes
-      run: dotnet pack ${{ env.PROJECT_PATH_SKYBOX }} --no-build -c Release -o "${{ env.NUPKG_ROOT }}\skyboxes"
-
-    - name: Publish - Stride.CommunityToolkit.Skyboxes
-      run: dotnet nuget push "${{ env.NUPKG_ROOT }}\skyboxes\*.nupkg" --source "${{ env.NUGET_SOURCE }}" --api-key "${{ secrets.NUGET_API_KEY }}" --skip-duplicate
-
-    # Stride.CommunityToolkit.Bepu
-    - name: Restore dependencies - Stride.CommunityToolkit.Bepu
-      run: dotnet restore ${{ env.PROJECT_PATH_BEPU }}
-
-    - name: Build - Stride.CommunityToolkit.Bepu
-      run: dotnet build ${{ env.PROJECT_PATH_BEPU }} --no-restore -c Release
-
-    - name: Test - Stride.CommunityToolkit.Bepu
-      run: dotnet test ${{ env.PROJECT_PATH_BEPU }} --no-build --verbosity normal
-
-    - name: Pack - Stride.CommunityToolkit.Bepu
-      run: dotnet pack ${{ env.PROJECT_PATH_BEPU }} --no-build -c Release -o "${{ env.NUPKG_ROOT }}\bepu"
-
-    - name: Publish - Stride.CommunityToolkit.Bepu
-      run: dotnet nuget push "${{ env.NUPKG_ROOT }}\bepu\*.nupkg" --source "${{ env.NUGET_SOURCE }}" --api-key "${{ secrets.NUGET_API_KEY }}" --skip-duplicate
-
-    # Stride.CommunityToolkit.Bullet
-    - name: Restore dependencies - Stride.CommunityToolkit.Bullet
-      run: dotnet restore ${{ env.PROJECT_PATH_BULLET }}
-
-    - name: Build - Stride.CommunityToolkit.Bullet
-      run: dotnet build ${{ env.PROJECT_PATH_BULLET }} --no-restore -c Release
-
-    - name: Test - Stride.CommunityToolkit.Bullet
-      run: dotnet test ${{ env.PROJECT_PATH_BULLET }} --no-build --verbosity normal
-
-    - name: Pack - Stride.CommunityToolkit.Bullet
-      run: dotnet pack ${{ env.PROJECT_PATH_BULLET }} --no-build -c Release -o "${{ env.NUPKG_ROOT }}\bullet"
-
-    - name: Publish - Stride.CommunityToolkit.Bullet
-      run: dotnet nuget push "${{ env.NUPKG_ROOT }}\bullet\*.nupkg" --source "${{ env.NUGET_SOURCE }}" --api-key "${{ secrets.NUGET_API_KEY }}" --skip-duplicate
-
-    # Stride.CommunityToolkit.DebugShapes
-    - name: Restore dependencies - Stride.CommunityToolkit.DebugShapes
-      run: dotnet restore ${{ env.PROJECT_PATH_DEBUG }}
-
-    - name: Build - Stride.CommunityToolkit.DebugShapes
-      run: dotnet build ${{ env.PROJECT_PATH_DEBUG }} --no-restore -c Release
-
-    - name: Test - Stride.CommunityToolkit.DebugShapes
-      run: dotnet test ${{ env.PROJECT_PATH_DEBUG }} --no-build --verbosity normal
-
-    - name: Pack - Stride.CommunityToolkit.DebugShapes
-      run: dotnet pack ${{ env.PROJECT_PATH_DEBUG }} --no-build -c Release -o "${{ env.NUPKG_ROOT }}\debug"
-
-    - name: Publish - Stride.CommunityToolkit.DebugShapes
-      run: dotnet nuget push "${{ env.NUPKG_ROOT }}\debug\*.nupkg" --source "${{ env.NUGET_SOURCE }}" --api-key "${{ secrets.NUGET_API_KEY }}" --skip-duplicate
-
-    # Stride.CommunityToolkit.ImGui
-    - name: Restore dependencies - Stride.CommunityToolkit.ImGui
-      run: dotnet restore ${{ env.PROJECT_PATH_IMGUI }}
-
-    - name: Build - Stride.CommunityToolkit.ImGui
-      run: dotnet build ${{ env.PROJECT_PATH_IMGUI }} --no-restore -c Release
-
-    - name: Test - Stride.CommunityToolkit.ImGui
-      run: dotnet test ${{ env.PROJECT_PATH_IMGUI }} --no-build --verbosity normal
-
-    - name: Pack - Stride.CommunityToolkit.ImGui
-      run: dotnet pack ${{ env.PROJECT_PATH_IMGUI }} --no-build -c Release -o "${{ env.NUPKG_ROOT }}\imgui"
-
-    - name: Publish - Stride.CommunityToolkit.ImGui
-      run: dotnet nuget push "${{ env.NUPKG_ROOT }}\imgui\*.nupkg" --source "${{ env.NUGET_SOURCE }}" --api-key "${{ secrets.NUGET_API_KEY }}" --skip-duplicate
+    # Everything is packed first and pushed afterwards: a build failure half-way
+    # through must not leave a partially published version on nuget.org
+    - name: Build and pack all packages
+      shell: bash
+      run: |
+        set -eo pipefail
+        while IFS= read -r entry; do
+          entry="${entry//$'\r'/}"
+          if [ -z "$entry" ]; then
+            continue
+          fi
+
+          project="${entry%%|*}"
+          restore_args=""
+          if [ "$entry" != "$project" ]; then
+            restore_args="${entry#*|}"
+          fi
+
+          echo "::group::$project"
+          dotnet restore "$project" $restore_args
+          dotnet build "$project" --no-restore -c Release
+          dotnet pack "$project" --no-build -c Release -o "$NUPKG_ROOT"
+          echo "::endgroup::"
+        done <<< "$PACK_PROJECTS"
+
+    - name: List packages
+      shell: bash
+      run: ls -l "$NUPKG_ROOT"
+
+    - name: Publish all packages
+      run: dotnet nuget push "${{ env.NUPKG_ROOT }}\*.nupkg" --source "${{ env.NUGET_SOURCE }}" --api-key "${{ secrets.NUGET_API_KEY }}" --skip-duplicate
 
     # Create release
     - name: Create GitHub Release
       run: |
         gh release create ${{ env.VERSION }} --title "v${{ env.VERSION }}" --notes "Release notes for ${{ env.VERSION }}" --draft
       env:
-        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/github-pages.yml

@@ -29,10 +29,10 @@ jobs:
     #  run: dotnet --info
 
     - name: Checkout Stride Community Toolkit
-      uses: actions/checkout@v6
+      uses: actions/checkout@v7
 
     - name: Setup .NET
-      uses: actions/setup-dotnet@v5
+      uses: actions/setup-dotnet@v6
       with:
         dotnet-version: 10.x
 
@@ -49,7 +49,7 @@ jobs:
       run: docfx docfx.json
 
     - name: Upload Pages artifact
-      uses: actions/upload-pages-artifact@v4
+      uses: actions/upload-pages-artifact@v5
       with:
         path: docs/_site
 

CLAUDE.md

@@ -0,0 +1,5 @@
+# Stride Community Toolkit
+
+Repository guidance for AI assistants lives in [.github/copilot-instructions.md](.github/copilot-instructions.md).
+Read it before making changes — it covers project structure, coding conventions, Stride and Bepu
+specifics, and how to run and debug the code-only examples.

Directory.Build.props

@@ -1,4 +1,16 @@
 <Project>
+  <!--
+    Auto-imported by MSBuild into every project in this repository.
+    Shared settings live here so a Stride upgrade is a one-line change.
+    Projects may override any of these locally (e.g. Stride.CommunityToolkit.Linux pins its own StrideVersion).
+  -->
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <StrideVersion>4.4.0-dev</StrideVersion>
+  </PropertyGroup>
+
   <PropertyGroup Condition="'$(SolutionDir)' != ''">
     <ErrorLog>$(SolutionDir)\.sarif\$(MSBuildProjectName).json</ErrorLog>
   </PropertyGroup>