Vector Motion · Expansion packs · Phaser AE

What it does

integrateMotion advances a bare body, a position and a velocity, by one frame. It applies the acceleration and any constant gravity, then drag, then a speed cap, and moves the body with its new velocity. The order matters: capping after drag means a ship at terminal velocity behaves the same whether it is coasting or under thrust.

gravityAccel sums the inverse-square pull of any number of point sources, each a position and a mass, with a softening floor, so a body passing exactly through a source does not divide by zero and fire off to infinity. Apply it to bullets as well as ships and the shots curve too. predictPath runs the same integrator forward a number of steps on a copy of the body and returns the points, which is how a game draws the dotted arc of a shot before it is fired; because it is the same function, the preview cannot drift from the flight.

Screen wrap is two jobs, and games forget the second. wrapPosition folds a position back into the field. wrapPositions returns every place a body must be drawn near an edge, up to four at a corner, because a ship straddling the seam has to appear on both sides or it visibly vanishes as it crosses. The same list is what a collision test needs, or a rock on the seam collides on one side of it only.

Features

Integration — acceleration, constant gravity, per-second drag and a terminal-speed cap, velocity before position, so it stays stable under gravity.
Point gravity — gravityAccel from any number of sources, with a gravitational constant G and a softening floor minR2.
Path prediction — predictPath returns the arc a body will fly under any acceleration function, with the same drag and cap.
Wrap that folds — wrapPosition brings a body back into the field after it moves.
Wrap that draws — wrapPositions lists the images a body near an edge or a corner needs, for drawing and for collision.
Pure — the trajectory a game shows is computed by the same code that will fly it.

Good for

Wrap-around shooters — drifting rocks and a thrusting ship crossing the edges, in the style of Asteroids.
Gravity games — ships and shots pulled toward planets, in the style of Gravitar or Thrust.
Artillery and golf — the arc of a shot shown before it is taken.
Space duels — two ships circling a central star, their shots curving round it.

Make it yours

Each call takes its own numbers: delta, accel, gravity, drag and maxSpeed to integrate; the sources, G and minR2 for gravity; steps, a time step, drag and a cap to predict. A floaty spaceship is a little thrust, no drag and a high cap; a heavy lander is constant downward gravity, some drag and a low cap.

Two different games from the same calls: an asteroid field where every body integrates with no gravity and wraps at the edges, drawn at each image wrapPositions returns; and a planet-hopping game where ships and bullets alike take gravityAccel from three planets, and the aiming line is predictPath fed the same pull.

Works with

vector-math — arithmetic over the same plain { x, y } data.
vector-hit — swept tests and surface response when a moving body meets a wall.
vector-terrain — the line landscapes a lander or a buggy moves over.
thrust-craft — the full flight rules of landers and cave flyers, with fuel, landing gear and tractor beams.
core-vector — includes this pack with the rest of the vector kit.

Good to know