Merge pull request #372 from stride3d/feature-bepu-physics-docs

docs: Bepu Physics addition and updates

.github/workflows/stride-docs-test-build.yml

@@ -0,0 +1,73 @@
+# Docs for the Azure Web Apps Deploy action: https://github.com/Azure/webapps-deploy
+# More GitHub Actions for Azure: https://github.com/Azure/actions
+
+name: Build Stride Docs - Test Build
+
+env:
+  COMMON_SETTINGS_PATH: en/docfx.json
+  VERSION: "2.0.0.${{ github.run_number }}"
+  DOCS_PATH: stride-docs
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: windows-2022
+
+    steps:
+    - name: .NET SDK Setup
+      uses: actions/setup-dotnet@v4
+      with:
+        dotnet-version: 8.x
+
+    # Checkout the Stride Docs repository from the branch that triggered the workflow
+    - name: Checkout Stride Docs
+      uses: actions/checkout@v4
+      with:
+        path: ${{ env.DOCS_PATH }}
+        lfs: true
+
+    - name: Set Version in docfx.json
+      run: |
+        $settingsContent = Get-Content -Path "${{ env.DOCS_PATH }}/${{ env.COMMON_SETTINGS_PATH }}" -Raw
+        $updatedDocFxJsonContent = $settingsContent -replace '2.0.0.x', "${{ env.VERSION }}"
+        Set-Content -Path "${{ env.DOCS_PATH }}/${{ env.COMMON_SETTINGS_PATH }}" -Value $updatedDocFxJsonContent
+      shell: pwsh
+
+    # - name: Display Updated docfx.json
+    #   run: cat "${{ env.DOCS_PATH }}/${{ env.COMMON_SETTINGS_PATH }}"
+    #   shell: pwsh
+
+    # - name: Fail the Workflow
+    #   run: exit 1
+    #   shell: pwsh
+
+    # Checkout the Stride repository from the default branch
+    - name: Checkout Stride (note the LFS)
+      uses: actions/checkout@v4
+      with:
+        repository: stride3d/stride
+        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.77.0
+
+    - name: Build documentation
+      run: ./build-all.bat
+      working-directory: ${{ env.DOCS_PATH }}
+
+    - name: Compress artifact
+      run: 7z a -r DocFX-app.zip ./${{ env.DOCS_PATH }}/_site/*
+
+    - name: Upload artifact for deployment job
+      uses: actions/upload-artifact@v4
+      with:
+        name: DocFX-app
+        path: DocFX-app.zip

en/docfx.json

@@ -21,7 +21,8 @@
             "sources/engine/Stride.Shaders/Stride.Shaders.csproj",
             "sources/engine/Stride.UI/Stride.UI.csproj",
             "sources/engine/Stride.VirtualReality/Stride.VirtualReality.csproj",
-            "sources/engine/Stride.Navigation/Stride.Navigation.csproj"
+            "sources/engine/Stride.Navigation/Stride.Navigation.csproj",
+            "sources/engine/Stride.BepuPhysics/Stride.BepuPhysics/Stride.BepuPhysics.csproj"
           ],
           "src": "../../stride",
           "properties": {

en/includes/bullet-physics-deprecation.md

@@ -0,0 +1,2 @@
+> [!WARNING]
+> Bullet Physics is being phased out. We no longer plan to support or expand its features as our focus shifts to [Bepu Physics](../manual/physics/index.md). We recommend transitioning to Bepu Physics for access to the latest updates and ongoing improvements.

en/manual/physics-bullet/characters.md

@@ -0,0 +1,46 @@
+# Characters
+
+<span class="badge text-bg-primary">Beginner</span>
+<span class="badge text-bg-success">Designer</span>
+
+[!INCLUDE [bullet-deprecation](../../includes/bullet-physics-deprecation.md)]
+
+**Character** colliders are used for player and script-controlled characters such as NPCs. Entities with [character components](xref:Stride.Physics.CharacterComponent) can only be moved with [SetVelocity](xref:Stride.Physics.CharacterComponent.SetVelocity\(Stride.Core.Mathematics.Vector3\)), [Jump](xref:Stride.Physics.CharacterComponent.Jump), and [Teleport](xref:Stride.Physics.CharacterComponent.Teleport\(Stride.Core.Mathematics.Vector3\)).
+
+## Add a character component to an entity
+
+1. In the **Scene Editor**, select the entity you want to add the component to.
+
+2. In the **Property Grid**, click **Add component** and select **Character**.
+
+    ![Add character component](media/add-character-component.png)
+
+>[!Note]
+> For the character collider to interact with other physics objects, you also need to set a  collider shape in the collider component properties. The capsule shape is appropriate for most character colliders. For more information, see [collider shapes](collider-shapes.md).
+
+## Component properties
+
+You can adjust the character component properties in the **Property Grid**.
+
+Property              |   Description
+----------------------|-----------------------
+Collision Group       | Sets which collision group the object belongs to.
+Can Collide With      | Sets which groups the object collides with.
+Collision Events      | If this is enabled, the object reports collision events, which you can use in scripts. It has no effect on physics. If you have no scripts using collision events for the object, disable this option to save CPU.
+Can Sleep             | If this is enabled, the physics engine doesn't process physics objects when they're not moving. This saves CPU.
+Restitution           | Sets the amount of kinetic energy lost or gained after a collision. A typical value is between 0 and 1. If the restitution property of colliding entities is 0, the entities lose all energy and stop moving immediately on impact. If the restitution is 1, they lose no energy and rebound with the same velocity they collided at. Use this to change the "bounciness" of rigidbodies.
+Friction              | Sets the surface friction.
+Rolling Friction      | Sets the rolling friction.
+CCD Motion Threshold  | Sets the velocity at which continuous collision detection (CCD) takes over. CCD prevents fast-moving entities (such as bullets) erroneously passing through other entities.
+CCD Swept Sphere Radius | Sets the radius of the bounding sphere containing the position between two physics frames during continuous collision detection. 
+Gravity               | For rigidbodies, sets a custom gravity vector applied if Override Gravity is selected. For characters, specifies how much gravity affects the character.
+Step Height           | The maximum height the character can step onto.
+Fall Speed            | The maximum fall speed.
+Max Slope             | The maximum slope the character can climb, in degrees. 
+Jump Speed            | The amount of jump force.
+
+## See also
+
+* [Static colliders](static-colliders.md)
+* [Rigidbodies](rigid-bodies.md)
+* [Collider shapes](collider-shapes.md)

en/manual/physics-bullet/collider-shapes.md

@@ -0,0 +1,145 @@
+# Collider shapes
+
+<span class="badge text-bg-primary">Beginner</span>
+<span class="badge text-bg-success">Designer</span>
+
+[!INCLUDE [bullet-deprecation](../../includes/bullet-physics-deprecation.md)]
+
+For [colliders](colliders.md) to interact, you need to set their shape in the **Property Grid**. You can specify a geometric shape, or use a collider shape asset.
+
+![Select a collider shape](media/select-collider-shape.png)
+
+Components can have multiple intersecting shapes, and don't have to match the entity model, if it has one. Each shape has additional properties including size, orientation, offset, and so on.
+
+## Types of collider shape
+
+### Box
+
+![Box](media/box.png)
+
+| Property       | Description |
+| -------------- |-------------| 
+| Is 2D | Makes the box infinitely flat in one dimension. |
+| Size    | The box size in XYZ values. |
+| Local offset     | The box position relative its entity.|
+| Local rotation      | The box rotation in XYZ values.|
+
+### Capsule
+
+![Capsule](media/capsule.png)
+
+The capsule shape is especially useful for character components, as its curved base lets the entity move to higher planes (eg when climbing staircases).
+
+| Property       | Description |
+| -------------- |-------------| 
+| Is 2D | Makes the capsule infinitely flat in one dimension.|
+| Length | The length of the capsule.|
+| Radius | The radius of the capsule.|
+| Orientation | The axis along which the shape is stretched (X, Y, or Z).|
+| Local offset     | The capsule position relative to its entity.|
+| Local rotation      | The capsule rotation in XYZ values.|
+
+### Cone
+
+![Cone](media/cone.png)
+
+| Property       | Description |
+| -------------- |-------------| 
+| Height | The height of the cone.|
+| Radius | The radius of the cone at the bottom end.|
+| Orientation | The axis along which the shape is stretched (X, Y, or Z).|
+| Local offset     | The cone position relative to its entity.|
+| Local rotation      | The cone rotation in XYZ values.|
+
+### Cylinder
+
+![Cylinder](media/cylinder.png)
+
+| Property       | Description |
+| -------------- |-------------| 
+| Height | The length of the cylinder.|
+| Radius | The radius of the cylinder.|
+| Orientation | Sets the axis along which the shape is stretched (X, Y, or Z).|
+| Local offset     | The cylinder position relative to its entity.|
+| Local rotation      | The cylinder  rotation in XYZ values.|
+
+### Sphere
+
+![Sphere](media/sphere.png)
+
+| Property       | Description |
+| -------------- |-------------| 
+| Is 2D | Makes the sphere infinitely flat in one dimension. |
+| Radius | The radius of the sphere.|
+| Local offset     | The sphere position relative to its entity.|
+
+### Infinite plane
+
+![Infinite plane](media/infinite-plane.png)
+
+The infinite plane covers an infinite distance across one dimension.
+Think of it like a wall or floor stretching into the distance for ever.
+You can use several infinite planes together to box users in and stop them "tunneling" outside the level.
+
+| Property       | Description |
+| -------------- |-------------| 
+| Normal  | Which vector (X, Y, or Z) is perpendicular to the plane. For example, to make an infinite floor, set the normal property to: _X:0, Y:1, Z:0_. |
+| Offset     | The plane position relative to its entity.|
+
+### Asset
+
+Assigns a collider shape from a collider shape asset (see **Collider shape assets** below).
+
+| Property       | Description |
+| -------------- |-------------| 
+| Shape | The collider shape asset used to generate the collider shape.|
+
+## Collider shape assets
+
+You can also create **collider shape assets** and use them as your collider shape. This means you can edit the collider shape asset and automatically update it in every entity that uses it.
+
+## Create a collider shape asset
+
+1. In the **Asset View** (bottom by default), click **Add asset**.
+
+2. Select **Physics**, then select the shape you want to create.
+
+    ![Create collider shape asset](media/create-collider-shape-asset.png)
+
+Game Studio creates the new collider shape asset in the **CollisionMeshes** folder.
+
+![Collider shape asset in Asset View](media/collider-shape-in-asset-view.png)
+
+### Create a collider shape asset from a model
+
+This is useful to quickly create a collider shape that matches a model.
+
+1. In the **Asset View** (bottom by default), click **Add asset**.
+
+2. Select **Physics** > **Convex hull**.
+
+    The **Select an asset** window opens.
+
+    ![Select model](media/select-model.png)
+
+3. Browse to the model asset you want to create a collider shape asset from and click **OK**.
+
+Game Studio creates a collider shape asset from the model.
+
+## Use a collider shape asset
+
+1. Under the **static collider** or **rigidbody** properties, under **Collider Shapes**, select **Asset**. 
+
+    ![Select collider shape asset](media/select-asset-collider-shape.png)
+
+2. Next to **Shape**, specify the collider shape asset you want to use.
+
+    ![Select collider shape asset](media/select-collider-shape-asset.png)
+
+    To do this, drag the asset from the **Asset View** to the **Shape** field in the Property Grid. Alternatively, click ![Hand icon](~/manual/game-studio/media/hand-icon.png) (**Select an asset**) and browse to the asset.
+
+## See also
+
+* [Colliders](colliders.md)
+* [Tutorial: Create a bouncing ball](create-a-bouncing-ball.md)
+* [Tutorial: Script a trigger](script-a-trigger.md)

en/manual/physics-bullet/colliders.md

@@ -0,0 +1,95 @@
+# Colliders
+
+<span class="badge text-bg-primary">Beginner</span>
+<span class="badge text-bg-success">Designer</span>
+
+[!INCLUDE [bullet-deprecation](../../includes/bullet-physics-deprecation.md)]
+
+To use physics in your project, add a **collider** component to an entity. 
+
+Colliders define the shapes and rules of physics objects. There are three types:
+
+* [static colliders](static-colliders.md) don't move (eg walls, floors, heavy objects, etc)
+* [rigidbodies](rigid-bodies.md) are moved around by forces such as collision and gravity (eg balls, barrels, etc)
+* [characters](characters.md) are controlled by user input (ie player characters)
+
+You can also: 
+
+* set the [shape of collider components](collider-shapes.md)
+* make [triggers](triggers.md), and detect when objects pass through them
+* constrict collider movement with [constraints](constraints.md)
+
+## How colliders interact
+
+Colliders interact according to the table below.
+
+|   | Kinematic objects   | Kinematic triggers   | Rigidbody colliders   | Rigidbody triggers   | Static colliders        | Static triggers   
+|---|-------------|---------------------|-------------|---------------------|----------|------------------
+| Kinematic objects        | Collisions           | Collisions  | Collisions and dynamic| Collisions   | Collisions    | Collisions     
+| Kinematic triggers | Collisions           | Collisions   |Collisions           | Collisions     | Collisions     | Collisions   
+| Rigidbody colliders          | Collisions and dynamic     | Collisions     | Collisions and dynamic     | Collisions     | Collisions and dynamic| Collisions
+| Rigidbody triggers | Collisions         | Collisions  | Collisions | Collisions     | Collisions     | Collisions
+| Static colliders| Collisions| Collisions| Collisions and dynamic | Collisions   | Nothing   | Nothing
+|Static triggers     | Collisions     | Collisions     | Collisions     | Collisions    | Nothing    | Nothing
+
+* "Collisions" refers to collision information and events only. This means the collision is detected in the code, but the objects don't bump into each other (no dynamic response).
+
+* "Dynamic" means both collision information and events, plus dynamic response (ie the colliders bump into each other instead of passing through).
+
+For example, rigidbody colliders dynamically collide with static colliders (ie bump into them). However, no objects dynamically collide with triggers; collisions are detected in the code, but objects simply pass through.
+
+## Show colliders in the Scene Editor
+
+By default, colliders are invisible in the Scene Editor. To show them:
+
+1. In the Game Studio toolbar, in the top right, click the **Display gizmo options** icon.
+
+   ![Display gizmo options](media/display-gizmo-options.png)
+
+2. Select **Physics**.
+
+    ![Display physics option](media/display-physics-option.png)
+
+The Scene Editor displays collider shapes.
+
+![Display physics](media/display-physics.png)
+
+## Show colliders at runtime
+
+You can make colliders visible at runtime, which is useful for debugging problems with physics. To do this, use:
+
+``
+this.GetSimulation().ColliderShapesRendering = true;
+``
+
+> [!Note]
+> Collider shapes for infinite planes are always invisible.
+
+### Keyboard shortcut
+
+To show or hide collider shapes at runtime with a keyboard shortcut, use the **Debug physics shapes** script.
+
+1. In the **Asset View**, click **Add asset**.
+
+2. Select **Scripts** > **Debug physics shapes**.
+
+    ![Add debug physics shape script](media/add-debug-physics-shapes-script.png)
+
+3. In the Game Studio toolbar, click **Reload assemblies and update scripts**.
+
+    ![Reload assemblies](../platforms/media/reload-assemblies.png)
+
+4. Add the **Debug physics shapes** script as a component to an entity in the scene. It doesn't matter which entity.
+
+    ![Add debug physics shapes script component](media/add-debug-physics-shapes-component.png)
+
+The script binds the collider shape visibility to **Left Shift + Left Ctrl + P**, so you can turn it on and off at runtime. You can edit the script to bind a different key combination.
+
+## See also
+
+* [Collider shapes](collider-shapes.md)
+* [Static colliders](static-colliders.md)
+* [Rigidbodies](rigid-bodies.md)
+* [Kinematic rigidbodies](kinematic-rigid-bodies.md)
+* [Simulation](simulation.md)
+* [Physics tutorials](tutorials.md)