Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

docs: add a physics joint-types cheat sheet (en + zh)

yhhd8198c930d6c
diff --git a/docs/astro/src/assets/guides/physics-joints.svg b/docs/astro/src/assets/guides/physics-joints.svg
new file mode 100644
index 000000000..8fe5eb8a2
--- /dev/null
+++ b/docs/astro/src/assets/guides/physics-joints.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 494 514" width="494" height="514" role="img"><rect x="18" y="16" width="220" height="150" rx="8" fill="#14161c" stroke="#2b2f3a" stroke-width="1"/><text x="32" y="40" fill="#cbd0db" font-size="14" font-weight="700" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Revolute</text><text x="32" y="56" fill="#8b91a0" font-size="11" font-weight="400" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">pin — bodies rotate about a point</text><rect x="58" y="132" width="56" height="18" rx="3" fill="#5b6472"/><rect x="80" y="115" width="54" height="14" rx="3" fill="#5b9cf0" transform="rotate(-30 84 128)"/><path d="M 128 106 A 46 46 0 0 1 136 126" fill="none" stroke="#54c479" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/><path d="M 134.6 120.2 L 136 126 L 140.1 121.7" fill="none" stroke="#54c479" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/><circle cx="84" cy="128" r="5" fill="#0d0f14" stroke="#54c479" stroke-width="2"/><rect x="256" y="16" width="220" height="150" rx="8" fill="#14161c" stroke="#2b2f3a" stroke-width="1"/><text x="270" y="40" fill="#cbd0db" font-size="14" font-weight="700" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Distance</text><text x="270" y="56" fill="#8b91a0" font-size="11" font-weight="400" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">held at a fixed distance (or springy)</text><rect x="272" y="62" width="34" height="34" rx="4" fill="#5b6472"/><rect x="410" y="62" width="34" height="34" rx="4" fill="#f0bd4f"/><path d="M 306 78 L 316 78 L 316 78 L 330 70 L 344 86 L 358 70 L 372 86 L 386 70 L 400 78 L 410 78" fill="none" stroke="#8b91a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/><circle cx="306" cy="78" r="3" fill="#54c479"/><circle cx="410" cy="78" r="3" fill="#54c479"/><rect x="18" y="182" width="220" height="150" rx="8" fill="#14161c" stroke="#2b2f3a" stroke-width="1"/><text x="32" y="206" fill="#cbd0db" font-size="14" font-weight="700" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Prismatic</text><text x="32" y="222" fill="#8b91a0" font-size="11" font-weight="400" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">slides along one axis</text><line x1="42" y1="266" x2="208" y2="266" stroke="#2b2f3a" stroke-width="3" stroke-linecap="round"/><rect x="40" y="242" width="20" height="22" rx="3" fill="#5b6472"/><rect x="108" y="240" width="40" height="26" rx="4" fill="#5b9cf0"/><line x1="96" y1="226" x2="160" y2="226" stroke="#8b91a0" stroke-width="2" stroke-linecap="round"/><path d="M 154.7 228.9 L 160 226 L 154.7 223.1" fill="none" stroke="#8b91a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/><path d="M 101.3 223.1 L 96 226 L 101.3 228.9" fill="none" stroke="#8b91a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/><rect x="256" y="182" width="220" height="150" rx="8" fill="#14161c" stroke="#2b2f3a" stroke-width="1"/><text x="270" y="206" fill="#cbd0db" font-size="14" font-weight="700" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Weld</text><text x="270" y="222" fill="#8b91a0" font-size="11" font-weight="400" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">rigidly fixed — no relative motion</text><rect x="300" y="222" width="60" height="40" rx="4" fill="#5b6472"/><rect x="360" y="222" width="60" height="40" rx="4" fill="#f0bd4f"/><line x1="360" y1="216" x2="360" y2="268" stroke="#54c479" stroke-width="2" stroke-dasharray="4 4" stroke-linecap="round"/><text x="366" y="286" fill="#8b91a0" font-size="11" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">🔒 rigid</text><rect x="18" y="348" width="220" height="150" rx="8" fill="#14161c" stroke="#2b2f3a" stroke-width="1"/><text x="32" y="372" fill="#cbd0db" font-size="14" font-weight="700" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Wheel</text><text x="32" y="388" fill="#8b91a0" font-size="11" font-weight="400" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">suspension travel + free spin</text><rect x="88" y="386" width="80" height="18" rx="3" fill="#5b6472"/><path d="M 128 404 L 128 414 L 128 414 L 134 414.5 L 122 415 L 134 415.5 L 128 416 L 128 426" fill="none" stroke="#8b91a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/><circle cx="128" cy="448" r="22" fill="#5b9cf0" stroke="#0d0f14" stroke-width="2"/><circle cx="128" cy="448" r="4" fill="#0d0f14"/><path d="M 158 436 A 32 32 0 0 1 162 456" fill="none" stroke="#54c479" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/><path d="M 161.1 450.1 L 162 456 L 166.5 452" fill="none" stroke="#54c479" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/><rect x="256" y="348" width="220" height="150" rx="8" fill="#14161c" stroke="#2b2f3a" stroke-width="1"/><text x="270" y="372" fill="#cbd0db" font-size="14" font-weight="700" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Motor</text><text x="270" y="388" fill="#8b91a0" font-size="11" font-weight="400" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">driven toward a target velocity</text><rect x="276" y="394" width="30" height="34" rx="4" fill="#5b6472"/><rect x="348" y="392" width="40" height="38" rx="4" fill="#f0bd4f"/><line x1="394" y1="410" x2="452" y2="410" stroke="#54c479" stroke-width="3" stroke-linecap="round"/><path d="M 445 413.8 L 452 410 L 445 406.2" fill="none" stroke="#54c479" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>
\ No newline at end of file
diff --git a/docs/astro/src/content/docs/guides/physics.mdx b/docs/astro/src/content/docs/guides/physics.mdx
index f710f85fa..bac2dfd86 100644
--- a/docs/astro/src/content/docs/guides/physics.mdx
+++ b/docs/astro/src/content/docs/guides/physics.mdx
@@ -242,6 +242,10 @@ const onHit = defineSystem([Res(PhysicsEvents)], (events) => {
## Joints
+![The joint types and what each constrains — Revolute, Distance, Prismatic, Weld, Wheel, Motor](../../../assets/guides/physics-joints.svg)
+
+*What each joint constrains: a **Revolute** hinge (rotate about a pin), a **Distance** spring/rod, a **Prismatic** slider (one axis), a rigid **Weld**, a **Wheel** (suspension + free spin), and a **Motor** (driven toward a target velocity).*
+
Connect two bodies. Add a joint **component** (`RevoluteJoint`, `DistanceJoint`,
`PrismaticJoint`, `WeldJoint`, `WheelJoint`, `MotorJoint`), or create one imperatively
and drive its motor / limits:
diff --git a/docs/astro/src/content/docs/zh-cn/guides/physics.mdx b/docs/astro/src/content/docs/zh-cn/guides/physics.mdx
index 2280ea6ac..e1e426a89 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/physics.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/physics.mdx
@@ -230,6 +230,10 @@ const onHit = defineSystem([Res(PhysicsEvents)], (events) => {
## 关节
+![各关节类型及其约束——Revolute、Distance、Prismatic、Weld、Wheel、Motor](../../../../assets/guides/physics-joints.svg)
+
+*每种关节约束什么:**Revolute** 铰链(绕销钉转动)、**Distance** 弹簧/连杆、**Prismatic** 滑轨(单轴滑动)、刚性 **Weld** 焊接、**Wheel** 车轮(悬挂 + 自由旋转),以及 **Motor** 马达(驱向目标速度)。*
+
连接两个刚体。加一个关节**组件**(`RevoluteJoint`、`DistanceJoint`、`PrismaticJoint`、
`WeldJoint`、`WheelJoint`、`MotorJoint`),或命令式创建一个并驱动它的马达 / 限位: