Docs

Hologram allow you to building virtual reality (VR) experiences. It is focus on simplicity and fun. It is easy to get started with Hologram. With the scene editor, you don't even need a single line of code to create your first scene! Hologram supports most VR headsets such as Vive, Rift, Daydream, GearVR, Cardboard.

Get started

  1. Entities

    Entities can be Box, Sphere, Plane, Sky and more. They have a hierarchy and properties defining their position, rotation, scale, appearance and interactivity.

    More on Entities

  2. Animation

    Animate states or layer properties like scale and color with various easing or spring curves, repeat and delay options and more.

    More on Animation

  3. Events

    Events are used to detect and respond to user interactions in VR when clicking or gazing, animations that start or end, respond to physics events and more.

    More on Events

  4. Assets

    Assets can be images, sounds, video, 3D models. The asset management system allows you to place your assets in one place and to preload and cache assets for better performance.

    More on Assets

Simple example

Here is a simple example to get you started!

myBox = new Box
  x: -1, y: 0.5, z: -3
  rotationY: 45
  color: "#4CC3D9"

mySphere = new Sphere
  y: 1.25, z: -5
  radius: 1.25
  color: "#EF2D5E"

myCylinder = new Cylinder
  x: 1, y: 0.75, z: -3
  radius: 0.5
  color: "#FFC65D"

myPlane = new Plane
  z: -4
  rotationX: -90
  width: 4
  height: 4
  color: "#7BC8A4"

mySky = new Sky
  color: "#ECECEC"

Animation

Animate entities is fairly simple, here is a first example:

myBox = new Box
    z: -5
    color: Color.cyan

myBox.animate
    rotationY: 360
    time: 3
    direction: Direction.reverse
    then: ->
        print "Animation done"

Alternatively you can also use the Animation object which allow you to start then animation whenever you desire.

myBox = new Box
    z: -5
    color: Color.cyan

myAnimation = new Animation
    entity: myBox
    rotationY: 360
    time: 3
    direction: Direction.reverse
    then: ->
        print "animation done"

myAnimation.start()

animate.time number

Duration in seconds of the animation. Default is 1.

myCone = new Cone
    color: Color.aquamarine

myCone.animate
    x: 2
    time: 4

animate.delay number

Delay in seconds before starting the animation. Default is 0.

myLight = new Light
    intensity: 1

myLight.animate
    intensity: 3
    time: 4
    delay: 0.5

animate.direction string

The direction attribute defines which way to animate between the starting value and the final value. When we define an alternating direction, the animation will go back and forth between the from and to values like a yo-yo. Alternating directions only take affect when we repeat the animation.

myCone = new Cone
    color: Color.gold

myCone.animate
    x: 2
    time: 4
    direction: reverse
Direction available:
  • Direction.alternate
  • Direction.alternateReverse
  • Direction.normal
  • Direction.reverse

animate.repeat number

The repeat attribute defines how often the animation repeats. Default is 0.

myCone = new Cone
    color: Color.green

myCone.animate
    x: 2
    time: 4
    repeat: 10

animate.curve string

Easing function of the animation. There are very many to choose from. Default is ease.

Curves available:
Basic effects
  • Curve.linear
  • Curve.ease
  • Curve.easeIn
  • Curve.easeOut
  • Curve.easeInOut
More effects
  • Curve.easeCubic, Curve.easeInCubic, Curve.easeOutCubic, Curve.easeInOutCubic
  • Curve.easeQuad, Curve.easeInQuad, Curve.easeOutQuad, Curve.easeInOutQuad
  • Curve.easeQuart, Curve.easeInQuart, Curve.easeOutQuart, Curve.easeInOutQuart
  • Curve.easeQuint, Curve.easeInQuint, Curve.easeOutQuint, Curve.easeInOutQuint
  • Curve.easeSine, Curve.easeInSine, Curve.easeOutSine, Curve.easeInOutSine
  • Curve.easeExpo, Curve.easeInExpo, Curve.easeOutExpo, Curve.easeInOutExpo
  • Curve.easeCirc, Curve.easeInCirc, Curve.easeOutCirc, Curve.easeInOutCirc
  • Curve.easeElastic, Curve.easeInElastic, Curve.easeOutElastic, Curve.easeInOutElastic
  • Curve.easeBack, Curve.easeInBack, Curve.easeOutBack, Curve.easeInOutBack
  • Curve.easeBounce, Curve.easeInBounce, Curve.easeOutBounce, Curve.easeInOutBounce

animate.fill string

The fill attribute defines the effect of animation when not actively in play. Think of fill as what values the animation sets on the entity before and/or after each animation cycle. Below are the possible values for fill and their effects. Default is forwards.

  • Fill.backwards
  • Fill.both
  • Fill.forwards
  • Fill.none

animate.then function

Called when the animation finishes. In case of repeats, emitted when the repeat count reaches 0. Not emitted for indefinite repeats.

myCone = new Cone
    color: Color.yellow

myCone.animate
    x: 2
    time: 4
    then: ->
        print "I am done!"

Assets

Hologram has an asset management system that allows you to place your assets in one place and to preload and cache assets for better performance.

Games and rich 3D experiences traditionally preload their assets, such as models or textures, before rendering their scenes. This makes sure that assets aren’t missing visually, and this is beneficial for performance to ensure scenes don’t try to fetch assets while rendering.

Assets include:

  • AssetModel, AssetItem: 3D models, textures
  • AssetAudio: Sound files
  • AssetImage: Image textures
  • AssetVideo: Video textures

Note: The scene won’t render or initialize until the browser fetches (or errors out) all the assets or the asset system reaches the timeout.

myCat = AssetImage 'assets/cat.jpg'
mySong = AssetAudio 'assets/song.mp3'
myVideo = AssetVideo 'assets/coolMovie.mp4'
myObject = AssetModel 'assets/object.obj'
myObjectTexture = AssetItem 'assets/object.mlt'
myVideo = AssetVideo 'assets/coolMovie.mp4'

Setting a Timeout

We can set a timeout that when reached, the scene will begin rendering and entities will begin initializing regardless of whether all the assets have loaded. The default timeout is 3 seconds. To set a different timeout, we just pass in the number of milliseconds to the timeout attribute:

If some assets are taking a long time to load, we may want to set an appropriate timeout such that the user isn’t waiting all day in case their network is slow.

Hologram.assets.timeout = 10000

Box

Extends: Entity

Box creates shapes such as boxes, cubes, or walls. It is an entity that prescribes the geometry with its geometric primitive set to box.

myBox = new Box
    z: -2
    width: 1
    height: 1
    depth: 1

box.width number

Set the width of the box. Default is 1.

myBox = new Box
    width: 2

box.height number

Set the height of the box. Default is 1.

myBox = new Box
    height: 5

box.depth number

Set the depth of the box. Default is 1.

myBox = new Box
    depth: 3

box.color color

Defines the color of the cube. Default is white.

myBox = new Box
    z: -2
    width: 1
    height: 1
    depth: 1
    color: "red"

box.transparent boolean

Set the transparency of the box. Default is yes.

myBox = new Box
    z: -2
    width: 1
    height: 1
    depth: 1
    transparent: no

box.opacity number

Set the opacity of the box. Default is 1.

myBox = new Box
    z: -2
    width: 1
    height: 1
    depth: 1
    opacity: 0.8

box.metalness number

Set the metalness aspect of the box. Default is 0.

myBox = new Box
    z: -2
    width: 1
    height: 1
    depth: 1
    metalness: 0.5

box.repeat string

Define how many times the texture should be repeated on the cube on the x and y axis. Default is None.

myBox = new Box
    z: -2
    width: 1
    height: 1
    depth: 1
    repeat: '20 20'

box.roughness number

Define the roughness aspect of the cube. Default is 0.5.

myBox = new Box
    z: -2
    width: 1
    height: 1
    depth: 1
    roughness: 1

box.shader string

Define the shader to use to render the cube on the scene. Default is standard.

myBox = new Box
    z: -2
    width: 1
    height: 1
    depth: 1
    shader: Shader.standard

box.side string

Defines which of the face sides will be rendered. Default is front, can be either front, back or double.

myBox = new Box
    z: -2
    width: 1
    height: 1
    depth: 1
    side: Side.double

box.segmentsWidth integer

Sets the segments width when rendering the cube. Default is 1.

myBox = new Box
    z: -2
    width: 1
    height: 1
    depth: 1
    segmentsWidth: 4

box.segmentsHeight integer

Sets the segments height when rendering the cube. Default is 1.

myBox = new Box
    z: -2
    width: 1
    height: 1
    depth: 1
    segmentsHeight: 3

box.segmentsDepth integer

Sets the segments depth when rendering the cube. Default is 1.

myBox = new Box
    z: -2
    width: 1
    height: 1
    depth: 1
    segmentsDepth: 5

box.wireframe boolean

Render the plane wireframe only. Default is false.

