# npm

## vinage

0.2.0 • Public • Published

# Vinage

Vinage is a collision library usable in both the browser and Node.js. It supports wrap-around. Your JavaScript implementation needs to support `Proxy` for it to work. Firefox 18+, Chrome 49+ and Node.js 6+ work.

## Geometric objects

To use it, you must define instances of the classes listed below, which represent geometric objects in a 2D space. You can modify some properties, as indicated. Other properties are calculated when you read them, then cached. When accessed again, they are either retrieved or recalculated, depending on the modifications you made to other properties of the object.

### vinage.Point(x, y)

#### Properties

• `x`: the point's x-coordinate (abscissa). Writable
• `y`: the point's y-coordinate (ordinate). Writable

### vinage.Vector(x, y) or vinage.Vector(pointOne, pointTwo)

An euclidean vector.

#### Properties

• `x`: the vector's x-component. Writable
• `y`: the vector's y-component. Writable
• `orthogonalVector`: a vector which is orthogonal to the vector
• `length`: the length of the vector

#### Methods

• `dotProduct(vector)`: returns the dot product of the vector and the other vector passed as a parameter
• `normalize()`: make the vector into a unit vector
• `apply(point)`: adds the vector to `point`'s coordinates

#### Properties

• `center`: a point, the center of the circle
• `radius`: the circle's radius. Writable

### vinage.Rectangle(point, width, height[, angle])

#### Properties

• `center`: a point, the center of the rectangle
• `width`: the width of the rectangle. Writable
• `height`: the height of the rectangle. Writable
• `angle`: the angle defining the orientation of the rectangle. Writable
• `vertices`: an array of points, which are the vertices of the rectangle

#### Methods

• `project(vector)`: returns the projection of the rectangle against an axis
• `forget()`: vinage may prevent rectangles from being garbage collected1. If you don't want to use a rectangle anymore, for example before using `delete` on it or replacing it with something else, please use this method. Do not use an object this method has been used on.

## Universes

If you want to check for collision, you must first define a universe where collisions happen. Universes are mere instances of Rectangle.

Most of the time you will want them to happen in an Cartesian plane (i.e. an infinite universe). You can create it like this:

However, if you want to implement wrap-around, you will need a bounded and finite universe:

If your universe is finite and one of your geometric object overlap the "edge" of the universe, it will be as if this part of it was actually on the other side of the universe. Note that your geometric objects can be beyond the limits of the universe; tests are internally remapped inside the universe.

## Collisions

You can check for collisions under your universe like this:

## How it works

Vinage relies on the Proxy object (introduced in ES6) to cache data. Every instance of the above classes is actually a proxy to a regular object. When a modification is made to a writable property, the proxy object searches for read-only properties relying on it, and keep a reminder that they must be calculated again. The next time one of those read-only properties will be retrieved, it will be recalculated and recached.

Every instance has a `_upToDate` property, where it is stored in an object (used as a map) whether properties must be calculated (a boolean is used). Every instance has a `_cache` property, an object (used as a map) where calculated values are stored. `Vector` and `Rectangle` instances have a `_proxyMap` property, inherited from their prototype, an object (used as a map) which contains for each modifiable variable, the list of the calculated variable which will have to be refreshed. `Point` instances have a `_proxyMap` property, inherited from their prototype, an object (used as a map) which contains for each modifiable variable, the list of the calculated variable which will have to be refreshed on the parent. That list takes into account the parent's type.

## Testing

You can open `graphical-tester.svg` in your browser and move around elements to check if collisions work as intended. When the library reports a collision the colliding elements are red, otherwise they are green.

## Footnotes

1: This happens when an object is child of multiple parents (for example a point used as the center of differents rectangles), because the child keeps a reference to each parent.

## Keywords

### Install

`npm i vinage`

### Repository

github.com/KordonBleu/vinage

### Homepage

github.com/KordonBleu/vinage

1

0.2.0