/pixi-cull

a library to visibly cull objects designed to work with pixi.js

Primary LanguageTypeScriptMIT LicenseMIT

pixi-cull

A library to visibly cull objects designed to work with pixi.js (but not dependent on pixi.js).

Includes two types of culling algorithms: simple and spatial hash. The spatial hash may be also be used for collision detection, AI, etc.

Features include:

  • automatic calculate bounding boxes for pixi.js objects
  • also allow manual calculation for objects
  • bounds calculated from any viewport including pixi-viewport (pixi-viewport.getVisibleBounds())

Moving from v1 to v2

pixi-cull has been reworked and ported to typescript. The following functionality was removed:

  • removed the options to change the object's parameter names for AABB, dirty, spatial, and visible (this greatly simplified) the code
  • removed calculatePIXI as an option, since this library is now solely designed for pixi.js

Rationale

Since I maintain pixi-viewport, I was asked a number of times for a culling library. Well here it is. Choose from two drop-in algorithms to cull your objects.

Simple Example

import * as PIXI from "pixi.js"
import { Viewport } from "pixi-viewport"
import { Simple, SpatialHash } from "pixi-cull"

const app = new PIXI.Application()
document.body.appendChild(app.view)

// create viewport
const viewport = new Viewport({
  screenWidth: app.view.offsetWidth,
  screenHeight: app.view.offsetHeight,
  worldWidth: 10000,
  worldHeight: 10000,
})

app.stage.addChild(viewport)
viewport.drag().pinch().wheel().decelerate().moveCenter(5000, 5000)

// add red boxes
for (let i = 0; i < 500; i++) {
  const sprite = viewport.addChild(new PIXI.Sprite(PIXI.Texture.WHITE))
  sprite.tint = 0xff0000
  sprite.width = sprite.height = 100
  sprite.position.set(Math.random() * 10000, Math.random() * 10000)
}

const cull = new Simple() // new SpatialHash()
cull.addList(viewport.children)
cull.cull(viewport.getVisibleBounds())

// cull whenever the viewport moves
PIXI.Ticker.shared.add(() => {
  if (viewport.dirty) {
    cull.cull(viewport.getVisibleBounds())
    viewport.dirty = false
  }
})

Live Example

https://davidfig.github.io/pixi-cull/

API Documentation

https://davidfig.github.io/pixi-cull/jsdoc/

Installation

npm i pixi-cull

or grab the latest release and use it:

<script src="/directory-to-file/pixi.js"></script>
<script src="/directory-to-file/pixi-cull.min.js"></script>
<script>
  const SimpleCull = new Cull.Simple()
</script>

license

MIT License (c) 2021 YOPEY YOPEY LLC by David Figatner