Skip to content

Commit

Permalink
clean up docs
Browse files Browse the repository at this point in the history
  • Loading branch information
shakiba committed May 2, 2024
1 parent 3d9286b commit 09cf743
Show file tree
Hide file tree
Showing 16 changed files with 84 additions and 40 deletions.
14 changes: 7 additions & 7 deletions docs/pages/collision.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ These points share the same normal vector so Planck.js groups them into a
manifold structure. The contact solver takes advantage of this to
improve stacking stability.

![Contact Manifold](/images/manifolds.svg)
![Contact Manifold](/planck.js/docs/images/manifolds.svg)

Normally you don't need to compute contact manifolds directly, however
you will likely use the results produced in the simulation.
Expand Down Expand Up @@ -70,13 +70,13 @@ shapes. The distance function needs both shapes to be converted into a
`DistanceProxy`. There is also some caching used to warm start the
distance function for repeated calls.

![Distance Function](/images/distance.svg)
![Distance Function](/planck.js/docs/images/distance.svg)

### Time of Impact
If two shapes are moving fast, they may *tunnel* through each other in a
single time step.

![Tunneling](/images/tunneling2.svg)
![Tunneling](/planck.js/docs/images/tunneling2.svg)

The `TimeOfImpact` function is used to determine the time when two
moving shapes collide. This is called the *time of impact* (TOI). The
Expand All @@ -94,9 +94,9 @@ ensures the shapes do not cross on that axis. This might miss collisions
that are clear at the final positions. While this approach may miss some
collisions, it is very fast and adequate for tunnel prevention.

![Captured Collision](/images/captured_toi.svg)
![Captured Collision](/planck.js/docs/images/captured_toi.svg)

![Missed Collision](/images/missed_toi.svg)
![Missed Collision](/planck.js/docs/images/missed_toi.svg)

It is difficult to put a restriction on the rotation magnitude. There
may be cases where collisions are missed for small rotations. Normally,
Expand Down Expand Up @@ -132,9 +132,9 @@ A region query uses the tree to find all leaf AABBs that overlap a query
AABB. This is faster than a brute force approach because many shapes can
be skipped.

![Raycast](/images/raycast.svg)
![Raycast](/planck.js/docs/images/raycast.svg)

![Overlap Test](/images/overlap_test.svg)
![Overlap Test](/planck.js/docs/images/overlap_test.svg)

Normally you will not use the dynamic tree directly. Rather you will go
through the `World` class for ray casts and region queries. If you plan
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/core-concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ The Planck.js solver is a high-performance iterative solver that operates in ord
### Continuous Collision
The solver advances bodies in time using discrete time steps. Without intervention this can lead to tunneling.

![Tunneling Effect](/images/tunneling1.svg)
![Tunneling Effect](/planck.js/docs/images/tunneling1.svg)

Planck.js contains specialized algorithms to deal with tunneling. First, the collision algorithms can interpolate the motion of two bodies to find the first time of impact (TOI).
Second, there is a sub-stepping solver that moves bodies to their first time of impact and then resolves the collision.
29 changes: 15 additions & 14 deletions docs/pages/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,35 +2,34 @@
showOutline: false
---

## Get Started
## Install

### Running Your Code

Planck.js is a physics simulation library, and it doesn't draw anything.

