diff --git a/docs/api/classes/mousejoint.md b/docs/api/classes/mousejoint.md index e08e91fe..25912d63 100644 --- a/docs/api/classes/mousejoint.md +++ b/docs/api/classes/mousejoint.md @@ -3,7 +3,7 @@ # Class: MouseJoint A mouse joint is used to make a point on a body track a specified world -point. This a soft constraint with a maximum force. This allows the +point. This is a soft constraint with a maximum force. This allows the constraint to stretch and without applying huge forces. You need to call setTarget(target) every time that mouse is diff --git a/docs/pages/api-conventions/factories-and-definitions.md b/docs/pages/api-conventions/factories-and-definitions.md index 3ff4cd45..65a4d584 100644 --- a/docs/pages/api-conventions/factories-and-definitions.md +++ b/docs/pages/api-conventions/factories-and-definitions.md @@ -1,6 +1,6 @@ ### Factories and Definitions -To create a Body or a Joint, you need to call the factory functions on World: +To create a `Body` or a `Joint`, you need to call the factory functions on World: ```js body = world.createBody(bodyDef); @@ -21,14 +21,14 @@ the number of function parameters small, provide sensible defaults, and reduce the number of accessors. Since fixtures must be parented to a body, they are created and -destroyed using a factory method on Body: +destroyed using a factory method on `Body`: ```js let fixture = body.createFixture(fixtureDef); body.destroyFixture(fixture); ``` -There is also shortcut to create a fixture directly from the shape and +There is also a shortcut to create a fixture directly from the shape and density. ```js diff --git a/docs/pages/api-conventions/implicit-destruction.md b/docs/pages/api-conventions/implicit-destruction.md index ab6871a3..8f844d1d 100644 --- a/docs/pages/api-conventions/implicit-destruction.md +++ b/docs/pages/api-conventions/implicit-destruction.md @@ -25,10 +25,10 @@ going to be implicitly destroyed. world.on('remove-joint', function(joint) { // remove all references to joint. }); -world.on('remove-fixture', function(joint) { +world.on('remove-fixture', function(fixture) { // remove all references to fixture. }); -world.on('remove-body', function(joint) { +world.on('remove-body', function(body) { // bodies are not removed implicitly, // but the world publishes this event if a body is removed }) diff --git a/docs/pages/body.md b/docs/pages/body.md index d30b2179..6a8e14c9 100644 --- a/docs/pages/body.md +++ b/docs/pages/body.md @@ -41,7 +41,7 @@ when you are done with them. #### Body Factory Bodies are created and destroyed using a body factory provided by the -world class. This lets the world create the body and add the body to the +`World` class. This lets the world create the body and add the body to the world data structure. ```js @@ -68,7 +68,7 @@ manage shape and joint references. Let's go over some of the key members of the body definition. -####3 Body Type +##### Body Type As discussed at the beginning of this chapter, there are three different body types: static, kinematic, and dynamic. You should specify the body type at creation because changing the body type later is expensive. @@ -94,8 +94,8 @@ A body has two main points of interest. The first point is the body's origin. Fixtures and joints are attached relative to the body's origin. The second point of interest is the center of mass. The center of mass is determined from mass distribution of the attached shapes or is -explicitly set with MassData. Much of Planck.js's internal computations -use the center of mass position. For example Body stores the linear +explicitly set with `MassData`. Much of Planck.js's internal computations +use the center of mass position. For example `Body` stores the linear velocity for the center of mass. When you are building the body definition, you may not know where the @@ -315,7 +315,7 @@ body.isFixedRotation(); // boolean ##### Position and Velocity You can access the position and rotation of a body. This is common when -rendering your associated game actor. You can also set the position, +rendering your associated game actor. You can also set the position and rotation, although this is less common since you will normally use Planck.js to simulate movement. @@ -373,14 +373,14 @@ if (myBody.isAwake()) { The body class has some utility functions to help you transform points and vectors between local and world space. -A localPoint is a coordination relative to body's origin. -A worldPoint is a coordination relative to world's origin. +A `localPoint` is a coordinate relative to the body's origin. +A `worldPoint` is a coordinate relative to the world's origin. -A localVector is a vector between two points relative to body's origin. -A worldVector is a vector between two points relative to world's origin. +A `localVector` is a vector between two points relative to the body's origin. +A `worldVector` is a vector between two points relative to the world's origin. -Here point means a point's 2D coordination, vector means the vector between two points. -In point conversion both position and angel of body are considered, in vector conversion only angle. +Here "point" means a point's 2D coordinate, "vector" means the vector between two points. +In point conversion both position and angle of body are considered, in vector conversion only angle. ```js body.getWorldPoint(localPoint); // Vec2 diff --git a/docs/pages/collision.md b/docs/pages/collision.md index a98eb998..92c7199c 100644 --- a/docs/pages/collision.md +++ b/docs/pages/collision.md @@ -1,5 +1,5 @@ ### Collision -The Collision classes includes shapes and functions that operate on them. +The Collision classes include shapes and functions that operate on them. The module also contains a dynamic tree and broad-phase to acceleration collision processing of large systems. @@ -25,15 +25,15 @@ improve stacking stability. Normally you don't need to compute contact manifolds directly, however you will likely use the results produced in the simulation. -The Manifold structure holds a normal vector and up to two contact +The `Manifold` structure holds a normal vector and up to two contact points. The normal and points are held in local coordinates. As a convenience for the contact solver, each point stores the normal and tangential (friction) impulses. -The data stored in Manifold is optimized for internal use. If you need -this data, it is usually best to use the WorldManifold structure to +The data stored in `Manifold` is optimized for internal use. If you need +this data, it is usually best to use the `WorldManifold` structure to generate the world coordinates of the contact normal and points. You -need to provide a Manifold and the shape transforms and radii. +need to provide a `Manifold` and the shape transforms and radii. ```js let worldManifold = manifold.getWorldManifold(null, transformA, shapeA.m_radius, transformB, shapeB.m_radius) @@ -48,7 +48,7 @@ Notice that the world manifold uses the point count from the original manifold. During simulation shapes may move and the manifolds may change. Points -may be added or removed. You can detect this using GetPointStates. +may be added or removed. You can detect this using `GetPointStates()`. ```js let state1 = []; // [PointState] @@ -63,7 +63,7 @@ if (state1[0] == PointState.removeState) { #### Distance The `Distance` function can be used to compute the distance between two shapes. The distance function needs both shapes to be converted into a -DistanceProxy. There is also some caching used to warm start the +`DistanceProxy`. There is also some caching used to warm start the distance function for repeated calls. ![Distance Function](./images/distance.svg) @@ -99,15 +99,15 @@ may be cases where collisions are missed for small rotations. Normally, these missed rotational collisions should not harm game play. They tend to be glancing collisions. -The function requires two shapes (converted to DistanceProxy) and two -Sweep structures. The sweep structure defines the initial and final +The function requires two shapes (converted to `DistanceProxy`) and two +`Sweep` structures. The sweep structure defines the initial and final transforms of the shapes. You can use fixed rotations to perform a *shape cast*. In this case, the time of impact function will not miss any collisions. ### Dynamic Tree -The DynamicTree class is used by Planck.js to organize large numbers of +The `DynamicTree` class is used by Planck.js to organize large numbers of shapes efficiently. The class does not know about shapes. Instead it operates on axis-aligned bounding boxes (AABBs) with user data pointers. @@ -133,7 +133,7 @@ be skipped. ![Overlap Test](./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 +through the `World` class for ray casts and region queries. If you plan to instantiate your own dynamic tree, you can learn how to use it by looking at how Planck.js uses it. @@ -143,7 +143,7 @@ and broad-phase. In the narrow-phase we compute contact points between pairs of shapes. Imagine we have N shapes. Using brute force, we would need to perform the narrow-phase for N*N/2 pairs. -The BroadPhase class reduces this load by using a dynamic tree for +The `BroadPhase` class reduces this load by using a dynamic tree for pair management. This greatly reduces the number of narrow-phase calls. Normally you do not interact with the broad-phase directly. Instead, diff --git a/docs/pages/core-concepts.md b/docs/pages/core-concepts.md index 6a867633..29d5b6b6 100644 --- a/docs/pages/core-concepts.md +++ b/docs/pages/core-concepts.md @@ -5,10 +5,10 @@ document. #### World A physics world is a collection of bodies, fixtures, and constraints that interact together. -World also manages running simulation. +`World` also manages running simulation. #### Shape -A shape is 2D geometrical object, such as a circle or polygon. +A shape is a 2D geometrical object, such as a circle or polygon. #### Rigid Body A chunk of matter that is so strong that the distance between any two bits of matter on the chunk is constant. @@ -27,7 +27,7 @@ At this point the body can only rotate about the pin, so the constraint has remo #### Contact Constraint A special constraint designed to prevent penetration of rigid bodies and to simulate friction and restitution. -You do not create contact constraints; they are created automatically by when two objects might collide. +You do not create contact constraints; they are created automatically when two objects might collide. #### Joint This is a constraint used to hold two or more bodies together. There are several joint types implemented in the library: revolute, prismatic, distance, and more. diff --git a/docs/pages/fixture.md b/docs/pages/fixture.md index 5a2b1669..c54a2fd2 100644 --- a/docs/pages/fixture.md +++ b/docs/pages/fixture.md @@ -1,6 +1,6 @@ ### Fixture -Shapes are only have geometrical coordination, they don't have physical properties and don't know about body's transformation, so may be used independently of the physics simulation. -Fixture class is used to attach shapes to bodies. A body may have zero or more fixtures. A +Shapes only have geometrical coordinates, they don't have physical properties and don't know about the body's transformation, so may be used independently of the physics simulation. +The `Fixture` class is used to attach shapes to bodies. A body may have zero or more fixtures. A body with multiple fixtures is sometimes called a *compound body.* Fixtures hold the following: @@ -145,8 +145,8 @@ Collision groups let you specify an integral group index. You can have all fixtures with the same group index always collide (positive index) or never collide (negative index). Group indices are usually used for things that are somehow related, like the parts of a bicycle. In the -following example, fixture1 and fixture2 always collide, but fixture3 -and fixture4 never collide. +following example, `fixture1` and `fixture2` always collide, but `fixture3` +and `fixture4` never collide. ```js fixture1Def.filterGroupIndex = 2; @@ -156,7 +156,7 @@ fixture4Def.filterGroupIndex = -8; ``` Collisions between fixtures of different group indices are filtered -according the category and mask bits. In other words, group filtering +according to the category and mask bits. In other words, group filtering has higher precedence than category filtering. Note that additional collision filtering occurs in Planck.js. Here is a diff --git a/docs/pages/hello-world.md b/docs/pages/hello-world.md index 73074e71..e37768d8 100644 --- a/docs/pages/hello-world.md +++ b/docs/pages/hello-world.md @@ -1,12 +1,12 @@ ### Getting Started -In this section we will walk through a simple example to sets up the physics world, and creates a platform and a small box. +In this section we will walk through a simple example to set up the physics world, and create a platform and a small box. #### Creating a World Every Planck.js program begins with the creation of a World object. World is the physics hub that manages objects, their physical interactions, and runs simulation. -To create a world we simply create an object from World class, and optionally pass gravity. +To create a world we simply create an object from the `World` class, and optionally pass gravity. ```js let world = new World({ @@ -21,9 +21,9 @@ Now that we have our physics world set up, let's start adding some stuff to it. We will create a platform using the following steps: 1. Use the world object to create the body with position. -1. Create a fixtures on the body with a shape. +1. Create a fixture on the body with a shape. -For the step 1, we pass body properties to the world object to create the platform body. +For step 1, we pass body properties to the world object to create the platform body. With the body properties we specify the type and initial position of the platform: ```js @@ -36,7 +36,7 @@ let platform = world.createBody({ Bodies are "static" by default. Static bodies don't collide with other static bodies and are immovable. -For the step 2, we need to create a Shape and add it to body as Fixture. +For step 2, we need to create a `Shape` and add it to body as `Fixture`. ```js platform.createFixture({ @@ -45,10 +45,10 @@ platform.createFixture({ ``` Shapes only have geometrical properties (such as vertices or radius), and do not have physical properties. -A fixture is used to add a shape to a body, and adds physical properties (such as density, friction, etc) to a body. +A fixture is used to add a shape to a body, and adds physical properties (such as density, friction, etc.) to a body. A body can have any number of shapes fixed together. -Shape's geometrical coordinates are local to the body. A fixture does not have location and angle. So when a body moves, all fixtures/shapes in the body move with the body. However we don't move a shape around on the body. +`Shape`'s geometrical coordinates are local to the body. A fixture does not have location and angle. So when a body moves, all fixtures/shapes in the body move with the body. However we don't move a shape around on the body. Planck.js is a rigid body engine and many of the assumptions made in Planck.js are based on the rigid body model. A body with morphing shapes is not a rigid body, and if this is violated many things will break. @@ -58,12 +58,12 @@ Every fixture must have a parent body, even fixtures that are static. However, you can attach all static fixtures to a single static body. A static body has zero mass by definition, so we don't need to specify density in this case. -Later we will see how to use a fixture properties to customize its physical behavior. +Later we will see how to use a fixture's properties to customize its physical behavior. #### Creating a dynamic box Creating a dynamic box is similar to the platform. The main difference, besides dimensions, is that for a dynamic body we need to specify mass properties. -First we create the body using createBody. By default bodies are static, so we should set the body's `type` at construction time to make the body dynamic. +First we create the body using `createBody`. By default bodies are static, so we should set the body's `type` at construction time to make the body dynamic. ```js let body = world.createBody({ @@ -99,5 +99,5 @@ So in this case the ground box is 2 units wide (x-axis) and 2 units tall (y-axis Planck.js by default is tuned for meters, kilograms, and seconds. So you can consider the dimensions to be in meters. Planck.js generally works best when objects are the size of typical real world objects. For example, a barrel is about 1 meter tall. Due to the limitations of floating point arithmetic, using Planck.js to model the movement of glaciers or dust particles is not a good idea. -If you use a different units for your objects, you can change value of `Settings.lengthUnitsPerMeter`. +If you use a different units for your objects, you can change the value of `Settings.lengthUnitsPerMeter`. For example if you use pixels and a barrel height is 80 pixels set the `lengthUnitsPerMeter` to 80. diff --git a/docs/pages/index.md b/docs/pages/index.md index 3369e8e8..12e63a84 100644 --- a/docs/pages/index.md +++ b/docs/pages/index.md @@ -1,13 +1,13 @@ #### Planck.js -Planck.js is JavaScript/TypeScript rewrite of Box2D C++ physics engine for cross-platform game development. +Planck.js is JavaScript/TypeScript rewrite of the [Box2D](https://box2d.org/) C++ physics engine for cross-platform game development. #### Box2D Box2D is a 2D rigid-body physics simulation library for games. You can use it in your games to make objects move in realistic ways and make the game world more interactive. From the game engine's point of view, a physics engine is just a system for procedural animation. -Planck.js documentation is based on Box2D manual with adjustments and addition for JavaScript. Both projects names are used interchangeably in the documentation. +Planck.js documentation is based on the Box2D manual with adjustments and additions for JavaScript. Both projects' names are used interchangeably in the documentation. #### Before You Start diff --git a/docs/pages/install.md b/docs/pages/install.md index 70e56b46..2daf16dc 100644 --- a/docs/pages/install.md +++ b/docs/pages/install.md @@ -17,7 +17,7 @@ const world = new World(); Planck.js is available on [jsDelivr](https://www.jsdelivr.com/package/npm/planck), [cdnjs](https://cdnjs.com/libraries/planck), and [unpkg](https://unpkg.com/planck/). ```html - ``` diff --git a/docs/pages/world.md b/docs/pages/world.md index cebcefb7..c5316e4e 100644 --- a/docs/pages/world.md +++ b/docs/pages/world.md @@ -83,5 +83,5 @@ while (node) { } ``` -Obviously to make this work, gameCrazyBodyDestroyer must be honest about +Obviously to make this work, `gameCrazyBodyDestroyer()` must be honest about what it has destroyed. diff --git a/docs/pages/world/aabb-query.md b/docs/pages/world/aabb-query.md index 489a183b..227626cb 100644 --- a/docs/pages/world/aabb-query.md +++ b/docs/pages/world/aabb-query.md @@ -1,17 +1,17 @@ ### AABB Queries Sometimes you want to determine all the shapes in a region. The World -class has a fast log(N) method for this using the broad-phase data +class has a fast O(log N) method for this using the broad-phase data structure. You provide an AABB in world coordinates and an -implementation of QueryCallback. The world calls your class with each -fixture whose AABB overlaps the query AABB. Return true to continue the -query, otherwise return false. For example, the following code finds all +implementation of `QueryCallback`. The world calls your class with each +fixture whose AABB overlaps the query AABB. Return `true` to continue the +query, otherwise return `false`. For example, the following code finds all the fixtures that potentially intersect a specified AABB and wakes up all of the associated bodies. ```js const query = new AABB( new Vec2(-1, -1), - new Vec2(-1, -1), + new Vec2(1, 1), ); myWorld.queryAABB(query, function(fixture) { let body = fixture.getBody(); diff --git a/docs/pages/world/ray-cast.md b/docs/pages/world/ray-cast.md index 437401da..f64652cd 100644 --- a/docs/pages/world/ray-cast.md +++ b/docs/pages/world/ray-cast.md @@ -42,4 +42,4 @@ myWorld.rayCast(Vec2(-1, 0), Vec2(3, 1), function(fixture, point, normal, fracti > **Caution**: > Due to round-off errors, ray casts can sneak through small cracks > between polygons in your static environment. If this is not acceptable -> in your application, trying slightly overlapping your polygons. +> in your application, try slightly overlapping your polygons.