myBox = new Box
    wireframe: yes

box.wireframeWidth integer

Wireframe width. Default is 2.

myBox = new Box
    wireframe: yes
    wireframeWidth: 4

box.fog boolean

React to the scene fog. Default is true.

myBox = new Box
    fog: no

Camera

Extends: Entity

The camera places the user somewhere within the scene. It is an entity that prescribes the camera component with mappings to controls-related components.

Let's add a camera situated at the average height of human eye level (1.6 meters).

myCamera = new Camera
    userHeight: 1.6

Note: by default a camera is added to the scene, here is how to access it:

myCamera = Hologram.camera
myCamera.userHeight = 1.6

camera.active boolean

Whether the camera is the active camera in a scene with more than one camera. Default is yes.

myCamera = new Camera
    active: no

camera.far integer

Camera frustum far clipping plane. Default is 10000.

myCamera = new Camera
    far: 15000

camera.fov integer

Field of view (in degrees). Default is 80.

myCamera = new Camera
    fov: 70

camera.near number

Camera frustum near clipping plane. Default is 0.005.

myCamera = new Camera
    near: 0.010

camera.userHeight number

How much height to add to the camera when not in VR mode. The default camera has this set to 1.6 (meters, to represent average eye level.). Default is 0.

myCamera = new Camera
    userHeight: 1.6

camera.zoom number

Zoom factor of the camera. Default is 1.

myCamera = new Camera
    zoom: 1.2

camera.wasdControls boolean

Setting whether the keyboard keys w, a, s, d can move the camera around the scene. Default is yes.

myCamera = new Camera
    wasdControls: no

camera.mouseCursor boolean

Add mouse cursor on the camera. A alternative to the cursor useful in development. Default is yes.

Hologram.camera.mouseCursor = no

VR Behavior

When not in VR mode, userHeight translates the camera up to approximate average height of human eye level. The injected camera has this set to 1.6 (meters). When entering VR, this height offset is removed such that we used absolute position returned from the VR headset. The offset is convenient for experiences that work both in and out of VR, as well as making experiences look decent from a desktop screen as opposed to clipping the ground if the headset was resting on the ground.

When exiting VR, the camera will restore its rotation to its rotation before it entered VR. This is so when we exit VR, the rotation of the camera is back to normal for a desktop screen.


Changing the Active Camera

When the active property gets toggled, the component will notify the camera system to change the current camera used by the renderer:

mySecondCamera = new Camera
    active: yes

Fixing Entities to the Camera

To fix entities onto the camera such that they stay within view no matter where the user looks, you can attach those entities as a child of the camera. Use cases might be a heads-up display (HUD).

myCamera = new Camera()

myBox = new Box
    z: -2
    parent: myCamera

Note that you should use HUDs sparingly as they cause irritation and eye strain in VR. Consider integrating menus into the fabric of the world itself. If you do create a HUD, make sure that the HUD is more in the center of the field of view such that the user does not have to strain their eyes to read it.

Circle

Extends: Entity

The circle geometry creates flat two-dimensional circles. These can be complete circles or partial circles (like Pac-Man).

myCircle = new Circle
    color: "#CCC"
    radius: 20

circle.color color

Defines the color of the circle. Default is white.

myCircle = new Circle
    color: Color.blue

circle.radius integer

Defines the radius of the circle. Default is 1.

myCircle = new Circle
    radius: 3
    color: Color.red

circle.src string/AssetImage

Defines the material used when rendering the circle.

myCircle = new Circle
    src: "assets/cat.png"

texture = AssetImage "assets/texture2.png"
myCircle = new Circle
    src: texture

Note that if you add the texture in Assets then you only need to specify the name of the asset.

myCircle = new Circle
    src: "cat"

circle.transparent boolean

Set the transparency of the circle. Default is yes.

myCircle = new Circle
    transparent: no

circle.opacity number

Set the opacity of the circle. Default is 1.

myCircle = new Circle
    z: -2
    opacity: 0.8

circle.metalness number

Set the metalness aspect of the circle. Default is 0.

myCircle = new Circle
    radius: 10
    metalness: 0.5

circle.repeat string

Define how many times the texture should be repeated on the circle on the x and y axes. Default is None.

myCircle = new Circle
    z: -2
    repeat: '20 20'

circle.roughness number

Define the roughness aspect of the circle. Default is 0.5.

myCircle = new Circle
    z: -2
    roughness: 1

circle.shader shader

Define the shader to use to render the circle on the scene. Default is standard.

myCircle = new Circle
    shader: Shader.standard

circle.segments integer

Defines the number of segments of the circle. Default is 32.

myCircle = new Circle
    segments: 42

circle.thetaLength integer

Defines the theta length of the circle. Default is 360.

myCircle = new Circle
    z: -2
    thetaLength: 80
    wireframe: yes

circle.thetaStart integer

Defines the theta start value of the circle. Default is 0.

myCircle = new Circle
    z: -2
    thetaLength: 80
    thetaStart: 30
    wireframe: yes

Cone

Extends: Entity

The cone geometry is a cylinder geometry that have different top and bottom radii.

myCone = new Cone
    color: Color.tomato
    radiusTop: 0.5
    radiusBottom: 2

cone.color color

Defines the color of the cone. Default is white.

myCone = new Cone
    color: Color.azure

cone.radiusTop number

Defines the top radius of the cone. Default is 0.8.

myCone = new Cone
    radiusTop: 2
    color: Color.deeppink

cone.radiusBottom number

Defines the bottom radius of the cone. Default is 1.

myCone = new Cone
    radiusTop: 2
    radiusBottom: 3
    color: Color.blue

cone.src string/AssetImage

Defines the material used when rendering the cone.

myCone = new Cone
    src: "assets/cat.png"

texture = AssetImage "assets/texture2.png"
myCone = new Cone
    src: texture

Note that if you add the texture in Assets then you only need to specify the name of the asset.

myCone = new Cone
    src: "cat"

cone.transparent boolean

Set the transparency of the cone. Default is yes.

myCone = new Cone
     transparent: no

cone.opacity number

Set the opacity of the cone. Default is 1.

myCone = new Cone
    z: -1
    opacity: 0.8

cone.metalness number

Set the metalness aspect of the cone. Default is 0.

myCone = new Cone
    radius: 10
    metalness: 0.5

cone.repeat string

Define how many times the texture should be repeated on the cone on the x and y axis. Default is None.

myCone = new Cone
    z: -1
    repeat: '20 20'

cone.roughness number

Define the roughness aspect of the cone. Default is 0.5.

myCone = new Cone
    z: -1
    roughness: 1

cone.shader shader

Define the shader to use to render the cone on the scene. Default is standard.

myCone = new Cone
    shader: Shader.standard

cone.segmentsHeight number

Defines the segments height to use when rendering the cone. Default is 18.

myCone = new Cone
    z: -1
    segmentsHeight: 3

cone.segmentsRadial number

Defines the segments radial to use when rendering the cone. Default is 36.

myCone = new Cone
    z: -1
    segmentsRadial: 4

cone.thetaLength integer

Defines the theta length of the cone. Default is 180.

myCone = new Cone
    z: -1
    thetaLength: 80
    wireframe: yes

cone.thetaStart integer

Defines the theta start value of the cone. Default is 0.

myCone = new Cone
    x: -2
    thetaLength: 80
    thetaStart: 30
    wireframe: yes

cone.wireframe boolean

Render the cone wireframe only. Default is false.

myCone = new Cone
    wireframe: yes

cone.wireframeWidth integer

Wireframe width. Default is 2.

myCone = new Cone
    wireframe: yes
    wireframeWidth: 4

cone.fog boolean

React to the scene fog. Default is true.

myCone = new Cone
    fog: no

Cursor

Extends: Entity

The cursor is a reticle that allows for clicking and basic interactivity with a scene on devices that do not have a hand controller. The cursor lets you interact with entities through clicking and gazing. Here is what it does:

  • Listens for mouse clicks and gaze-based fuses.
  • Captures only the first intersected entity.
  • Emits special mouse and hover events (e.g., relating to mouse down/up/enter/leave).

When the mouse clicks, the closest visible entity intersecting the cursor, if any, will emit a click event. Note the cursor component only applies the ray-casting behavior. To provide a shape or appearance to the cursor, you could apply the geometry and material components.

# Enable the cursor
Hologram.cursor.enabled = true

myBox = new Box
    color: Color.tomato

# When the cursor enter the box, the click event is triggered.
myCamera.onClick ->
    print "clicked"

All the cursor events are listed in the entity events section.

Hologram.cursor.enabled boolean

Hologram.cursor.enabled = true

Hologram.cursor.fuse boolean

Whether cursor is fuse-based. Default is true.

Hologram.cursor.fuse = true

Hologram.cursor.fuseTimeout number

How long to wait in seconds before triggering a fuse-based click event. Default is 1.5.

Hologram.cursor.fuseTimeout = 0.5

Hologram.cursor.maxDistance number

How far can the cursor reach. Default is 1000.

# Max distance of 10 meters
Hologram.cursor.maxDistance = 10

Custom cursor

# Little red cursor
Hologram.cursor.enabled = yes
Hologram.cursor.color = Color.red
Hologram.cursor.radiusInner = 0.005
Hologram.cursor.radiusOuter = 0.01

Super custom cursor

Note: only for the braves. Cursors are entities and therefore can be totally changed to your need.

# Change the position, geometry, material
Hologram.cursor.position = "0 0 -1"
Hologram.cursor.geometry = "primitive: ring; radiusInner: 0.02; radiusOuter: 0.03"
Hologram.cursor.material = "color: black; shader: flat"

Curved Image

Extends: Entity

The curved image primitive creates images that bend around the user. Curved images arranged around the camera can be pleasing for legibility since each pixel sits at the same distance from the user. They can be a better choice than angled flat planes for complex layouts because they ensure a smooth surface rather than a series of awkward seams between planes.

Under the hood, a curved image is a double-sided open-ended cylinder with textures mapped to the inside of the cylinder.

myCurvedImage = new CurvedImage
    src: "assets/image.png"
    height: 3
    radius: 5.7
    thetaLength: 72
    rotationY: 100
    scale: 0.8

Fine-Tuning

Ensuring that the image is not distorted by stretching requires us to carefully set the height, radius, and theta-length attributes relative to the image aspect ratio. Once those values are fine-tuned to avoid distortion, we can use scale to safely adjust the distance of the curved image relative to the user.


curvedImage.color color

Defines the color of the curved image. Default is white.

myCurvedImage = new CurvedImage
    color: Color.blue

curvedImage.radius number

Defines the radius of the curved image. Default is 0.8.

myCurvedImage = new CurvedImage
    radius: 2
    color: Color.indigo

curvedImage.height number

Set the height of the curved image. Default is 1.

myCurvedImage = new CurvedImage
    height: 5

curvedImage.src string/AssetImage

Defines the material used when rendering the curved image.

myCurvedImage = new CurvedImage
    src: "assets/cat.png"

texture = AssetImage "assets/texture2.png"
myCurvedImage = new CurvedImage
    src: texture

Note that if you add the texture in Assets then you only need to specify the name of the asset.

myCurvedImage = new CurvedImage
    src: "cat"

curvedImage.transparent boolean

Set the transparency of the curved image. Default is yes.

myCurvedImage = new CurvedImage
    transparent: no

curvedImage.opacity number

Set the opacity of the curved image. Default is 1.

myCurvedImage = new CurvedImage
    x: -2
    opacity: 0.8

curvedImage.metalness number

Set the metalness aspect of the curved image. Default is 0.

myCurvedImage = new CurvedImage
    radius: 10
    metalness: 0.5

curvedImage.repeat string

Define how many times the texture should be repeated on the curved image on the x and y axies. Default is None.

myCurvedImage = new CurvedImage
    x: -2
    repeat: '20 20'

curvedImage.roughness number

Define the roughness aspect of the curved image. Default is 0.5.

myCurvedImage = new CurvedImage
    x: -2
    roughness: 1

curvedImage.shader shader

Define the shader to use to render the curved image on the scene. Default is standard.

myCurvedImage = new CurvedImage
    shader: Shader.standard

curvedImage.segmentsHeight number

Defines the segments height to use when rendering the curved image. Default is 18.

myCurvedImage = new CurvedImage
    x: -2
    segmentsHeight: 30

curvedImage.segmentsRadial number

Defines the segments radial to use when rendering the curved image. Default is 48.

myCurvedImage = new CurvedImage
    x: -2
    segmentsRadial: 42

curvedImage.thetaLength integer

Defines the theta length of the curved image. Default is 270.

myCurvedImage = new CurvedImage
    x: -2
    thetaLength: 80
    wireframe: yes

curvedImage.thetaStart integer

Defines the theta start value of the curved image. Default is 0.

myCurvedImage = new CurvedImage
    x: -2
    thetaLength: 80
    thetaStart: 30
    wireframe: yes

Cylinder

Extends: Entity

The cylinder geometry creates cylinders in the traditional sense like a Coca-Cola™ can, but it can also define shapes such as tubes and curved surfaces.

# Basic cylinder
myCylinder = new Cylinder
    color: Color.crimson
    height: 3
    radius: 1.5

# Hexagon
hexagon = new Cylinder
    color: Color.cyan
    segmentsRadial: 8

# Pac-Man
pacMan = new Cylinder
    color: Color.yellow
    thetaStart: 50
    thetaLength: 280
    side: Side.double

# Green pipe
hexagon = new Cylinder
    color: Color.green
    openEnded: yes

cylinder.color color

Defines the color of the cylinder. Default is white.

myCylinder = new Cylinder
    color: Color.blue

cylinder.radius number

Defines the radius of the cylinder. Default is 1.

myCylinder = new Cylinder
    radius: 2
    color: Color.blue

cylinder.height number

Set the height of the cylinder. Default is 2.

myCylinder = new Cylinder
    height: 5

cylinder.openEnded boolean

Whether the ends of the cylinder are open (true) or capped (false).

myCylinder = new Cylinder
    openEnded: true

cylinder.src string/AssetImage

Defines the material used when rendering the cylinder.

myCylinder = new Cylinder
    src: "assets/cat.png"

texture = AssetImage "assets/texture2.png"
myCylinder = new Cylinder
    src: texture

Note that if you add the texture in Assets then you only need to specify the name of the asset.

myCylinder = new Cylinder
    src: "cat"

cylinder.transparent boolean

Set the transparency of the cylinder. Default is yes.

myCylinder = new Cylinder
    transparent: no

cylinder.opacity number

Set the opacity of the cylinder. Default is 1.

myCylinder = new Cylinder
    x: -2
    opacity: 0.8

cylinder.metalness number

Set the metalness aspect of the cylinder. Default is 0.

myCylinder = new Cylinder
    radius: 10
    metalness: 0.5

cylinder.repeat string

Define how many times the texture should be repeated on the cylinder on the x and y axies. Default is None.

myCylinder = new Cylinder
    x: -2
    repeat: '20 20'

cylinder.roughness number

Define the roughness aspect of the cylinder. Default is 0.5.

myCylinder = new Cylinder
    x: -2
    roughness: 1

cylinder.shader shader

Define the shader to use to render the cylinder on the scene. Default is standard.

myCylinder = new Cylinder
    shader: Shader.standard

cylinder.segmentsHeight number

Defines the segments height to use when rendering the cylinder. Default is 18.

myCylinder = new Cylinder
    x: -2
    segmentsHeight: 3

cylinder.segmentsRadial number

Defines the segments radial to use when rendering the cylinder. Default is 36.

myCylinder = new Cylinder
    x: -2
    segmentsRadial: 4

cylinder.thetaLength integer

Defines the theta length of the cylinder. Default is 180.

myCylinder = new Cylinder
    x: -2
    thetaLength: 80
    wireframe: yes

cylinder.thetaStart integer

Defines the theta start value of the cylinder. Default is 0.

myCylinder = new Cylinder
    x: -2
    thetaLength: 80
    thetaStart: 30
    wireframe: yes

cylinder.wireframe boolean

Render the cylinder wireframe only. Default is false.

myCylinder = new Cylinder
    wireframe: yes

cylinder.wireframeWidth integer

Wireframe width. Default is 2.

myCylinder = new Cylinder
    wireframe: yes
    wireframeWidth: 4

cylinder.fog boolean

React to the scene fog. Default is true.

myCylinder = new Cylinder
    fog: no

Dodecahedron

Extends: Entity

The dodecahedron geometry creates a polygon with twelve equally-sized faces.

myDodecahedron = new Dodecahedron
    color: "#FF926B"
    radius: 5

dodecahedron.color color

Defines the color of the dodecahedron. Default is white.

myDodecahedron = new Dodecahedron
    color: Color.blue

dodecahedron.radius number

Defines the radius of the dodecahedron. Default is 1.

myDodecahedron = new Dodecahedron
    radius: 2
    color: Color.coral

dodecahedron.src string/AssetImage

Defines the material used when rendering the dodecahedron.

myDodecahedron = new Dodecahedron
    src: "assets/cat.png"

texture = AssetImage "assets/texture2.png"
myDodecahedron = new Dodecahedron
    src: texture

Note that if you add the texture in Assets then you only need to specify the name of the asset.

myDodecahedron = new Dodecahedron
    src: "cat"

dodecahedron.transparent boolean

Set the transparency of the dodecahedron. Default is yes.

myDodecahedron = new Dodecahedron
    transparent: no

dodecahedron.opacity number

Set the opacity of the dodecahedron. Default is 1.

myDodecahedron = new Dodecahedron
    x: -2
    opacity: 0.8

dodecahedron.metalness number

Set the metalness aspect of the dodecahedron. Default is 0.

myDodecahedron = new Dodecahedron
    radius: 10
    metalness: 0.5

dodecahedron.repeat string

Define how many times the texture should be repeated on the dodecahedron on the x and y axis. Default is None.

myDodecahedron = new Dodecahedron
    x: -2
    repeat: '20 20'

dodecahedron.roughness number

Define the roughness aspect of the dodecahedron. Default is 0.5.

myDodecahedron = new Dodecahedron
    x: -2
    roughness: 1

dodecahedron.shader shader

Define the shader to use to render the dodecahedron on the scene. Default is standard.

myDodecahedron = new Dodecahedron
    shader: Shader.standard

dodecahedron.segmentsHeight number

Defines the segments height to use when rendering the dodecahedron. Default is 18.

myDodecahedron = new Dodecahedron
    x: -2
    segmentsHeight: 3

dodecahedron.segmentsRadial number

Defines the segments radial to use when rendering the dodecahedron. Default is 36.

myDodecahedron = new Dodecahedron
    x: -2
    segmentsRadial: 4

dodecahedron.thetaLength integer

Defines the theta length of the dodecahedron. Default is 360.

myDodecahedron = new Dodecahedron
    x: -2
    thetaLength: 80
    wireframe: yes

dodecahedron.thetaStart integer

Defines the theta start value of the dodecahedron. Default is 0.

myDodecahedron = new Dodecahedron
    x: -2
    thetaLength: 80
    thetaStart: 30
    wireframe: yes

dodecahedron.wireframe boolean

Render the dodecahedron wireframe only. Default is false.

myDodecahedron = new Dodecahedron
    wireframe: yes

dodecahedron.wireframeWidth integer

Wireframe width. Default is 2.

myDodecahedron = new Dodecahedron
    wireframe: yes
    wireframeWidth: 4

dodecahedron.fog boolean

React to the scene fog. Default is true.

myDodecahedron = new Dodecahedron
    fog: no

Effects

Add post processing effects to your scene.

Hologram.effects.film = yes
Hologram.effects.bloom =
  strength: 4
  radius: 2
  threshold: 0.6

effects.fxaa boolean/object

Add a fxaa (Fast Approximate Anti-Aliasing) effect to your scene.

Hologram.effects.fxaa = yes

effects.bloom boolean/object

Add a bloom effect to your scene.

Hologram.effects.bloom =
  strength: 8
  radius: 1.2
  threshold: 0.2

effects.film boolean/object

Add a bloom effect to your scene.

Hologram.effects.film =
  sIntensity: 0.03
  nIntensity: 0.2

effects.outline boolean/object

Add a outline effect to your scene.

Hologram.effects.outline =
  width: '1.33 1.33'
  range: '0 10'
  strength: 3
  smooth: yes

effects.glitch boolean/object

Add a glitch effect to your scene.

Hologram.effects.glitch = yes

# With more advanced settings
Hologram.effects.glitch =
  amount: 0.2
  angle: 0.02
  seed: 0.04

Entity

Add text to your scene.

To change the size of the text, use the scale component or position the text closer or further away.

myEntity = new Entity

textA = new Text
    text: "Hello, World!"
    parent: myEntity

entity.parent entity

Add child entities to parent entity.

myBox = new Box
    x:1, y:2, z:3

textA = new Text
    text: "Cool stuff!"
    parent: myCamera

# Will remove textA from its parent (myCamera)
textA.parent = null

entity.x number

The x property of a entity defines its x position in 3D space. From left to right. All entities inherently have the x property.

myBox = new Box
myBox.x = 2

entity.y number

The x property of a entity defines its x position in 3D space. From up to down. All entities inherently have the x property.

myBox = new Box
myBox.y = 3

entity.z number

The z property of a entity defines its z position in 3D space. From in to out. All entities inherently have the z property.

myBox = new Box
myBox.z = -5

Relative Positioning

World-space positions of child entities inherit from parent entities.

myEntity = new Entity
    z: 10

# The text will be positioned relative to its parent.
textA = new Text
    x: 1, y: 1
    text: "Hello, World!"
    parent: myEntity

entity.rotation number

Sets all orientations of the entity. The rotation is defined in degrees between 0 and 360. The default value is 0.

myBox = new Box
myBox.rotation = 45

entity.rotationX number

Sets the x rotation of the entity (roll, rotation on the X-axis). The rotation is defined in degrees between 0 and 360. The default value is 0.

myBox = new Box
myBox.rotationX = 45

entity.rotationY number

Sets the z rotation of the entity (pitch, rotation on the Y-axis). The rotation is defined in degrees between 0 and 360. The default value is 0.

myBox = new Box
myBox.rotationY = 45

entity.rotationZ number

Sets the z rotation of the entity (yaw, rotation on the Z-axis). The rotation is defined in degrees between 0 and 360. The default value is 0.

myBox = new Box
myBox.rotationZ = 45

Relative Rotation

Child entities inherit from world-space rotations from parent entities.

myEntity = new Entity
    rotationY: 45

# Will appear to be rotated
textA = new Text
    text: "Hello, World!"
    parent: myEntity

entity.scale number

Sets the scale of the entity. The default scale is 1. Any number smaller then one will decrease the size and vice versa.

myBox = new Box
myBox.scale = 4

entity.scaleX number

Sets the horizontal scale, relative to its transform origin. The default scale is 1. Any number smaller then one will decrease the size and vice versa.

myBox = new Box
myBox.scaleX = 2

entity.scaleY number

Sets the vertical scale, relative to its transform origin. The default scale is 1. Any number smaller then one will decrease the size and vice versa.

myBox = new Box
myBox.scaleY = 3

entity.scaleZ number

Sets the scale in the Z direction, relative to its transform origin. The default scale is 1. Any number smaller then one will decrease the size and vice versa.

myBox = new Box
myBox.scaleZ = 2

entity.visible boolean

Whether to render an entity. If true the entity will be rendered and visible. Default is true.

textA = new Text
    text: "Hello, World!"
    visible: no

entity.lookAt entity

Tell an entity to face towards another entity or position.

myBox = new Box
    position: "3 0 3"

# Will be oriented towards myCamera direction
myOtherBox = new Box
    lookAt: myCamera

Add an hyperlink to your entity.

myBox = new Box
    link:
        href: "index.html"
        title: "My Homepage"
        image: "assets/homeThumbnail.png"
        visualAspectEnabled: no
    position: "3 0 3"
Values:
  • color: Background color of the portal. Default #FFF
  • highlighted: Boolean to toggle link highlight color. Default is false.
  • highlightedColor: Border color when highlighted. Default is #24CAFF
  • href: Destination URL where the link points to.
  • image: 360° image used as scene preview in the portal.
  • peekMode: Whether the 360° image is fully expanded for preview. Default is false.
  • title: Text displayed on the link. The href or page URL is used if not defined.
  • visualAspectEnabled: Whether to enable the default visual appearance of a portal. Set to false if we want to implement our own pattern or form of link traversal. Default is true.

entity.shadow entity

Enable shadows to your entity.

myBox = new Box
    shadow: yes
    position: "3 0 3"

Events

entity.onClick(callback)

Emitted on both cursor and intersected entity if a currently intersected entity is clicked (whether by mouse or by fuse).

myBox = new Box
    color: Color.darkblue
myBox.onClick ->
    print "clicked!"

entity.onFusing(callback)

Emitted on both cursor and intersected entity when fuse-based cursor starts counting down.

myBox = new Box
    color: Color.lavender
myBox.onFusing ->
    print "fuse!"

entity.onCursorDown(callback)

Emitted on both cursor and intersected entity (if any) on mouse down on the canvas element.

myBox = new Box
    color: Color.gold
myBox.onCursorDown ->
    print "cursor down on me!"

entity.onCursorUp(callback)

Emitted on both cursor and intersected entity (if any) on mouse up on the canvas element.

myBox = new Box
    color: Color.turquoise
myBox.onCursorUp ->
    print "cursor up!"

entity.onCursorIn(callback)

Emitted on both cursor and intersected entity (if any) when cursor intersects with an entity.

myBox = new Box
    color: Color.yellow
myBox.onCursorUp ->
    print "cursor in!"

entity.onCursorOut(callback)

Emitted on both cursor and intersected entity (if any) when cursor no longer intersects with previously intersected entity.

myBox = new Box
    color: Color.silver
myBox.onCursorOut ->
    print "cursor out!"

entity.onCollide(callback)

Emitted when an entity collide another that both have physics enabled. Read the physics section in Capabilities (app only) for more info.

myBox = new Box
    color: Color.yellow
myBox.onCollide (event)->
    print "WOW! I just collided an object!"

Hand Controls

Extends: Entity

The hand-controls gives tracked hands (using a prescribed model) with animated gestures. It works with the vive controls and oculus touch controls.

leftHand = Hologram.leftHand
rightHand = Hologram.rightHand

