# hecs-plugin-three

> A plugin for hecs that provides rendering, models and primitive shapes via three.js

Latest version **0.17.0** (published 2020-10-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install hecs-plugin-three
pnpm add hecs-plugin-three
yarn add hecs-plugin-three
bun add hecs-plugin-three
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.17.0 |
| Published | 2020-10-28 |
| First published | 2020-08-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 85.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 23 |
| Author | Ash Connell |
| Maintainers | ashconnell |
| Keywords | ECS, plugin, archetype, entity, component, system |

## Links

- npm: https://www.npmjs.com/package/hecs-plugin-three
- Repository: https://github.com/gohyperr/hecs
- Homepage: https://github.com/gohyperr/hecs/tree/master/packages/hecs-plugin-three
- Issues: https://github.com/gohyperr/hecs/issues
- npm.io page: https://npm.io/package/hecs-plugin-three

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 0.17.0 (latest) — 2020-10-28
- 0.16.0 — 2020-10-27
- 0.14.0 — 2020-09-14
- 0.13.0 — 2020-09-14
- 0.12.0 — 2020-09-14
- 0.11.0 — 2020-09-04
- 0.10.0 — 2020-08-31
- 0.9.0 — 2020-08-26
- 0.8.1 — 2020-08-25
- 0.8.0 — 2020-08-25
- 0.7.2 — 2020-08-24
- 0.7.1 — 2020-08-23
- 0.7.0 — 2020-08-23

## README

| :warning: Important: This package is WIP and is not ready for use |
| --- |

# Hecs Plugin Three

A plugin for Hecs that adds functionality to render three.js models and primitives. When used in node or without a viewport configured then appropriate systems become inactive.

---

## Usage

Install via npm/yarn:

```
yarn add hecs hecs-plugin-core hecs-plugin-three three
```

Add the plugin to your plugin list when creating a World

```js
import { World } from 'hecs'
import ThreePlugin from 'hecs-plugin-three'

const world = new World({
  plugins: [ThreePlugin],
  systems: [/* your systems */],
  components: [/* your components */],
})
```

A world instance with this plugin installed can now use all of the features below:

---

### World.presentation.scene

This is the three.js scene used internally. It's available if you need it but completely optional.

### World.presentation.setViewport(DOMElement)

Configuring this with a DOMElement will attach the renderer and start rendering your scenes to it. Interally it uses ResizeObserver to watch for resize and automatically updates the camera and renderer perspectives. When no viewport is defined nothing will be rendered and some systems will run passively. Can be unset with `null`

### World.presentation.takePhoto(width, height)

Allows you to take a photo of the scene at any arbitrary size, from the point of view of the camera. The returned value is a base64 string representing the image. Internally this uses CanvasElement.toDataURL().
This is useful for editors to generate thumbnails of a scene, but could also be used during a running simulation to take photos.

### Camera (Component)

Adding this component to an entity controls where the camera is in the scene. This component is a singleton so adding it to another entity will remove it from any previous entity.

Requires: `Transform`

```js
import { Transform } from 'hecs-plugin-core'
import { Camera } from 'hecs-plugin-three'

entity
  .add(Transform)
  .add(Camera)
```

### Model (Component)

Adding this component to an entity will load and render a GLTF asset.

Field|Type|Default|Description
---|---|---|---
asset|Asset|new Asset()|The asset to load and use for the model

Requires: `Transform`

Advanced: You can determine whether a model is still loading by looking for a `ModelLoading` component. Once loaded, a `ModelMesh` component is available to access the actual three.js mesh.


```js
import { Transform, Asset } from 'hecs-plugin-core'
import { Model } from 'hecs-plugin-three'

entity
  .add(Transform)
  .add(Model, { 
    asset: new Asset('me.com/spaceship.glb') 
  })
```

### Shape (Component)

Adding this component to an entity will build and render a primitive shape

Field|Type|Default|Description
---|---|---|---
kind|String|'BOX'|The kind of shape to build. Must be one of `BOX`, `SPHERE` or `CAPSULE`
boxSize|Vector3|new Vector3(1, 1, 1)|The size of the box. Only applicable when kind is `BOX`.
sphereRadius|Number|0.5|The radius of the sphere. Only applicable when kind is `SPHERE`.
sphereWidthSegments|Number|16|The width segments of the sphere. Only applicable when kind is `SPHERE`.
sphereHeightSegments|Number|12|The height segments of the sphere. Only applicable when kind is `SPHERE`.
capsuleRadius|Number|0.5|The radius of the capsule. Only applicable when kind is `CAPSULE`.
capsuleHeight|Number|1|The height of the capsule. Only applicable when kind is `CAPSULE`.
capsuleSegments|Number|5|The number of segments for the capsule. Only applicable when kind is `CAPSULE`.
color|Color|'#fff'|The color of the shape.

Requires: `Transform`

Advanced: A `ShapeMesh` component is available to access the actual three.js mesh.


```js
import { Transform, Vector3 } from 'hecs-plugin-core'
import { Shape } from 'hecs-plugin-three'

entity
  .add(Transform)
  .add(Shape, { 
    kind: 'BOX',
    boxSize: new Vector3(1, 1, 1),
    color: 'purple'
  })
```

### Object3D (Component)

All entities with a `Transform` are given an `Object3D` component which will be displayed in the scene in the correct hierarchical position. This container is used internally for all `Model` and `Shape` meshes that are created.

Field|Type|Default|Description
---|---|---|---
value|Object3D|new Object3D()|The object3d

Advanced: You can use this container to add and remove your own meshes without needing to worry about scene hierarchy. See how this can be done in the ModelSystem and ShapeSystem.

### Image (Component)

Adding this component to an entity will render an image at its location

Field|Type|Default|Description
---|---|---|---
asset|Asset|new Asset()|The image asset to render
width|Number|1|The width of the plane the image is displayed on.
height|Number|1|The height of the plane the image is displayed on.
fit|String|'CONTAIN'|The fitting mode. `CONTAIN` means the image will be made to fit inside of the width and height props. `COVER` means the image will be resized to ensure it covers all width and height surface, cropping the overflow.

Requires: `Transform`


```js
import { Transform, Asset } from 'hecs-plugin-core'
import { Image } from 'hecs-plugin-three'

entity
  .add(Transform)
  .add(Image, { 
    asset: new Asset('billboard-sign.png'),
    width: 6,
    height: 3,
    fit: 'COVER',
  })
```

### LookAt (Component)

An entity with this component will have its transform constantly updated to look at it's target

Field|Type|Default|Description
---|---|---|---
entity|String|''|The target entity id
limit|String|'NONE'|Limits the axis of rotation. `NONE` means all axis will be rotated, `Y_AXIS` means only Y will rotate. You can also use `X_AXIS` and `Z_AXIS`.

Requires: `Transform`


```js
import { Transform, Asset } from 'hecs-plugin-core'
import { LookAt, Image } from 'hecs-plugin-three'

entity
  .add(Transform)
  .add(Image, { asset: new Asset('billboard-sign.png') })
  .add(LookAt, { 
    entity: '0:1',
    limit: 'Y_AXIS'
  })
```

### LookAtCamera (Component)

Works the same as the `LookAt` component but always targets the camera.

Field|Type|Default|Description
---|---|---|---
limit|String|'NONE'|Limits the axis of rotation. `NONE` means all axis will be rotated, `Y_AXIS` means only Y will rotate. You can also use `X_AXIS` and `Z_AXIS`.

Requires: `Transform`


```js
import { Transform, Asset } from 'hecs-plugin-core'
import { LookAtCamera, Image } from 'hecs-plugin-three'

entity
  .add(Transform)
  .add(Image, { asset: new Asset('billboard-sign.png') })
  .add(LookAtCamera, { limit: 'Y_AXIS' })
```

---
_Source: https://npm.io/package/hecs-plugin-three · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._