Skip to content

Commit 4ef5405

Browse files
VaclavEliasVaclavElias
authored
Merge pull request #372 from stride3d/feature-bepu-physics-docs
docs: Bepu Physics addition and updates
2 parents ef70881 + 8a4b896 commit 4ef5405

File tree

152 files changed

+2046
-776
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

152 files changed

+2046
-776
lines changed

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

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Docs for the Azure Web Apps Deploy action: https://github.com/Azure/webapps-deploy
2+
# More GitHub Actions for Azure: https://github.com/Azure/actions
3+
4+
name: Build Stride Docs - Test Build
5+
6+
env:
7+
COMMON_SETTINGS_PATH: en/docfx.json
8+
VERSION: "2.0.0.${{ github.run_number }}"
9+
DOCS_PATH: stride-docs
10+
11+
on:
12+
workflow_dispatch:
13+
14+
jobs:
15+
build:
16+
runs-on: windows-2022
17+
18+
steps:
19+
- name: .NET SDK Setup
20+
uses: actions/setup-dotnet@v4
21+
with:
22+
dotnet-version: 8.x
23+
24+
# Checkout the Stride Docs repository from the branch that triggered the workflow
25+
- name: Checkout Stride Docs
26+
uses: actions/checkout@v4
27+
with:
28+
path: ${{ env.DOCS_PATH }}
29+
lfs: true
30+
31+
- name: Set Version in docfx.json
32+
run: |
33+
$settingsContent = Get-Content -Path "${{ env.DOCS_PATH }}/${{ env.COMMON_SETTINGS_PATH }}" -Raw
34+
$updatedDocFxJsonContent = $settingsContent -replace '2.0.0.x', "${{ env.VERSION }}"
35+
Set-Content -Path "${{ env.DOCS_PATH }}/${{ env.COMMON_SETTINGS_PATH }}" -Value $updatedDocFxJsonContent
36+
shell: pwsh
37+
38+
# - name: Display Updated docfx.json
39+
# run: cat "${{ env.DOCS_PATH }}/${{ env.COMMON_SETTINGS_PATH }}"
40+
# shell: pwsh
41+
42+
# - name: Fail the Workflow
43+
# run: exit 1
44+
# shell: pwsh
45+
46+
# Checkout the Stride repository from the default branch
47+
- name: Checkout Stride (note the LFS)
48+
uses: actions/checkout@v4
49+
with:
50+
repository: stride3d/stride
51+
token: ${{ secrets.GITHUB_TOKEN }}
52+
path: stride
53+
lfs: true
54+
ref: master
55+
56+
- name: Install DocFX
57+
# This installs the latest version of DocFX and may introduce breaking changes
58+
# run: dotnet tool update -g docfx
59+
# This installs a specific, tested version of DocFX.
60+
run: dotnet tool update -g docfx --version 2.77.0
61+
62+
- name: Build documentation
63+
run: ./build-all.bat
64+
working-directory: ${{ env.DOCS_PATH }}
65+
66+
- name: Compress artifact
67+
run: 7z a -r DocFX-app.zip ./${{ env.DOCS_PATH }}/_site/*
68+
69+
- name: Upload artifact for deployment job
70+
uses: actions/upload-artifact@v4
71+
with:
72+
name: DocFX-app
73+
path: DocFX-app.zip

‎en/docfx.json

+2-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,8 @@
2121
"sources/engine/Stride.Shaders/Stride.Shaders.csproj",
2222
"sources/engine/Stride.UI/Stride.UI.csproj",
2323
"sources/engine/Stride.VirtualReality/Stride.VirtualReality.csproj",
24-
"sources/engine/Stride.Navigation/Stride.Navigation.csproj"
24+
"sources/engine/Stride.Navigation/Stride.Navigation.csproj",
25+
"sources/engine/Stride.BepuPhysics/Stride.BepuPhysics/Stride.BepuPhysics.csproj"
2526
],
2627
"src": "../../stride",
2728
"properties": {

‎en/includes/bullet-physics-deprecation.md

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
> [!WARNING]
2+
> 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

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Characters
2+
3+
<span class="badge text-bg-primary">Beginner</span>
4+
<span class="badge text-bg-success">Designer</span>
5+
6+
[!INCLUDE [bullet-deprecation](../../includes/bullet-physics-deprecation.md)]
7+
8+
**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\)).
9+
10+
## Add a character component to an entity
11+
12+
1. In the **Scene Editor**, select the entity you want to add the component to.
13+
14+
2. In the **Property Grid**, click **Add component** and select **Character**.
15+
16+
![Add character component](media/add-character-component.png)
17+
18+
>[!Note]
19+
> 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).
20+
21+
## Component properties
22+
23+
You can adjust the character component properties in the **Property Grid**.
24+
25+
Property | Description
26+
----------------------|-----------------------
27+
Collision Group | Sets which collision group the object belongs to.
28+
Can Collide With | Sets which groups the object collides with.
29+
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.
30+
Can Sleep | If this is enabled, the physics engine doesn't process physics objects when they're not moving. This saves CPU.
31+
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.
32+
Friction | Sets the surface friction.
33+
Rolling Friction | Sets the rolling friction.
34+
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.
35+
CCD Swept Sphere Radius | Sets the radius of the bounding sphere containing the position between two physics frames during continuous collision detection.
36+
Gravity | For rigidbodies, sets a custom gravity vector applied if Override Gravity is selected. For characters, specifies how much gravity affects the character.
37+
Step Height | The maximum height the character can step onto.
38+
Fall Speed | The maximum fall speed.
39+
Max Slope | The maximum slope the character can climb, in degrees.
40+
Jump Speed | The amount of jump force.
41+
42+
## See also
43+
44+
* [Static colliders](static-colliders.md)
45+
* [Rigidbodies](rigid-bodies.md)
46+
* [Collider shapes](collider-shapes.md)

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

+145
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Collider shapes
2+
3+
<span class="badge text-bg-primary">Beginner</span>
4+
<span class="badge text-bg-success">Designer</span>
5+
6+
[!INCLUDE [bullet-deprecation](../../includes/bullet-physics-deprecation.md)]
7+
8+
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.
9+
10+
![Select a collider shape](media/select-collider-shape.png)
11+
12+
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.
13+
14+
## Types of collider shape
15+
16+
### Box
17+
18+
![Box](media/box.png)
19+
20+
| Property | Description |
21+
| -------------- |-------------|
22+
| Is 2D | Makes the box infinitely flat in one dimension. |
23+
| Size | The box size in XYZ values. |
24+
| Local offset | The box position relative its entity.|
25+
| Local rotation | The box rotation in XYZ values.|
26+
27+
### Capsule
28+
29+
![Capsule](media/capsule.png)
30+
31+
The capsule shape is especially useful for character components, as its curved base lets the entity move to higher planes (eg when climbing staircases).
32+
33+
| Property | Description |
34+
| -------------- |-------------|
35+
| Is 2D | Makes the capsule infinitely flat in one dimension.|
36+
| Length | The length of the capsule.|
37+
| Radius | The radius of the capsule.|
38+
| Orientation | The axis along which the shape is stretched (X, Y, or Z).|
39+
| Local offset | The capsule position relative to its entity.|
40+
| Local rotation | The capsule rotation in XYZ values.|
41+
42+
### Cone
43+
44+
![Cone](media/cone.png)
45+
46+
| Property | Description |
47+
| -------------- |-------------|
48+
| Height | The height of the cone.|
49+
| Radius | The radius of the cone at the bottom end.|
50+
| Orientation | The axis along which the shape is stretched (X, Y, or Z).|
51+
| Local offset | The cone position relative to its entity.|
52+
| Local rotation | The cone rotation in XYZ values.|
53+
54+
### Cylinder
55+
56+
![Cylinder](media/cylinder.png)
57+
58+
| Property | Description |
59+
| -------------- |-------------|
60+
| Height | The length of the cylinder.|
61+
| Radius | The radius of the cylinder.|
62+
| Orientation | Sets the axis along which the shape is stretched (X, Y, or Z).|
63+
| Local offset | The cylinder position relative to its entity.|
64+
| Local rotation | The cylinder rotation in XYZ values.|
65+
66+
### Sphere
67+
68+
![Sphere](media/sphere.png)
69+
70+
| Property | Description |
71+
| -------------- |-------------|
72+
| Is 2D | Makes the sphere infinitely flat in one dimension. |
73+
| Radius | The radius of the sphere.|
74+
| Local offset | The sphere position relative to its entity.|
75+
76+
### Infinite plane
77+
78+
![Infinite plane](media/infinite-plane.png)
79+
80+
The infinite plane covers an infinite distance across one dimension.
81+
Think of it like a wall or floor stretching into the distance for ever.
82+
You can use several infinite planes together to box users in and stop them "tunneling" outside the level.
83+
84+
| Property | Description |
85+
| -------------- |-------------|
86+
| 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_. |
87+
| Offset | The plane position relative to its entity.|
88+
89+
### Asset
90+
91+
Assigns a collider shape from a collider shape asset (see **Collider shape assets** below).
92+
93+
| Property | Description |
94+
| -------------- |-------------|
95+
| Shape | The collider shape asset used to generate the collider shape.|
96+
97+
## Collider shape assets
98+
99+
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.
100+
101+
## Create a collider shape asset
102+
103+
1. In the **Asset View** (bottom by default), click **Add asset**.
104+
105+
2. Select **Physics**, then select the shape you want to create.
106+
107+
![Create collider shape asset](media/create-collider-shape-asset.png)
108+
109+
Game Studio creates the new collider shape asset in the **CollisionMeshes** folder.
110+
111+
![Collider shape asset in Asset View](media/collider-shape-in-asset-view.png)
112+
113+
### Create a collider shape asset from a model
114+
115+
This is useful to quickly create a collider shape that matches a model.
116+
117+
1. In the **Asset View** (bottom by default), click **Add asset**.
118+
119+
2. Select **Physics** > **Convex hull**.
120+
121+
The **Select an asset** window opens.
122+
123+
![Select model](media/select-model.png)
124+
125+
3. Browse to the model asset you want to create a collider shape asset from and click **OK**.
126+
127+
Game Studio creates a collider shape asset from the model.
128+
129+
## Use a collider shape asset
130+
131+
1. Under the **static collider** or **rigidbody** properties, under **Collider Shapes**, select **Asset**.
132+
133+
![Select collider shape asset](media/select-asset-collider-shape.png)
134+
135+
2. Next to **Shape**, specify the collider shape asset you want to use.
136+
137+
![Select collider shape asset](media/select-collider-shape-asset.png)
138+
139+
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.
140+
141+
## See also
142+
143+
* [Colliders](colliders.md)
144+
* [Tutorial: Create a bouncing ball](create-a-bouncing-ball.md)
145+
* [Tutorial: Script a trigger](script-a-trigger.md)

‎en/manual/physics-bullet/colliders.md

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Colliders
2+
3+
<span class="badge text-bg-primary">Beginner</span>
4+
<span class="badge text-bg-success">Designer</span>
5+
6+
[!INCLUDE [bullet-deprecation](../../includes/bullet-physics-deprecation.md)]
7+
8+
To use physics in your project, add a **collider** component to an entity.
9+
10+
Colliders define the shapes and rules of physics objects. There are three types:
11+
12+
* [static colliders](static-colliders.md) don't move (eg walls, floors, heavy objects, etc)
13+
* [rigidbodies](rigid-bodies.md) are moved around by forces such as collision and gravity (eg balls, barrels, etc)
14+
* [characters](characters.md) are controlled by user input (ie player characters)
15+
16+
You can also:
17+
18+
* set the [shape of collider components](collider-shapes.md)
19+
* make [triggers](triggers.md), and detect when objects pass through them
20+
* constrict collider movement with [constraints](constraints.md)
21+
22+
## How colliders interact
23+
24+
Colliders interact according to the table below.
25+
26+
| | Kinematic objects | Kinematic triggers | Rigidbody colliders | Rigidbody triggers | Static colliders | Static triggers
27+
|---|-------------|---------------------|-------------|---------------------|----------|------------------
28+
| Kinematic objects | Collisions | Collisions | Collisions and dynamic| Collisions | Collisions | Collisions
29+
| Kinematic triggers | Collisions | Collisions |Collisions | Collisions | Collisions | Collisions
30+
| Rigidbody colliders | Collisions and dynamic | Collisions | Collisions and dynamic | Collisions | Collisions and dynamic| Collisions
31+
| Rigidbody triggers | Collisions | Collisions | Collisions | Collisions | Collisions | Collisions
32+
| Static colliders| Collisions| Collisions| Collisions and dynamic | Collisions | Nothing | Nothing
33+
|Static triggers | Collisions | Collisions | Collisions | Collisions | Nothing | Nothing
34+
35+
* "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).
36+
37+
* "Dynamic" means both collision information and events, plus dynamic response (ie the colliders bump into each other instead of passing through).
38+
39+
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.
40+
41+
## Show colliders in the Scene Editor
42+
43+
By default, colliders are invisible in the Scene Editor. To show them:
44+
45+
1. In the Game Studio toolbar, in the top right, click the **Display gizmo options** icon.
46+
47+
![Display gizmo options](media/display-gizmo-options.png)
48+
49+
2. Select **Physics**.
50+
51+
![Display physics option](media/display-physics-option.png)
52+
53+
The Scene Editor displays collider shapes.
54+
55+
![Display physics](media/display-physics.png)
56+
57+
## Show colliders at runtime
58+
59+
You can make colliders visible at runtime, which is useful for debugging problems with physics. To do this, use:
60+
61+
``
62+
this.GetSimulation().ColliderShapesRendering = true;
63+
``
64+
65+
> [!Note]
66+
> Collider shapes for infinite planes are always invisible.
67+
68+
### Keyboard shortcut
69+
70+
To show or hide collider shapes at runtime with a keyboard shortcut, use the **Debug physics shapes** script.
71+
72+
1. In the **Asset View**, click **Add asset**.
73+
74+
2. Select **Scripts** > **Debug physics shapes**.
75+
76+
![Add debug physics shape script](media/add-debug-physics-shapes-script.png)
77+
78+
3. In the Game Studio toolbar, click **Reload assemblies and update scripts**.
79+
80+
![Reload assemblies](../platforms/media/reload-assemblies.png)
81+
82+
4. Add the **Debug physics shapes** script as a component to an entity in the scene. It doesn't matter which entity.
83+
84+
![Add debug physics shapes script component](media/add-debug-physics-shapes-component.png)
85+
86+
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.
87+
88+
## See also
89+
90+
* [Collider shapes](collider-shapes.md)
91+
* [Static colliders](static-colliders.md)
92+
* [Rigidbodies](rigid-bodies.md)
93+
* [Kinematic rigidbodies](kinematic-rigid-bodies.md)
94+
* [Simulation](simulation.md)
95+
* [Physics tutorials](tutorials.md)

0 commit comments

Comments
 (0)