Events

hand.onGripDown(callback)

The hand is closed into a fist without thumb raised.

leftHand = Hologram.leftHand
leftHand.onGripDown ->
    print "grip down"

hand.onGripUp(callback)

The hand is no longer closed into a fist without thumb raised.

leftHand = Hologram.leftHand
leftHand.onGripUp ->
    print "grip up"

hand.onPointUp(callback)

The hand is touching or pressing the trigger only.

leftHand = Hologram.leftHand
leftHand.onPointUp ->
    print "point up"

hand.onGripDown(callback)

The hand is no longer touching or pressing the trigger only.

leftHand = Hologram.leftHand
leftHand.onGripDown ->
    print "point down"

hand.onThumbUp(callback)

The hand is closed into a fist with thumb raised.

leftHand = Hologram.leftHand
leftHand.onThumbUp ->
    print "thumb up"

hand.onThumbDown(callback)

The hand is no longer closed into a fist with thumb raised.

leftHand = Hologram.leftHand
leftHand.onThumbDown ->
    print "thumb down"

hand.onPointingStart(callback)

The hand is pointing with index finger without thumb raised.

leftHand = Hologram.leftHand
leftHand.onPointingStart ->
    print "pointing started"

hand.onPointingEnd(callback)

The hand is no longer pointing without thumb raised.

leftHand = Hologram.leftHand
leftHand.onPointingEnd ->
    print "pointing ended"

hand.onPistolStart(callback)

The hand is pointing with index finger and thumb raised.

leftHand = Hologram.leftHand
leftHand.onPistolStart ->
    print "pistol start"

hand.onPistolEnd(callback)

The hand is no longer pointing with thumb raised.

leftHand = Hologram.leftHand
leftHand.onPistolEnd ->
    print "pistol end"

Icosahedron

Extends: Entity

The icosahedron primitive is used to create icosahedron.

myIcosahedron = new Icosahedron
    color: "#FF926B"
    radius: 5

icosahedron.color color

Defines the color of the icosahedron. Default is white.

myIcosahedron = new Icosahedron
    color: Color.blue

icosahedron.radius number

Defines the radius of the icosahedron. Default is 1.

myIcosahedron = new Icosahedron
    radius: 2
    color: Color.blue

icosahedron.src string/AssetImage

Defines the material used when rendering the icosahedron.

myIcosahedron = new Icosahedron
    src: "assets/cat.png"

texture = AssetImage "assets/texture2.png"
myIcosahedron = new Icosahedron
    src: texture

Note that if you add the texture in Assets then you only need to specify the name of the asset.

myIcosahedron = new Icosahedron
    src: "cat"

Image

Extends: Entity

The image primitive shows an image on a flat plane.

myImage = new Image
    width: 2
    height: 2
    src: "cat"

image.width number

Set the width of the plane. Default is 1.

myImage = new Image
    width: 2
    src: "cat"

image.height number

Set the height of the image. Default is 1.

myImage = new Image
    height: 5
    src: "cat"

image.src string/AssetImage

Defines the material used when rendering the image.

myImage = new Image
    src: "assets/cat.png"

texture = AssetImage "assets/texture2.png"
myImage = new Image
    src: texture

Note that if you add the texture in Assets then you only need to specify the name of the asset.

myImage = new Image
    src: "cat"

image.transparent boolean

Set the transparency of the image. Default is yes.

myImage = new Image
    transparent: no
    src: "cat"

image.opacity number

Set the opacity of the image. Default is 1.

myImage = new Image
    x: -2
    opacity: 0.8
    src: "cat"

Light

Extends: Entity

Add a source of light to your scene. Light affects all materials that have not specified a flat shading model with shader: flat. Note that lights are computationally expensive we should limit number of lights in a scene.

myLight = new Light
    x: -1, y: 1
    color: "#AFA"
    intensity: 1.5

By default, Hologram scenes have a default lighting: an ambient light and a directional light. Whenever you add any lights, Hologram will removes the default lights from the scene.


light.type string

Set the type of light. Default is no.

Ambient

Ambient lights globally affect all entities in the scene. The color and intensity properties define ambient lights. Additionally, position, rotation, and scale have no effect on ambient lights. It is recommend to have some form of ambient light such that shadowed areas are not fully black and to mimic indirect lighting.

myLight = new Light
    type: Light.ambient
    color: "#CCC"

Directional

Directional lights are like a light source that is infinitely far away, but shining from a specific direction, like the sun. Thus, absolute position do not have an effect on the intensity of the light on an entity. The example below creates a light source shining from the upper-left at a 45-degree angle. Note that because only the vector matters, position "-100 100 0" and position "-1 1 0" are the same.

myLight = new Light
    x: -1, y: 1
    type: Light.directional
    color: "#EEE"
    intensity: 0.5

We can specify the direction of the directional light with its orientation by creating a child entity it targets. For example, pointing down its -Z axis:

myLight = new Light
    type: Light.directional
    rotationX: -90

myLightEntity = new Entity
    z: -1
    parent: myLight

myLightEntity.target = myLightEntity

Hemisphere

Hemisphere lights are like an ambient light, but with two different colors, one from above (color) and one from below (groundColor). This can be useful for scenes with two distinct lighting colors (e.g., a grassy field under a gray sky).

myLight = new Light
    type: Light.hemisphere
    color: "#33C"
    groundColor: "#3C3"
    intensity: 2
Property
  • groundColor: Light color from below.

Point

Point lights, unlike directional lights, are omni-directional and affect materials depending on their position and distance. Point likes are like light bulb. The closer the light bulb gets to an object, the greater the object is lit.

myLight = new Light
    y: 10, z: 10
    type: Light.point
    distance: 50
    decay: 2
    intensity: 0.75
Properties
  • decay: Amount the light dims along the distance of the light. Default is 1.0.
  • distance: Distance where intensity becomes 0. If distance is 0, then the point light does not decay with distance. Default is 0.0.

Spot

Spot lights are like point lights in the sense that they affect materials depending on its position and distance, but spot lights are not omni-directional. They mainly cast light in one direction, like the Bat-Signal.

myLight = new Light
    type: Light.spot
Properties
  • angle: Maximum extent of spot light from its direction (in degrees). Default is 60.
  • decay: Amount the light dims along the distance of the light. Default is 1.0.
  • distance: Distance where intensity becomes 0. If distance is 0, then the point light does not decay with distance. Default is 0.0.
  • penumbra: Percent of the spotlight cone that is attenuated due to penumbra. Default is 0.0.
  • target: Element the spot should point to. set to null to transform spotlight by orientation, pointing to it’s -Z axis. Default is 1.0.

light.color color

Defines the color of the cube. Default is white.

myLight = new Light
    color: Color.tomato

light.intensity number

Defines the intensity of the light. Default is 1.0.

myLight = new Light
    intensity: 2.0

light.castShadow number

Whether this light casts shadows on the scene. Default is false. Note that shadows are supported by Point, Spot and Directional lights.

myLight = new Light
    castShadow: yes

Line

Extends: Entity

The line component draws a line given a start coordinate and end coordinate.

myLine = new Line
    start: x: 1
    end: x: 2, z: -5
    color: Color.red

line.start string

Set the start point coordinate x, y, z. Default is x: 0, y: 0, z: 0.

myLine = new Line
    start: x: 1

line.end string

Set the end coordinate. Default is x: 0, y: 0, z: 0.

myLine = new Line
    end: x: 2, z: -5

line.color string

Set the color of the line. Default is #74BEC1.

myLine = new Line
    color: "#FF00CC"

line.visible string

Whether the material visible. Default is true.

myLine = new Line
    visible: no

Model

Extends: Entity

Add 3D Object to your scene. Supported Object files (.obj/.mtl), Collada (.dae) and glTF (.gltf).

myModel = new Model
    src: "assets/model.gltf"

model.src string/AssetItem

Path to the model to render.

myModel = new Model
    src: "assets/car.gltf"

# OR
object = AssetObject "assets/model.gltf"
myModelB = new Model
    src: object

Note that if you add the texture in Assets then you only need to specify the name of the asset.

myModel = new Model
    src: "car"

model.mtl string/AssetItem

Path to the object texture to render.

myModel = new Model
    src: "assets/object.obj"
    mtl: "assets/object.mtl"

# OR
object = AssetObject "assets/object.obj"
texture = AssetItem "assets/object.mtl"

myModelB = new Model
    src: object
    texture: texture

Note that if you add the texture in Assets then you only need to specify the name of the asset.

myModel = new Model
    src: "object"

Events

model.onLoad(callback)

myModel = new Model
    src: "assets/model.dae"

myModel.onLoad ->
    print "loaded"

Octahedron

Extends: Entity

The octahedron geometry creates a polygon with eight equilateral triangular faces.

myOctahedron = new Octahedron
    color: "#FF926B"
    radius: 5

octahedron.color color

