Phaser home
Log inCreate a game

← Expansion packsVector

Phaser AE

Vector Motion

Free packv3.0.0-32DVector

Advance a body one frame and keep it on screen: integration with thrust and drag, point gravity, path prediction and the screen wrap the vector arcade games run on.

This is a Free pack. Every phaser.io account can use it in their games.

Released October 14, 2026 · updated October 20, 2026

Vector Motion: a screenshot of its demo
A note about these graphics

Expansion packs don't come with graphics. This screenshot is one way of drawing what the pack does, made for its demo: none of the sprites, tiles or backgrounds in it are in the pack.

That's by design. A pack is a game's logic, mechanics and effects, and it works with whatever art you give it. Some packs draw effects, backdrops or 3D scenes of their own, but none carries a game's sprites.

So the look is yours. Make the art on phaser.io, bring your own, or let your agent draw it in code: the same pack can look like anything.

The pack

vectorMotion

function vectorMotion(): Pack<{ vecMotion: VecMotionApi }>

The vector-motion pack. Pure maths, so it needs no backend and runs headless.

Helpers

integrateMotion

function integrateMotion(body: Body, opts: MotionOptions): void

Advance a bare body one frame, in place — semi-implicit Euler (velocity before position; stable under gravity and frame-rate independent) with a terminal-speed clamp.

wrapPositions

function wrapPositions(position: Vec2, radius: number, width: number, height: number): Vec2[]

Return every screen position at which a wrapping sprite should be drawn this frame — the real position plus mirrors for each edge the sprite straddles (corners yield the diagonal mirror too, so up to 4 positions).

Functions

gravityAccel

function gravityAccel(pos: Vec2, sources: GravitySource[], opts: GravityOptions = {}): Vec2

The summed inverse-square gravitational acceleration on a body at pos from all sources (softened — no singularity at the centre). Add it to the body's accel before integrateMotion; apply to ships AND bullets so shots curve too.

predictPath

function predictPath( body: Body, accelFn: (state: Body) => Vec2, steps: number, dt: number, opts: { maxSpeed?: number; drag?: number } = {}, ): Vec2[]

Forward-simulate a body under an acceleration function, returning sampled positions (steps + 1, starting at the current position) — aim arcs, shot previews. Pass the SAME acceleration the physics uses so the prediction matches.

wrapPosition

function wrapPosition(position: Vec2, width: number, height: number): void

Wrap a position back into [0, width) × [0, height) after integrating movement. Mutates position in place. Call once per frame.

Types

Body

interface Body

A bare point body for integrateMotion/predictPath.

  • x: number — The world x position of the body.
  • y: number — The world y position of the body.
  • vx: number — The horizontal speed, in world units each second.
  • vy: number — The vertical speed, in world units each second. Positive is down.

GravityOptions

interface GravityOptions

Tuning for gravityAccel.

  • G?: number — Gravitational constant — scales how deep every well feels. Default 1.
  • minR2?: number — Softening floor on r² (> 0) so the pull never blows up at a well's centre. Default 1.

GravitySource

interface GravitySource

A point mass that pulls on bodies: where it is and how heavy (see gravityAccel).

  • x: number — The world x position of the source.
  • y: number — The world y position of the source.
  • mass: number — The mass of the source. Scales the pull.

MotionOptions

interface MotionOptions

Per-frame inputs to integrateMotion.

  • delta: number — Frame time in seconds.
  • accel?: Vec2 — Summed acceleration this frame (thrust + any extra pulls).
  • gravity?: Vec2 — Optional constant gravity vector (added to accel).
  • drag?: number — Per-second linear drag coefficient (0/undefined = none).
  • maxSpeed?: number — Terminal-speed clamp (undefined = uncapped).

Vec2

interface Vec2

A 2D point or vector. Plain data, so anything can produce one.

  • x: number — Horizontal position or component, in world units; +x is right.
  • y: number — Vertical position or component, in world units; +y is down.

VecMotionApi

type VecMotionApi = typeof kit

game.vecMotion — every function this pack carries, as one namespace.

VecPt

type VecPt = Vec2

A point on a path — the same shape, named for what it is used as.