Skip to content

Commit 1115e2a

Browse files
Mugen87walcht
Mugen87
and
walcht
authored
Manual: Add Physics page. (#33004)
Co-authored-by: Walid Chtioui <89390465+walcht@users.noreply.github.com>
1 parent 6054daa commit 1115e2a

File tree

2 files changed

+179
-1
lines changed

2 files changed

+179
-1
lines changed

‎manual/en/physics.html‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
4+
<head>
5+
<meta charset="utf-8">
6+
<title>Physics</title>
7+
<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
8+
<meta name="twitter:card" content="summary_large_image">
9+
<meta name="twitter:site" content="@threejs">
10+
<meta name="twitter:title" content="Three.js – Physics">
11+
<meta property="og:image" content="https://threejs.org/files/share.png">
12+
<link rel="shortcut icon" href="../../files/favicon_white.ico" media="(prefers-color-scheme: dark)">
13+
<link rel="shortcut icon" href="../../files/favicon.ico" media="(prefers-color-scheme: light)">
14+
15+
<link rel="stylesheet" href="../resources/lesson.css">
16+
<link rel="stylesheet" href="../resources/lang.css">
17+
<script type="importmap">
18+
{
19+
"imports": {
20+
"three": "../../build/three.module.js"
21+
}
22+
}
23+
</script>
24+
</head>
25+
26+
<body>
27+
<div class="container">
28+
<div class="lesson-title">
29+
<h1>Physics</h1>
30+
</div>
31+
<div class="lesson">
32+
<div class="lesson-main">
33+
34+
<p>
35+
Physics engines allow you to simulate physical phenomena like gravity, collisions, and forces within
36+
your 3D capabilities. In a typical three.js scene, objects are moved by directly modifying their
37+
position or rotation. When using a physics engine, however, you create a parallel physics world
38+
where bodies react to forces and collisions. You then synchronize the three.js meshes with these
39+
physics bodies on every frame, creating the illusion of a physically simulated environment.
40+
</p>
41+
42+
<p>
43+
It should be noted that the physics engine does not necessarily have to be updated every frame.
44+
Usually, to keep experiences consistent, physics are updated at fixed time steps. For instance, it could
45+
be that we are running the game loop at 60fps but the physics engine at 30fps (that is 1/30=3.33ms)
46+
while updating the three.js meshes' transforms (e.g., positions and rotations) with the most recent
47+
state from the physics engine.
48+
</p>
49+
50+
<p>
51+
Physics simulations are particularly useful for games, interactive visualizations, and any
52+
application requiring realistic object behavior, such as objects falling, bouncing, or sliding.
53+
</p>
54+
55+
<h2>Integration Approaches</h2>
56+
57+
<p>
58+
There are three main ways to integrate a physics engine into a three.js project:
59+
</p>
60+
61+
<h3>1. Using Three.js Physics Addons</h3>
62+
63+
<p>
64+
Three.js provides wrapper classes for several popular physics engines in the
65+
<i>examples/jsm/physics</i> directory. These addons simplify the setup process by handling the
66+
initialization of the physics world and the synchronization of meshes.
67+
</p>
68+
69+
<p>
70+
Available addons include:
71+
</p>
72+
73+
<ul>
74+
<li><b>AmmoPhysics:</b> A wrapper for Ammo.js (Bullet Physics).</li>
75+
<li><b>JoltPhysics:</b> A wrapper for Jolt Physics.</li>
76+
<li><b>RapierPhysics:</b> A wrapper for Rapier.</li>
77+
</ul>
78+
79+
<p>
80+
These addons effectively hide much of the complexity of the underlying engines. For standard use
81+
cases, they offer a very quick way to get started.
82+
</p>
83+
84+
<h4>
85+
Examples
86+
</h4>
87+
<ul>
88+
<li><a href="https://threejs.org/examples/physics_ammo_instancing.html" target="_blank">physics / ammo / instancing</a></li>
89+
<li><a href="https://threejs.org/examples/physics_jolt_instancing.html" target="_blank">physics / jolt / instancing</a></li>
90+
<li><a href="https://threejs.org/examples/physics_rapier_instancing.html" target="_blank">physics / rapier / instancing</a></li>
91+
</ul>
92+
93+
<h3>2. Using 3rd-Party Physics JS/TS Libraries</h3>
94+
95+
<p>
96+
Many physics engines are written directly in JavaScript or TypeScript and are designed to work
97+
easily with the web ecosystem. Libraries like <b>cannon-es</b> are popular choices because they are
98+
lightweight and easy to integrate specifically with three.js.
99+
</p>
100+
101+
<p>
102+
When using these libraries, you instantiate the physics world and bodies yourself, then manually
103+
copy the position and quaternion from the physics body to the three.js mesh in your animation loop.
104+
</p>
105+
106+
107+
<h4>
108+
Projects
109+
</h4>
110+
<ul>
111+
<li><b><a href="https://github.com/pmndrs/cannon-es" target="_blank">cannon-es</a></b>: A lightweight 3D physics engine purely written in JS/TS. Under an MIT license. Apparently no longer maintained (latest commit more than a couple years ago).</li>
112+
<li><b><a href="https://github.com/schteppe/cannon.js" target="_blank">cannon.js</a></b>: A lightweight 3D physics engine purely written in JavaScript. Under an MIT license. No longer maintained (latest commit more than a couple years ago). Consider using its more recent fork cannon-es.</li>
113+
<li><b><a href="https://github.com/lo-th/phy" target="_blank">phy</a></b>: Physics engine for three.js purely written in JavaScript. Under an MIT license. Latest commit. Currently maintained.</li>
114+
<li><b><a href="https://github.com/lo-th/Oimo.js" target="_blank">Oimo.js</a></b>: A no-longer maintained lightweight 3D physics engine written purely in JavaScript. Under an MIT license. Consider using phy instead (as per the author's advise).</li>
115+
</ul>
116+
<p>
117+
It should also be noted that there are a couple of 3D physics engines that are seemingly written in JS/TS but are in reality calling other standalone 3D physics engines. For example:
118+
</p>
119+
<ul>
120+
<li><b><a href="https://github.com/chandlerprall/Physijs" target="_blank">Physijs</a></b>: Calls ammo.js under the hood to do physics work in a separate thread (using web workers). Under MIT license. Apparently no longer maintained (latest commit more than a couple of years ago).</li>
121+
<li><b><a href="https://github.com/enable3d/enable3d" target="_blank">enable3d</a></b>: 3D physics framework for three.js built on top of ammo.js. Under LGPL-3.0 license. Apparently maintained.</li>
122+
</ul>
123+
124+
<h3>3. Importing WASM-based Engines</h3>
125+
126+
<p>
127+
For maximum performance, stability, and precision, especially with complex simulations, you can use physics engines written in
128+
C++ or Rust (or any other language that supports WASM) that have been compiled to WebAssembly (WASM). Engines like <b>Ammo.js</b> (a port of
129+
Bullet Physics) and <b>Rapier</b> fall into this category.
130+
</p>
131+
132+
<p>
133+
While this approach offers the most features and best performance, it often requires more setup code
134+
to handle the WASM memory management and interaction with the physics API directly.
135+
</p>
136+
137+
<h4>
138+
Examples
139+
</h4>
140+
<ul>
141+
<li><a href="https://threejs.org/examples/physics_ammo_break.html" target="_blank">physics / ammo / break</a></li>
142+
<li><a href="https://threejs.org/examples/physics_ammo_cloth.html" target="_blank">physics / ammo / cloth</a></li>
143+
<li><a href="https://threejs.org/examples/physics_ammo_rope.html" target="_blank">physics / ammo / rope</a></li>
144+
<li><a href="https://threejs.org/examples/physics_ammo_terrain.html" target="_blank">physics / ammo / terrain</a></li>
145+
<li><a href="https://threejs.org/examples/physics_ammo_volume.html" target="_blank">physics / ammo / volume</a></li>
146+
</ul>
147+
148+
<h4>
149+
Projects
150+
</h4>
151+
<ul>
152+
<li><b><a href="https://github.com/jrouwe/JoltPhysics" target="_blank">JoltPhysics</a></b>: A multi core friendly rigid body physics and collision detection library. Written in C++. Under MIT license. Actively maintained. Proven with its usage in world-renowned titles and game engines including: Horizon Forbidden West, Death Stranding 2, and official supported by the Godot game engine.</li>
153+
<li><b><a href="https://github.com/NVIDIA-Omniverse/PhysX" target="_blank">PhysX</a></b>: Industry-standard realtime 3D physics engine provided by NVIDIA. Under BSD-3-Clause license. Actively maintained and very stable.</li>
154+
<li><b><a href="https://github.com/dimforge/rapier" target="_blank">Rapier</a></b>: 2D and 3D physics engines focused on performance. Written in Rust. Under an MIT license. Actively maintained.</li>
155+
<li><b><a href="https://github.com/bulletphysics/bullet3" target="_blank">Bullet</a></b>:
156+
Real-time collision detection and multi-physics simulation for VR, games, visual effects, robotics, machine learning etc. Written in C++. Under a ZLIB license. Potentially no longer maintained.</li>
157+
</ul>
158+
<p>
159+
Some of these multi-platform 3D physics engines have a ready-to-use WASM port, including:
160+
</p>
161+
<ul>
162+
<li><b><a href="https://github.com/jrouwe/JoltPhysics.js" target="_blank">JoltPhysics.js</a></b>: Port of JoltPhysics to JavaScript using Emscripten. Under MIT license. Currently maintained.</li>
163+
<li><b><a href="https://github.com/fabmax/physx-js-webidl" target="_blank">physx-js-webidl</a></b>: Javascript WASM bindings for Nvidia PhysX. Under MIT license. Currently maintained.</li>
164+
<li><b><a href="https://github.com/dimforge/rapier.js" target="_blank">Rapier.js</a></b>: Official JavaScript bindings for the Rapier physics engine. Under Apache-2.0 license. Actively maintained.</li>
165+
<li><b><a href="https://github.com/kripken/ammo.js" target="_blank">Ammo.js</a></b>: Direct port of the Bullet physics engine to JavaScript using Emscripten. No longer maintained (latest commit a couple of years ago). Under an MIT-like custom permissive license.</li>
166+
</ul>
167+
168+
</div>
169+
</div>
170+
</div>
171+
172+
<script src="../resources/prettify.js"></script>
173+
<script src="../resources/lesson.js"></script>
174+
175+
</body>
176+
177+
</html>

‎manual/list.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,8 @@
3838
"Shadows": "en/shadows",
3939
"Fog": "en/fog",
4040
"Render Targets": "en/rendertargets",
41-
"Custom BufferGeometry": "en/custom-buffergeometry"
41+
"Custom BufferGeometry": "en/custom-buffergeometry",
42+
"Physics": "en/physics"
4243
},
4344
"Tips": {
4445
"Rendering On Demand": "en/rendering-on-demand",

0 commit comments

Comments
 (0)