Defines the color of the octahedron. Default is white.

myOctahedron = new Octahedron
    color: Color.blue

octahedron.radius number

Defines the radius of the octahedron. Default is 1.

myOctahedron = new Octahedron
    radius: 2
    color: Color.sienna

octahedron.src string/AssetImage

Defines the material used when rendering the octahedron.

myOctahedron = new Octahedron
    src: "assets/texture.png"

Plane

Extends: Entity

The plane geometry creates a flat surface.

myPlane = new Plane
    width: 20
    height: 20
    color: "#CCC"

plane.width number

Set the width of the plane. Default is 1.

myPlane = new Plane
    width: 2

plane.height number

Set the height of the plane. Default is 1.

myPlane = new Plane
    height: 5

plane.color color

Defines the color of the plane. Default is white.

myPlane = new Plane
    color: Color.aquamarine

plane.src string/AssetImage

Defines the material used when rendering the plane.

myPlane = new Plane
    src: "assets/cat.png"

texture = AssetImage "assets/texture2.png"
myPlaneB = new Plane
    src: texture

Note that if you add the texture in Assets then you only need to specify the name of the asset.

myPlane = new Plane
    src: "cat"

plane boolean

Set the transparency of the plane. Default is yes.

myPlane = new Plane
    transparent: no

plane.opacity number

Set the opacity of the plane. Default is 1.

myPlane = new Plane
    z: -2
    opacity: 0.8

plane.metalness number

Set the metalness aspect of the plane. Default is 0.

myPlane = new Plane
    radius: 10
    metalness: 0.5

plane.repeat string

Define how many times the texture should be repeated on the plane on the x and y axis. Default is None.

myPlane = new Plane
    z: -2
    repeat: '20 20'

plane.roughness number

Define the roughness aspect of the plane. Default is 0.5.

myPlane = new Plane
    z: -2
    roughness: 1

plane.shader shader

Define the shader to use to render the plane on the scene. Default is standard.

myPlane = new Plane
    shader: standard

plane.wireframe boolean

Render the plane wireframe only. Default is false.

myPlane = new Plane
    wireframe: yes

plane.wireframeWidth integer

Wireframe width. Default is 2.

myPlane = new Plane
    wireframe: yes
    wireframeWidth: 4

plane.fog boolean

React to the scene fog. Default is true.

myPlane = new Plane
    fog: no

Portal

Extends: Entity

A portal is a VR portal that can be anything such as grabbing onto an object, placing something on our head, clicking something, even eating something! The default implementation of portals are portals or windows, using a 360° image thumbnail to preview the destination.

myPortal = new Portal
    y: 1.5, z: -2
    href: "https://aframe.io/aframe/examples/showcase/link-traversal/"
    title: "My Homepage"
    image: "assets/homeThumbnail.png"

portal.href string

Set the destination URL where the portal points to.

myPortal = new Portal
    href: "cool.html"

portal.title string

Set the text displayed on the portal. The href or page URL is used if not defined.

myPortal = new Portal
    title: "Hahaha"

portal.image string

Set the portal preview, a 360° image used as scene preview in the portal.

myPortal = new Portal
    image: "assets/homeThumbnail.png"

Ring

Extends: Entity

The ring geometry creates a flat ring, like a CD.

myRing = new Ring
    color: Color.olive
    radiusInner: 1
    radiusOuter: 2

ring.color color

Defines the color of the ring. Default is white.

myRing = new Ring
    color: Color.olive

ring.radiusInner number

Defines the inner radius of the ring. Default is 1.

myRing = new Ring
    radiusInner: 1.2
    color: Color.blue

ring.radiusOuter number

Defines the outer radius of the ring. Default is 1.

myRing = new Ring
    radiusOuter: 2.4
    color: Color.blue

ring.src string/AssetImage

Defines the material used when rendering the ring.

myRing = new Ring
    src: "assets/texture.png"

ring boolean

Set the transparency of the ring. Default is yes.

myRing = new Ring
    transparent: no

ring.opacity number

Set the opacity of the ring. Default is 1.

myRing = new Ring
    z: -2
    opacity: 0.8

ring.metalness number

Set the metalness aspect of the ring. Default is 0.

myRing = new Ring
    radius: 10
    metalness: 0.5

ring.repeat string

Define how many times the texture should be repeated on the ring on the x and y axies. Default is None.

myRing = new Ring
    z: -2
    repeat: '20 20'

ring.roughness number

Define the roughness aspect of the ring. Default is 0.5.

myRing = new Ring
    z: -2
    roughness: 1

ring.shader shader

Define the shader to use to render the ring on the scene. Default is standard.

myRing = new Ring
    shader: Shader.standard

ring.side string

Defines which of the face sides will be rendered. Default is front, can be either front, back or both.

myRing = new Ring
    side: Side.both

ring.segmentsTheta integer

Number of segments. A higher number means the ring will be more round. Default is 32.

myRing = new Ring
    segmentsTheta: 42

ring.segmentsPhi integer

Number of triangles within each face defined by segmentsTheta. Default is 8.

myRing = new Ring
    segmentsPhi: 12

ring.thetaLength integer

Starting angle in degrees of the ring. Default is 180.

myRing = new Ring
    z: -2
    thetaLength: 80
    wireframe: yes

ring.thetaStart integer

Central angle in degrees of the ring. Default is 0.

myRing = new Ring
    z: -2
    thetaLength: 80
    thetaStart: 30
    wireframe: yes

Scene

Extends: Entity

The scene is the global root object, and all entities are contained within the scene.

You don't have to specify the scene when adding an entity to the root element: myBox = new Box

But this is also possible and will have the same effect:

myBox = new Box
    parent: Hologram.scene

Hologram.scene.embed boolean

Remove fullscreen styles from the canvas.

print Hologram.scene.embed = yes

Hologram.scene.fog object

Add fog to the scene. The fog property obscures entities in fog given distance from the camera. The fog type can be either linear or exponential.

Hologram.scene.fog =
    type: Fog.linear
    color: "#AAA"

# Remove the fog from the scene
Hologram.scene.fog = null
Properties
  • enabled - Whether the fog is enabled.
  • type - Type of the fog: linear or exponential
  • color - Color of the fog
  • near - How close should the fog propagate (in meters)
  • far - How far should the fog propagate (in meters)

Hologram.scene.stats boolean

Toggle performance stats.

Hologram.scene.stats = yes

Metrics
  • fps - Frames per second, frame-rate. Aim for stable 90 fps with the WebVR 1.0 API.
  • requestAnimationFrame (raf) - Latency.
  • Textures - Number of three.js textures in the scene. A lower count means the scene is using less memory and sending less data to the GPU.
  • Programs - Number of GLSL shaders in the scene.
  • Geometries - Number of three.js geometries in the scene. A lower count means the scene is using less memory.
  • Vertices - Number of vertices in the scene.
  • Faces - Number of faces in the scene.
  • Calls - Number of draw calls on each frame.
  • Load Time - How long it took for the scene to start rendering, in ms.
  • Entities -Number of A-Frame entities.

Screenshots

The screenshot component lets us take different types of screenshots with keyboard shortcuts. Hologram attaches this component to the scene by default so we don’t have to do anything to use the component.


Simple Screenshot

To take a normal (perspective) screenshot, press CTRL + ALT + S on the keyboard.


360 Screenshot

To take a 360° (equirectangular) screenshot, press CTRL + ALT + SHIFT + S on the keyboard.

Sky

Extends: Entity

The sky primitive adds a background color or 360° image to a scene. A sky is a large sphere with a color or texture mapped to the inside.

With an image as a background:

texture = AssetImage "assets/sky.png"
mySky = new Sky
    src: texture

With a plain color as a background:

mySky = new Sky
    color: "#6EBAA7"

sky.color color

Defines the color of the sky. Default is white.

mySky = new Sky
    color: Color.skyblue

sky.radius integer

Defines the radius of the sky. Default is 5000.

myBox = new Box
    radius: 4000
    color: Color.springgreen

sky.src string/AssetImage/AssetVideo

Defines the material used when rendering the sky.

mySky = new Sky
    src: "assets/sky.png"

# OR
texture = AssetImage "assets/texture2.png"
mySky = new Sky
    src: texture

Note that if you add the texture in Assets then you only need to specify the name of the asset.

mySky = new Sky
    src: "sky"

Sound

Extends: Entity

The sound primitive wraps the sound component.

With an image as a background:

mySound = new Sound
    y: 2, z: 5
    src: "assets/song.mp3"
    autoplay: true

sound.autoplay color

Whether the sound should play right after being loaded. Default is false.

mySound = new Sound
    src: "assets/song.mp3"
    autoplay: true

sound.loop boolean

Whether the sound should repeat. Default is false.

mySound = new Sound
    src: "assets/song.mp3"
    loop: true

sound.volume number

Defines the volume of the sound. Default is 1.

mySound = new Sound
    src: "assets/song.mp3"
    volume: 0.8

