physics-arcade

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha d14f4c86f869 · 31 Oct 2026Report an issue or request a re-scan

• Publisherphaserjs GitHub organizationOwner of the repository this skill is read from
• Source folderphaserjs/phaser/skills/physics-arcadeThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdictd14f4c86f869A new audit runs when the source changes
• Repository statusNot archivedLast push 71 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Use this skill when using Arcade Physics in Phaser 4. Covers enabling physics, velocity, acceleration, gravity, collisions, overlap, world bounds, physics groups, static bodies, and collision categories. Triggers on:…

---
name: physics-arcade
description: "Use this skill when using Arcade Physics in Phaser 4. Covers enabling physics, velocity, acceleration, gravity, collisions, overlap, world bounds, physics groups, static bodies, and collision categories. Triggers on: physics, arcade, velocity, gravity, collide, overlap, bounce, physics body."
---

# Arcade Physics
> Setting up and using Arcade Physics in Phaser 4 -- enabling physics in GameConfig, creating physics-enabled sprites/images/groups, velocity, acceleration, gravity, collisions (collide/overlap), world bounds, body properties, and collision categories.

**Key source paths:** `src/physics/arcade/ArcadePhysics.js`, `src/physics/arcade/World.js`, `src/physics/arcade/Body.js`, `src/physics/arcade/StaticBody.js`, `src/physics/arcade/Factory.js`, `src/physics/arcade/components/`, `src/physics/arcade/events/`
**Related skills:** ../game-setup-and-config/SKILL.md, ../sprites-and-images/SKILL.md, ../tilemaps/SKILL.md, ../groups-and-containers/SKILL.md

## Quick Start

```js
class GameScene extends Phaser.Scene {
    create() {
        // Physics sprite (dynamic body, affected by gravity)
        this.player = this.physics.add.sprite(100, 300, 'player');
        this.player.setCollideWorldBounds(true);
        this.player.setBounce(0.2);

        // Static group (immovable platforms)
        this.platforms = this.physics.add.staticGroup();
        this.platforms.create(400, 568, 'ground').setScale(2).refreshBody();

        // Register a persistent collider (checked every frame automatically)
        this.physics.add.collider(this.player, this.platforms);

        this.cursors = this.input.keyboard.createCursorKeys();
    }

    update() {
        if (this.cursors.left.isDown) {
            this.player.setVelocityX(-160);
        } else if (this.cursors.right.isDown) {
            this.player.setVelocityX(160);
        } else {
            this.player.setVelocityX(0);
        }
    }
}

// Enable Arcade Physics in game config
const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    physics: {
        default: 'arcade',
        arcade: {
            gravity: { y: 300 },
            debug: false
        }
    },
    scene: GameScene
};

const game = new Phaser.Game(config);
```

## Core Concepts

### World (`this.physics.world`)

The `Phaser.Physics.Arcade.World` manages all bodies in the simulation. Accessed via `this.physics.world` in a Scene.

- **gravity** -- `Vector2` applied to all dynamic bodies each step. Set via config or `this.physics.world.gravity.y = 300`.
- **bounds** -- `Rectangle` defining the world boundary. Defaults to game canvas size.
- **bodies** -- `Set` of all dynamic `Body` instances.
- **staticBodies** -- `Set` of all `StaticBody` instances.
- **colliders** -- `ProcessQueue` of registered `Collider` objects (from `this.physics.add.collider` / `this.physics.add.overlap`).
- **fps** -- Physics steps per second (default 60). Read-only; change via `world.setFPS(120)`.
- **fixedStep** -- `true` (default) uses fixed timestep; `false` syncs to render fps.
- **timeScale** -- Scaling factor: 1.0 = normal, 2.0 = half speed, 0.5 = double speed.
- **isPaused** -- When true, no bodies update and no colliders run. Toggle via `world.pause()` / `world.resume()`.
- **useTree** -- `true` (default) uses RTree spatial index for dynamic bodies. Disable for 5000+ bodies.
- **drawDebug** -- Enables debug rendering when `true`. Set via config `debug: true`.

### Bodies (`Body`)

A dynamic body is created automatically when you use `this.physics.add.sprite()` or `this.physics.add.image()`. Access it via `gameObject.body`.

Key properties (all on `Body`):
- **velocity** -- `Vector2`, pixels/sec
- **acceleration** -- `Vector2`, pixels/sec^2
- **drag** -- `Vector2`, deceleration (applied only when acceleration is zero)
- **gravity** -- `Vector2`, per-body gravity added to world gravity
- **bounce** -- `Vector2`, rebound factor relative to 1
- **friction** -- `Vector2`, default `(1, 0)` -- velocity imparted by immovable body to riding body
- **maxVelocity** -- `Vector2`, default `(10000, 10000)` | **maxSpeed** -- scalar cap, default `-1` (none)
- **mass** -- default `1`, affects collision momentum exchange
- **immovable** -- `false`; if `true`, never moved by collisions
- **pushable** -- `true`; if `false`, reflects velocity to colliding body
- **moves** -- `true`; if `false`, position/rotation not updated by physics
- **enable** -- `true`; `false` removes from simulation
- **useDamping** -- `false`; when `true`, drag is a multiplier (0-1) instead of linear
- **collideWorldBounds** -- `false`; **onWorldBounds/onCollide/onOverlap** -- `false`, set `true` to emit events

Shape: **isCircle** (set via `setCircle`), **width/height**, **offset** (`Vector2`), **center** (read-only midpoint).

Collision state (read-only, reset each step): **touching** / **blocked** / **wasTouching** -- `{ none, up, down, left, right }`. **embedded** -- both overlapping with zero velocity.

Angular: **angularVelocity** (deg/sec), **angularAcceleration**, **angularDrag**, **maxAngular** (default 1000), **allowRotation** (default true).

### Static Bodies (`StaticBody`)

A static body never moves and is not affected by gravity or velocity. It uses an optimized RTree for fast spatial lookups.

- Created via `this.physics.add.staticSprite()`, `this.physics.add.staticImage()`, or `this.physics.add.staticGroup()`.
- After changing the parent Game Object's position or scale, call `body.reset()` or `gameObject.refreshBody()` to sync.
- Has `collisionCategory` and `collisionMask` like dynamic bodies.
- Does not have velocity, acceleration, drag, or gravity properties.

## Common Patterns

### Enabling Physics on Existing Game Objects

```js
// Add a physics body to any existing Game Object
this.physics.add.existing(mySprite);           // dynamic body
this.physics.add.existing(mySprite, true);     // static body

// Or enable via the world directly
this.physics.world.ena

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/phaserjs/phaser
git -C phaser checkout d14f4c86f869

Works in

1. 2026-10-31
   ✓SAFE B 89 / 100

   first audit · source d14f4c86f869

Questions about physics-arcade

• github.com/phaserjs/phaser/tree/master/skills/physics-arcade — the audited source at commit d14f4c86f869 and every finding aboveObserved · 31 Oct 2026

Spotted something wrong? Report a correction · Methodology