pixi-collision-system

This is a simple library for creating collisions based on static black and white collision maps and dynamic collisions for sprites.

It is recommended to create static collision maps using Collision map maker. You can read about how to use the Collision map maker in this article.

Example

Try this example (use WASD or arrows to control the character)

Installation

Npm

npm install pixi-collision-system

Import

import CollisionSystem from 'pixi-collision-system'

CDN

    <script src = 'https://cdn.jsdelivr.net/npm/pixi-collision-system@latest/cdn/index.min.js'></script>

Description of the concept

The idea is very simple. We have two maps in our scene:

1. Front map - a beautiful map that the user sees.
2. Collision map - black and white map. It is invisible to the user.

When you move your sprite, the pixi-collision-system determines if the sprite can move further or not.

If there is a dynamic collision ahead (another sprite) or a black pixel in a static collision map, our sprite will not be able to move forward.

Usage

For a complete picture of what is happening, I recommend looking at the example code

    import * as PIXI from 'pixi.js'
    import CollisionSystem from 'pixi-collision-system'

    // Init PIXI app
    const app = new PIXI.Application(options)

    // Use some function for creating maps
    const front_map = createFrontMap()
    const collision_map = createCollisionMap()

    // Use some function for creating sprites
    const character = createSprite()
    const sprite = createSprite()

    // Create instance of Collision System
    const System = new CollisionSystem({ collision_map, front_map }, app, PIXI)

    // Draw collision sprite in collision_map
    System.createCollision(sprite)

    // Get actual collision options
    const options = System.getCollisionOptions(sprite)

    // Increase collision scaleX += 0.1 and change shape to 'rect'
    System.updateCollision(sprite, { scaleX: options.scaleX + 0.1, shape: 'rect' })

    // Check if there is a collision at coordinates north of the character
    const bool = System.isCollision(character.position.x, character.position.y + 50)

    // Try moving the character to the west
    System.moveWithCollisions(character, 'walkW')

    // Get PIXI.Graphics collision
    System.getCollisionBySprite(sprite)

    // Remove the collision (сollision is removed automatically when the sprite is removed)
    System.removeCollision(sprite)

    // Hide/show front map
    System.displayFrontMap(false)

Api

Collision options

Options shown with default values

options = {
    shape: 'ellipse', // The geometric shape of the collision (can be 'ellipse' or 'rect')
    scaleX: 0, // Scale by x coord
    scaleY: 0, // Scale by y coord
    rotation: 0, // Rotation
}

Constructor

const System = new CollisionSystem({front_map, collision_map}, app, PIXI)

Initializes everything necessary for the operation of the CollisionSystem

1. front_map and collision_map are PIXI Sprites. In the example, TilingSprites are used

2. app is PIXI.Application

3. PIXI is PIXI himself

Create Collision

System.createCollision(sprite, options)

Creates a collision for the sprite.

See Collision options at the top for a better understanding of what options the method accepts.

options is not required

Update Collision

System.updateCollision(sprite, options)

Use this function to change the collision (its size, rotation, shape)

See Collision options at the top for a better understanding of what options the method accepts.

options is not required

Remove Collision

System.removeCollision(sprite)

You can manually remove the collision if you need to. The collision will also be removed automatically if you delete the sprite to which it is attached.

Is Collision

System.isCollision(x, y)

Checks x, y coordinates. If these coordinates contain a black pixel of a static collision_map or a dynamic sprite collision created by createCollision return true.

(Converts coordinates to local collision_map coordinates. Don't worry if your front_map and collision_map are the same size)

Move with collisions

System.moveWithCollisions(sprite, direction, options)

Allows you to move the sprite in one of the available directions using collisions.

Available directions

'walkNE', 'walkNW', 'walkN', 'walkSE', 'walkSW', 'walkS', 'walkE', 'walkW'

Available options (Default values)

options = {
    marginTop: 30,
    marginBottom: 10,
    marginRight: 30,
    marginLeft: 30,
    speed: 5,
    stepXY: speed * app.ticker.deltaTime,
    stepD: stepXY * 0.707
}

marginTop, marginBottom, marginRight, marginLeft - It's like margin from css. If you want to increase or decrease the distance between the character and collisions, you can change these values. The default values ​​are fine if your sprite's anchor is at the feet sprite.anchor.set(0.5, 1)

speed - The speed at which the sprite will move.

stepXY - Most of the time it doesn't need to be changed. This is the character's step in x and y

stepD - Most of the time it doesn't need to be changed. This is the character's diagonal step.

options is not required

Get collision options

System.getCollisionOptions(sprite)

Returns Collision options for the current collision

See Collision options at the top for a better understanding of what options the method returns.

Get collision by sprite

System.getCollisionBySprite(sprite)

If you need the collision itself (PIXI.Graphics), you can get it with this method

Display front map

System.displayFrontMap(bool)

Sometimes it is useful to hide the front_map. This method will help hide/show front_map

Useful things

Collision map maker

It is recommended to create collision maps using Collision map maker

Medium articles

Pixi-collision-system article

Collision map maker tutorial