sound.src string/AssetAudio

Path to sound.

myTrack = AssetAudio "assets/song.mp3"
mySound = new Sound
    src: myTrack
    volume: 0.8

# OR
myTrack = AssetAudio "assets/noise.mp3"
mySound = new Sound
    src: myTrack

Note that if you add the texture in Assets then you only need to specify the name of the asset.

mySound = new Sound
    src: "song"

Pause and Resume

To programmatically pause or resume a playing sound, we can tell the entity to pause or resume:

mySound.stop()

Or to pause only the sound:

mySound.pause()

And to play the sound:

mySound.play()

Sphere

Extends: Entity

The sphere geometry creates spheres (e.g., balls).

mySphere = new Sphere
    color: Color.yellow
    radius: 5

sphere.color color

Defines the color of the sphere. Default is white.

mySphere = new Sphere
    color: Color.blue

sphere.radius integer

Defines the radius of the sphere. Default is 1.

mySphere = new Sphere
    radius: 2
    color: Color.blue

sphere.src string/AssetImage

Defines the material used when rendering the sphere.

mySphere = new Sphere
    src: "assets/cat.png"

# OR
texture = AssetImage "assets/texture2.png"
mySphere = new Sphere
    src: texture

Note that if you add the texture in Assets then you only need to specify the name of the asset.

mySphere = new Sphere
    src: "cat"

sphere.transparent boolean

Set the transparency of the sphere. Default is yes.

mySphere = new Sphere
    transparent: no

sphere.opacity number

Set the opacity of the sphere. Default is 1.

mySphere = new Sphere
    z: -2
    opacity: 0.8

sphere.metalness number

Set the metalness aspect of the sphere. Default is 0.

mySphere = new Sphere
    radius: 10
    metalness: 0.5

sphere.repeat string

Define how many times the texture should be repeated on the sphere on the x and y axis. Default is None.

mySphere = new Sphere
    z: -2
    repeat: '20 20'

sphere.roughness number

Define the roughness aspect of the sphere. Default is 0.5.

mySphere = new Sphere
    z: -2
    roughness: 1

sphere.shader shader

Define the shader to use to render the sphere on the scene. Default is standard.

mySphere = new Sphere
    shader: Shader.standard

sphere.side string

Defines which of the face sides will be rendered. Default is front, can be either front, back or both.

mySphere = new Sphere
    z: -2
    side: Side.both

sphere.segmentsWidth integer

Defines the segments width to use when rendering the sphere. Default is 18.

mySphere = new Sphere
    z: -2
    segmentsWidth: 4

sphere.segmentsHeight integer

Defines the segments height to use when rendering the sphere. Default is 36.

mySphere = new Sphere
    z: -2
    segmentsHeight: 3

sphere.thetaLength integer

Defines the theta length of the sphere. Default is 180.

mySphere = new Sphere
    z: -2
    thetaLength: 80
    wireframe: yes

sphere.thetaStart integer

Defines the theta start value of the sphere. Default is 0.

mySphere = new Sphere
    z: -2
    thetaLength: 80
    thetaStart: 30
    wireframe: yes

sphere.phiLength integer

Defines the phi length of the sphere. Default is 360.

mySphere = new Sphere
    z: -2
    phiLength: 180
    wireframe: yes

sphere.phiStart integer

Defines the phi start value of the sphere. Default is 0.

mySphere = new Sphere
    z: -2
    phiLength: 180
    phiStart: 30
    wireframe: yes

sphere.wireframe boolean

Render the sphere wireframe only. Default is false.

mySphere = new Sphere
    wireframe: yes

sphere.wireframeWidth integer

Wireframe width. Default is 2.

mySphere = new Sphere
    wireframe: yes
    wireframeWidth: 4

sphere.fog boolean

React to the scene fog. Default is true.

mySphere = new Sphere
    fog: no

Tetrahedron

Extends: Entity

The tetrahedron geometry creates a polygon with four triangular faces.

myTetrahedron = new Tetrahedron
    color: "#FF926B"
    radius: 5

tetrahedron.color color

Defines the color of the tetrahedron. Default is white.

myTetrahedron = new Tetrahedron
    color: Color.blue

tetrahedron.radius number

Defines the radius of the tetrahedron. Default is 1.

myTetrahedron = new Tetrahedron
    radius: 2
    color: Color.blue

tetrahedron.src string/AssetImage

Defines the material used when rendering the tetrahedron.

myTetrahedron = new Tetrahedron
    src: "assets/texture.png"

Text

Extends: Entity

Add text to your scene.

NOTE: To change the size of the text, use the scale component or position the text closer or further away.

textA = new Text
    text: "Hello, World!"
    y: 2, z: -10

text.align string

Multi-line text alignment (Align.left, Align.center, Align.right). Default is Align.left.

textA = new Text
    text: "Hello, World!"
    align: Align.center

text.anchor string

Horizontal positioning (Anchor.left, Anchor.center, Anchor.right, Anchor.align). Default is Anchor.center.

textA = new Text
    text: "Hello, World!"
    anchor: Anchor.right

text.baseline string

Vertical positioning (Baseline.top, Baseline.center, Baseline.bottom). Default is Baseline.center.

textA = new Text
    text: "Hello, World!"
    baseline: Baseline.center

text.color color

Text color. Default is white.

textA = new Text
    text: "Hello, World!"
    color: "#00F"

text.font string

Font to render text, either the name of one of Hologram’s stock fonts or a URL to a font file.

textA = new Text
    text: "Hello, World!"
    font: Font.mozillavr
Available font:
Font.aileronsemibold
Font.dejavu
Font.exo2bold
Font.exo2semibold
Font.kelsonsans
Font.monoid
Font.mozillavr
Font.sourcecodepro

text.width number

Set the width of the text block.

textA = new Text
    text: "Hello, World!"
    width: 5

text.height number

Set the height of the text block.

textA = new Text
    text: "Hello, World!"
    height: 5

text.lineHeight number

Line height in pixels.

textA = new Text
    text: "Hello, World!"
    lineHeight: 20

text.transparent boolean

Set the transparency of the text. Default is yes.

textA = new Text
    transparent: no

text.opacity number

Set the opacity of the text. Default is 1.

textA = new Text
    text: "Hello, World!"
    opacity: 0.8

text.whitespace number

How whitespace should be handled (i.e., Whitespace.normal, Whitespace.pre, Whitespace.nowrap). Default is Whitespace.normal.

textA = new Text
    text: "Hello, World!"
    whitespace: Whitespace.pre

text.zindex number

Z-index to apply to avoid Z-fighting if using with a geometry as a background. Default is 0.001

textA = new Text
    text: "Hello, World!"
    zindex: 100

text.shader string

Define the shader to use to render the text on the scene. Default is standard.

textA = new Text
    shader: Shader.standard

text.side string

Defines which of the face sides will be rendered. Default is front, can be either Side.front, Side.back or Side.both.

textA = new Text
    side: Side.both

Torus

Extends: Entity

The torus geometry creates a donut or curved tube shape.

myTorus = new Torus
    color: "#B84A39"
    arc: 180
    radius: 5
    radiusTubular: 0.5

torus.color color

Defines the color of the torus. Default is white.

myTorus = new Torus
    color: Color.blue

torus.radius number

Radius that contains the torus. Default is 1.

myTorus = new Torus
    radius: 2
    color: Color.blue

torus.radiusTubular number

Radius of the tubes of the torus. Default is 0.2.

myTorus = new Torus
    radiusTubular: 0.3
    color: Color.blue

torus.segmentsRadial integer

Number of segments along the circumference of the tube ends. A higher number means the tube will be more round. Default is 36.

myTorus = new Torus
    segmentsRadial: 42

torus.segmentsTubular integer

Number of segments along the circumference of the tube face. A higher number means the tube will be more round. Default is 32.

myTorus = new Torus
    segmentsTubular: 36

torus.arc integer

Central angle. Default is 360.

myTorus = new Torus
    arc: 180

torus.src string/AssetImage

Defines the material used when rendering the torus.

myTorus = new Torus
    src: "assets/cat.png"

texture = AssetImage "assets/texture2.png"
myTorus = new Torus
    src: texture

Note that if you add the texture in Assets then you only need to specify the name of the asset.

myTorus = new Torus
    src: "cat"

Torus Knot

Extends: Entity

The torus knot geometry creates a pretzel shape. A pair of coprime integers, p and q, defines the particular shape of the pretzel. If p and q are not coprime the result will be a torus link.

myTorusKnot = new TorusKnot
    color: "#B84A39"
    p: 2
    q: 7
    radius: 5
    radiusTubular: 0.1

torusKnot.color color

Defines the color of the torus knot. Default is white.

myTorusKnot = new TorusKnot
    color: Color.blue

torusKnot.radius number

Radius that contains the torus knot. Default is 1.

