Use Phaser 4 Arcade Physics: enable the world, give sprites bodies, set velocity/acceleration/gravity, and resolve collisions with colliders, overlaps, groups, and world bounds. Use when a Phaser game needs movement or collisions — when the user mentions Arcade Physics, this.physics, setVelocity, co

Phaser 4 Arcade Physics Add movement and collision to a Phaser game with the lightweight Arcade Physics engine (AABB rectangles and circles only). Targets Phaser 4.2 for new projects; inspect the installed major before editing an existing project. When to use Use for top down or platformer movement, velocity/acceleration/gravity, bouncing, world bounds, and collision/overlap resolution between sprites, groups, and tiles. Use when the scene enables physics: { default: 'arcade' } and code calls this.physics.add. , body.setVelocity , or this.physics.add.collider . When not to use: the Game config, scene structure, asset loading, or cameras → use phaser core . Hinges, springs, complex polygons, or stacking rigid bodies → use Matter physics (a different engine; Arcade and Matter bodies do not interact). For engine agnostic feel tuning see physics tuning . Core workflow 1. Enable the world. Set physics: { default: 'arcade', arcade: { gravity: {...}, debug: true } } in the game or scene config. Turn debug on while building to see body outlines and velocity vectors. 2. Give a sprite a body. Create it with this.physics.add.sprite(...) (dynamic) or this.physics.add.staticImage(...) (static), or attach to an existing object with this.physics.add.existing(obj) . 3. Drive it through the body, not by setting x / y . Use setVelocity , setAcceleration , gravity, setBounce , and setCollideWorldBounds . The engine integrates position from velocity each step (already frame rate independent). 4. Resolve interactions. this.physics.add.collider(a, b) separates bodies; this.physics.add.overlap(a, b, cb) detects without separating (pickups, triggers). Pass a callback to react. 5. Group many objects. Use this.physics.add.group() (dynamic) or staticGroup() (platforms) so one collider call handles all members. 6. Check ground contact with body.onFloor() / body.blocked.down before jumping. Run with debug: true and confirm bodies, contacts, and bounds. Patterns 1. Enable Arcade Physics (game config) 2. Top down movement (velocity from input) 3. Platformer jump (gravity + ground check) 4. Colliders vs overlaps (separate vs detect) 5. A group of moving objects Pitfalls Sprite ignores physics → it was added with this.add.sprite instead of this.physics.add.sprite (or this.physics.add.existing(obj) ), so it has no body. Setting sprite.x directly fights the engine → move dynamic bodies with setVelocity / setAcceleration . Direct position writes can tunnel through colliders. Diagonal movement is faster → independent X and Y velocities add up; normalise the velocity vector and rescale to the intended speed. Platforms get pushed by the player → use a staticGroup , or set body.setImmovable(true) on a dynamic platform. onFloor() is always false → the body needs something to collide with; add the collider against the ground/platforms before checking, and ensure gravity is on. Standing on an ordinary dynamic body does not count as blocked; make platforms static, immovable, or non pushable ( platform.setPushable(false) ). Moved a static body but collisions are stale → static bodies don't auto sync; call body.updateFromGameObject() (or refreshBody() on the game object). Collider added every frame → register collider / overlap once in create , not in update . Fast bullets pass through thin walls → Arcade has no swept collision; a body that moves farther than a wall's thickness in one physics step skips it. Thicken the wall's body, cap speed with setMaxVelocity , or raise the step rate ( arcade: { fps: 120 } , default 60) at extra CPU cost. Bodies pass through each other after adding collision categories → a pair only collides when each side's mask includes the other's category, and untouched bodies keep mask 1 . Widen the other side's mask too, and set groups and their members separately (see the reference). Drag does nothing while a key is held → Arcade applies drag only on an axis with zero acceleration; set the acceleration to 0 when input stops. References For body anatomy and tuning (drag, bounce, max velocity, custom setSize / setCircle / setOffset hitboxes, collision categories/masks, and worldbounds events), read references/bodies and collision.md . Related skills phaser core — game config, scenes, loader, cameras (the prerequisite setup). physics tuning — engine agnostic feel (fixed timestep, tunneling, jitter). platformer / tower defense — genres that compose this skill. level design — laying out tile/platform geometry these bodies collide with.

phaser-arcade-physics