[Piqnt](https://piqnt.com/) is an online playground for Planck.js. You can explore [examples](https://piqnt.com/planck.js/), inspect and edit them, or create new ones.

[Testbed](./testbed) is a simple tool (included in the project repository) to visualize and interact with physics simulation. Testbed is compatible with Piqnt playground.

You can use Planck.js with any game engines or frameworks, or use an existing integrations. See [Simulation](./world/simulation) and [Rendering](./rendering) page for more information.

### Install
Planck can be installed or downloaded from NPM or a CDN.

#### NPM

First install the package.
```sh
npm install planck
```

Import the library in your code:
Then import the library in your code:

```js
import { World } from 'planck';

const world = new World();
```

Import the library with testbed:
You can alternatively import planck namespace to access all classes:

```js
import planck from 'planck';

const world = new planck.World();
```

To use testbed you need to import `planck/with-testbed` instead:

```js
import { World, Testbed } from 'planck/with-testbed';
Expand All @@ -54,6 +53,8 @@ Planck.js is available on [jsDelivr](https://www.jsdelivr.com/package/npm/planck
</script>
```

To use testbed you need to use `planck-with-testbed.min.js` instead:

```html
<html><body>
<span id="testbed-info"></span>
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/joint/distance-joint.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ you specify the two anchor points in world coordinates. The first anchor
point is connected to body 1, and the second anchor point is connected
to body 2. These points imply the length of the distance constraint.

![Distance Joint](/images/distance_joint.gif)
![Distance Joint](/planck.js/docs/images/distance_joint.gif)

Here is an example of a distance joint definition. In this case we
decide to allow the bodies to collide.
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/joint/gear-joint.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ might be tedious to author. You also have to be careful to line up the
gears so the teeth mesh smoothly. Planck.js has a simpler method of creating
gears: the gear joint.

![Gear Joint](/images/gear_joint.gif)
![Gear Joint](/planck.js/docs/images/gear_joint.gif)

The gear joint can only connect revolute and/or prismatic joints.

Expand Down
2 changes: 1 addition & 1 deletion docs/pages/joint/prismatic-joint.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ A prismatic joint allows for relative translation of two bodies along a
specified axis. A prismatic joint prevents relative rotation. Therefore,
a prismatic joint has a single degree of freedom.

![Prismatic Joint](/images/prismatic_joint.gif)
![Prismatic Joint](/planck.js/docs/images/prismatic_joint.gif)

The prismatic joint definition is similar to the revolute joint
description; just substitute translation for angle, and force for torque.
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/joint/pulley.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ For example, if the ratio is 2, then `length1` will vary at twice the rate
of `length2`. Also the force in the rope attached to `body1` will have half
the constraint force as the rope attached to `body2`.

![Pulley Joint](/images/pulley_joint.gif)
![Pulley Joint](/planck.js/docs/images/pulley_joint.gif)

Pulleys can be troublesome when one side is fully extended. The rope on
the other side will have zero length. At this point the constraint
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/joint/revolute-joint.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ A revolute joint forces two bodies to share a common anchor point, often
called a hinge point. The revolute joint has a single degree of freedom:
the relative rotation of the two bodies. This is called the joint angle.

![Revolute Joint](/images/revolute_joint.gif)
![Revolute Joint](/planck.js/docs/images/revolute_joint.gif)

To specify a revolute you need to provide two bodies and a single anchor
point in world space. The initialization function assumes that the
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/joint/wheel-joint.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,4 @@ The wheel joint restricts a point on bodyB to a line on bodyA. The wheel
joint also provides a suspension spring. See WheelJoint.js and Car.js
for details.

![Wheel Joint](/images/wheel_joint.svg)
![Wheel Joint](/planck.js/docs/images/wheel_joint.svg)
2 changes: 1 addition & 1 deletion docs/pages/rendering.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
showOutline: false
---

### Rendering
## Rendering

Planck.js is a physics engine and it can be used with any graphics library or ui framework for rendering.

Expand Down
14 changes: 14 additions & 0 deletions docs/pages/run-your-code.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
---
showOutline: false
---

## Run Your Code

Planck.js is a physics simulation library, and it doesn't draw anything.

[Piqnt](https://piqnt.com/) is an online playground for Planck.js. You can explore [examples](https://piqnt.com/planck.js/), inspect and edit them, or create new ones.

[Testbed](./testbed) is a simple tool (included in the project repository) to visualize and interact with physics simulation. Testbed is compatible with Piqnt playground.

You can use Planck.js with any game engines or frameworks, or use an existing integrations. See [Simulation](./world/simulation) and [Rendering](./rendering) page for more information.

4 changes: 2 additions & 2 deletions docs/pages/shape/chain.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ The chain shape provides an efficient way to connect many edges together
to construct your static game worlds. Chain shapes automatically
eliminate ghost collisions and provide two-sided collision.

![Chain Shape](/images/chain_shape.svg)
![Chain Shape](/planck.js/docs/images/chain_shape.svg)

```js
// This is a chain shape with isolated vertices
Expand Down Expand Up @@ -44,7 +44,7 @@ might not. The code that prevents ghost collisions assumes there are no
self-intersections of the chain. Also, very close vertices can cause
problems. Make sure all your edges are longer than Settings.linearSlop (5mm).

![Self Intersection](/images/self_intersect.svg)
![Self Intersection](/planck.js/docs/images/self_intersect.svg)

Each edge in the chain is treated as a child shape and can be accessed
by index. When a chain shape is connected to a body, each edge gets its
Expand Down
4 changes: 2 additions & 2 deletions docs/pages/shape/edge.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ see a box colliding with an internal vertex. These *ghost* collisions
are caused when the polygon collides with an internal vertex generating
an internal collision normal.

![Ghost Collision](/images/ghost_collision.svg)
![Ghost Collision](/planck.js/docs/images/ghost_collision.svg)

If edge1 did not exist this collision would seem fine. With edge1
present, the internal collision seems like a bug. But normally when
Expand All @@ -32,7 +32,7 @@ Fortunately, the edge shape provides a mechanism for eliminating ghost
collisions by storing the adjacent *ghost* vertices. Planck.js uses these
ghost vertices to prevent internal collisions.

![Ghost Vertices](/images/ghost_vertices.svg)
![Ghost Vertices](/planck.js/docs/images/ghost_vertices.svg)

```js
// This is an edge shape with ghost vertices.
Expand Down
8 changes: 4 additions & 4 deletions docs/pages/shape/polygon.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,15 @@ line segments connecting two points in the interior do not cross any
edge of the polygon. Polygons are solid and never hollow. A polygon must
have 3 or more vertices.

![Convex and Concave Polygons](/images/convex_concave.gif)
![Convex and Concave Polygons](/planck.js/docs/images/convex_concave.gif)

Polygon vertices are stored with a counter-clockwise winding (CCW). We
must be careful because the notion of CCW is with respect to a
right-handed coordinate system with the z-axis pointing out of the
plane. This might turn out to be clockwise on your screen, depending on
your coordinate system conventions.

![Polygon Winding Order](/images/winding.svg)
![Polygon Winding Order](/planck.js/docs/images/winding.svg)

The initialization functions create normal vectors and perform validation.
So you should use initialization functions to create a polygon.
Expand Down Expand Up @@ -55,10 +55,10 @@ the polygon. The skin is used in stacking scenarios to keep polygons
slightly separated. This allows continuous collision to work against the
core polygon.

![Polygon Skin](/images/skinned_polygon.svg)
![Polygon Skin](/planck.js/docs/images/skinned_polygon.svg)

The polygon skin helps prevent tunneling by keeping the polygons
separated. This results in small gaps between the shapes. Your visual
representation can be larger than the polygon to hide any gaps.

![Skin Collision](/images/skin_collision.svg)
![Skin Collision](/planck.js/docs/images/skin_collision.svg)
28 changes: 28 additions & 0 deletions docs/styles.css
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,31 @@ p img {
font-weight: var(--vocs-fontWeight_medium);
color: var(--vocs-color_text3);
}

.vocs_Sidebar_section {
border-bottom: none !important;
border-top: none !important;
}

.vocs_Sidebar_level {
padding-top: 0px;
padding-bottom: 0px;
}

.vocs_Sidebar_level .vocs_Sidebar_sectionHeader {
padding-top: 0px;
padding-bottom: 0px;
}

.vocs_Sidebar_level .vocs_Sidebar_items {
padding-left: 12px;
}

.vocs_Sidebar_items {
padding-top: var(--vocs-space_4) !important;
padding-bottom: var(--vocs-space_4) !important;
}

.vocs_Sidebar_group {
padding-top: var(--vocs-space_12);
}
7 changes: 4 additions & 3 deletions docs/vocs.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,15 @@ export default defineConfig({
{ text: 'Discord', link: 'https://discord.gg/znjh6J7'},
],
sidebar: [
{ link: "/", text: "Introduction" },
{
text: 'Getting Started',
text: 'Get Started',
collapsed: true,
items: [
{ link: "/", text: "Introduction" },
{ link: "/install", text: "Install" },
{ link: "/run-your-code", text: "Run Your Code" },
{ link: "/hello-world", text: "Hello World" },
{ link: "/core-concepts", text: "Core Concepts" },
{ link: "/install", text: "Install" },
],
},

Expand Down

0 comments on commit 09cf743

Please sign in to comment.