aframe-vertical-billboard-component

a simple vertical "billboard" component and primitive for A-Frame

Three.js Sprites are planes which always face the camera - but sometimes, the vertical axis of such objects should keep pointing upwards, regardless of the current camera position: that's what "billboards" are good for.

aframe-vertical-billboard-component implements a simple vertically oriented billboard component for A-Frame.

NPM users: please consider the Github README for the latest description of this package (as updating the docs would otherwise always require a new NPM package version)

Just a small note: if you like this work and plan to use it, consider "starring" this repository (you will find the "Star" button on the top right of this page), so that I know which of my repositories to take most care of.

Installation

aframe-vertical-billboard-component may be used as an ECMAScript module (ESM) or explicitly loaded after the <script> tag for A-Frame itself.

For the ESM variant, install the package into your build environment using NPM with the command

npm install aframe-vertical-billboard-component

and import it into your code whereever needed

import "aframe-vertical-billboard-component"

Otherwise, load the plain script file directly

<script src="https://unpkg.com/aframe-vertical-billboard-component"></script>

Properties

aframe-vertical-billboard-component is an A-Frame component with the following properties:

Usage

Once loaded or imported, aframe-vertical-billboard-component may be used as a component of a plain A-Frame entity

<a-scene>
  <a-assets>
    <img id="BillboardTexture" src="..."/>
  </a-assets>
  <a-entity billboard="map:#BillboardTexture; height:2" position="0 0 0"></a-entity>
</a-scene>

Without a valid map, the billboard will remain invisible. If one of width or height is 0, its value will be computed from the other setting (which should therefore be > 0) and the natural aspect ratio of the map (if both values are 0, the height will be set to 1)

Since billboards are naturally vertical objects, their position will not specify their center, but the middle of their lower edge - this helps positioning them programmatically.

Example

Here is a complete example (albeit without the HTML boilerplate)

<script src="https://unpkg.com/aframe"></script>
<script src="https://unpkg.com/aframe-hemisphere-controls"></script>
<script src="https://unpkg.com/aframe-vertical-billboard-component"></script>

<a-scene embedded
  hemisphere-controls="position:0 0.5 4; target:0 0 0"
  style="width:600px; height:450px"
>
  <a-assets>
    <img id="Tree" src="https://raw.githubusercontent.com/rozek/aframe-vertical-billboard-component/main/free-standing-Tree.png"/>
  </a-assets>

  <a-sky color="#ECECEC"></a-sky>

  <a-plane width="4" height="4" color="#7BC8A4"
    position="0 0 0" rotation="-90 0 0"></a-plane>

  <a-entity billboard="map:#Tree; height:2" position="-2 0 0.5"></a-entity>
  <a-entity billboard="map:#Tree; height:2" position=" 0 0 0"></a-entity>
  <a-entity billboard="map:#Tree; height:2" position=" 2 0 -0.5"></a-entity>
</a-scene>

The tree texture was made by Krzysztof Czerwiński, taken from the freebies section of his blog and scaled down in order to save resources - it is free even for commercial use.

Build Instructions

You may easily build this package yourself.

Just install NPM according to the instructions for your platform and follow these steps:

1. either clone this repository using git or download a ZIP archive with its contents to your disk and unpack it there
2. open a shell and navigate to the root directory of this repository
3. run npm install in order to install the complete build environment
4. execute npm run build to create a new build

You may also look into the author's build-configuration-study for a general description of his build environment.

License

MIT License