myTorusKnot = new TorusKnot
    radius: 2
    color: Color.blue

torusKnot.radiusTubular number

Radius of the tubes of the torus knot. Default is 0.2.

myTorusKnot = new TorusKnot
    radiusTubular: 0.3
    color: Color.blue

torusKnot.segmentsRadial integer

Number of segments along the circumference of the tube ends. A higher number means the tube will be more round. Default is 36.

myTorusKnot = new TorusKnot
    segmentsRadial: 42

torusKnot.segmentsTubular integer

Number of segments along the circumference of the tube face. A higher number means the tube will be more round. Default is 32.

myTorusKnot = new TorusKnot
    segmentsTubular: 36

torusKnot.p integer

How many times the geometry winds around its axis of rotational symmetry. Default is 2.

myTorusKnot = new TorusKnot
    p: 4

torusKnot.q integer

How many times the geometry winds around a circle in the interior of the torus. Default is 3.

myTorusKnot = new TorusKnot
    q: 10

torusKnot-src string/AssetImage

Defines the material used when rendering the torus knot.

myTorusKnot = new TorusKnot
    src: "assets/texture.png"

Triangle

Extends: Entity

Time to creates a triangle.

myTriangle = new Triangle
    color: "#FF926B"

triangle.width number

Set the width of the triangle. Default is 1.

myTriangle = new Triangle
    width: 2

triangle.height number

Set the height of the triangle. Default is 1.

myTriangle = new Triangle
    height: 5

triangle.color color

Defines the color of the triangle. Default is white.

myTriangle = new Triangle
    color: Color.blue

triangle.src string/AssetImage

Defines the material used when rendering the triangle.

myTriangle = new Triangle
    src: "assets/texture.png"

Utils

Hologram utility modules to help you create cool stuff faster!


Basics

Utils.round(value, decimals=0)

Rounds a number.

Arguments
  • value - A floating point number.
  • decimals - The amount which appear after the decimal point. (Optional)
print Utils.round(100.12345, 0)
# Output: 100

print Utils.round(100.12345, 2)
# Output: 100.12

print Utils.round(100.12345, 4)
# Output: 100.1234

Utils.randomColor()

Returns a random color with the specified opacity.

print Utils.randomColor()
# Output: 'rgba(124, 12, 33, 0.5)'

Utils.randomNumber(a, b)

Generate a random number between a and b.

Arguments
  • a - A number, the first value of the range.
  • b - A number, the final value of the range.
print Utils.randomNumber(0, 1)
# Output: 0.2

print Utils.randomNumber(0, 100)
# Output: 22

Utils.capitalizeFirst(string)

Capitalize the first letter of a string.

print Utils.capitalizeFirst('we do not remember days, we remember moments.')
# Output: 'We do not remember days, we remember moments.'

Delay, Interval

Utils.delay(delay, handler)

Calls a function after a certain day defined in seconds.

Arguments
  • delay - Delay in seconds.
  • handler - Callback function.
Utils.delay 0.5, ->
    print 'hello'
# Output: 'hello', after 0.5 seconds

Utils.interval(interval, handler)

Calls a function every x seconds.

Arguments
  • interval - Interval in seconds.
  • handler - Callback function.
Utils.interval 2, ->
    print 'hello'
# Output: 'hello'
# Output: 'hello'
# Output: 'hello'  etc...

Device

Utils.hasPositionalTracking()

Checks if there is positional tracking available. Returns a boolean.

print Utils.hasPositionalTracking()
# Output: true

Utils.isHeadsetConnected()

Checks if a VR headset is connected by looking for orientation data. Returns a boolean.

print Utils.isHeadsetConnected()
# Output: true

Utils.isGearVR()

Checks if device is Gear VR. Returns a boolean.

print Utils.isGearVR()
# Output: false

Utils.isMobile()

Checks if device is a smartphone. Returns a boolean.

print Utils.isMobile()
# Output: true

Vectors

Utils.isVector(value)

Tests whether a string is a vec3.

print Utils.isCoordinate('4 2 2')
# Output: true

Utils.parseVector(value)

Parses an “x y z” string to an {x, y, z} vec3 object. Or parses an “x y z w” string to an {x, y, z, w} vec4 object.

print Utils.parse('-6 2 3')
# Output: {x: -6, y: 2, z: 3}

Utils.stringifyVector(data)

Stringifies an {x, y, z} vec3 object to an “x y z” string.

print Utils.stringifyVector({x: 1, y: 2, z: -3})
# Output: "1 2 -3"

Objects

Utils.deepEqual(a, b)

Checks if two objects have the same attributes and values, including nested objects.

print Utils.deepEqual({a: 1, b: {c: 3}}, {a: 1, b: {c: 3}})
# Output: true

Utils.diff(a, b)

Returns difference between two objects. The returned object’s set of keys denote which values were not equal, and the set of values are b‘s values.

print Utils.diff({a: 1, b: 2, c: 3}, {b: 2, c: 4})
# Output: {"a": undefined, "c": 4}

Variable checks

Utils.isString(value)

Returns true if object is a String.

print Utils.isString("Steve")
# Output: true

Utils.isFunction(value)

Returns true if object is a Function.

print Utils.isFunction(alert)
# Output: true

Utils.isBoolean(value)

Returns true if object is a boolean.

a = false
print Utils.isBoolean(a)
# Output: true

Utils.isFloat(value)

Returns true if object is a float.

print Utils.isFloat(3.14)
# Output: true

Utils.isInteger(value)

Returns true if object is a integer.

print Utils.isInteger(42)
# Output: true

Utils.isNumber(value)

Returns true if object is a number.

print Utils.isNumber(8.4 * 5)
# Output: true

Utils.isArray(value)

Returns true if object is an Array.

print Utils.isArray([1,2,3])
# Output: true

Utils.isObject(value)

Returns true if value is an Object. Note that JavaScript/CoffeeScript arrays and functions are objects, while (normal) strings and numbers are not.

print Utils.isArray({})
# Output: true

print Utils.isArray(1)
# Output: false

Array, Object

Utils.first(array)

Return first key of array

myArray = ['a', 'b', 'c']
Utils.first(myArray)
# Output: 'a'

Utils.last(array)

Return last key of array

myArray = ['a', 'b', 'c']
Utils.last(myArray)
# Output: 'c'

Utils.keys(object)

Return the keys of an object

myObject = {'a': {}, 'b': [], 'c': 5}
Utils.keys(myObject)
# Output: ['a', 'b', 'c']

Video

Extends: Entity

The video primitive plays a video as a texture on a flat plane.

myVideo = new Video
    y: 2, z: 5
    src: "assets/festival.mp4"
    autoplay: yes
    width: 16
    height: 9

# Using the asset management system.
cat = AssetVideo "assets/space.mp4"
myVideo = new Video
    src: cat

video.width number

Set the width of the video. Default is 1.

myVideo = new Video
    width: 2

video.height number

Set the height of the video. Default is 1.

myVideo = new Video
    height: 5

video.color color

Defines the color of the video. Default is white.

myVideo = new Video
    color: Color.blue

video.autoplay color

Whether the video should play right after being loaded. Default is false.

myVideo = new Video
    src: "assets/video.mp4"
    autoplay: yes

# OR
cloudsVideo = AssetVideo "assets/clouds.mp4"
myVideo = new Video
    src: cloudsVideo

Note that if you add the texture in Assets then you only need to specify the name of the asset.

myTorus = new Torus
    src: "video"

video.loop boolean

Whether the video should repeat. Default is false.

myVideo = new Video
    src: "assets/video.mp4"
    loop: yes

video.src string/AssetAudio

Path to video.

myVideo = AssetVideo "assets/video.mp4"
myVideo = new Video
    src: myVideo

VideoSphere

Extends: Entity

The videosphere primitive plays 360° videos in the background of the scene. Videospheres are a large sphere with the video texture mapped to the inside.

myVideoSphere = new VideoSphere
    src: "assets/venice-beach.mp4"
    autoplay: yes

# Using the asset management system.
landscape = AssetVideo "assets/san-francisco.mp4"
myVideoSphere = new VideoSphere
    src: landscape

Note that if you add the texture in Assets then you only need to specify the name of the asset.

myVideoSphere = new VideoSphere
    src: "venice-beach"

videoSphere.src string/AssetVideo

Path to video.

myVideo = AssetVideo "assets/video.mp4"
myVideoSphere = new VideoSphere
    src: myVideo

videoSphere.autoplay color

Whether the video sphere should play right after being loaded. Default is false.

myVideoSphere = new VideoSphere
    src: "assets/video.mp4"
    autoplay: yes

videoSphere.loop boolean

Whether the video sphere should repeat. Default is false.

myVideoSphere = new VideoSphere
    src: "assets/video.mp4"
    loop: yes

videoSphere.radius integer

Defines the radius of the video sphere. Default is 5000.

myVideoSphere = new VideoSphere
    radius: 3000
    color: Color.blue