On this page

A-Frame P5

A-Frame P5 is a library created by Craig Kapp that serves as a wrapper around the A-Frame Mixed Reality framework. Its primary function is to make it easy to construct VR worlds algorithmically using the p5 graphical framework.

Version 2.4 (latest stable release, 2026)

Version 2.3 (legacy release, 2024)

Version 2.2 (legacy release, 2023)

Version 2.1 (legacy release, 2021)

What's New in Version 2.4

Getting Started (A-Frame P5 version 2.4)

Since version 2.3, all A-Frame P5 classes live inside an AFrameP5 object. Versions 2.1 and 2.2 let you write let b = new Box({}), but in version 2.3 and later you need to write:

let b = new AFrameP5.Box({})

If you are using p5 version 2 (which the examples use), keep in mind that:

Begin by downloading the example gallery for the A-Frame P5 library. This template includes a series of examples that showcase the basic usage of this A-Frame P5 library, starting with the basics and building up to VR. They are grouped into numbered topic folders (1_worldAndObjects, 2_movementAndInteraction, and so on up to 7_vr), and the examples in each folder are numbered in the order we suggest working through them. Each example folder contains the following:

Once you've downloaded and unzipped the example gallery go ahead and open up one of the projects in your favorite text editor. Next, show the sketch.js and index.html files - this is where most of your work will take place. The index.html file can be used to load images or external media (you can also load images from your sketch using world.loadImage). The sketch.js file will be used to algorithmically add or manipulate object in the 3D world (boxes, planes, spheres, etc). To view any of these projects you will need to run them over a local web server, or by uploading them to a SSL enabled web hosting service.

If you are using a legacy version you can download the version 2.3 example gallery or the version 2.1 / 2.2 example gallery.

Here are live demos of each of the examples, in the order we suggest working through them:

World & objects

Movement & interaction

Dynamic textures

Heads-up displays

Physics

Voxels

VR (view these using a headset such as the Meta Quest)

Scene & Asset Management

All A-Frame P5 projects require some minimal HTML code to get started. A boilerplate HTML document will look something like this:

<!doctype html>
<html lang="en-us">
   <head>
      <meta charset="UTF-8">

      <!-- p5 core library -->
      <script src="https://cdn.jsdelivr.net/npm/p5@2.3.3/lib/p5.min.js"></script>

      <!-- A-Frame core library -->
      <script src="https://aframe.io/releases/1.7.1/aframe.min.js"></script>

      <!-- AFrameP5 library -->
      <script src="https://craignyu.github.io/aframep5/libraries/aframep5-v2.4.js"></script>

      <!-- Your p5 Sketch -->
      <script src="sketch.js"></script>

      <!-- custom styles -->
      <style>
         body {
            padding: 0;
            margin: 0;
         }
      </style>
   </head>
   <body>
	
      <!-- container to hold our VR scene - make sure to give this element an ID of 'VRScene' -->
      <a-scene id="VRScene">

         <!--
            The 'a-assets' container is used to load in any external artwork
            you may want to use as "textures" for your objects. Ensure that 
            this element has an ID of 'VRAssets'
            
            Textures can be loaded by creating a new 'img' tag inside of 
            the 'a-assets' container. When doing this you will need to make 
            sure to give your textures a unique ID - this will be used by p5 
            to create new objects.
            
            Example:
            
            <img id="brick" src="images/tiles/brick_red.png">
         -->
         
         <a-assets id="VRAssets">
         </a-assets>
      </a-scene>

   </body>
</html>

If you are planning on using external artwork or 3D models in your virtual world they will need to be included in your HTML document. All assets must be given unique ID's which will be referenced whenever you wish to use this texture in your world. This can be done using a <a-assets> tag, which needs to be nested inside of the <a-scene> tag. Images can also be loaded from your sketch using world.loadImage (see the loading textures example).

Coordinate System

A-Frame renders a three dimensional world that simulates width, height and depth. Every point within an A-Frame world can be expressed in terms of an x, y and z value.

When a world loads the x axis runs left to right, with values to the left being negative and values to the right being positive. The y axis extends up and down with negative values toward the bottom of the screen and positive values toward the top of the screen. The z axis extends forward and back - negative values extend forward into the screen and positive values extend back behind the screen (initially invisible unless the user turns around).

The world is rendered using a camera object which can be manipulated at runtime. The camera initially starts at position (0,1,5) - slightly higher than the true origin of the world, and slightly in front of it. The small height difference allows you to the height of a user (i.e. the camera won't be seeing your world from the perspective of a "bug" on the ground!)

When developing an A-Frame P5 project you will most likely be testing your work on a desktop or laptop. By default the system will enable the WASD keys (and the arrow keys) to allow you to move around using standard gaming mechanics ('W' moves you forward, 'S' moves you backward, 'A' moves you to the left and 'D' moves to you to the right). You can click and hold your mouse button down and drag the mouse to adjust the angle of your camera, allowing you to pan up, down and to the sides. The camera's direction determines your movement direction -- if you point the camera to the left and then click the 'W' key you will move in that direction.

Because VR headsets don't usually have a keyboard WASD navigation isn't usually feasible. Some ways to address this include:

Deploying to VR

A-Frame P5 should work out of the box when rendered through a browser on a VR headset. The basic process includes posting your project to a public web server (it needs to use https) and then loading the URL of the project through your headset's internal browser. When your project loads you will see it rendering on a flat plane, but if you click the small "VR" button at the bottom right side of the screen you will enter immersive VR mode.

In this immersive mode your controls re-map a bit. WASD navigation no longer functions, and pressing the trigger on your VR controller will fire a standard mouse event. Your controllers will also be visually displayed in the world and will emit "rays" - these rays act as mouse pointers and can be used to interact with objects in the world. You can hide the controllers (setControllerModels), change how the rays look (setControllerPointer) and attach your own objects to the controllers (addToController) - see the holding objects and VR painting examples.

Library Documentation

What follows is a technical overview of the various classes that can be used within a p5 sketch to construct and manipulate 3D objects. Please download the A-Frame P5 Examples ZIP archive for a series of comprehensive examples.

Class: World

Used to connect a p5 sketch to the A-Frame world. Instantiating a 'World' object is required in order to use all other classes in this library. This class requires that an a-scene tag has been added to the body of the HTML document.

Constructor

new AFrameP5.World(id, interactionMode)

ParameterTypeDefaultDescription
id string 'VRScene' The id of the 'a-scene' tag in the 'body' of the HTML document that should be used to render the VR world.
interactionMode string 'mouse' Determines how the user can interact with objects in terms of mouse events. The default is 'mouse' which allows the user to click on any object in their visible field - this is generally best for desktop and VR applications on a headset that supports controllers. You can also set this property to 'gaze' which will display a small reticle in the center of the user's field of view. This reticle will need to line up with an item while the user is clicking the mouse in order to trigger it. This is mainly useful for Google Cardboard style headsets which allow you to "tap" on the screen to indicate a mouse click. In 'gaze' mode the item that is directly in front of the user will receive any mouse/touch events that are fired.
Example

Instantiate a new AFrameP5.World object within your sketch.js file. Make sure to declare your world variable in the global scope to allow all functions the ability to access it. Ensure that the ID being passed to the World constructor includes the ID of the a-scene HTML tag.

// sketch.js file
let world;
			  		
function setup() {
   // no canvas needed
   noCanvas();
   
   world = new AFrameP5.World('VRScene');
}

In your HTML document make sure to include an a-scene tag with a valid ID.

<!-- index.html file -->					
<body>
  <a-scene id='VRScene'>
  
  </a-scene>
</body>
Methods
MethodDescription
add(entity: Entity) Adds an entity to the VR world.
addChild(entity: Entity) Adds an entity to the VR world (alias for add)
createDynamicTextureFromCreateGraphics(graphics: p5.Renderer) Accepts a reference to a p5.Renderer object created by the createGraphics function in p5. A-Frame P5 then turns this object into a dynamic texture that can be used with a 3D entity. It does this by setting up a small p5 sketch in 'instance mode' and registers the texture with the system so that it updates on a regular basis. For more inforamtion on how to use this feature please see the Multiple dynamic textures example.
enableWASD(enabled: boolean) Enables or disables navigation with the WASD keys.
getFlying(): boolean Gets whether the world currently supports "flying"
getPointInFrontOfUser(): object Returns an object that contains the position of a point about 1 meter in front of the user, as follows: {x:0, y:0, z:0}
getUserPosition(): object Returns an object that contains the camera's current position, as follows: {x:0, y:0, z:0}. The y value is the height of the user's eyes, which are 1.6 meters above their feet.
getUserRotation(): object Returns an object that contains the camera's current rotation, as follows: {x:0, y:0, z:0}
getWASDAcceleration(): number Gets the current value for WASD acceleration
hideCursor() Hide the cursor in front of the user (only works in "gaze" mode)
showCursor() Shows the cursor in front of the user (only works in "gaze" mode)
loop(): object Call's p5's loop function and turns on the draw callback cycle. This is the default behavior of both p5 and A-Frame P5 and generally you don't need to ever call this method. The only real use for this function is to reverse a call to noLoop which has implications for rendering on some VR headsets.
moveUserForward(distance: number) Moves the user forward along the camera's current heading by a desired amount. Distance is expressed in meters.
moveUserBackward(distance: number) (v2.4) Moves the user backward, away from the direction the camera is facing. Distance is expressed in meters.
moveUserLeft(distance: number) (v2.4) Moves the user to their left (relative to the direction the camera is facing). Distance is expressed in meters.
moveUserRight(distance: number) (v2.4) Moves the user to their right (relative to the direction the camera is facing). Distance is expressed in meters.
moveUserUp(distance: number) (v2.4) Moves the user up, relative to the camera (straight up if you are looking straight ahead). Distance is expressed in meters.
moveUserDown(distance: number) (v2.4) Moves the user down, relative to the camera. Distance is expressed in meters.
moveUser360(x: number, y: number, speed: number) (v2.4) Moves the user along the ground in any direction, relative to where they are looking. x and y are values from -1 to 1 (like a thumbstick: y = -1 is forward, x = 1 is to the right) and speed is how far to move per call. moveUserBasedOnControllerThumbstick does the same with the VR thumbsticks.
noLoop(): object Call's p5's noLoop function and turns off the draw callback cycle. If you plan on using p5's built-in noLoop function to disable the 'draw' function you should use this function instead. This is because p5 interally uses the requestAnimationFrame function to call the 'draw' function continually. On VR headsets this function is often disabled, which prevents 'draw' from ever being called. Because of this A-Frame P5 will "take over" calling the 'draw' function for you if necessary. Calling world.noLoop will prevent both p5 and A-Frame P5 from calling the draw loop. This function can be reversed by calling world.loop
remove(entity: Entity) Removes an entity to the VR world.
removeChild(entity: Entity) Removes an entity to the VR world (alias for remove)
rotateCameraX(degrees: number) Rotate's the user's view by the specified number of degrees along the X axis
rotateCameraY(degrees: number) Rotate's the user's view by the specified number of degrees along the Y axis
rotateCameraZ(degrees: number) Rotate's the user's view by the specified number of degrees along the Z axis
snapCameraY(degrees: number) (v2.4) "Snap turns" the user's view by the specified number of degrees along the Y axis (default 30). Call this every frame while a thumbstick or key is held: the view only turns once per push, and the thumbstick must be released before it will turn again. Returns true if the view turned on this call.
removeDefaultWorldLighting() Removes the default lights added by A-Frame.
loadImage(filename: string, id: string, callback?: function) (v2.4) Loads an image so it can be used as a texture (asset) without adding an <img> tag to your HTML file. Returns a Promise that gives back the id, so in an async function setup() you can wait for it: let tree = await world.loadImage('images/tree.png', 'tree'); then use asset: tree. The optional callback runs when the image has loaded.
setBackground(red: number, green: number, blue: number) Sets the background color of the world to a flat RGB color. The default background color is 255,255,255 (white) if you don't call this method.
setFog(options: object) (v2.4) Makes things fade into a color as they get further away - good for atmosphere, and for hiding the edge of a world. Options (all optional): near (how far away the fog starts, in meters, default 10), far (how far away everything is completely hidden, default 50) and red / green / blue (the fog color; by default it uses the background color set with setBackground, so the horizon blends in). setFog(false) turns the fog off. Example: world.setFog({ near: 8, far: 16 }); (see the voxel field example).
setClickOnRelease(enabled: boolean, tolerance?: number) (v2.4) On desktop you look around by dragging the mouse, but a drag that starts on an object also clicks it. setClickOnRelease(true) waits until the mouse button is released before calling an entity's clickFunction, and skips the click if the mouse moved more than tolerance pixels (default 5) - a bigger move counts as a drag to look around. The hit data is from where the button was pressed. With this on, clickFunction and upFunction both happen when the button is released (clickFunction first), and upFunction still happens after a drag. VR controller clicks aren't affected. Off by default; setClickOnRelease(false) turns it off again.
setFlying(flying: boolean) Sets whether the world supports "flying" (essentially allowing the user to move in the y axis). Default value is false
setUserPosition(x: number, y: number, z: number) Sets the user's position, essentially teleporting the user to this location. Like getUserPosition, y is the height of the user's eyes (their feet are 1.6 meters lower). With gravity on, the user can't be moved up into a solid object, so to put them on a platform whose top is at height t, use a y a little above t + 1.6 and let them drop onto it. The obstacle course example uses this to put the user back at the start when they fall off.
setWASDAcceleration(acceleration: number) Sets how fast the user will accelerate when navigating with the WASD keys. Default value is 65
setGazeControls() Sets the VR system to allow interaction events on all objects based on whether the interact with the camera reticle in the center of the user's view. Calling this method negates setMouseControls.
setMouseControls() Sets the VR system to allow interaction events on all objects based on the 2D position of the mouse. Also hides the camera reticle in the center of the user's view. This is the default setting for A-Frame P5. Calling this method negates setGazeControls.
slideToObject(entity: Entity, duration: number) Moves the user toward an entity over a period of time, expressed in milliseconds.
teleportToObject(entity: Entity) Immediately transports the user to the position of another entity.
setHUDDistance(z: number) Sets the distance of the Heads Up Display (HUD) in front of the user. Default value is -1, which represents 1 meter in front of the user. Note that by calling this function you can adjust the current HUD distance, which will affact any previously added HUD elements.
getHUDDistance(z: number): number Returns the current distance of the Heads Up Display (HUD) in front of the user. The default HUD distance is -1.
addToHUD(entity: Entity, x: number, y: number, z: number) Adds an entity to the Heads Up Display (HUD), allowing the entity to move along with the camera and always appear a fixed distance in front of the user. The coordinates x, y and y and relative to the user's position, so to place an item directly in front of the user you could use something like 0, 0 and -1.

The default for z is -1 which can be changed by the setHUDDistance method. Leaving off z will use the currently set HUD distance. You can also leave off all three coordinate values to relatively position the element in the HUD yourself.

(v2.4) Entities can be moved between the world and the HUD, and removed from the HUD and added back again.
removeFromHUD(entity: Entity) Removes an entity from the Heads Up Display (HUD).
Physics Methods (v2.4)

Entities created with solid: true (or made solid with setSolid(true)) block the user's movement and can be stood on. See the physics example.

MethodDescription
setGravity(options: object | false) Turns on gravity: the user falls until they land on the floor or on top of a solid entity. Options (all optional): strength (how quickly the user speeds up when falling, default 0.005), maxFallSpeed (the fastest the user can fall, default 0.15), floorY (the height of the ground, default 0) and stepHeight (the user automatically steps up onto anything this tall or shorter, like stairs; default 0 = off). Call setGravity(false) to turn gravity off. You'll usually also want setFlying(false). Big, fast drops and jumps can make people feel sick in VR, so keep these gentle. Example: world.setGravity({ strength: 0.005, maxFallSpeed: 0.15, stepHeight: 0.5 });
userJump(options: object) Makes the user jump, but only if gravity is on and they are standing on something (so it's safe to call every frame while a button is held). Option: strength (how high to jump, default 0.12: about 1.3 meters with the default gravity). Example: if (keyIsDown(' ')) { world.userJump({ strength: 0.12 }); }
setCreepingMode(options: object | false) While the given key or controller button is held, the user can't walk off the edge of whatever they are standing on. Options: key (e.g. 'shift') and/or controller ('leftTrigger', 'rightTrigger', 'leftGrip' or 'rightGrip'). Example: world.setCreepingMode({ key: 'shift', controller: 'leftGrip' });
setDebug(enabled: boolean) Turns on extra debugging information (a small label in the HUD, and information about voxel field chunks in the browser console).
VR Controller Methods
MethodDescription
getControllerRightThumbstickDirection(): string | boolean Reports the current direction that the user is pointing in with the right thumbstick. Return values could be "UP", "DOWN", "LEFT", "RIGHT", or false
getControllerLeftThumbstickDirection(): string | boolean Reports the current direction that the user is pointing in with the left thumbstick. Return values could be "UP", "DOWN", "LEFT", "RIGHT", or false
getControllerRightThumbstickRawData(): object Reports the current direction that the user is pointing in with right left thumbstick. Object will be returned in the following format: {x: Number; y: Number}
getControllerLeftThumbstickRawData(): object Reports the current direction that the user is pointing in with left left thumbstick. Object will be returned in the following format: {x: Number; y: Number}
isControllerRightTriggerDown(): boolean Reports whether the VR controller right trigger button is currently down
isControllerLeftTriggerDown(): boolean Reports whether the VR controller left trigger button is currently down
isControllerRightGripDown(): boolean Reports whether the VR controller right grip button is currently down
isControllerLeftGripDown(): boolean Reports whether the VR controller left grip button is currently down
isControllerAButtonDown(): boolean Reports whether the VR controller A button is currently down
isControllerBButtonDown(): boolean Reports whether the VR controller B button is currently down
isControllerXButtonDown(): boolean Reports whether the VR controller X button is currently down
isControllerYButtonDown(): boolean Reports whether the VR controller Y button is currently down
isControllerLeftMenuButtonDown(): boolean (v2.4) Reports whether the menu button on the left VR controller is currently down. Experimental on Meta Quest: A-Frame doesn't name this button for Quest controllers, so the library reads it as button number 12, which is what the Quest browser reports today. This isn't documented by Meta, so a future browser update could change it.
isControllerRightThumbstickPressed(): boolean (v2.4) Reports whether the right thumbstick is currently pressed in (clicked like a button)
isControllerLeftThumbstickPressed(): boolean (v2.4) Reports whether the left thumbstick is currently pressed in (clicked like a button)
isControllerRightThumbstickMoving(): boolean (v2.4) Reports whether the right thumbstick is currently being pushed in any direction (past the sensitivity set with setControllerSensitivity)
isControllerLeftThumbstickMoving(): boolean (v2.4) Reports whether the left thumbstick is currently being pushed in any direction
setControllerSensitivity(amount: number) (v2.4) How far a thumbstick has to be pushed (from 0 to 1) before it counts as a direction. The default is 0.95 (almost all the way); 0.5 is a good choice for movement.
moveUserBasedOnControllerThumbstick(hand: string, speed: number) (v2.4) Moves the user in whatever direction a thumbstick is pushed, relative to where they are looking. hand is 'left' or 'right'. Call this every frame in draw, e.g. world.moveUserBasedOnControllerThumbstick('left', 0.05); speed is how far to move per frame at 60 frames per second (0.05 is 3 meters per second). The movement itself happens on every frame the headset shows, so it stays smooth on headsets that run faster than 60 frames per second. Pair it with snapCameraY on the other thumbstick for turning (see the thumbstick movement example).
addToController(options: object) (v2.4) Attaches an entity to a VR controller so that it moves and turns with your hand. Options: controller ('left' or 'right'), entity, and optionally x, y, z (its position relative to the controller). The entity's negative Z axis points the same way as the controller's pointer. A hand's pointer ignores the objects that hand is holding, so they can't block it (the other hand can still click them). Example: world.addToController({ controller: 'right', entity: wand, x: 0, y: 0, z: 0 }); (see the holding objects example).
setControllerModels(visible: boolean) (v2.4) Shows (true, the default) or hides (false) the 3D models of the VR controllers, for example so that you can replace them with your own objects using addToController. The pointers and any objects you've attached to the controllers are still shown.
setControllerPointer(options: object) (v2.4) Changes how the VR controller pointers (lasers) look. Options (all optional): hand ('left', 'right' or 'both', the default), red / green / blue (the color), thickness (0 for the standard thin line, or the width of a thicker beam in meters, e.g. 0.005; a beam stops where it hits something) and visible (false hides the pointer, but you can still point and click). Example: world.setControllerPointer({ hand: 'right', thickness: 0.004, red: 255, green: 0, blue: 0 }); (see the VR painting example).

Class: Box (entity)

Used to construct a six-faced box entity.

Constructor Parameters (common to all entities)

new AFrameP5.Box(options)

OptionTypeDefaultDescription
x number 0 x-position of the entity
y number 0 y-position of the entity
z number 0 z-position of the entity
opacity number 1.0 how transparent this entity is (0.0 = fully transparent, 1.0 = fully opaque)
transparent boolean false whether the texture associated with this entity supports transparency (i.e. a PNG file with an alpha channel)
alphaTest number 0 (v2.4) pixels less opaque than this value (0.0 to 1.0) are not drawn at all. Use 0.5 for cut-out pictures such as trees (PNGs with see-through parts), otherwise the see-through parts can hide whatever is behind them. 0 turns it off.
shader string 'standard' the ThreeJS shader to use to render this entity - other valid value is flat
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
roughness number 0.5 how 'rough' the material appears. valid range = 0.0 to 1.0
metalness number 0 how 'metallic' the material appears. valid range = 0.0 to 1.0
red integer 255 how red the entity appears. valid range = 0 to 255
green integer 255 how green the entity appears. valid range = 0 to 255
blue integer 255 how blue the entity appears. valid range = 0 to 255
repeatX integer 1 how many times to repeat the texture associated with the entity along the x-axis of each face of the object. valid range = any positive number
repeatY integer 1 how many times to repeat the texture associated with the entity along the y-axis of each face of the object. valid range = any positive number
asset string 'None' the id (string) of the element that should be used as a texture for this entity. all textures should be set up in the 'index.html' file inside of the a-assets tag.
scaleX number 1.0 the scale of the object in the x-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleY number 1.0 the scale of the object in the y-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleZ number 1.0 the scale of the object in the z-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
rotationX number 0 the rotation of the object along the x-axis.
rotationY number 0 the rotation of the object along the y-axis.
rotationZ number 0 the rotation of the object along the z-axis.
visible boolean true determines whether the entity is visible in the scene.
solid boolean false (v2.4) solid entities block the user's movement and can be stood on when gravity is turned on (see world.setGravity and the physics example).
dynamicTexture boolean false sets whether the texture used on the entity is being drawn from a dynamically drawn canvas element. see these examples for more information: Dynamic textures, Multiple dynamic textures and Interactive dynamic textures
dynamicTextureHeight number 0 tells the entity the height of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
dynamicTextureWidth number 0 tells the entity the width of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
customData object undefined a custom object that can be used by the entity to keep track of user-specified data. example:
let b = new AFrameP5.Box({
   customData: {
      numClicks: 0
   },
   clickFunction: function(e) { 
      e.customData.numClicks++;
      console.log("This element has been clicked " + e.customData.numClicks + " times");
   }
});
clickFunction function undefined a custom function that will run every time the user clicks on the entity. this function receives a reference to the entity that was clicked, and (v2.4) a second argument with information about the click (see below). example:
let b = new AFrameP5.Box({
   clickFunction: function(e) { 
      e.setRed(random(255)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   clickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});


(v2.4) the second argument, often called hit, describes the click:
  • point3d : the exact point in the world where the click landed (an object with x, y and z)
  • distance : how far away that point is from the user, in meters
  • hand : what did the clicking: 'mouse' (the mouse, or the gaze cursor), 'left' or 'right' (the VR controllers)
  • uv : the raw texture coordinates of the click (x and y, from 0 to 1)
  • point2d : for entities that use a dynamic texture, where on the texture the click landed (x and y, in pixels)
  • voxel and voxelAdjacent : for voxel grids, the cube that was clicked and the empty space next to the face that was clicked
example:
let b = new AFrameP5.Box({
   clickFunction: function(e, hit) {
      console.log("clicked at " + hit.point3d.x + ", " + hit.point3d.y + ", " + hit.point3d.z + " with the " + hit.hand);
   }
});
see the click information example.
upFunction function undefined a custom function that will run every time the releases the mouse after the entity has been clicked. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   upFunction: function(e) { 
      e.spinX(random(360)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   upFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
enterFunction function undefined a custom function that will run every time the mouse hovers over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   enterFunction: function(e) { 
      e.setScale(2,2,2); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   enterFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
leaveFunction function undefined a custom function that will run every time the mouse stops hovering over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   leaveFunction: function(e) { 
      e.setScale(1,1,1); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   leaveFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
overFunction function undefined a custom function that will run continually whenever the mouse is hovering over the entity. this function should be implemented to accept two arguments - the first is a reference to the entity that was clicked, and the second is an object that contains information about the interaction that just occured. example:
let b = AFrameP5.Box({
   overFunction: function(e, intersectionInfo) { 
      console.log(intersectionInfo);
   }
});
intersectionInfo is an object that contains info about how the user is interacting with this entity. it contains the following properties:
  • distance : a float describing how far away the user is
  • point3d : an object with three properties (x, y & z) describing where the user is touching the entity
  • point2d : an object with two properites (x & y) describing where the user is touching the entity in 2D space (useful for determining where on a dynamic canvas the user is touching)
  • uv : an object with two properies (x & y) describing the raw textural offset (used to compute point2d)
  • hand : (v2.4) which pointer is hovering: 'mouse', 'left' or 'right'. Each VR controller calls overFunction separately, so check this if only one hand should do something (for example, only paint with the right hand).
For an example please see the Interactive dynamic textures sample program.

as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   overFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
dragFunction function undefined (v2.4) a custom function that runs every frame while the user holds the mouse button (or a VR controller trigger) down after pressing on this entity and keeps pointing at it - for example, to draw on a dynamic texture. A drag that starts somewhere else and moves onto the entity doesn't count. While the mouse is dragging on the entity, it doesn't turn the camera, so the view stays still while you draw. It takes the same two arguments as overFunction (the entity and hit), plus two more properties in hit:
  • previousPoint2d : where the user was pointing on the dynamic texture on the previous frame (x and y, in pixels). It is null when a new drag starts, and again when the pointer comes back onto the entity during a drag, so you can draw a line from it to point2d without joining separate strokes.
  • previousPoint3d : the same thing in the world (x, y and z)
example:
let canvas = new AFrameP5.Plane({
   asset: texture, dynamicTexture: true, dynamicTextureWidth: 512, dynamicTextureHeight: 512,
   dragFunction: function(e, hit) {
      if (hit.previousPoint2d) {
         buffer.line(hit.previousPoint2d.x, hit.previousPoint2d.y, hit.point2d.x, hit.point2d.y);
      }
   }
});
Each VR controller drags separately, so check hit.hand if only one hand should draw.

In VR, clickFunction runs as soon as the trigger is pressed (setClickOnRelease only changes mouse clicks), so avoid giving one entity both a clickFunction and a dragFunction if that matters. To do something at the start of each drag (for example, stamp a dot), check for hit.previousPoint2d === null inside dragFunction instead.
tickFunction function undefined a custom function that will run once per frame (like draw does for the main sketch). this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   tickFunction: function(e) { 
      e.setRed( random(255) ); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   tickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
Constructor Parameters (specific to this class)

new AFrameP5.Box(options)

OptionTypeDefaultDescription
width number 1 width of the entity (along the x-axis)
height number 1 height of the entity (along the y-axis)
depth number 1 depth of the entity (along the z-axis)
Example
// sketch.js file

let world;
let box;
			  		
function setup() {
   // no canvas needed
   noCanvas();
   
   // create a new VR World object
   world = new AFrameP5.World('VRScene');
   
   // construct a new box
   box = new AFrameP5.Box({
      x:0, 
      y:2, 
      z:-2, 
      width: 1, 
      depth: 1.5, 
      height: 1.2, 
      red:255, 
      green:0, 
      blue:0
    });
    
    // add the box to the world
    world.add(box);
}
Methods (common to all entities)
MethodCategoryDescription
constrainPosition(xMin: number, xMax: number, yMin: number, yMax: number, zMin: number, zMax: number) Position ensures that the entity is constrained within the desired boundaries along all three axes. if an entity exceeds any of the constraints it is nudged back into position accordingly.
getX(): number Position returns the current x position of the entity. this is the entity's LOCAL position in relation to its container.
getY(): number Position returns the current y position of the entity. this is the entity's LOCAL position in relation to its container.
getZ(): number Position returns the current z position of the entity. this is the entity's LOCAL position in relation to its container.
nudge(x: number, y: number, z: number) Position nudges the element based on its current position. accepts three numeric values (i.e. myEntity.nudge(1,0,0); will nudge the entity 1 meter from its current position along the x-axis. this is the entity's LOCAL position in relation to its container.
setPosition(x: number, y: number, z: number) Position sets the position of the entity. this is the entity's LOCAL position in relation to its container.
setX(x: number) Position sets the x position of the entity. this is the entity's LOCAL position in relation to its container.
setY(y: number) Position sets the y position of the entity. this is the entity's LOCAL position in relation to its container.
setZ(z: number) Position sets the z position of the entity. this is the entity's LOCAL position in relation to its container.
getWorldPosition(): object Position returns the entity's WORLD position, not it's local position within its current container. this method is often used to compute the absolute position of an element in world space in order to deal with collisions of objects that may be nested inside of containers.
getRotationX(): number Rotation returns the current x rotation of the entity.
getRotationY(): number Rotation returns the current y rotation of the entity.
getRotationZ(): number Rotation returns the current z rotation of the entity.
rotateX(x: number) Rotation sets the x rotation of the entity
rotateY(y: number) Rotation sets the y rotation of the entity
rotateZ(z: number) Rotation sets the z rotation of the entity
setRotation(x: number, y: number, z: number) Rotation sets the rotation of the entity.
spinX(x: number) Rotation spins the entity along the x axis based on its current rotation. i.e. myEntity.spinX(1); // spin by 1 degree
spinY(y: number) Rotation spins the entity along the y axis based on its current rotation. i.e. myEntity.spinY(1); // spin by 1 degree
spinZ(z: number) Rotation spins the entity along the z axis based on its current rotation. i.e. myEntity.spinZ(1); // spin by 1 degree
lookAtUser(upright?: boolean) Rotation forces the entity to orient itself so that it is facing the user. (v2.4) lookAtUser(true) keeps the entity upright, so it only turns left and right - use this for billboards such as trees, which would otherwise tip over when the user walks up close.
getVisibility(): boolean Visibility returns the current visibility state of the entity
hide() Visibility hides the entity by setting its visible property to false
show() Visibility shows the entity by setting its visible property to true
toggleVisibility() Visibility hides the entity if it is current visible and shows the entity if it is current hidden
getScale(): object Scale returns the scale of the entity as an object (i.e. {x:0, y:0, z:0}
getScaleX(): number Scale returns the x scale of the entity
getScaleY(): number Scale returns the y scale of the entity
getScaleZ(): number Scale returns the z scale of the entity
setScale(x: number, y: number, z: number) Scale sets the scale of the object in all axes
setScaleX(x: number) Scale sets the x scale of the object
setScaleY(y: number) Scale sets the y scale of the object
setScaleZ(z: number) Scale sets the z scale of the object
getAsset(): string Material returns the current id of the asset being used to texture this entity
getBlue(): number Material returns the current blue color of the entity
getGreen(): number Material returns the current green color of the entity
getMetalness(): number Material returns the current metalness setting for the texture of the entity (range = 0.0 to 1.0)
getOpacity(): number Material returns the current opacity of the entity
getRed(): number Material returns the current red color of the entity
setRoughness(roughness: number) Material sets the roughness for the texture of the entity (range = 0.0 to 1.0)
getSide(): string Material returns which faces of the entity will be textured (valid values are front, back and double)
getTransparent(): boolean Material returns the current transparency of the entity
setAsset(asset: string) Material sets the id for the asset to texture this entity
setColor(red: number, green: number, blue: number) Material sets the color of the entity
setBlue(blue: number) Material sets the blue color of the entity
setGreen(green: number) Material sets the green color of the entity
setMetalness(metalness: number) Material sets the metalness for the texture of the entity (range = 0.0 to 1.0)
setOpacity(opacity: number) Material sets the opacity of the entity (range = 0.0 to 1.0)
setRed(red: number) Material sets the red color of the entity
getRoughness(): number Material returns the current roughness setting for the texture of the entity (range = 0.0 to 1.0)
setTransparent(transparent: boolean) Material sets whether the entity supports transparent textures
getAlphaTest(): number Material (v2.4) returns the entity's alphaTest value
setAlphaTest(alphaTest: number) Material (v2.4) sets the alphaTest value (see the alphaTest constructor option)
setSide(side: string) Material sets which faces of the entity will be textured (valid values are front, back and double)
getRepeatX(): number Material returns how many times the texture repeats across the entity horizontally
getRepeatY(): number Material (v2.4) returns how many times the texture repeats across the entity vertically
setRepeatX(times: number) Material sets how many times the texture repeats across the entity horizontally
setRepeatY(times: number) Material (v2.4) sets how many times the texture repeats across the entity vertically
getSolid(): boolean Physics (v2.4) returns whether the entity is solid
setSolid(solid: boolean) Physics (v2.4) makes the entity solid (true: it blocks the user and can be stood on) or not solid (false: the user can walk through it)
add(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity. alias for addChild.
addChild(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity.
getChildren(): Array Hierarchy returns an Array of all children of this entity
removeChild(entity: Entity) Hierarchy removes a child entity from this entity.
Methods (specific to this class)
MethodCategoryDescription
getDepth(): number Geometry returns the current depth of the entity
getHeight(): number Geometry returns the current height of the entity
getWidth(): number Geometry returns the current width of the entity
setDepth(depth: number) Geometry sets the depth of the entity
setHeight(height: number) Geometry sets the height of the entity
setWidth(width: number) Geometry sets the width of the entity

Class: Plane (entity)

Used to construct a flat two dimensional plane entity.

Constructor Parameters (common to all entities)

new AFrameP5.Plane(options)

OptionTypeDefaultDescription
x number 0 x-position of the entity
y number 0 y-position of the entity
z number 0 z-position of the entity
opacity number 1.0 how transparent this entity is (0.0 = fully transparent, 1.0 = fully opaque)
transparent boolean false whether the texture associated with this entity supports transparency (i.e. a PNG file with an alpha channel)
alphaTest number 0 (v2.4) pixels less opaque than this value (0.0 to 1.0) are not drawn at all. Use 0.5 for cut-out pictures such as trees (PNGs with see-through parts), otherwise the see-through parts can hide whatever is behind them. 0 turns it off.
shader string 'standard' the ThreeJS shader to use to render this entity - other valid value is flat
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
roughness number 0.5 how 'rough' the material appears. valid range = 0.0 to 1.0
metalness number 0 how 'metallic' the material appears. valid range = 0.0 to 1.0
red integer 255 how red the entity appears. valid range = 0 to 255
green integer 255 how green the entity appears. valid range = 0 to 255
blue integer 255 how blue the entity appears. valid range = 0 to 255
repeatX integer 1 how many times to repeat the texture associated with the entity along the x-axis of each face of the object. valid range = any positive number
repeatY integer 1 how many times to repeat the texture associated with the entity along the y-axis of each face of the object. valid range = any positive number
asset string 'None' the id (string) of the element that should be used as a texture for this entity. all textures should be set up in the 'index.html' file inside of the a-assets tag.
scaleX number 1.0 the scale of the object in the x-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleY number 1.0 the scale of the object in the y-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleZ number 1.0 the scale of the object in the z-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
rotationX number 0 the rotation of the object along the x-axis.
rotationY number 0 the rotation of the object along the y-axis.
rotationZ number 0 the rotation of the object along the z-axis.
visible boolean true determines whether the entity is visible in the scene.
solid boolean false (v2.4) solid entities block the user's movement and can be stood on when gravity is turned on (see world.setGravity and the physics example).
dynamicTexture boolean false sets whether the texture used on the entity is being drawn from a dynamically drawn canvas element. see these examples for more information: Dynamic textures, Multiple dynamic textures and Interactive dynamic textures
dynamicTextureHeight number 0 tells the entity the height of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
dynamicTextureWidth number 0 tells the entity the width of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
customData object undefined a custom object that can be used by the entity to keep track of user-specified data. example:
let b = new AFrameP5.Box({
   customData: {
      numClicks: 0
   },
   clickFunction: function(e) { 
      e.customData.numClicks++;
      console.log("This element has been clicked " + e.customData.numClicks + " times");
   }
});
clickFunction function undefined a custom function that will run every time the user clicks on the entity. this function receives a reference to the entity that was clicked, and (v2.4) a second argument with information about the click (see below). example:
let b = new AFrameP5.Box({
   clickFunction: function(e) { 
      e.setRed(random(255)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   clickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});


(v2.4) the second argument, often called hit, describes the click:
  • point3d : the exact point in the world where the click landed (an object with x, y and z)
  • distance : how far away that point is from the user, in meters
  • hand : what did the clicking: 'mouse' (the mouse, or the gaze cursor), 'left' or 'right' (the VR controllers)
  • uv : the raw texture coordinates of the click (x and y, from 0 to 1)
  • point2d : for entities that use a dynamic texture, where on the texture the click landed (x and y, in pixels)
  • voxel and voxelAdjacent : for voxel grids, the cube that was clicked and the empty space next to the face that was clicked
example:
let b = new AFrameP5.Box({
   clickFunction: function(e, hit) {
      console.log("clicked at " + hit.point3d.x + ", " + hit.point3d.y + ", " + hit.point3d.z + " with the " + hit.hand);
   }
});
see the click information example.
upFunction function undefined a custom function that will run every time the releases the mouse after the entity has been clicked. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   upFunction: function(e) { 
      e.spinX(random(360)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   upFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
enterFunction function undefined a custom function that will run every time the mouse hovers over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   enterFunction: function(e) { 
      e.setScale(2,2,2); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   enterFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
leaveFunction function undefined a custom function that will run every time the mouse stops hovering over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   leaveFunction: function(e) { 
      e.setScale(1,1,1); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   leaveFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
overFunction function undefined a custom function that will run continually whenever the mouse is hovering over the entity. this function should be implemented to accept two arguments - the first is a reference to the entity that was clicked, and the second is an object that contains information about the interaction that just occured. example:
let b = AFrameP5.Box({
   overFunction: function(e, intersectionInfo) { 
      console.log(intersectionInfo);
   }
});
intersectionInfo is an object that contains info about how the user is interacting with this entity. it contains the following properties:
  • distance : a float describing how far away the user is
  • point3d : an object with three properties (x, y & z) describing where the user is touching the entity
  • point2d : an object with two properites (x & y) describing where the user is touching the entity in 2D space (useful for determining where on a dynamic canvas the user is touching)
  • uv : an object with two properies (x & y) describing the raw textural offset (used to compute point2d)
  • hand : (v2.4) which pointer is hovering: 'mouse', 'left' or 'right'. Each VR controller calls overFunction separately, so check this if only one hand should do something (for example, only paint with the right hand).
For an example please see the Interactive dynamic textures sample program.

as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   overFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
dragFunction function undefined (v2.4) a custom function that runs every frame while the user holds the mouse button (or a VR controller trigger) down after pressing on this entity and keeps pointing at it - for example, to draw on a dynamic texture. A drag that starts somewhere else and moves onto the entity doesn't count. While the mouse is dragging on the entity, it doesn't turn the camera, so the view stays still while you draw. It takes the same two arguments as overFunction (the entity and hit), plus two more properties in hit:
  • previousPoint2d : where the user was pointing on the dynamic texture on the previous frame (x and y, in pixels). It is null when a new drag starts, and again when the pointer comes back onto the entity during a drag, so you can draw a line from it to point2d without joining separate strokes.
  • previousPoint3d : the same thing in the world (x, y and z)
example:
let canvas = new AFrameP5.Plane({
   asset: texture, dynamicTexture: true, dynamicTextureWidth: 512, dynamicTextureHeight: 512,
   dragFunction: function(e, hit) {
      if (hit.previousPoint2d) {
         buffer.line(hit.previousPoint2d.x, hit.previousPoint2d.y, hit.point2d.x, hit.point2d.y);
      }
   }
});
Each VR controller drags separately, so check hit.hand if only one hand should draw.

In VR, clickFunction runs as soon as the trigger is pressed (setClickOnRelease only changes mouse clicks), so avoid giving one entity both a clickFunction and a dragFunction if that matters. To do something at the start of each drag (for example, stamp a dot), check for hit.previousPoint2d === null inside dragFunction instead.
tickFunction function undefined a custom function that will run once per frame (like draw does for the main sketch). this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   tickFunction: function(e) { 
      e.setRed( random(255) ); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   tickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
Constructor Parameters (specific to this class)

new AFrameP5.Plane(options)

OptionTypeDefaultDescription
width number 1 width of the entity (along the x-axis)
height number 1 height of the entity (along the y-axis)
Example
// sketch.js file

let world;
let plane;
			  		
function setup() {
   // no canvas needed
   noCanvas();
   
   // create a new VR World object
   world = new AFrameP5.World('VRScene');
   
   // construct a new plane to serve as the 'ground' for our world
   plane = new AFrameP5.Plane({
      x:0, 
      y:0, 
      z:0, 
      width: 100, 
      height: 100, 
      red:0, 
      green:255, 
      blue:0, 
      rotationX:-90
   });
   
   // add the plane to the world
   world.add(plane);
}
Methods (common to all entities)
MethodCategoryDescription
constrainPosition(xMin: number, xMax: number, yMin: number, yMax: number, zMin: number, zMax: number) Position ensures that the entity is constrained within the desired boundaries along all three axes. if an entity exceeds any of the constraints it is nudged back into position accordingly.
getX(): number Position returns the current x position of the entity. this is the entity's LOCAL position in relation to its container.
getY(): number Position returns the current y position of the entity. this is the entity's LOCAL position in relation to its container.
getZ(): number Position returns the current z position of the entity. this is the entity's LOCAL position in relation to its container.
nudge(x: number, y: number, z: number) Position nudges the element based on its current position. accepts three numeric values (i.e. myEntity.nudge(1,0,0); will nudge the entity 1 meter from its current position along the x-axis. this is the entity's LOCAL position in relation to its container.
setPosition(x: number, y: number, z: number) Position sets the position of the entity. this is the entity's LOCAL position in relation to its container.
setX(x: number) Position sets the x position of the entity. this is the entity's LOCAL position in relation to its container.
setY(y: number) Position sets the y position of the entity. this is the entity's LOCAL position in relation to its container.
setZ(z: number) Position sets the z position of the entity. this is the entity's LOCAL position in relation to its container.
getWorldPosition(): object Position returns the entity's WORLD position, not it's local position within its current container. this method is often used to compute the absolute position of an element in world space in order to deal with collisions of objects that may be nested inside of containers.
getRotationX(): number Rotation returns the current x rotation of the entity.
getRotationY(): number Rotation returns the current y rotation of the entity.
getRotationZ(): number Rotation returns the current z rotation of the entity.
rotateX(x: number) Rotation sets the x rotation of the entity
rotateY(y: number) Rotation sets the y rotation of the entity
rotateZ(z: number) Rotation sets the z rotation of the entity
setRotation(x: number, y: number, z: number) Rotation sets the rotation of the entity.
spinX(x: number) Rotation spins the entity along the x axis based on its current rotation. i.e. myEntity.spinX(1); // spin by 1 degree
spinY(y: number) Rotation spins the entity along the y axis based on its current rotation. i.e. myEntity.spinY(1); // spin by 1 degree
spinZ(z: number) Rotation spins the entity along the z axis based on its current rotation. i.e. myEntity.spinZ(1); // spin by 1 degree
lookAtUser(upright?: boolean) Rotation forces the entity to orient itself so that it is facing the user. (v2.4) lookAtUser(true) keeps the entity upright, so it only turns left and right - use this for billboards such as trees, which would otherwise tip over when the user walks up close.
getVisibility(): boolean Visibility returns the current visibility state of the entity
hide() Visibility hides the entity by setting its visible property to false
show() Visibility shows the entity by setting its visible property to true
toggleVisibility() Visibility hides the entity if it is current visible and shows the entity if it is current hidden
getScale(): object Scale returns the scale of the entity as an object (i.e. {x:0, y:0, z:0}
getScaleX(): number Scale returns the x scale of the entity
getScaleY(): number Scale returns the y scale of the entity
getScaleZ(): number Scale returns the z scale of the entity
setScale(x: number, y: number, z: number) Scale sets the scale of the object in all axes
setScaleX(x: number) Scale sets the x scale of the object
setScaleY(y: number) Scale sets the y scale of the object
setScaleZ(z: number) Scale sets the z scale of the object
getAsset(): string Material returns the current id of the asset being used to texture this entity
getBlue(): number Material returns the current blue color of the entity
getGreen(): number Material returns the current green color of the entity
getMetalness(): number Material returns the current metalness setting for the texture of the entity (range = 0.0 to 1.0)
getOpacity(): number Material returns the current opacity of the entity
getRed(): number Material returns the current red color of the entity
setRoughness(roughness: number) Material sets the roughness for the texture of the entity (range = 0.0 to 1.0)
getSide(): string Material returns which faces of the entity will be textured (valid values are front, back and double)
getTransparent(): boolean Material returns the current transparency of the entity
setAsset(asset: string) Material sets the id for the asset to texture this entity
setColor(red: number, green: number, blue: number) Material sets the color of the entity
setBlue(blue: number) Material sets the blue color of the entity
setGreen(green: number) Material sets the green color of the entity
setMetalness(metalness: number) Material sets the metalness for the texture of the entity (range = 0.0 to 1.0)
setOpacity(opacity: number) Material sets the opacity of the entity (range = 0.0 to 1.0)
setRed(red: number) Material sets the red color of the entity
getRoughness(): number Material returns the current roughness setting for the texture of the entity (range = 0.0 to 1.0)
setTransparent(transparent: boolean) Material sets whether the entity supports transparent textures
getAlphaTest(): number Material (v2.4) returns the entity's alphaTest value
setAlphaTest(alphaTest: number) Material (v2.4) sets the alphaTest value (see the alphaTest constructor option)
setSide(side: string) Material sets which faces of the entity will be textured (valid values are front, back and double)
getRepeatX(): number Material returns how many times the texture repeats across the entity horizontally
getRepeatY(): number Material (v2.4) returns how many times the texture repeats across the entity vertically
setRepeatX(times: number) Material sets how many times the texture repeats across the entity horizontally
setRepeatY(times: number) Material (v2.4) sets how many times the texture repeats across the entity vertically
getSolid(): boolean Physics (v2.4) returns whether the entity is solid
setSolid(solid: boolean) Physics (v2.4) makes the entity solid (true: it blocks the user and can be stood on) or not solid (false: the user can walk through it)
add(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity. alias for addChild.
addChild(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity.
getChildren(): Array Hierarchy returns an Array of all children of this entity
removeChild(entity: Entity) Hierarchy removes a child entity from this entity.
Methods (specific to this class)
MethodCategoryDescription
getHeight(): number Geometry returns the current height of the entity
getWidth(): number Geometry returns the current width of the entity
setHeight(height: number) Geometry sets the height of the entity
setWidth(width: number) Geometry sets the width of the entity

Class: Circle (entity)

Used to construct a flat two dimensional circular entity.

Constructor Parameters (common to all entities)

new AFrameP5.Circle(options)

OptionTypeDefaultDescription
x number 0 x-position of the entity
y number 0 y-position of the entity
z number 0 z-position of the entity
opacity number 1.0 how transparent this entity is (0.0 = fully transparent, 1.0 = fully opaque)
transparent boolean false whether the texture associated with this entity supports transparency (i.e. a PNG file with an alpha channel)
alphaTest number 0 (v2.4) pixels less opaque than this value (0.0 to 1.0) are not drawn at all. Use 0.5 for cut-out pictures such as trees (PNGs with see-through parts), otherwise the see-through parts can hide whatever is behind them. 0 turns it off.
shader string 'standard' the ThreeJS shader to use to render this entity - other valid value is flat
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
roughness number 0.5 how 'rough' the material appears. valid range = 0.0 to 1.0
metalness number 0 how 'metallic' the material appears. valid range = 0.0 to 1.0
red integer 255 how red the entity appears. valid range = 0 to 255
green integer 255 how green the entity appears. valid range = 0 to 255
blue integer 255 how blue the entity appears. valid range = 0 to 255
repeatX integer 1 how many times to repeat the texture associated with the entity along the x-axis of each face of the object. valid range = any positive number
repeatY integer 1 how many times to repeat the texture associated with the entity along the y-axis of each face of the object. valid range = any positive number
asset string 'None' the id (string) of the element that should be used as a texture for this entity. all textures should be set up in the 'index.html' file inside of the a-assets tag.
scaleX number 1.0 the scale of the object in the x-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleY number 1.0 the scale of the object in the y-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleZ number 1.0 the scale of the object in the z-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
rotationX number 0 the rotation of the object along the x-axis.
rotationY number 0 the rotation of the object along the y-axis.
rotationZ number 0 the rotation of the object along the z-axis.
visible boolean true determines whether the entity is visible in the scene.
solid boolean false (v2.4) solid entities block the user's movement and can be stood on when gravity is turned on (see world.setGravity and the physics example).
dynamicTexture boolean false sets whether the texture used on the entity is being drawn from a dynamically drawn canvas element. see these examples for more information: Dynamic textures, Multiple dynamic textures and Interactive dynamic textures
dynamicTextureHeight number 0 tells the entity the height of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
dynamicTextureWidth number 0 tells the entity the width of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
customData object undefined a custom object that can be used by the entity to keep track of user-specified data. example:
let b = new AFrameP5.Box({
   customData: {
      numClicks: 0
   },
   clickFunction: function(e) { 
      e.customData.numClicks++;
      console.log("This element has been clicked " + e.customData.numClicks + " times");
   }
});
clickFunction function undefined a custom function that will run every time the user clicks on the entity. this function receives a reference to the entity that was clicked, and (v2.4) a second argument with information about the click (see below). example:
let b = new AFrameP5.Box({
   clickFunction: function(e) { 
      e.setRed(random(255)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   clickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});


(v2.4) the second argument, often called hit, describes the click:
  • point3d : the exact point in the world where the click landed (an object with x, y and z)
  • distance : how far away that point is from the user, in meters
  • hand : what did the clicking: 'mouse' (the mouse, or the gaze cursor), 'left' or 'right' (the VR controllers)
  • uv : the raw texture coordinates of the click (x and y, from 0 to 1)
  • point2d : for entities that use a dynamic texture, where on the texture the click landed (x and y, in pixels)
  • voxel and voxelAdjacent : for voxel grids, the cube that was clicked and the empty space next to the face that was clicked
example:
let b = new AFrameP5.Box({
   clickFunction: function(e, hit) {
      console.log("clicked at " + hit.point3d.x + ", " + hit.point3d.y + ", " + hit.point3d.z + " with the " + hit.hand);
   }
});
see the click information example.
upFunction function undefined a custom function that will run every time the releases the mouse after the entity has been clicked. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   upFunction: function(e) { 
      e.spinX(random(360)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   upFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
enterFunction function undefined a custom function that will run every time the mouse hovers over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   enterFunction: function(e) { 
      e.setScale(2,2,2); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   enterFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
leaveFunction function undefined a custom function that will run every time the mouse stops hovering over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   leaveFunction: function(e) { 
      e.setScale(1,1,1); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   leaveFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
overFunction function undefined a custom function that will run continually whenever the mouse is hovering over the entity. this function should be implemented to accept two arguments - the first is a reference to the entity that was clicked, and the second is an object that contains information about the interaction that just occured. example:
let b = AFrameP5.Box({
   overFunction: function(e, intersectionInfo) { 
      console.log(intersectionInfo);
   }
});
intersectionInfo is an object that contains info about how the user is interacting with this entity. it contains the following properties:
  • distance : a float describing how far away the user is
  • point3d : an object with three properties (x, y & z) describing where the user is touching the entity
  • point2d : an object with two properites (x & y) describing where the user is touching the entity in 2D space (useful for determining where on a dynamic canvas the user is touching)
  • uv : an object with two properies (x & y) describing the raw textural offset (used to compute point2d)
  • hand : (v2.4) which pointer is hovering: 'mouse', 'left' or 'right'. Each VR controller calls overFunction separately, so check this if only one hand should do something (for example, only paint with the right hand).
For an example please see the Interactive dynamic textures sample program.

as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   overFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
dragFunction function undefined (v2.4) a custom function that runs every frame while the user holds the mouse button (or a VR controller trigger) down after pressing on this entity and keeps pointing at it - for example, to draw on a dynamic texture. A drag that starts somewhere else and moves onto the entity doesn't count. While the mouse is dragging on the entity, it doesn't turn the camera, so the view stays still while you draw. It takes the same two arguments as overFunction (the entity and hit), plus two more properties in hit:
  • previousPoint2d : where the user was pointing on the dynamic texture on the previous frame (x and y, in pixels). It is null when a new drag starts, and again when the pointer comes back onto the entity during a drag, so you can draw a line from it to point2d without joining separate strokes.
  • previousPoint3d : the same thing in the world (x, y and z)
example:
let canvas = new AFrameP5.Plane({
   asset: texture, dynamicTexture: true, dynamicTextureWidth: 512, dynamicTextureHeight: 512,
   dragFunction: function(e, hit) {
      if (hit.previousPoint2d) {
         buffer.line(hit.previousPoint2d.x, hit.previousPoint2d.y, hit.point2d.x, hit.point2d.y);
      }
   }
});
Each VR controller drags separately, so check hit.hand if only one hand should draw.

In VR, clickFunction runs as soon as the trigger is pressed (setClickOnRelease only changes mouse clicks), so avoid giving one entity both a clickFunction and a dragFunction if that matters. To do something at the start of each drag (for example, stamp a dot), check for hit.previousPoint2d === null inside dragFunction instead.
tickFunction function undefined a custom function that will run once per frame (like draw does for the main sketch). this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   tickFunction: function(e) { 
      e.setRed( random(255) ); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   tickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
Constructor Parameters (specific to this class)

new AFrameP5.Circle(options)

OptionTypeDefaultDescription
radius number 1 radius of the entity (in meters)
segments integer 32 the number of segments to use when drawing the circle (higher numbers will yield a "smoother" looking circle)
thetaStart integer 0 start angle for first segment. can be used to define a partial circle.
thetaLength integer 360 the central angle (in degrees). defaults to 360, which makes for a complete circle.
Example
// sketch.js file

let world;
let circle;
			  		
function setup() {
   // no canvas needed
   noCanvas();
   
   // create a new VR World object
   world = new AFrameP5.World('VRScene');
   
   // construct a new circle to serve as a circular 'ground' for our world
   circle = new AFrameP5.Circle({
      x:0, 
      y:0, 
      z:0, 
      radius:25, 
      red:0, 
      green:255, 
      blue:0, r
      otationX:-90
   });
   
   // add the circle to the world
   world.add(circle);
}
Methods (common to all entities)
MethodCategoryDescription
constrainPosition(xMin: number, xMax: number, yMin: number, yMax: number, zMin: number, zMax: number) Position ensures that the entity is constrained within the desired boundaries along all three axes. if an entity exceeds any of the constraints it is nudged back into position accordingly.
getX(): number Position returns the current x position of the entity. this is the entity's LOCAL position in relation to its container.
getY(): number Position returns the current y position of the entity. this is the entity's LOCAL position in relation to its container.
getZ(): number Position returns the current z position of the entity. this is the entity's LOCAL position in relation to its container.
nudge(x: number, y: number, z: number) Position nudges the element based on its current position. accepts three numeric values (i.e. myEntity.nudge(1,0,0); will nudge the entity 1 meter from its current position along the x-axis. this is the entity's LOCAL position in relation to its container.
setPosition(x: number, y: number, z: number) Position sets the position of the entity. this is the entity's LOCAL position in relation to its container.
setX(x: number) Position sets the x position of the entity. this is the entity's LOCAL position in relation to its container.
setY(y: number) Position sets the y position of the entity. this is the entity's LOCAL position in relation to its container.
setZ(z: number) Position sets the z position of the entity. this is the entity's LOCAL position in relation to its container.
getWorldPosition(): object Position returns the entity's WORLD position, not it's local position within its current container. this method is often used to compute the absolute position of an element in world space in order to deal with collisions of objects that may be nested inside of containers.
getRotationX(): number Rotation returns the current x rotation of the entity.
getRotationY(): number Rotation returns the current y rotation of the entity.
getRotationZ(): number Rotation returns the current z rotation of the entity.
rotateX(x: number) Rotation sets the x rotation of the entity
rotateY(y: number) Rotation sets the y rotation of the entity
rotateZ(z: number) Rotation sets the z rotation of the entity
setRotation(x: number, y: number, z: number) Rotation sets the rotation of the entity.
spinX(x: number) Rotation spins the entity along the x axis based on its current rotation. i.e. myEntity.spinX(1); // spin by 1 degree
spinY(y: number) Rotation spins the entity along the y axis based on its current rotation. i.e. myEntity.spinY(1); // spin by 1 degree
spinZ(z: number) Rotation spins the entity along the z axis based on its current rotation. i.e. myEntity.spinZ(1); // spin by 1 degree
lookAtUser(upright?: boolean) Rotation forces the entity to orient itself so that it is facing the user. (v2.4) lookAtUser(true) keeps the entity upright, so it only turns left and right - use this for billboards such as trees, which would otherwise tip over when the user walks up close.
getVisibility(): boolean Visibility returns the current visibility state of the entity
hide() Visibility hides the entity by setting its visible property to false
show() Visibility shows the entity by setting its visible property to true
toggleVisibility() Visibility hides the entity if it is current visible and shows the entity if it is current hidden
getScale(): object Scale returns the scale of the entity as an object (i.e. {x:0, y:0, z:0}
getScaleX(): number Scale returns the x scale of the entity
getScaleY(): number Scale returns the y scale of the entity
getScaleZ(): number Scale returns the z scale of the entity
setScale(x: number, y: number, z: number) Scale sets the scale of the object in all axes
setScaleX(x: number) Scale sets the x scale of the object
setScaleY(y: number) Scale sets the y scale of the object
setScaleZ(z: number) Scale sets the z scale of the object
getAsset(): string Material returns the current id of the asset being used to texture this entity
getBlue(): number Material returns the current blue color of the entity
getGreen(): number Material returns the current green color of the entity
getMetalness(): number Material returns the current metalness setting for the texture of the entity (range = 0.0 to 1.0)
getOpacity(): number Material returns the current opacity of the entity
getRed(): number Material returns the current red color of the entity
setRoughness(roughness: number) Material sets the roughness for the texture of the entity (range = 0.0 to 1.0)
getSide(): string Material returns which faces of the entity will be textured (valid values are front, back and double)
getTransparent(): boolean Material returns the current transparency of the entity
setAsset(asset: string) Material sets the id for the asset to texture this entity
setColor(red: number, green: number, blue: number) Material sets the color of the entity
setBlue(blue: number) Material sets the blue color of the entity
setGreen(green: number) Material sets the green color of the entity
setMetalness(metalness: number) Material sets the metalness for the texture of the entity (range = 0.0 to 1.0)
setOpacity(opacity: number) Material sets the opacity of the entity (range = 0.0 to 1.0)
setRed(red: number) Material sets the red color of the entity
getRoughness(): number Material returns the current roughness setting for the texture of the entity (range = 0.0 to 1.0)
setTransparent(transparent: boolean) Material sets whether the entity supports transparent textures
getAlphaTest(): number Material (v2.4) returns the entity's alphaTest value
setAlphaTest(alphaTest: number) Material (v2.4) sets the alphaTest value (see the alphaTest constructor option)
setSide(side: string) Material sets which faces of the entity will be textured (valid values are front, back and double)
getRepeatX(): number Material returns how many times the texture repeats across the entity horizontally
getRepeatY(): number Material (v2.4) returns how many times the texture repeats across the entity vertically
setRepeatX(times: number) Material sets how many times the texture repeats across the entity horizontally
setRepeatY(times: number) Material (v2.4) sets how many times the texture repeats across the entity vertically
getSolid(): boolean Physics (v2.4) returns whether the entity is solid
setSolid(solid: boolean) Physics (v2.4) makes the entity solid (true: it blocks the user and can be stood on) or not solid (false: the user can walk through it)
add(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity. alias for addChild.
addChild(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity.
getChildren(): Array Hierarchy returns an Array of all children of this entity
removeChild(entity: Entity) Hierarchy removes a child entity from this entity.
Methods (specific to this class)
MethodCategoryDescription
getRadius(): number Geometry returns the current radius of the entity
getSegments(): number Geometry returns the number of segments being used to draw the entity
getThetaStart(): number Geometry returns the current thetaStart value for the entity
getThetaLength(): number Geometry returns the current thetaLength value for the entity
setRadius(radius: number) Geometry sets the radius of the entity
changeRadius(amount: number) Geometry updates the radius by the value provided (i.e. entity.changeRadius(0.1); will increase the radius by 0.1 meters.
setSegments(segments: number) Geometry sets the number of segments being used to draw the entity
setThetaStart(thetaStart: number) Geometry sets the the thetaStart value for the entity
setThetaLength(thetaLength: number) Geometry sets the the thetaLength value for the entity

Class: Ring (entity)

Used to construct a flat two dimensional ring entity.

Constructor Parameters (common to all entities)

new AFrameP5.Ring(options)

OptionTypeDefaultDescription
x number 0 x-position of the entity
y number 0 y-position of the entity
z number 0 z-position of the entity
opacity number 1.0 how transparent this entity is (0.0 = fully transparent, 1.0 = fully opaque)
transparent boolean false whether the texture associated with this entity supports transparency (i.e. a PNG file with an alpha channel)
alphaTest number 0 (v2.4) pixels less opaque than this value (0.0 to 1.0) are not drawn at all. Use 0.5 for cut-out pictures such as trees (PNGs with see-through parts), otherwise the see-through parts can hide whatever is behind them. 0 turns it off.
shader string 'standard' the ThreeJS shader to use to render this entity - other valid value is flat
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
roughness number 0.5 how 'rough' the material appears. valid range = 0.0 to 1.0
metalness number 0 how 'metallic' the material appears. valid range = 0.0 to 1.0
red integer 255 how red the entity appears. valid range = 0 to 255
green integer 255 how green the entity appears. valid range = 0 to 255
blue integer 255 how blue the entity appears. valid range = 0 to 255
repeatX integer 1 how many times to repeat the texture associated with the entity along the x-axis of each face of the object. valid range = any positive number
repeatY integer 1 how many times to repeat the texture associated with the entity along the y-axis of each face of the object. valid range = any positive number
asset string 'None' the id (string) of the element that should be used as a texture for this entity. all textures should be set up in the 'index.html' file inside of the a-assets tag.
scaleX number 1.0 the scale of the object in the x-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleY number 1.0 the scale of the object in the y-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleZ number 1.0 the scale of the object in the z-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
rotationX number 0 the rotation of the object along the x-axis.
rotationY number 0 the rotation of the object along the y-axis.
rotationZ number 0 the rotation of the object along the z-axis.
visible boolean true determines whether the entity is visible in the scene.
solid boolean false (v2.4) solid entities block the user's movement and can be stood on when gravity is turned on (see world.setGravity and the physics example).
dynamicTexture boolean false sets whether the texture used on the entity is being drawn from a dynamically drawn canvas element. see these examples for more information: Dynamic textures, Multiple dynamic textures and Interactive dynamic textures
dynamicTextureHeight number 0 tells the entity the height of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
dynamicTextureWidth number 0 tells the entity the width of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
customData object undefined a custom object that can be used by the entity to keep track of user-specified data. example:
let b = new AFrameP5.Box({
   customData: {
      numClicks: 0
   },
   clickFunction: function(e) { 
      e.customData.numClicks++;
      console.log("This element has been clicked " + e.customData.numClicks + " times");
   }
});
clickFunction function undefined a custom function that will run every time the user clicks on the entity. this function receives a reference to the entity that was clicked, and (v2.4) a second argument with information about the click (see below). example:
let b = new AFrameP5.Box({
   clickFunction: function(e) { 
      e.setRed(random(255)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   clickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});


(v2.4) the second argument, often called hit, describes the click:
  • point3d : the exact point in the world where the click landed (an object with x, y and z)
  • distance : how far away that point is from the user, in meters
  • hand : what did the clicking: 'mouse' (the mouse, or the gaze cursor), 'left' or 'right' (the VR controllers)
  • uv : the raw texture coordinates of the click (x and y, from 0 to 1)
  • point2d : for entities that use a dynamic texture, where on the texture the click landed (x and y, in pixels)
  • voxel and voxelAdjacent : for voxel grids, the cube that was clicked and the empty space next to the face that was clicked
example:
let b = new AFrameP5.Box({
   clickFunction: function(e, hit) {
      console.log("clicked at " + hit.point3d.x + ", " + hit.point3d.y + ", " + hit.point3d.z + " with the " + hit.hand);
   }
});
see the click information example.
upFunction function undefined a custom function that will run every time the releases the mouse after the entity has been clicked. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   upFunction: function(e) { 
      e.spinX(random(360)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   upFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
enterFunction function undefined a custom function that will run every time the mouse hovers over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   enterFunction: function(e) { 
      e.setScale(2,2,2); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   enterFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
leaveFunction function undefined a custom function that will run every time the mouse stops hovering over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   leaveFunction: function(e) { 
      e.setScale(1,1,1); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   leaveFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
overFunction function undefined a custom function that will run continually whenever the mouse is hovering over the entity. this function should be implemented to accept two arguments - the first is a reference to the entity that was clicked, and the second is an object that contains information about the interaction that just occured. example:
let b = AFrameP5.Box({
   overFunction: function(e, intersectionInfo) { 
      console.log(intersectionInfo);
   }
});
intersectionInfo is an object that contains info about how the user is interacting with this entity. it contains the following properties:
  • distance : a float describing how far away the user is
  • point3d : an object with three properties (x, y & z) describing where the user is touching the entity
  • point2d : an object with two properites (x & y) describing where the user is touching the entity in 2D space (useful for determining where on a dynamic canvas the user is touching)
  • uv : an object with two properies (x & y) describing the raw textural offset (used to compute point2d)
  • hand : (v2.4) which pointer is hovering: 'mouse', 'left' or 'right'. Each VR controller calls overFunction separately, so check this if only one hand should do something (for example, only paint with the right hand).
For an example please see the Interactive dynamic textures sample program.

as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   overFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
dragFunction function undefined (v2.4) a custom function that runs every frame while the user holds the mouse button (or a VR controller trigger) down after pressing on this entity and keeps pointing at it - for example, to draw on a dynamic texture. A drag that starts somewhere else and moves onto the entity doesn't count. While the mouse is dragging on the entity, it doesn't turn the camera, so the view stays still while you draw. It takes the same two arguments as overFunction (the entity and hit), plus two more properties in hit:
  • previousPoint2d : where the user was pointing on the dynamic texture on the previous frame (x and y, in pixels). It is null when a new drag starts, and again when the pointer comes back onto the entity during a drag, so you can draw a line from it to point2d without joining separate strokes.
  • previousPoint3d : the same thing in the world (x, y and z)
example:
let canvas = new AFrameP5.Plane({
   asset: texture, dynamicTexture: true, dynamicTextureWidth: 512, dynamicTextureHeight: 512,
   dragFunction: function(e, hit) {
      if (hit.previousPoint2d) {
         buffer.line(hit.previousPoint2d.x, hit.previousPoint2d.y, hit.point2d.x, hit.point2d.y);
      }
   }
});
Each VR controller drags separately, so check hit.hand if only one hand should draw.

In VR, clickFunction runs as soon as the trigger is pressed (setClickOnRelease only changes mouse clicks), so avoid giving one entity both a clickFunction and a dragFunction if that matters. To do something at the start of each drag (for example, stamp a dot), check for hit.previousPoint2d === null inside dragFunction instead.
tickFunction function undefined a custom function that will run once per frame (like draw does for the main sketch). this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   tickFunction: function(e) { 
      e.setRed( random(255) ); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   tickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
Constructor Parameters (specific to this class)

new AFrameP5.Ring(options)

OptionTypeDefaultDescription
radiusInner number 0.5 inner radius of the ring (in meters)
radiusOuter number 1 outer radius of the ring (in meters)
segmentsTheta integer 32 number of segments. a higher number means the ring will be more round.
segmentsPhi integer 8 number of triangles within each face defined by segmentsTheta.
thetaStart integer 0 start angle for first segment.
thetaLength integer 360 the central angle (in degrees)
Example
// sketch.js file

let world;
let ring;
			  		
function setup() {
   // no canvas needed
   noCanvas();
   
   // create a new VR World object
   world = new AFrameP5.World('VRScene');
   
   // construct a new ring
   ring = new AFrameP5.Ring({
      x:0, 
      y:2, 
      z:-2, 
      radiusInner: 0.5, 
      radiusOuter: 1, 
      red:0, 
      green:255, 
      blue:0
   });
   
   // add the ring to the world
   world.add(ring);
}
Methods (common to all entities)
MethodCategoryDescription
constrainPosition(xMin: number, xMax: number, yMin: number, yMax: number, zMin: number, zMax: number) Position ensures that the entity is constrained within the desired boundaries along all three axes. if an entity exceeds any of the constraints it is nudged back into position accordingly.
getX(): number Position returns the current x position of the entity. this is the entity's LOCAL position in relation to its container.
getY(): number Position returns the current y position of the entity. this is the entity's LOCAL position in relation to its container.
getZ(): number Position returns the current z position of the entity. this is the entity's LOCAL position in relation to its container.
nudge(x: number, y: number, z: number) Position nudges the element based on its current position. accepts three numeric values (i.e. myEntity.nudge(1,0,0); will nudge the entity 1 meter from its current position along the x-axis. this is the entity's LOCAL position in relation to its container.
setPosition(x: number, y: number, z: number) Position sets the position of the entity. this is the entity's LOCAL position in relation to its container.
setX(x: number) Position sets the x position of the entity. this is the entity's LOCAL position in relation to its container.
setY(y: number) Position sets the y position of the entity. this is the entity's LOCAL position in relation to its container.
setZ(z: number) Position sets the z position of the entity. this is the entity's LOCAL position in relation to its container.
getWorldPosition(): object Position returns the entity's WORLD position, not it's local position within its current container. this method is often used to compute the absolute position of an element in world space in order to deal with collisions of objects that may be nested inside of containers.
getRotationX(): number Rotation returns the current x rotation of the entity.
getRotationY(): number Rotation returns the current y rotation of the entity.
getRotationZ(): number Rotation returns the current z rotation of the entity.
rotateX(x: number) Rotation sets the x rotation of the entity
rotateY(y: number) Rotation sets the y rotation of the entity
rotateZ(z: number) Rotation sets the z rotation of the entity
setRotation(x: number, y: number, z: number) Rotation sets the rotation of the entity.
spinX(x: number) Rotation spins the entity along the x axis based on its current rotation. i.e. myEntity.spinX(1); // spin by 1 degree
spinY(y: number) Rotation spins the entity along the y axis based on its current rotation. i.e. myEntity.spinY(1); // spin by 1 degree
spinZ(z: number) Rotation spins the entity along the z axis based on its current rotation. i.e. myEntity.spinZ(1); // spin by 1 degree
lookAtUser(upright?: boolean) Rotation forces the entity to orient itself so that it is facing the user. (v2.4) lookAtUser(true) keeps the entity upright, so it only turns left and right - use this for billboards such as trees, which would otherwise tip over when the user walks up close.
getVisibility(): boolean Visibility returns the current visibility state of the entity
hide() Visibility hides the entity by setting its visible property to false
show() Visibility shows the entity by setting its visible property to true
toggleVisibility() Visibility hides the entity if it is current visible and shows the entity if it is current hidden
getScale(): object Scale returns the scale of the entity as an object (i.e. {x:0, y:0, z:0}
getScaleX(): number Scale returns the x scale of the entity
getScaleY(): number Scale returns the y scale of the entity
getScaleZ(): number Scale returns the z scale of the entity
setScale(x: number, y: number, z: number) Scale sets the scale of the object in all axes
setScaleX(x: number) Scale sets the x scale of the object
setScaleY(y: number) Scale sets the y scale of the object
setScaleZ(z: number) Scale sets the z scale of the object
getAsset(): string Material returns the current id of the asset being used to texture this entity
getBlue(): number Material returns the current blue color of the entity
getGreen(): number Material returns the current green color of the entity
getMetalness(): number Material returns the current metalness setting for the texture of the entity (range = 0.0 to 1.0)
getOpacity(): number Material returns the current opacity of the entity
getRed(): number Material returns the current red color of the entity
setRoughness(roughness: number) Material sets the roughness for the texture of the entity (range = 0.0 to 1.0)
getSide(): string Material returns which faces of the entity will be textured (valid values are front, back and double)
getTransparent(): boolean Material returns the current transparency of the entity
setAsset(asset: string) Material sets the id for the asset to texture this entity
setColor(red: number, green: number, blue: number) Material sets the color of the entity
setBlue(blue: number) Material sets the blue color of the entity
setGreen(green: number) Material sets the green color of the entity
setMetalness(metalness: number) Material sets the metalness for the texture of the entity (range = 0.0 to 1.0)
setOpacity(opacity: number) Material sets the opacity of the entity (range = 0.0 to 1.0)
setRed(red: number) Material sets the red color of the entity
getRoughness(): number Material returns the current roughness setting for the texture of the entity (range = 0.0 to 1.0)
setTransparent(transparent: boolean) Material sets whether the entity supports transparent textures
getAlphaTest(): number Material (v2.4) returns the entity's alphaTest value
setAlphaTest(alphaTest: number) Material (v2.4) sets the alphaTest value (see the alphaTest constructor option)
setSide(side: string) Material sets which faces of the entity will be textured (valid values are front, back and double)
getRepeatX(): number Material returns how many times the texture repeats across the entity horizontally
getRepeatY(): number Material (v2.4) returns how many times the texture repeats across the entity vertically
setRepeatX(times: number) Material sets how many times the texture repeats across the entity horizontally
setRepeatY(times: number) Material (v2.4) sets how many times the texture repeats across the entity vertically
getSolid(): boolean Physics (v2.4) returns whether the entity is solid
setSolid(solid: boolean) Physics (v2.4) makes the entity solid (true: it blocks the user and can be stood on) or not solid (false: the user can walk through it)
add(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity. alias for addChild.
addChild(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity.
getChildren(): Array Hierarchy returns an Array of all children of this entity
removeChild(entity: Entity) Hierarchy removes a child entity from this entity.
Methods (specific to this class)
MethodCategoryDescription
getRadiusInner(): number Geometry returns the current inner radius of the entity
getRadiusOuter(): number Geometry returns the current outer radius of the entity
getSegmentsTheta(): number Geometry returns the current segmentsTheta value for the entity
getSegmentsPhi(): number Geometry returns the current segmentsPhi value for the entity
getThetaStart(): number Geometry returns the current thetaStart value for the entity
getThetaLength(): number Geometry returns the current thetaLength value for the entity
setRadiusInner(radiusInner: number) Geometry sets the inner radius of the entity
setRadiusOuter(radiusOuter: number) Geometry sets the outer radius of the entity
setSegmentsTheta(segmentsTheta: number) Geometry sets the current segmentsTheta value for the entity
setSegmentsPhi(segmentsPhi: number) Geometry sets the current segmentsPhi value for the entity
setThetaStart(thetaStart: number) Geometry sets the the thetaStart value for the entity
setThetaLength(thetaLength: number) Geometry sets the the thetaLength value for the entity

Class: Sphere (entity)

Used to construct a three dimensional spherical entity.

Constructor Parameters (common to all entities)

new AFrameP5.Sphere(options)

OptionTypeDefaultDescription
x number 0 x-position of the entity
y number 0 y-position of the entity
z number 0 z-position of the entity
opacity number 1.0 how transparent this entity is (0.0 = fully transparent, 1.0 = fully opaque)
transparent boolean false whether the texture associated with this entity supports transparency (i.e. a PNG file with an alpha channel)
alphaTest number 0 (v2.4) pixels less opaque than this value (0.0 to 1.0) are not drawn at all. Use 0.5 for cut-out pictures such as trees (PNGs with see-through parts), otherwise the see-through parts can hide whatever is behind them. 0 turns it off.
shader string 'standard' the ThreeJS shader to use to render this entity - other valid value is flat
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
roughness number 0.5 how 'rough' the material appears. valid range = 0.0 to 1.0
metalness number 0 how 'metallic' the material appears. valid range = 0.0 to 1.0
red integer 255 how red the entity appears. valid range = 0 to 255
green integer 255 how green the entity appears. valid range = 0 to 255
blue integer 255 how blue the entity appears. valid range = 0 to 255
repeatX integer 1 how many times to repeat the texture associated with the entity along the x-axis of each face of the object. valid range = any positive number
repeatY integer 1 how many times to repeat the texture associated with the entity along the y-axis of each face of the object. valid range = any positive number
asset string 'None' the id (string) of the element that should be used as a texture for this entity. all textures should be set up in the 'index.html' file inside of the a-assets tag.
scaleX number 1.0 the scale of the object in the x-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleY number 1.0 the scale of the object in the y-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleZ number 1.0 the scale of the object in the z-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
rotationX number 0 the rotation of the object along the x-axis.
rotationY number 0 the rotation of the object along the y-axis.
rotationZ number 0 the rotation of the object along the z-axis.
visible boolean true determines whether the entity is visible in the scene.
solid boolean false (v2.4) solid entities block the user's movement and can be stood on when gravity is turned on (see world.setGravity and the physics example).
dynamicTexture boolean false sets whether the texture used on the entity is being drawn from a dynamically drawn canvas element. see these examples for more information: Dynamic textures, Multiple dynamic textures and Interactive dynamic textures
dynamicTextureHeight number 0 tells the entity the height of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
dynamicTextureWidth number 0 tells the entity the width of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
customData object undefined a custom object that can be used by the entity to keep track of user-specified data. example:
let b = new AFrameP5.Box({
   customData: {
      numClicks: 0
   },
   clickFunction: function(e) { 
      e.customData.numClicks++;
      console.log("This element has been clicked " + e.customData.numClicks + " times");
   }
});
clickFunction function undefined a custom function that will run every time the user clicks on the entity. this function receives a reference to the entity that was clicked, and (v2.4) a second argument with information about the click (see below). example:
let b = new AFrameP5.Box({
   clickFunction: function(e) { 
      e.setRed(random(255)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   clickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});


(v2.4) the second argument, often called hit, describes the click:
  • point3d : the exact point in the world where the click landed (an object with x, y and z)
  • distance : how far away that point is from the user, in meters
  • hand : what did the clicking: 'mouse' (the mouse, or the gaze cursor), 'left' or 'right' (the VR controllers)
  • uv : the raw texture coordinates of the click (x and y, from 0 to 1)
  • point2d : for entities that use a dynamic texture, where on the texture the click landed (x and y, in pixels)
  • voxel and voxelAdjacent : for voxel grids, the cube that was clicked and the empty space next to the face that was clicked
example:
let b = new AFrameP5.Box({
   clickFunction: function(e, hit) {
      console.log("clicked at " + hit.point3d.x + ", " + hit.point3d.y + ", " + hit.point3d.z + " with the " + hit.hand);
   }
});
see the click information example.
upFunction function undefined a custom function that will run every time the releases the mouse after the entity has been clicked. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   upFunction: function(e) { 
      e.spinX(random(360)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   upFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
enterFunction function undefined a custom function that will run every time the mouse hovers over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   enterFunction: function(e) { 
      e.setScale(2,2,2); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   enterFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
leaveFunction function undefined a custom function that will run every time the mouse stops hovering over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   leaveFunction: function(e) { 
      e.setScale(1,1,1); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   leaveFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
overFunction function undefined a custom function that will run continually whenever the mouse is hovering over the entity. this function should be implemented to accept two arguments - the first is a reference to the entity that was clicked, and the second is an object that contains information about the interaction that just occured. example:
let b = AFrameP5.Box({
   overFunction: function(e, intersectionInfo) { 
      console.log(intersectionInfo);
   }
});
intersectionInfo is an object that contains info about how the user is interacting with this entity. it contains the following properties:
  • distance : a float describing how far away the user is
  • point3d : an object with three properties (x, y & z) describing where the user is touching the entity
  • point2d : an object with two properites (x & y) describing where the user is touching the entity in 2D space (useful for determining where on a dynamic canvas the user is touching)
  • uv : an object with two properies (x & y) describing the raw textural offset (used to compute point2d)
  • hand : (v2.4) which pointer is hovering: 'mouse', 'left' or 'right'. Each VR controller calls overFunction separately, so check this if only one hand should do something (for example, only paint with the right hand).
For an example please see the Interactive dynamic textures sample program.

as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   overFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
dragFunction function undefined (v2.4) a custom function that runs every frame while the user holds the mouse button (or a VR controller trigger) down after pressing on this entity and keeps pointing at it - for example, to draw on a dynamic texture. A drag that starts somewhere else and moves onto the entity doesn't count. While the mouse is dragging on the entity, it doesn't turn the camera, so the view stays still while you draw. It takes the same two arguments as overFunction (the entity and hit), plus two more properties in hit:
  • previousPoint2d : where the user was pointing on the dynamic texture on the previous frame (x and y, in pixels). It is null when a new drag starts, and again when the pointer comes back onto the entity during a drag, so you can draw a line from it to point2d without joining separate strokes.
  • previousPoint3d : the same thing in the world (x, y and z)
example:
let canvas = new AFrameP5.Plane({
   asset: texture, dynamicTexture: true, dynamicTextureWidth: 512, dynamicTextureHeight: 512,
   dragFunction: function(e, hit) {
      if (hit.previousPoint2d) {
         buffer.line(hit.previousPoint2d.x, hit.previousPoint2d.y, hit.point2d.x, hit.point2d.y);
      }
   }
});
Each VR controller drags separately, so check hit.hand if only one hand should draw.

In VR, clickFunction runs as soon as the trigger is pressed (setClickOnRelease only changes mouse clicks), so avoid giving one entity both a clickFunction and a dragFunction if that matters. To do something at the start of each drag (for example, stamp a dot), check for hit.previousPoint2d === null inside dragFunction instead.
tickFunction function undefined a custom function that will run once per frame (like draw does for the main sketch). this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   tickFunction: function(e) { 
      e.setRed( random(255) ); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   tickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
Constructor Parameters (specific to this class)

new AFrameP5.Sphere(options)

OptionTypeDefaultDescription
radius number 1 radius of the sphere (in meters)
segmentsWidth integer 18 number of horizontal segments
segmentsHeight integer 36 number horizontal segments
phiStart integer 0 horizontal starting angle
phiLength integer 360 horizontal sweep angle size
thetaStart integer 0 start angle for first segment.
thetaLength integer 360 the central angle (in degrees)
Example
// sketch.js file

let world;
let sphere;
			  		
function setup() {
   // no canvas needed
   noCanvas();
   
   // create a new VR World object
   world = new AFrameP5.World('VRScene');
   
   // construct a new sphere
   sphere = new AFrameP5.Sphere({
      x:0, 
      y:2, 
      z:0, 
      red:0, 
      green:255, 
      blue:0
   });
   
   // add the sphere to the world
   world.add(sphere);
}
Methods (common to all entities)
MethodCategoryDescription
constrainPosition(xMin: number, xMax: number, yMin: number, yMax: number, zMin: number, zMax: number) Position ensures that the entity is constrained within the desired boundaries along all three axes. if an entity exceeds any of the constraints it is nudged back into position accordingly.
getX(): number Position returns the current x position of the entity. this is the entity's LOCAL position in relation to its container.
getY(): number Position returns the current y position of the entity. this is the entity's LOCAL position in relation to its container.
getZ(): number Position returns the current z position of the entity. this is the entity's LOCAL position in relation to its container.
nudge(x: number, y: number, z: number) Position nudges the element based on its current position. accepts three numeric values (i.e. myEntity.nudge(1,0,0); will nudge the entity 1 meter from its current position along the x-axis. this is the entity's LOCAL position in relation to its container.
setPosition(x: number, y: number, z: number) Position sets the position of the entity. this is the entity's LOCAL position in relation to its container.
setX(x: number) Position sets the x position of the entity. this is the entity's LOCAL position in relation to its container.
setY(y: number) Position sets the y position of the entity. this is the entity's LOCAL position in relation to its container.
setZ(z: number) Position sets the z position of the entity. this is the entity's LOCAL position in relation to its container.
getWorldPosition(): object Position returns the entity's WORLD position, not it's local position within its current container. this method is often used to compute the absolute position of an element in world space in order to deal with collisions of objects that may be nested inside of containers.
getRotationX(): number Rotation returns the current x rotation of the entity.
getRotationY(): number Rotation returns the current y rotation of the entity.
getRotationZ(): number Rotation returns the current z rotation of the entity.
rotateX(x: number) Rotation sets the x rotation of the entity
rotateY(y: number) Rotation sets the y rotation of the entity
rotateZ(z: number) Rotation sets the z rotation of the entity
setRotation(x: number, y: number, z: number) Rotation sets the rotation of the entity.
spinX(x: number) Rotation spins the entity along the x axis based on its current rotation. i.e. myEntity.spinX(1); // spin by 1 degree
spinY(y: number) Rotation spins the entity along the y axis based on its current rotation. i.e. myEntity.spinY(1); // spin by 1 degree
spinZ(z: number) Rotation spins the entity along the z axis based on its current rotation. i.e. myEntity.spinZ(1); // spin by 1 degree
lookAtUser(upright?: boolean) Rotation forces the entity to orient itself so that it is facing the user. (v2.4) lookAtUser(true) keeps the entity upright, so it only turns left and right - use this for billboards such as trees, which would otherwise tip over when the user walks up close.
getVisibility(): boolean Visibility returns the current visibility state of the entity
hide() Visibility hides the entity by setting its visible property to false
show() Visibility shows the entity by setting its visible property to true
toggleVisibility() Visibility hides the entity if it is current visible and shows the entity if it is current hidden
getScale(): object Scale returns the scale of the entity as an object (i.e. {x:0, y:0, z:0}
getScaleX(): number Scale returns the x scale of the entity
getScaleY(): number Scale returns the y scale of the entity
getScaleZ(): number Scale returns the z scale of the entity
setScale(x: number, y: number, z: number) Scale sets the scale of the object in all axes
setScaleX(x: number) Scale sets the x scale of the object
setScaleY(y: number) Scale sets the y scale of the object
setScaleZ(z: number) Scale sets the z scale of the object
getAsset(): string Material returns the current id of the asset being used to texture this entity
getBlue(): number Material returns the current blue color of the entity
getGreen(): number Material returns the current green color of the entity
getMetalness(): number Material returns the current metalness setting for the texture of the entity (range = 0.0 to 1.0)
getOpacity(): number Material returns the current opacity of the entity
getRed(): number Material returns the current red color of the entity
setRoughness(roughness: number) Material sets the roughness for the texture of the entity (range = 0.0 to 1.0)
getSide(): string Material returns which faces of the entity will be textured (valid values are front, back and double)
getTransparent(): boolean Material returns the current transparency of the entity
setAsset(asset: string) Material sets the id for the asset to texture this entity
setColor(red: number, green: number, blue: number) Material sets the color of the entity
setBlue(blue: number) Material sets the blue color of the entity
setGreen(green: number) Material sets the green color of the entity
setMetalness(metalness: number) Material sets the metalness for the texture of the entity (range = 0.0 to 1.0)
setOpacity(opacity: number) Material sets the opacity of the entity (range = 0.0 to 1.0)
setRed(red: number) Material sets the red color of the entity
getRoughness(): number Material returns the current roughness setting for the texture of the entity (range = 0.0 to 1.0)
setTransparent(transparent: boolean) Material sets whether the entity supports transparent textures
getAlphaTest(): number Material (v2.4) returns the entity's alphaTest value
setAlphaTest(alphaTest: number) Material (v2.4) sets the alphaTest value (see the alphaTest constructor option)
setSide(side: string) Material sets which faces of the entity will be textured (valid values are front, back and double)
getRepeatX(): number Material returns how many times the texture repeats across the entity horizontally
getRepeatY(): number Material (v2.4) returns how many times the texture repeats across the entity vertically
setRepeatX(times: number) Material sets how many times the texture repeats across the entity horizontally
setRepeatY(times: number) Material (v2.4) sets how many times the texture repeats across the entity vertically
getSolid(): boolean Physics (v2.4) returns whether the entity is solid
setSolid(solid: boolean) Physics (v2.4) makes the entity solid (true: it blocks the user and can be stood on) or not solid (false: the user can walk through it)
add(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity. alias for addChild.
addChild(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity.
getChildren(): Array Hierarchy returns an Array of all children of this entity
removeChild(entity: Entity) Hierarchy removes a child entity from this entity.
Methods (specific to this class)
MethodCategoryDescription
getRadius(): number Geometry returns the current radius of the entity
getSegmentsWidth(): number Geometry returns the current segmentsWidth value for the entity
getSegmentsHeight(): number Geometry returns the current segmentsHeight value for the entity
getPhiStart(): number Geometry returns the current phiStart value for the entity
getPhiLength(): number Geometry returns the current phiLength value for the entity
getThetaStart(): number Geometry returns the current thetaStart value for the entity
getThetaLength(): number Geometry returns the current thetaLength value for the entity
setRadius(radius: number) Geometry sets the radius of the entity
changeRadius(amount: number) Geometry updates the radius by the value provided (i.e. entity.changeRadius(0.1); will increase the radius by 0.1 meters.
setSegmentsWidth(segmentsWidth: number) Geometry sets the current segmentsWidth value for the entity
setSegmentsHeight(segmentsHeight: number) Geometry sets the current segmentsHeight value for the entity
setPhiStart(phiStart: number) Geometry sets the the phiStart value for the entity
setPhiLength(phiLength: number) Geometry sets the the phiLength value for the entity
setThetaStart(thetaStart: number) Geometry sets the the thetaStart value for the entity
setThetaLength(thetaLength: number) Geometry sets the the thetaLength value for the entity

Class: Cone (entity)

Used to construct a three dimensional conical entity.

Constructor Parameters (common to all entities)

new AFrameP5.Cone(options)

OptionTypeDefaultDescription
x number 0 x-position of the entity
y number 0 y-position of the entity
z number 0 z-position of the entity
opacity number 1.0 how transparent this entity is (0.0 = fully transparent, 1.0 = fully opaque)
transparent boolean false whether the texture associated with this entity supports transparency (i.e. a PNG file with an alpha channel)
alphaTest number 0 (v2.4) pixels less opaque than this value (0.0 to 1.0) are not drawn at all. Use 0.5 for cut-out pictures such as trees (PNGs with see-through parts), otherwise the see-through parts can hide whatever is behind them. 0 turns it off.
shader string 'standard' the ThreeJS shader to use to render this entity - other valid value is flat
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
roughness number 0.5 how 'rough' the material appears. valid range = 0.0 to 1.0
metalness number 0 how 'metallic' the material appears. valid range = 0.0 to 1.0
red integer 255 how red the entity appears. valid range = 0 to 255
green integer 255 how green the entity appears. valid range = 0 to 255
blue integer 255 how blue the entity appears. valid range = 0 to 255
repeatX integer 1 how many times to repeat the texture associated with the entity along the x-axis of each face of the object. valid range = any positive number
repeatY integer 1 how many times to repeat the texture associated with the entity along the y-axis of each face of the object. valid range = any positive number
asset string 'None' the id (string) of the element that should be used as a texture for this entity. all textures should be set up in the 'index.html' file inside of the a-assets tag.
scaleX number 1.0 the scale of the object in the x-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleY number 1.0 the scale of the object in the y-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleZ number 1.0 the scale of the object in the z-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
rotationX number 0 the rotation of the object along the x-axis.
rotationY number 0 the rotation of the object along the y-axis.
rotationZ number 0 the rotation of the object along the z-axis.
visible boolean true determines whether the entity is visible in the scene.
solid boolean false (v2.4) solid entities block the user's movement and can be stood on when gravity is turned on (see world.setGravity and the physics example).
dynamicTexture boolean false sets whether the texture used on the entity is being drawn from a dynamically drawn canvas element. see these examples for more information: Dynamic textures, Multiple dynamic textures and Interactive dynamic textures
dynamicTextureHeight number 0 tells the entity the height of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
dynamicTextureWidth number 0 tells the entity the width of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
customData object undefined a custom object that can be used by the entity to keep track of user-specified data. example:
let b = new AFrameP5.Box({
   customData: {
      numClicks: 0
   },
   clickFunction: function(e) { 
      e.customData.numClicks++;
      console.log("This element has been clicked " + e.customData.numClicks + " times");
   }
});
clickFunction function undefined a custom function that will run every time the user clicks on the entity. this function receives a reference to the entity that was clicked, and (v2.4) a second argument with information about the click (see below). example:
let b = new AFrameP5.Box({
   clickFunction: function(e) { 
      e.setRed(random(255)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   clickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});


(v2.4) the second argument, often called hit, describes the click:
  • point3d : the exact point in the world where the click landed (an object with x, y and z)
  • distance : how far away that point is from the user, in meters
  • hand : what did the clicking: 'mouse' (the mouse, or the gaze cursor), 'left' or 'right' (the VR controllers)
  • uv : the raw texture coordinates of the click (x and y, from 0 to 1)
  • point2d : for entities that use a dynamic texture, where on the texture the click landed (x and y, in pixels)
  • voxel and voxelAdjacent : for voxel grids, the cube that was clicked and the empty space next to the face that was clicked
example:
let b = new AFrameP5.Box({
   clickFunction: function(e, hit) {
      console.log("clicked at " + hit.point3d.x + ", " + hit.point3d.y + ", " + hit.point3d.z + " with the " + hit.hand);
   }
});
see the click information example.
upFunction function undefined a custom function that will run every time the releases the mouse after the entity has been clicked. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   upFunction: function(e) { 
      e.spinX(random(360)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   upFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
enterFunction function undefined a custom function that will run every time the mouse hovers over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   enterFunction: function(e) { 
      e.setScale(2,2,2); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   enterFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
leaveFunction function undefined a custom function that will run every time the mouse stops hovering over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   leaveFunction: function(e) { 
      e.setScale(1,1,1); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   leaveFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
overFunction function undefined a custom function that will run continually whenever the mouse is hovering over the entity. this function should be implemented to accept two arguments - the first is a reference to the entity that was clicked, and the second is an object that contains information about the interaction that just occured. example:
let b = AFrameP5.Box({
   overFunction: function(e, intersectionInfo) { 
      console.log(intersectionInfo);
   }
});
intersectionInfo is an object that contains info about how the user is interacting with this entity. it contains the following properties:
  • distance : a float describing how far away the user is
  • point3d : an object with three properties (x, y & z) describing where the user is touching the entity
  • point2d : an object with two properites (x & y) describing where the user is touching the entity in 2D space (useful for determining where on a dynamic canvas the user is touching)
  • uv : an object with two properies (x & y) describing the raw textural offset (used to compute point2d)
  • hand : (v2.4) which pointer is hovering: 'mouse', 'left' or 'right'. Each VR controller calls overFunction separately, so check this if only one hand should do something (for example, only paint with the right hand).
For an example please see the Interactive dynamic textures sample program.

as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   overFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
dragFunction function undefined (v2.4) a custom function that runs every frame while the user holds the mouse button (or a VR controller trigger) down after pressing on this entity and keeps pointing at it - for example, to draw on a dynamic texture. A drag that starts somewhere else and moves onto the entity doesn't count. While the mouse is dragging on the entity, it doesn't turn the camera, so the view stays still while you draw. It takes the same two arguments as overFunction (the entity and hit), plus two more properties in hit:
  • previousPoint2d : where the user was pointing on the dynamic texture on the previous frame (x and y, in pixels). It is null when a new drag starts, and again when the pointer comes back onto the entity during a drag, so you can draw a line from it to point2d without joining separate strokes.
  • previousPoint3d : the same thing in the world (x, y and z)
example:
let canvas = new AFrameP5.Plane({
   asset: texture, dynamicTexture: true, dynamicTextureWidth: 512, dynamicTextureHeight: 512,
   dragFunction: function(e, hit) {
      if (hit.previousPoint2d) {
         buffer.line(hit.previousPoint2d.x, hit.previousPoint2d.y, hit.point2d.x, hit.point2d.y);
      }
   }
});
Each VR controller drags separately, so check hit.hand if only one hand should draw.

In VR, clickFunction runs as soon as the trigger is pressed (setClickOnRelease only changes mouse clicks), so avoid giving one entity both a clickFunction and a dragFunction if that matters. To do something at the start of each drag (for example, stamp a dot), check for hit.previousPoint2d === null inside dragFunction instead.
tickFunction function undefined a custom function that will run once per frame (like draw does for the main sketch). this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   tickFunction: function(e) { 
      e.setRed( random(255) ); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   tickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
Constructor Parameters (specific to this class)

new AFrameP5.Cone(options)

OptionTypeDefaultDescription
height number 1 height of the entity (along the y-axis)
openEnded boolean false whether the cone is open ended or not
radiusBottom number 1 radius of the bottom of the cone (in meters)
radiusTop number 1 radius of the top of the cone (in meters)
segmentsRadial integer 36 number of segmented faces around the circumference of the cone.
segmentsHeight integer 18 Number of rows of faces along the height of the cone.
thetaStart integer 0 start angle in degrees
thetaLength integer 360 the central angle (in degrees)
Example
// sketch.js file

let world;
let cone;
			  		
function setup() {
   // no canvas needed
   noCanvas();
   
   // create a new VR World object
   world = new AFrameP5.World('VRScene');
   
   // construct a new cone
   cone = new AFrameP5.Cone({
      x:0, 
      y:2, 
      z:0, 
      red:0, 
      green:255, 
      blue:0
   });
   
   // add the cone to the world
   world.add(cone);
}
Methods (common to all entities)
MethodCategoryDescription
constrainPosition(xMin: number, xMax: number, yMin: number, yMax: number, zMin: number, zMax: number) Position ensures that the entity is constrained within the desired boundaries along all three axes. if an entity exceeds any of the constraints it is nudged back into position accordingly.
getX(): number Position returns the current x position of the entity. this is the entity's LOCAL position in relation to its container.
getY(): number Position returns the current y position of the entity. this is the entity's LOCAL position in relation to its container.
getZ(): number Position returns the current z position of the entity. this is the entity's LOCAL position in relation to its container.
nudge(x: number, y: number, z: number) Position nudges the element based on its current position. accepts three numeric values (i.e. myEntity.nudge(1,0,0); will nudge the entity 1 meter from its current position along the x-axis. this is the entity's LOCAL position in relation to its container.
setPosition(x: number, y: number, z: number) Position sets the position of the entity. this is the entity's LOCAL position in relation to its container.
setX(x: number) Position sets the x position of the entity. this is the entity's LOCAL position in relation to its container.
setY(y: number) Position sets the y position of the entity. this is the entity's LOCAL position in relation to its container.
setZ(z: number) Position sets the z position of the entity. this is the entity's LOCAL position in relation to its container.
getWorldPosition(): object Position returns the entity's WORLD position, not it's local position within its current container. this method is often used to compute the absolute position of an element in world space in order to deal with collisions of objects that may be nested inside of containers.
getRotationX(): number Rotation returns the current x rotation of the entity.
getRotationY(): number Rotation returns the current y rotation of the entity.
getRotationZ(): number Rotation returns the current z rotation of the entity.
rotateX(x: number) Rotation sets the x rotation of the entity
rotateY(y: number) Rotation sets the y rotation of the entity
rotateZ(z: number) Rotation sets the z rotation of the entity
setRotation(x: number, y: number, z: number) Rotation sets the rotation of the entity.
spinX(x: number) Rotation spins the entity along the x axis based on its current rotation. i.e. myEntity.spinX(1); // spin by 1 degree
spinY(y: number) Rotation spins the entity along the y axis based on its current rotation. i.e. myEntity.spinY(1); // spin by 1 degree
spinZ(z: number) Rotation spins the entity along the z axis based on its current rotation. i.e. myEntity.spinZ(1); // spin by 1 degree
lookAtUser(upright?: boolean) Rotation forces the entity to orient itself so that it is facing the user. (v2.4) lookAtUser(true) keeps the entity upright, so it only turns left and right - use this for billboards such as trees, which would otherwise tip over when the user walks up close.
getVisibility(): boolean Visibility returns the current visibility state of the entity
hide() Visibility hides the entity by setting its visible property to false
show() Visibility shows the entity by setting its visible property to true
toggleVisibility() Visibility hides the entity if it is current visible and shows the entity if it is current hidden
getScale(): object Scale returns the scale of the entity as an object (i.e. {x:0, y:0, z:0}
getScaleX(): number Scale returns the x scale of the entity
getScaleY(): number Scale returns the y scale of the entity
getScaleZ(): number Scale returns the z scale of the entity
setScale(x: number, y: number, z: number) Scale sets the scale of the object in all axes
setScaleX(x: number) Scale sets the x scale of the object
setScaleY(y: number) Scale sets the y scale of the object
setScaleZ(z: number) Scale sets the z scale of the object
getAsset(): string Material returns the current id of the asset being used to texture this entity
getBlue(): number Material returns the current blue color of the entity
getGreen(): number Material returns the current green color of the entity
getMetalness(): number Material returns the current metalness setting for the texture of the entity (range = 0.0 to 1.0)
getOpacity(): number Material returns the current opacity of the entity
getRed(): number Material returns the current red color of the entity
setRoughness(roughness: number) Material sets the roughness for the texture of the entity (range = 0.0 to 1.0)
getSide(): string Material returns which faces of the entity will be textured (valid values are front, back and double)
getTransparent(): boolean Material returns the current transparency of the entity
setAsset(asset: string) Material sets the id for the asset to texture this entity
setColor(red: number, green: number, blue: number) Material sets the color of the entity
setBlue(blue: number) Material sets the blue color of the entity
setGreen(green: number) Material sets the green color of the entity
setMetalness(metalness: number) Material sets the metalness for the texture of the entity (range = 0.0 to 1.0)
setOpacity(opacity: number) Material sets the opacity of the entity (range = 0.0 to 1.0)
setRed(red: number) Material sets the red color of the entity
getRoughness(): number Material returns the current roughness setting for the texture of the entity (range = 0.0 to 1.0)
setTransparent(transparent: boolean) Material sets whether the entity supports transparent textures
getAlphaTest(): number Material (v2.4) returns the entity's alphaTest value
setAlphaTest(alphaTest: number) Material (v2.4) sets the alphaTest value (see the alphaTest constructor option)
setSide(side: string) Material sets which faces of the entity will be textured (valid values are front, back and double)
getRepeatX(): number Material returns how many times the texture repeats across the entity horizontally
getRepeatY(): number Material (v2.4) returns how many times the texture repeats across the entity vertically
setRepeatX(times: number) Material sets how many times the texture repeats across the entity horizontally
setRepeatY(times: number) Material (v2.4) sets how many times the texture repeats across the entity vertically
getSolid(): boolean Physics (v2.4) returns whether the entity is solid
setSolid(solid: boolean) Physics (v2.4) makes the entity solid (true: it blocks the user and can be stood on) or not solid (false: the user can walk through it)
add(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity. alias for addChild.
addChild(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity.
getChildren(): Array Hierarchy returns an Array of all children of this entity
removeChild(entity: Entity) Hierarchy removes a child entity from this entity.
Methods (specific to this class)
MethodCategoryDescription
getHeight(): number Geometry returns the current height of the entity
getOpenEnded(): boolean Geometry returns whether the entity is open ended or not
getRadiusBottom(): number Geometry returns the current bottom radius of the entity
getRadiusTop(): number Geometry returns the current top radius of the entity
getSegmentsRadial(): number Geometry returns the current segmentsRadial value for the entity
getSegmentsHeight(): number Geometry returns the current segmentsHeight value for the entity
getThetaStart(): number Geometry returns the current thetaStart value for the entity
getThetaLength(): number Geometry returns the current thetaLength value for the entity
setHeight(height: number) Geometry sets the height of the entity
setOpenEnded(openEnded: boolean) Geometry sets whether the entity is open ended or not
setRadiusBottom(radiusBottom: number) Geometry sets the radiusBottom value for the entity
setRadiusTop(radiusTop: number) Geometry sets the radiusTop value for the entity
setSegmentsRadial(segmentsRadial: number) Geometry sets the current segmentsRadial value for the entity
setSegmentsHeight(segmentsHeight: number) Geometry sets the current segmentsHeight value for the entity
setThetaStart(thetaStart: number) Geometry sets the the thetaStart value for the entity
setThetaLength(thetaLength: number) Geometry sets the the thetaLength value for the entity

Class: Cylinder (entity)

Used to construct a three dimensional cylindrical entity.

Constructor Parameters (common to all entities)

new AFrameP5.Cylinder(options)

OptionTypeDefaultDescription
x number 0 x-position of the entity
y number 0 y-position of the entity
z number 0 z-position of the entity
opacity number 1.0 how transparent this entity is (0.0 = fully transparent, 1.0 = fully opaque)
transparent boolean false whether the texture associated with this entity supports transparency (i.e. a PNG file with an alpha channel)
alphaTest number 0 (v2.4) pixels less opaque than this value (0.0 to 1.0) are not drawn at all. Use 0.5 for cut-out pictures such as trees (PNGs with see-through parts), otherwise the see-through parts can hide whatever is behind them. 0 turns it off.
shader string 'standard' the ThreeJS shader to use to render this entity - other valid value is flat
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
roughness number 0.5 how 'rough' the material appears. valid range = 0.0 to 1.0
metalness number 0 how 'metallic' the material appears. valid range = 0.0 to 1.0
red integer 255 how red the entity appears. valid range = 0 to 255
green integer 255 how green the entity appears. valid range = 0 to 255
blue integer 255 how blue the entity appears. valid range = 0 to 255
repeatX integer 1 how many times to repeat the texture associated with the entity along the x-axis of each face of the object. valid range = any positive number
repeatY integer 1 how many times to repeat the texture associated with the entity along the y-axis of each face of the object. valid range = any positive number
asset string 'None' the id (string) of the element that should be used as a texture for this entity. all textures should be set up in the 'index.html' file inside of the a-assets tag.
scaleX number 1.0 the scale of the object in the x-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleY number 1.0 the scale of the object in the y-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleZ number 1.0 the scale of the object in the z-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
rotationX number 0 the rotation of the object along the x-axis.
rotationY number 0 the rotation of the object along the y-axis.
rotationZ number 0 the rotation of the object along the z-axis.
visible boolean true determines whether the entity is visible in the scene.
solid boolean false (v2.4) solid entities block the user's movement and can be stood on when gravity is turned on (see world.setGravity and the physics example).
dynamicTexture boolean false sets whether the texture used on the entity is being drawn from a dynamically drawn canvas element. see these examples for more information: Dynamic textures, Multiple dynamic textures and Interactive dynamic textures
dynamicTextureHeight number 0 tells the entity the height of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
dynamicTextureWidth number 0 tells the entity the width of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
customData object undefined a custom object that can be used by the entity to keep track of user-specified data. example:
let b = new AFrameP5.Box({
   customData: {
      numClicks: 0
   },
   clickFunction: function(e) { 
      e.customData.numClicks++;
      console.log("This element has been clicked " + e.customData.numClicks + " times");
   }
});
clickFunction function undefined a custom function that will run every time the user clicks on the entity. this function receives a reference to the entity that was clicked, and (v2.4) a second argument with information about the click (see below). example:
let b = new AFrameP5.Box({
   clickFunction: function(e) { 
      e.setRed(random(255)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   clickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});


(v2.4) the second argument, often called hit, describes the click:
  • point3d : the exact point in the world where the click landed (an object with x, y and z)
  • distance : how far away that point is from the user, in meters
  • hand : what did the clicking: 'mouse' (the mouse, or the gaze cursor), 'left' or 'right' (the VR controllers)
  • uv : the raw texture coordinates of the click (x and y, from 0 to 1)
  • point2d : for entities that use a dynamic texture, where on the texture the click landed (x and y, in pixels)
  • voxel and voxelAdjacent : for voxel grids, the cube that was clicked and the empty space next to the face that was clicked
example:
let b = new AFrameP5.Box({
   clickFunction: function(e, hit) {
      console.log("clicked at " + hit.point3d.x + ", " + hit.point3d.y + ", " + hit.point3d.z + " with the " + hit.hand);
   }
});
see the click information example.
upFunction function undefined a custom function that will run every time the releases the mouse after the entity has been clicked. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   upFunction: function(e) { 
      e.spinX(random(360)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   upFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
enterFunction function undefined a custom function that will run every time the mouse hovers over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   enterFunction: function(e) { 
      e.setScale(2,2,2); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   enterFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
leaveFunction function undefined a custom function that will run every time the mouse stops hovering over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   leaveFunction: function(e) { 
      e.setScale(1,1,1); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   leaveFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
overFunction function undefined a custom function that will run continually whenever the mouse is hovering over the entity. this function should be implemented to accept two arguments - the first is a reference to the entity that was clicked, and the second is an object that contains information about the interaction that just occured. example:
let b = AFrameP5.Box({
   overFunction: function(e, intersectionInfo) { 
      console.log(intersectionInfo);
   }
});
intersectionInfo is an object that contains info about how the user is interacting with this entity. it contains the following properties:
  • distance : a float describing how far away the user is
  • point3d : an object with three properties (x, y & z) describing where the user is touching the entity
  • point2d : an object with two properites (x & y) describing where the user is touching the entity in 2D space (useful for determining where on a dynamic canvas the user is touching)
  • uv : an object with two properies (x & y) describing the raw textural offset (used to compute point2d)
  • hand : (v2.4) which pointer is hovering: 'mouse', 'left' or 'right'. Each VR controller calls overFunction separately, so check this if only one hand should do something (for example, only paint with the right hand).
For an example please see the Interactive dynamic textures sample program.

as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   overFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
dragFunction function undefined (v2.4) a custom function that runs every frame while the user holds the mouse button (or a VR controller trigger) down after pressing on this entity and keeps pointing at it - for example, to draw on a dynamic texture. A drag that starts somewhere else and moves onto the entity doesn't count. While the mouse is dragging on the entity, it doesn't turn the camera, so the view stays still while you draw. It takes the same two arguments as overFunction (the entity and hit), plus two more properties in hit:
  • previousPoint2d : where the user was pointing on the dynamic texture on the previous frame (x and y, in pixels). It is null when a new drag starts, and again when the pointer comes back onto the entity during a drag, so you can draw a line from it to point2d without joining separate strokes.
  • previousPoint3d : the same thing in the world (x, y and z)
example:
let canvas = new AFrameP5.Plane({
   asset: texture, dynamicTexture: true, dynamicTextureWidth: 512, dynamicTextureHeight: 512,
   dragFunction: function(e, hit) {
      if (hit.previousPoint2d) {
         buffer.line(hit.previousPoint2d.x, hit.previousPoint2d.y, hit.point2d.x, hit.point2d.y);
      }
   }
});
Each VR controller drags separately, so check hit.hand if only one hand should draw.

In VR, clickFunction runs as soon as the trigger is pressed (setClickOnRelease only changes mouse clicks), so avoid giving one entity both a clickFunction and a dragFunction if that matters. To do something at the start of each drag (for example, stamp a dot), check for hit.previousPoint2d === null inside dragFunction instead.
tickFunction function undefined a custom function that will run once per frame (like draw does for the main sketch). this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   tickFunction: function(e) { 
      e.setRed( random(255) ); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   tickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
Constructor Parameters (specific to this class)

new AFrameP5.Cylinder(options)

OptionTypeDefaultDescription
radius number 1 radius of the entity (in meters)
height number 1 height of the entity (along the y-axis)
openEnded boolean false whether the cone is open ended or not
segmentsRadial integer 36 number of segmented faces around the circumference of the cylinder.
segmentsHeight integer 18 Number of rows of faces along the height of the cylinder.
thetaStart integer 0 start angle in degrees
thetaLength integer 360 the central angle (in degrees)
Example
// sketch.js file

let world;
let cylinder;
			  		
function setup() {
   // no canvas needed
   noCanvas();
   
   // create a new VR World object
   world = new AFrameP5.World('VRScene');
   
   // construct a new cylinder
   cylinder = new AFrameP5.Cylinder({
      x:0, 
      y:2, 
      z:0, 
      red:0, 
      green:255, 
      blue:0
   });
   
   // add the cylinder to the world
   world.add(cylinder);
}
Methods (common to all entities)
MethodCategoryDescription
constrainPosition(xMin: number, xMax: number, yMin: number, yMax: number, zMin: number, zMax: number) Position ensures that the entity is constrained within the desired boundaries along all three axes. if an entity exceeds any of the constraints it is nudged back into position accordingly.
getX(): number Position returns the current x position of the entity. this is the entity's LOCAL position in relation to its container.
getY(): number Position returns the current y position of the entity. this is the entity's LOCAL position in relation to its container.
getZ(): number Position returns the current z position of the entity. this is the entity's LOCAL position in relation to its container.
nudge(x: number, y: number, z: number) Position nudges the element based on its current position. accepts three numeric values (i.e. myEntity.nudge(1,0,0); will nudge the entity 1 meter from its current position along the x-axis. this is the entity's LOCAL position in relation to its container.
setPosition(x: number, y: number, z: number) Position sets the position of the entity. this is the entity's LOCAL position in relation to its container.
setX(x: number) Position sets the x position of the entity. this is the entity's LOCAL position in relation to its container.
setY(y: number) Position sets the y position of the entity. this is the entity's LOCAL position in relation to its container.
setZ(z: number) Position sets the z position of the entity. this is the entity's LOCAL position in relation to its container.
getWorldPosition(): object Position returns the entity's WORLD position, not it's local position within its current container. this method is often used to compute the absolute position of an element in world space in order to deal with collisions of objects that may be nested inside of containers.
getRotationX(): number Rotation returns the current x rotation of the entity.
getRotationY(): number Rotation returns the current y rotation of the entity.
getRotationZ(): number Rotation returns the current z rotation of the entity.
rotateX(x: number) Rotation sets the x rotation of the entity
rotateY(y: number) Rotation sets the y rotation of the entity
rotateZ(z: number) Rotation sets the z rotation of the entity
setRotation(x: number, y: number, z: number) Rotation sets the rotation of the entity.
spinX(x: number) Rotation spins the entity along the x axis based on its current rotation. i.e. myEntity.spinX(1); // spin by 1 degree
spinY(y: number) Rotation spins the entity along the y axis based on its current rotation. i.e. myEntity.spinY(1); // spin by 1 degree
spinZ(z: number) Rotation spins the entity along the z axis based on its current rotation. i.e. myEntity.spinZ(1); // spin by 1 degree
lookAtUser(upright?: boolean) Rotation forces the entity to orient itself so that it is facing the user. (v2.4) lookAtUser(true) keeps the entity upright, so it only turns left and right - use this for billboards such as trees, which would otherwise tip over when the user walks up close.
getVisibility(): boolean Visibility returns the current visibility state of the entity
hide() Visibility hides the entity by setting its visible property to false
show() Visibility shows the entity by setting its visible property to true
toggleVisibility() Visibility hides the entity if it is current visible and shows the entity if it is current hidden
getScale(): object Scale returns the scale of the entity as an object (i.e. {x:0, y:0, z:0}
getScaleX(): number Scale returns the x scale of the entity
getScaleY(): number Scale returns the y scale of the entity
getScaleZ(): number Scale returns the z scale of the entity
setScale(x: number, y: number, z: number) Scale sets the scale of the object in all axes
setScaleX(x: number) Scale sets the x scale of the object
setScaleY(y: number) Scale sets the y scale of the object
setScaleZ(z: number) Scale sets the z scale of the object
getAsset(): string Material returns the current id of the asset being used to texture this entity
getBlue(): number Material returns the current blue color of the entity
getGreen(): number Material returns the current green color of the entity
getMetalness(): number Material returns the current metalness setting for the texture of the entity (range = 0.0 to 1.0)
getOpacity(): number Material returns the current opacity of the entity
getRed(): number Material returns the current red color of the entity
setRoughness(roughness: number) Material sets the roughness for the texture of the entity (range = 0.0 to 1.0)
getSide(): string Material returns which faces of the entity will be textured (valid values are front, back and double)
getTransparent(): boolean Material returns the current transparency of the entity
setAsset(asset: string) Material sets the id for the asset to texture this entity
setColor(red: number, green: number, blue: number) Material sets the color of the entity
setBlue(blue: number) Material sets the blue color of the entity
setGreen(green: number) Material sets the green color of the entity
setMetalness(metalness: number) Material sets the metalness for the texture of the entity (range = 0.0 to 1.0)
setOpacity(opacity: number) Material sets the opacity of the entity (range = 0.0 to 1.0)
setRed(red: number) Material sets the red color of the entity
getRoughness(): number Material returns the current roughness setting for the texture of the entity (range = 0.0 to 1.0)
setTransparent(transparent: boolean) Material sets whether the entity supports transparent textures
getAlphaTest(): number Material (v2.4) returns the entity's alphaTest value
setAlphaTest(alphaTest: number) Material (v2.4) sets the alphaTest value (see the alphaTest constructor option)
setSide(side: string) Material sets which faces of the entity will be textured (valid values are front, back and double)
getRepeatX(): number Material returns how many times the texture repeats across the entity horizontally
getRepeatY(): number Material (v2.4) returns how many times the texture repeats across the entity vertically
setRepeatX(times: number) Material sets how many times the texture repeats across the entity horizontally
setRepeatY(times: number) Material (v2.4) sets how many times the texture repeats across the entity vertically
getSolid(): boolean Physics (v2.4) returns whether the entity is solid
setSolid(solid: boolean) Physics (v2.4) makes the entity solid (true: it blocks the user and can be stood on) or not solid (false: the user can walk through it)
add(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity. alias for addChild.
addChild(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity.
getChildren(): Array Hierarchy returns an Array of all children of this entity
removeChild(entity: Entity) Hierarchy removes a child entity from this entity.
Methods (specific to this class)
MethodCategoryDescription
getRadius(): number Geometry returns the current radius of the entity
getHeight(): number Geometry returns the current height of the entity
getOpenEnded(): boolean Geometry returns whether the entity is open ended or not
getSegmentsRadial(): number Geometry returns the current segmentsRadial value for the entity
getSegmentsHeight(): number Geometry returns the current segmentsHeight value for the entity
getThetaStart(): number Geometry returns the current thetaStart value for the entity
getThetaLength(): number Geometry returns the current thetaLength value for the entity
setRadius(radius: number) Geometry sets the radius of the entity
changeRadius(amount: number) Geometry updates the radius by the value provided (i.e. entity.changeRadius(0.1); will increase the radius by 0.1 meters.
setHeight(height: number) Geometry sets the height of the entity
setOpenEnded(openEnded: boolean) Geometry sets whether the entity is open ended or not
setSegmentsRadial(segmentsRadial: number) Geometry sets the current segmentsRadial value for the entity
setSegmentsHeight(segmentsHeight: number) Geometry sets the current segmentsHeight value for the entity
setThetaStart(thetaStart: number) Geometry sets the the thetaStart value for the entity
setThetaLength(thetaLength: number) Geometry sets the the thetaLength value for the entity

Class: Dodecahedron (entity)

Used to construct a three dimensional 12-sided entity.

Constructor Parameters (common to all entities)

new AFrameP5.Dodecahedron(options)

OptionTypeDefaultDescription
x number 0 x-position of the entity
y number 0 y-position of the entity
z number 0 z-position of the entity
opacity number 1.0 how transparent this entity is (0.0 = fully transparent, 1.0 = fully opaque)
transparent boolean false whether the texture associated with this entity supports transparency (i.e. a PNG file with an alpha channel)
alphaTest number 0 (v2.4) pixels less opaque than this value (0.0 to 1.0) are not drawn at all. Use 0.5 for cut-out pictures such as trees (PNGs with see-through parts), otherwise the see-through parts can hide whatever is behind them. 0 turns it off.
shader string 'standard' the ThreeJS shader to use to render this entity - other valid value is flat
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
roughness number 0.5 how 'rough' the material appears. valid range = 0.0 to 1.0
metalness number 0 how 'metallic' the material appears. valid range = 0.0 to 1.0
red integer 255 how red the entity appears. valid range = 0 to 255
green integer 255 how green the entity appears. valid range = 0 to 255
blue integer 255 how blue the entity appears. valid range = 0 to 255
repeatX integer 1 how many times to repeat the texture associated with the entity along the x-axis of each face of the object. valid range = any positive number
repeatY integer 1 how many times to repeat the texture associated with the entity along the y-axis of each face of the object. valid range = any positive number
asset string 'None' the id (string) of the element that should be used as a texture for this entity. all textures should be set up in the 'index.html' file inside of the a-assets tag.
scaleX number 1.0 the scale of the object in the x-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleY number 1.0 the scale of the object in the y-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleZ number 1.0 the scale of the object in the z-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
rotationX number 0 the rotation of the object along the x-axis.
rotationY number 0 the rotation of the object along the y-axis.
rotationZ number 0 the rotation of the object along the z-axis.
visible boolean true determines whether the entity is visible in the scene.
solid boolean false (v2.4) solid entities block the user's movement and can be stood on when gravity is turned on (see world.setGravity and the physics example).
dynamicTexture boolean false sets whether the texture used on the entity is being drawn from a dynamically drawn canvas element. see these examples for more information: Dynamic textures, Multiple dynamic textures and Interactive dynamic textures
dynamicTextureHeight number 0 tells the entity the height of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
dynamicTextureWidth number 0 tells the entity the width of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
customData object undefined a custom object that can be used by the entity to keep track of user-specified data. example:
let b = new AFrameP5.Box({
   customData: {
      numClicks: 0
   },
   clickFunction: function(e) { 
      e.customData.numClicks++;
      console.log("This element has been clicked " + e.customData.numClicks + " times");
   }
});
clickFunction function undefined a custom function that will run every time the user clicks on the entity. this function receives a reference to the entity that was clicked, and (v2.4) a second argument with information about the click (see below). example:
let b = new AFrameP5.Box({
   clickFunction: function(e) { 
      e.setRed(random(255)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   clickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});


(v2.4) the second argument, often called hit, describes the click:
  • point3d : the exact point in the world where the click landed (an object with x, y and z)
  • distance : how far away that point is from the user, in meters
  • hand : what did the clicking: 'mouse' (the mouse, or the gaze cursor), 'left' or 'right' (the VR controllers)
  • uv : the raw texture coordinates of the click (x and y, from 0 to 1)
  • point2d : for entities that use a dynamic texture, where on the texture the click landed (x and y, in pixels)
  • voxel and voxelAdjacent : for voxel grids, the cube that was clicked and the empty space next to the face that was clicked
example:
let b = new AFrameP5.Box({
   clickFunction: function(e, hit) {
      console.log("clicked at " + hit.point3d.x + ", " + hit.point3d.y + ", " + hit.point3d.z + " with the " + hit.hand);
   }
});
see the click information example.
upFunction function undefined a custom function that will run every time the releases the mouse after the entity has been clicked. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   upFunction: function(e) { 
      e.spinX(random(360)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   upFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
enterFunction function undefined a custom function that will run every time the mouse hovers over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   enterFunction: function(e) { 
      e.setScale(2,2,2); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   enterFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
leaveFunction function undefined a custom function that will run every time the mouse stops hovering over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   leaveFunction: function(e) { 
      e.setScale(1,1,1); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   leaveFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
overFunction function undefined a custom function that will run continually whenever the mouse is hovering over the entity. this function should be implemented to accept two arguments - the first is a reference to the entity that was clicked, and the second is an object that contains information about the interaction that just occured. example:
let b = AFrameP5.Box({
   overFunction: function(e, intersectionInfo) { 
      console.log(intersectionInfo);
   }
});
intersectionInfo is an object that contains info about how the user is interacting with this entity. it contains the following properties:
  • distance : a float describing how far away the user is
  • point3d : an object with three properties (x, y & z) describing where the user is touching the entity
  • point2d : an object with two properites (x & y) describing where the user is touching the entity in 2D space (useful for determining where on a dynamic canvas the user is touching)
  • uv : an object with two properies (x & y) describing the raw textural offset (used to compute point2d)
  • hand : (v2.4) which pointer is hovering: 'mouse', 'left' or 'right'. Each VR controller calls overFunction separately, so check this if only one hand should do something (for example, only paint with the right hand).
For an example please see the Interactive dynamic textures sample program.

as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   overFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
dragFunction function undefined (v2.4) a custom function that runs every frame while the user holds the mouse button (or a VR controller trigger) down after pressing on this entity and keeps pointing at it - for example, to draw on a dynamic texture. A drag that starts somewhere else and moves onto the entity doesn't count. While the mouse is dragging on the entity, it doesn't turn the camera, so the view stays still while you draw. It takes the same two arguments as overFunction (the entity and hit), plus two more properties in hit:
  • previousPoint2d : where the user was pointing on the dynamic texture on the previous frame (x and y, in pixels). It is null when a new drag starts, and again when the pointer comes back onto the entity during a drag, so you can draw a line from it to point2d without joining separate strokes.
  • previousPoint3d : the same thing in the world (x, y and z)
example:
let canvas = new AFrameP5.Plane({
   asset: texture, dynamicTexture: true, dynamicTextureWidth: 512, dynamicTextureHeight: 512,
   dragFunction: function(e, hit) {
      if (hit.previousPoint2d) {
         buffer.line(hit.previousPoint2d.x, hit.previousPoint2d.y, hit.point2d.x, hit.point2d.y);
      }
   }
});
Each VR controller drags separately, so check hit.hand if only one hand should draw.

In VR, clickFunction runs as soon as the trigger is pressed (setClickOnRelease only changes mouse clicks), so avoid giving one entity both a clickFunction and a dragFunction if that matters. To do something at the start of each drag (for example, stamp a dot), check for hit.previousPoint2d === null inside dragFunction instead.
tickFunction function undefined a custom function that will run once per frame (like draw does for the main sketch). this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   tickFunction: function(e) { 
      e.setRed( random(255) ); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   tickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
Constructor Parameters (specific to this class)

new AFrameP5.Dodecahedron(options)

OptionTypeDefaultDescription
radius number 1 radius of the entity (in meters)
Example
// sketch.js file

let world;
let dodecahedron;
			  		
function setup() {
   // no canvas needed
   noCanvas();
   
   // create a new VR World object
   world = new AFrameP5.World('VRScene');
   
   // construct a new dodecahedron
   dodecahedron = new AFrameP5.Dodecahedron({
      x:0, 
      y:2, 
      z:0, 
      red:0, 
      green:255, 
      blue:0
   });
   
   // add the dodecahedron to the world
   world.add(dodecahedron);
}
Methods (common to all entities)
MethodCategoryDescription
constrainPosition(xMin: number, xMax: number, yMin: number, yMax: number, zMin: number, zMax: number) Position ensures that the entity is constrained within the desired boundaries along all three axes. if an entity exceeds any of the constraints it is nudged back into position accordingly.
getX(): number Position returns the current x position of the entity. this is the entity's LOCAL position in relation to its container.
getY(): number Position returns the current y position of the entity. this is the entity's LOCAL position in relation to its container.
getZ(): number Position returns the current z position of the entity. this is the entity's LOCAL position in relation to its container.
nudge(x: number, y: number, z: number) Position nudges the element based on its current position. accepts three numeric values (i.e. myEntity.nudge(1,0,0); will nudge the entity 1 meter from its current position along the x-axis. this is the entity's LOCAL position in relation to its container.
setPosition(x: number, y: number, z: number) Position sets the position of the entity. this is the entity's LOCAL position in relation to its container.
setX(x: number) Position sets the x position of the entity. this is the entity's LOCAL position in relation to its container.
setY(y: number) Position sets the y position of the entity. this is the entity's LOCAL position in relation to its container.
setZ(z: number) Position sets the z position of the entity. this is the entity's LOCAL position in relation to its container.
getWorldPosition(): object Position returns the entity's WORLD position, not it's local position within its current container. this method is often used to compute the absolute position of an element in world space in order to deal with collisions of objects that may be nested inside of containers.
getRotationX(): number Rotation returns the current x rotation of the entity.
getRotationY(): number Rotation returns the current y rotation of the entity.
getRotationZ(): number Rotation returns the current z rotation of the entity.
rotateX(x: number) Rotation sets the x rotation of the entity
rotateY(y: number) Rotation sets the y rotation of the entity
rotateZ(z: number) Rotation sets the z rotation of the entity
setRotation(x: number, y: number, z: number) Rotation sets the rotation of the entity.
spinX(x: number) Rotation spins the entity along the x axis based on its current rotation. i.e. myEntity.spinX(1); // spin by 1 degree
spinY(y: number) Rotation spins the entity along the y axis based on its current rotation. i.e. myEntity.spinY(1); // spin by 1 degree
spinZ(z: number) Rotation spins the entity along the z axis based on its current rotation. i.e. myEntity.spinZ(1); // spin by 1 degree
lookAtUser(upright?: boolean) Rotation forces the entity to orient itself so that it is facing the user. (v2.4) lookAtUser(true) keeps the entity upright, so it only turns left and right - use this for billboards such as trees, which would otherwise tip over when the user walks up close.
getVisibility(): boolean Visibility returns the current visibility state of the entity
hide() Visibility hides the entity by setting its visible property to false
show() Visibility shows the entity by setting its visible property to true
toggleVisibility() Visibility hides the entity if it is current visible and shows the entity if it is current hidden
getScale(): object Scale returns the scale of the entity as an object (i.e. {x:0, y:0, z:0}
getScaleX(): number Scale returns the x scale of the entity
getScaleY(): number Scale returns the y scale of the entity
getScaleZ(): number Scale returns the z scale of the entity
setScale(x: number, y: number, z: number) Scale sets the scale of the object in all axes
setScaleX(x: number) Scale sets the x scale of the object
setScaleY(y: number) Scale sets the y scale of the object
setScaleZ(z: number) Scale sets the z scale of the object
getAsset(): string Material returns the current id of the asset being used to texture this entity
getBlue(): number Material returns the current blue color of the entity
getGreen(): number Material returns the current green color of the entity
getMetalness(): number Material returns the current metalness setting for the texture of the entity (range = 0.0 to 1.0)
getOpacity(): number Material returns the current opacity of the entity
getRed(): number Material returns the current red color of the entity
setRoughness(roughness: number) Material sets the roughness for the texture of the entity (range = 0.0 to 1.0)
getSide(): string Material returns which faces of the entity will be textured (valid values are front, back and double)
getTransparent(): boolean Material returns the current transparency of the entity
setAsset(asset: string) Material sets the id for the asset to texture this entity
setColor(red: number, green: number, blue: number) Material sets the color of the entity
setBlue(blue: number) Material sets the blue color of the entity
setGreen(green: number) Material sets the green color of the entity
setMetalness(metalness: number) Material sets the metalness for the texture of the entity (range = 0.0 to 1.0)
setOpacity(opacity: number) Material sets the opacity of the entity (range = 0.0 to 1.0)
setRed(red: number) Material sets the red color of the entity
getRoughness(): number Material returns the current roughness setting for the texture of the entity (range = 0.0 to 1.0)
setTransparent(transparent: boolean) Material sets whether the entity supports transparent textures
getAlphaTest(): number Material (v2.4) returns the entity's alphaTest value
setAlphaTest(alphaTest: number) Material (v2.4) sets the alphaTest value (see the alphaTest constructor option)
setSide(side: string) Material sets which faces of the entity will be textured (valid values are front, back and double)
getRepeatX(): number Material returns how many times the texture repeats across the entity horizontally
getRepeatY(): number Material (v2.4) returns how many times the texture repeats across the entity vertically
setRepeatX(times: number) Material sets how many times the texture repeats across the entity horizontally
setRepeatY(times: number) Material (v2.4) sets how many times the texture repeats across the entity vertically
getSolid(): boolean Physics (v2.4) returns whether the entity is solid
setSolid(solid: boolean) Physics (v2.4) makes the entity solid (true: it blocks the user and can be stood on) or not solid (false: the user can walk through it)
add(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity. alias for addChild.
addChild(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity.
getChildren(): Array Hierarchy returns an Array of all children of this entity
removeChild(entity: Entity) Hierarchy removes a child entity from this entity.
Methods (specific to this class)
MethodCategoryDescription
getRadius(): number Geometry returns the current radius of the entity
setRadius(radius: number) Geometry sets the radius of the entity
changeRadius(amount: number) Geometry updates the radius by the value provided (i.e. entity.changeRadius(0.1); will increase the radius by 0.1 meters.

Class: Octahedron (entity)

Used to construct a three dimensional 8-sided entity.

Constructor Parameters (common to all entities)

new AFrameP5.Octahedron(options)

OptionTypeDefaultDescription
x number 0 x-position of the entity
y number 0 y-position of the entity
z number 0 z-position of the entity
opacity number 1.0 how transparent this entity is (0.0 = fully transparent, 1.0 = fully opaque)
transparent boolean false whether the texture associated with this entity supports transparency (i.e. a PNG file with an alpha channel)
alphaTest number 0 (v2.4) pixels less opaque than this value (0.0 to 1.0) are not drawn at all. Use 0.5 for cut-out pictures such as trees (PNGs with see-through parts), otherwise the see-through parts can hide whatever is behind them. 0 turns it off.
shader string 'standard' the ThreeJS shader to use to render this entity - other valid value is flat
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
roughness number 0.5 how 'rough' the material appears. valid range = 0.0 to 1.0
metalness number 0 how 'metallic' the material appears. valid range = 0.0 to 1.0
red integer 255 how red the entity appears. valid range = 0 to 255
green integer 255 how green the entity appears. valid range = 0 to 255
blue integer 255 how blue the entity appears. valid range = 0 to 255
repeatX integer 1 how many times to repeat the texture associated with the entity along the x-axis of each face of the object. valid range = any positive number
repeatY integer 1 how many times to repeat the texture associated with the entity along the y-axis of each face of the object. valid range = any positive number
asset string 'None' the id (string) of the element that should be used as a texture for this entity. all textures should be set up in the 'index.html' file inside of the a-assets tag.
scaleX number 1.0 the scale of the object in the x-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleY number 1.0 the scale of the object in the y-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleZ number 1.0 the scale of the object in the z-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
rotationX number 0 the rotation of the object along the x-axis.
rotationY number 0 the rotation of the object along the y-axis.
rotationZ number 0 the rotation of the object along the z-axis.
visible boolean true determines whether the entity is visible in the scene.
solid boolean false (v2.4) solid entities block the user's movement and can be stood on when gravity is turned on (see world.setGravity and the physics example).
dynamicTexture boolean false sets whether the texture used on the entity is being drawn from a dynamically drawn canvas element. see these examples for more information: Dynamic textures, Multiple dynamic textures and Interactive dynamic textures
dynamicTextureHeight number 0 tells the entity the height of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
dynamicTextureWidth number 0 tells the entity the width of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
customData object undefined a custom object that can be used by the entity to keep track of user-specified data. example:
let b = new AFrameP5.Box({
   customData: {
      numClicks: 0
   },
   clickFunction: function(e) { 
      e.customData.numClicks++;
      console.log("This element has been clicked " + e.customData.numClicks + " times");
   }
});
clickFunction function undefined a custom function that will run every time the user clicks on the entity. this function receives a reference to the entity that was clicked, and (v2.4) a second argument with information about the click (see below). example:
let b = new AFrameP5.Box({
   clickFunction: function(e) { 
      e.setRed(random(255)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   clickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});


(v2.4) the second argument, often called hit, describes the click:
  • point3d : the exact point in the world where the click landed (an object with x, y and z)
  • distance : how far away that point is from the user, in meters
  • hand : what did the clicking: 'mouse' (the mouse, or the gaze cursor), 'left' or 'right' (the VR controllers)
  • uv : the raw texture coordinates of the click (x and y, from 0 to 1)
  • point2d : for entities that use a dynamic texture, where on the texture the click landed (x and y, in pixels)
  • voxel and voxelAdjacent : for voxel grids, the cube that was clicked and the empty space next to the face that was clicked
example:
let b = new AFrameP5.Box({
   clickFunction: function(e, hit) {
      console.log("clicked at " + hit.point3d.x + ", " + hit.point3d.y + ", " + hit.point3d.z + " with the " + hit.hand);
   }
});
see the click information example.
upFunction function undefined a custom function that will run every time the releases the mouse after the entity has been clicked. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   upFunction: function(e) { 
      e.spinX(random(360)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   upFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
enterFunction function undefined a custom function that will run every time the mouse hovers over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   enterFunction: function(e) { 
      e.setScale(2,2,2); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   enterFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
leaveFunction function undefined a custom function that will run every time the mouse stops hovering over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   leaveFunction: function(e) { 
      e.setScale(1,1,1); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   leaveFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
overFunction function undefined a custom function that will run continually whenever the mouse is hovering over the entity. this function should be implemented to accept two arguments - the first is a reference to the entity that was clicked, and the second is an object that contains information about the interaction that just occured. example:
let b = AFrameP5.Box({
   overFunction: function(e, intersectionInfo) { 
      console.log(intersectionInfo);
   }
});
intersectionInfo is an object that contains info about how the user is interacting with this entity. it contains the following properties:
  • distance : a float describing how far away the user is
  • point3d : an object with three properties (x, y & z) describing where the user is touching the entity
  • point2d : an object with two properites (x & y) describing where the user is touching the entity in 2D space (useful for determining where on a dynamic canvas the user is touching)
  • uv : an object with two properies (x & y) describing the raw textural offset (used to compute point2d)
  • hand : (v2.4) which pointer is hovering: 'mouse', 'left' or 'right'. Each VR controller calls overFunction separately, so check this if only one hand should do something (for example, only paint with the right hand).
For an example please see the Interactive dynamic textures sample program.

as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   overFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
dragFunction function undefined (v2.4) a custom function that runs every frame while the user holds the mouse button (or a VR controller trigger) down after pressing on this entity and keeps pointing at it - for example, to draw on a dynamic texture. A drag that starts somewhere else and moves onto the entity doesn't count. While the mouse is dragging on the entity, it doesn't turn the camera, so the view stays still while you draw. It takes the same two arguments as overFunction (the entity and hit), plus two more properties in hit:
  • previousPoint2d : where the user was pointing on the dynamic texture on the previous frame (x and y, in pixels). It is null when a new drag starts, and again when the pointer comes back onto the entity during a drag, so you can draw a line from it to point2d without joining separate strokes.
  • previousPoint3d : the same thing in the world (x, y and z)
example:
let canvas = new AFrameP5.Plane({
   asset: texture, dynamicTexture: true, dynamicTextureWidth: 512, dynamicTextureHeight: 512,
   dragFunction: function(e, hit) {
      if (hit.previousPoint2d) {
         buffer.line(hit.previousPoint2d.x, hit.previousPoint2d.y, hit.point2d.x, hit.point2d.y);
      }
   }
});
Each VR controller drags separately, so check hit.hand if only one hand should draw.

In VR, clickFunction runs as soon as the trigger is pressed (setClickOnRelease only changes mouse clicks), so avoid giving one entity both a clickFunction and a dragFunction if that matters. To do something at the start of each drag (for example, stamp a dot), check for hit.previousPoint2d === null inside dragFunction instead.
tickFunction function undefined a custom function that will run once per frame (like draw does for the main sketch). this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   tickFunction: function(e) { 
      e.setRed( random(255) ); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   tickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
Constructor Parameters (specific to this class)

new AFrameP5.Octahedron(options)

OptionTypeDefaultDescription
radius number 1 radius of the entity (in meters)
Example
// sketch.js file

let world;
let octahedron;
			  		
function setup() {
   // no canvas needed
   noCanvas();
   
   // create a new VR World object
   world = new AFrameP5.World('VRScene');
   
   // construct a new Octahedron
   octahedron = new AFrameP5.Octahedron({
      x:0, 
      y:2, 
      z:0, 
      red:0, 
      green:255, 
      blue:0
   });
   
   // add the Octahedron to the world
   world.add(octahedron);
}
Methods (common to all entities)
MethodCategoryDescription
constrainPosition(xMin: number, xMax: number, yMin: number, yMax: number, zMin: number, zMax: number) Position ensures that the entity is constrained within the desired boundaries along all three axes. if an entity exceeds any of the constraints it is nudged back into position accordingly.
getX(): number Position returns the current x position of the entity. this is the entity's LOCAL position in relation to its container.
getY(): number Position returns the current y position of the entity. this is the entity's LOCAL position in relation to its container.
getZ(): number Position returns the current z position of the entity. this is the entity's LOCAL position in relation to its container.
nudge(x: number, y: number, z: number) Position nudges the element based on its current position. accepts three numeric values (i.e. myEntity.nudge(1,0,0); will nudge the entity 1 meter from its current position along the x-axis. this is the entity's LOCAL position in relation to its container.
setPosition(x: number, y: number, z: number) Position sets the position of the entity. this is the entity's LOCAL position in relation to its container.
setX(x: number) Position sets the x position of the entity. this is the entity's LOCAL position in relation to its container.
setY(y: number) Position sets the y position of the entity. this is the entity's LOCAL position in relation to its container.
setZ(z: number) Position sets the z position of the entity. this is the entity's LOCAL position in relation to its container.
getWorldPosition(): object Position returns the entity's WORLD position, not it's local position within its current container. this method is often used to compute the absolute position of an element in world space in order to deal with collisions of objects that may be nested inside of containers.
getRotationX(): number Rotation returns the current x rotation of the entity.
getRotationY(): number Rotation returns the current y rotation of the entity.
getRotationZ(): number Rotation returns the current z rotation of the entity.
rotateX(x: number) Rotation sets the x rotation of the entity
rotateY(y: number) Rotation sets the y rotation of the entity
rotateZ(z: number) Rotation sets the z rotation of the entity
setRotation(x: number, y: number, z: number) Rotation sets the rotation of the entity.
spinX(x: number) Rotation spins the entity along the x axis based on its current rotation. i.e. myEntity.spinX(1); // spin by 1 degree
spinY(y: number) Rotation spins the entity along the y axis based on its current rotation. i.e. myEntity.spinY(1); // spin by 1 degree
spinZ(z: number) Rotation spins the entity along the z axis based on its current rotation. i.e. myEntity.spinZ(1); // spin by 1 degree
lookAtUser(upright?: boolean) Rotation forces the entity to orient itself so that it is facing the user. (v2.4) lookAtUser(true) keeps the entity upright, so it only turns left and right - use this for billboards such as trees, which would otherwise tip over when the user walks up close.
getVisibility(): boolean Visibility returns the current visibility state of the entity
hide() Visibility hides the entity by setting its visible property to false
show() Visibility shows the entity by setting its visible property to true
toggleVisibility() Visibility hides the entity if it is current visible and shows the entity if it is current hidden
getScale(): object Scale returns the scale of the entity as an object (i.e. {x:0, y:0, z:0}
getScaleX(): number Scale returns the x scale of the entity
getScaleY(): number Scale returns the y scale of the entity
getScaleZ(): number Scale returns the z scale of the entity
setScale(x: number, y: number, z: number) Scale sets the scale of the object in all axes
setScaleX(x: number) Scale sets the x scale of the object
setScaleY(y: number) Scale sets the y scale of the object
setScaleZ(z: number) Scale sets the z scale of the object
getAsset(): string Material returns the current id of the asset being used to texture this entity
getBlue(): number Material returns the current blue color of the entity
getGreen(): number Material returns the current green color of the entity
getMetalness(): number Material returns the current metalness setting for the texture of the entity (range = 0.0 to 1.0)
getOpacity(): number Material returns the current opacity of the entity
getRed(): number Material returns the current red color of the entity
setRoughness(roughness: number) Material sets the roughness for the texture of the entity (range = 0.0 to 1.0)
getSide(): string Material returns which faces of the entity will be textured (valid values are front, back and double)
getTransparent(): boolean Material returns the current transparency of the entity
setAsset(asset: string) Material sets the id for the asset to texture this entity
setColor(red: number, green: number, blue: number) Material sets the color of the entity
setBlue(blue: number) Material sets the blue color of the entity
setGreen(green: number) Material sets the green color of the entity
setMetalness(metalness: number) Material sets the metalness for the texture of the entity (range = 0.0 to 1.0)
setOpacity(opacity: number) Material sets the opacity of the entity (range = 0.0 to 1.0)
setRed(red: number) Material sets the red color of the entity
getRoughness(): number Material returns the current roughness setting for the texture of the entity (range = 0.0 to 1.0)
setTransparent(transparent: boolean) Material sets whether the entity supports transparent textures
getAlphaTest(): number Material (v2.4) returns the entity's alphaTest value
setAlphaTest(alphaTest: number) Material (v2.4) sets the alphaTest value (see the alphaTest constructor option)
setSide(side: string) Material sets which faces of the entity will be textured (valid values are front, back and double)
getRepeatX(): number Material returns how many times the texture repeats across the entity horizontally
getRepeatY(): number Material (v2.4) returns how many times the texture repeats across the entity vertically
setRepeatX(times: number) Material sets how many times the texture repeats across the entity horizontally
setRepeatY(times: number) Material (v2.4) sets how many times the texture repeats across the entity vertically
getSolid(): boolean Physics (v2.4) returns whether the entity is solid
setSolid(solid: boolean) Physics (v2.4) makes the entity solid (true: it blocks the user and can be stood on) or not solid (false: the user can walk through it)
add(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity. alias for addChild.
addChild(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity.
getChildren(): Array Hierarchy returns an Array of all children of this entity
removeChild(entity: Entity) Hierarchy removes a child entity from this entity.
Methods (specific to this class)
MethodCategoryDescription
getRadius(): number Geometry returns the current radius of the entity
setRadius(radius: number) Geometry sets the radius of the entity
changeRadius(amount: number) Geometry updates the radius by the value provided (i.e. entity.changeRadius(0.1); will increase the radius by 0.1 meters.

Class: Tetrahedron (entity)

Used to construct a three dimensional 4-sided entity.

Constructor Parameters (common to all entities)

new AFrameP5.Tetrahedron(options)

OptionTypeDefaultDescription
x number 0 x-position of the entity
y number 0 y-position of the entity
z number 0 z-position of the entity
opacity number 1.0 how transparent this entity is (0.0 = fully transparent, 1.0 = fully opaque)
transparent boolean false whether the texture associated with this entity supports transparency (i.e. a PNG file with an alpha channel)
alphaTest number 0 (v2.4) pixels less opaque than this value (0.0 to 1.0) are not drawn at all. Use 0.5 for cut-out pictures such as trees (PNGs with see-through parts), otherwise the see-through parts can hide whatever is behind them. 0 turns it off.
shader string 'standard' the ThreeJS shader to use to render this entity - other valid value is flat
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
roughness number 0.5 how 'rough' the material appears. valid range = 0.0 to 1.0
metalness number 0 how 'metallic' the material appears. valid range = 0.0 to 1.0
red integer 255 how red the entity appears. valid range = 0 to 255
green integer 255 how green the entity appears. valid range = 0 to 255
blue integer 255 how blue the entity appears. valid range = 0 to 255
repeatX integer 1 how many times to repeat the texture associated with the entity along the x-axis of each face of the object. valid range = any positive number
repeatY integer 1 how many times to repeat the texture associated with the entity along the y-axis of each face of the object. valid range = any positive number
asset string 'None' the id (string) of the element that should be used as a texture for this entity. all textures should be set up in the 'index.html' file inside of the a-assets tag.
scaleX number 1.0 the scale of the object in the x-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleY number 1.0 the scale of the object in the y-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleZ number 1.0 the scale of the object in the z-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
rotationX number 0 the rotation of the object along the x-axis.
rotationY number 0 the rotation of the object along the y-axis.
rotationZ number 0 the rotation of the object along the z-axis.
visible boolean true determines whether the entity is visible in the scene.
solid boolean false (v2.4) solid entities block the user's movement and can be stood on when gravity is turned on (see world.setGravity and the physics example).
dynamicTexture boolean false sets whether the texture used on the entity is being drawn from a dynamically drawn canvas element. see these examples for more information: Dynamic textures, Multiple dynamic textures and Interactive dynamic textures
dynamicTextureHeight number 0 tells the entity the height of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
dynamicTextureWidth number 0 tells the entity the width of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
customData object undefined a custom object that can be used by the entity to keep track of user-specified data. example:
let b = new AFrameP5.Box({
   customData: {
      numClicks: 0
   },
   clickFunction: function(e) { 
      e.customData.numClicks++;
      console.log("This element has been clicked " + e.customData.numClicks + " times");
   }
});
clickFunction function undefined a custom function that will run every time the user clicks on the entity. this function receives a reference to the entity that was clicked, and (v2.4) a second argument with information about the click (see below). example:
let b = new AFrameP5.Box({
   clickFunction: function(e) { 
      e.setRed(random(255)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   clickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});


(v2.4) the second argument, often called hit, describes the click:
  • point3d : the exact point in the world where the click landed (an object with x, y and z)
  • distance : how far away that point is from the user, in meters
  • hand : what did the clicking: 'mouse' (the mouse, or the gaze cursor), 'left' or 'right' (the VR controllers)
  • uv : the raw texture coordinates of the click (x and y, from 0 to 1)
  • point2d : for entities that use a dynamic texture, where on the texture the click landed (x and y, in pixels)
  • voxel and voxelAdjacent : for voxel grids, the cube that was clicked and the empty space next to the face that was clicked
example:
let b = new AFrameP5.Box({
   clickFunction: function(e, hit) {
      console.log("clicked at " + hit.point3d.x + ", " + hit.point3d.y + ", " + hit.point3d.z + " with the " + hit.hand);
   }
});
see the click information example.
upFunction function undefined a custom function that will run every time the releases the mouse after the entity has been clicked. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   upFunction: function(e) { 
      e.spinX(random(360)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   upFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
enterFunction function undefined a custom function that will run every time the mouse hovers over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   enterFunction: function(e) { 
      e.setScale(2,2,2); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   enterFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
leaveFunction function undefined a custom function that will run every time the mouse stops hovering over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   leaveFunction: function(e) { 
      e.setScale(1,1,1); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   leaveFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
overFunction function undefined a custom function that will run continually whenever the mouse is hovering over the entity. this function should be implemented to accept two arguments - the first is a reference to the entity that was clicked, and the second is an object that contains information about the interaction that just occured. example:
let b = AFrameP5.Box({
   overFunction: function(e, intersectionInfo) { 
      console.log(intersectionInfo);
   }
});
intersectionInfo is an object that contains info about how the user is interacting with this entity. it contains the following properties:
  • distance : a float describing how far away the user is
  • point3d : an object with three properties (x, y & z) describing where the user is touching the entity
  • point2d : an object with two properites (x & y) describing where the user is touching the entity in 2D space (useful for determining where on a dynamic canvas the user is touching)
  • uv : an object with two properies (x & y) describing the raw textural offset (used to compute point2d)
  • hand : (v2.4) which pointer is hovering: 'mouse', 'left' or 'right'. Each VR controller calls overFunction separately, so check this if only one hand should do something (for example, only paint with the right hand).
For an example please see the Interactive dynamic textures sample program.

as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   overFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
dragFunction function undefined (v2.4) a custom function that runs every frame while the user holds the mouse button (or a VR controller trigger) down after pressing on this entity and keeps pointing at it - for example, to draw on a dynamic texture. A drag that starts somewhere else and moves onto the entity doesn't count. While the mouse is dragging on the entity, it doesn't turn the camera, so the view stays still while you draw. It takes the same two arguments as overFunction (the entity and hit), plus two more properties in hit:
  • previousPoint2d : where the user was pointing on the dynamic texture on the previous frame (x and y, in pixels). It is null when a new drag starts, and again when the pointer comes back onto the entity during a drag, so you can draw a line from it to point2d without joining separate strokes.
  • previousPoint3d : the same thing in the world (x, y and z)
example:
let canvas = new AFrameP5.Plane({
   asset: texture, dynamicTexture: true, dynamicTextureWidth: 512, dynamicTextureHeight: 512,
   dragFunction: function(e, hit) {
      if (hit.previousPoint2d) {
         buffer.line(hit.previousPoint2d.x, hit.previousPoint2d.y, hit.point2d.x, hit.point2d.y);
      }
   }
});
Each VR controller drags separately, so check hit.hand if only one hand should draw.

In VR, clickFunction runs as soon as the trigger is pressed (setClickOnRelease only changes mouse clicks), so avoid giving one entity both a clickFunction and a dragFunction if that matters. To do something at the start of each drag (for example, stamp a dot), check for hit.previousPoint2d === null inside dragFunction instead.
tickFunction function undefined a custom function that will run once per frame (like draw does for the main sketch). this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   tickFunction: function(e) { 
      e.setRed( random(255) ); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   tickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
Constructor Parameters (specific to this class)

new AFrameP5.Tetrahedron(options)

OptionTypeDefaultDescription
radius number 1 radius of the entity (in meters)
Example
// sketch.js file

let world;
let tetrahedron;
			  		
function setup() {
   // no canvas needed
   noCanvas();
   
   // create a new VR World object
   world = new AFrameP5.World('VRScene');
   
   // construct a new Tetrahedron
   tetrahedron = new AFrameP5.Tetrahedron({
      x:0, 
      y:2, 
      z:0, 
      red:0, 
      green:255, 
      blue:0
   });
   
   // add the Tetrahedron to the world
   world.add(tetrahedron);
}
Methods (common to all entities)
MethodCategoryDescription
constrainPosition(xMin: number, xMax: number, yMin: number, yMax: number, zMin: number, zMax: number) Position ensures that the entity is constrained within the desired boundaries along all three axes. if an entity exceeds any of the constraints it is nudged back into position accordingly.
getX(): number Position returns the current x position of the entity. this is the entity's LOCAL position in relation to its container.
getY(): number Position returns the current y position of the entity. this is the entity's LOCAL position in relation to its container.
getZ(): number Position returns the current z position of the entity. this is the entity's LOCAL position in relation to its container.
nudge(x: number, y: number, z: number) Position nudges the element based on its current position. accepts three numeric values (i.e. myEntity.nudge(1,0,0); will nudge the entity 1 meter from its current position along the x-axis. this is the entity's LOCAL position in relation to its container.
setPosition(x: number, y: number, z: number) Position sets the position of the entity. this is the entity's LOCAL position in relation to its container.
setX(x: number) Position sets the x position of the entity. this is the entity's LOCAL position in relation to its container.
setY(y: number) Position sets the y position of the entity. this is the entity's LOCAL position in relation to its container.
setZ(z: number) Position sets the z position of the entity. this is the entity's LOCAL position in relation to its container.
getWorldPosition(): object Position returns the entity's WORLD position, not it's local position within its current container. this method is often used to compute the absolute position of an element in world space in order to deal with collisions of objects that may be nested inside of containers.
getRotationX(): number Rotation returns the current x rotation of the entity.
getRotationY(): number Rotation returns the current y rotation of the entity.
getRotationZ(): number Rotation returns the current z rotation of the entity.
rotateX(x: number) Rotation sets the x rotation of the entity
rotateY(y: number) Rotation sets the y rotation of the entity
rotateZ(z: number) Rotation sets the z rotation of the entity
setRotation(x: number, y: number, z: number) Rotation sets the rotation of the entity.
spinX(x: number) Rotation spins the entity along the x axis based on its current rotation. i.e. myEntity.spinX(1); // spin by 1 degree
spinY(y: number) Rotation spins the entity along the y axis based on its current rotation. i.e. myEntity.spinY(1); // spin by 1 degree
spinZ(z: number) Rotation spins the entity along the z axis based on its current rotation. i.e. myEntity.spinZ(1); // spin by 1 degree
lookAtUser(upright?: boolean) Rotation forces the entity to orient itself so that it is facing the user. (v2.4) lookAtUser(true) keeps the entity upright, so it only turns left and right - use this for billboards such as trees, which would otherwise tip over when the user walks up close.
getVisibility(): boolean Visibility returns the current visibility state of the entity
hide() Visibility hides the entity by setting its visible property to false
show() Visibility shows the entity by setting its visible property to true
toggleVisibility() Visibility hides the entity if it is current visible and shows the entity if it is current hidden
getScale(): object Scale returns the scale of the entity as an object (i.e. {x:0, y:0, z:0}
getScaleX(): number Scale returns the x scale of the entity
getScaleY(): number Scale returns the y scale of the entity
getScaleZ(): number Scale returns the z scale of the entity
setScale(x: number, y: number, z: number) Scale sets the scale of the object in all axes
setScaleX(x: number) Scale sets the x scale of the object
setScaleY(y: number) Scale sets the y scale of the object
setScaleZ(z: number) Scale sets the z scale of the object
getAsset(): string Material returns the current id of the asset being used to texture this entity
getBlue(): number Material returns the current blue color of the entity
getGreen(): number Material returns the current green color of the entity
getMetalness(): number Material returns the current metalness setting for the texture of the entity (range = 0.0 to 1.0)
getOpacity(): number Material returns the current opacity of the entity
getRed(): number Material returns the current red color of the entity
setRoughness(roughness: number) Material sets the roughness for the texture of the entity (range = 0.0 to 1.0)
getSide(): string Material returns which faces of the entity will be textured (valid values are front, back and double)
getTransparent(): boolean Material returns the current transparency of the entity
setAsset(asset: string) Material sets the id for the asset to texture this entity
setColor(red: number, green: number, blue: number) Material sets the color of the entity
setBlue(blue: number) Material sets the blue color of the entity
setGreen(green: number) Material sets the green color of the entity
setMetalness(metalness: number) Material sets the metalness for the texture of the entity (range = 0.0 to 1.0)
setOpacity(opacity: number) Material sets the opacity of the entity (range = 0.0 to 1.0)
setRed(red: number) Material sets the red color of the entity
getRoughness(): number Material returns the current roughness setting for the texture of the entity (range = 0.0 to 1.0)
setTransparent(transparent: boolean) Material sets whether the entity supports transparent textures
getAlphaTest(): number Material (v2.4) returns the entity's alphaTest value
setAlphaTest(alphaTest: number) Material (v2.4) sets the alphaTest value (see the alphaTest constructor option)
setSide(side: string) Material sets which faces of the entity will be textured (valid values are front, back and double)
getRepeatX(): number Material returns how many times the texture repeats across the entity horizontally
getRepeatY(): number Material (v2.4) returns how many times the texture repeats across the entity vertically
setRepeatX(times: number) Material sets how many times the texture repeats across the entity horizontally
setRepeatY(times: number) Material (v2.4) sets how many times the texture repeats across the entity vertically
getSolid(): boolean Physics (v2.4) returns whether the entity is solid
setSolid(solid: boolean) Physics (v2.4) makes the entity solid (true: it blocks the user and can be stood on) or not solid (false: the user can walk through it)
add(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity. alias for addChild.
addChild(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity.
getChildren(): Array Hierarchy returns an Array of all children of this entity
removeChild(entity: Entity) Hierarchy removes a child entity from this entity.
Methods (specific to this class)
MethodCategoryDescription
getRadius(): number Geometry returns the current radius of the entity
setRadius(radius: number) Geometry sets the radius of the entity
changeRadius(amount: number) Geometry updates the radius by the value provided (i.e. entity.changeRadius(0.1); will increase the radius by 0.1 meters.

Class: Torus (entity)

A torus is a surface of revolution generated by revolving a circle in three-dimensional space about an axis coplanar with the circle.

Constructor Parameters (common to all entities)

new AFrameP5.Torus(options)

OptionTypeDefaultDescription
x number 0 x-position of the entity
y number 0 y-position of the entity
z number 0 z-position of the entity
opacity number 1.0 how transparent this entity is (0.0 = fully transparent, 1.0 = fully opaque)
transparent boolean false whether the texture associated with this entity supports transparency (i.e. a PNG file with an alpha channel)
alphaTest number 0 (v2.4) pixels less opaque than this value (0.0 to 1.0) are not drawn at all. Use 0.5 for cut-out pictures such as trees (PNGs with see-through parts), otherwise the see-through parts can hide whatever is behind them. 0 turns it off.
shader string 'standard' the ThreeJS shader to use to render this entity - other valid value is flat
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
roughness number 0.5 how 'rough' the material appears. valid range = 0.0 to 1.0
metalness number 0 how 'metallic' the material appears. valid range = 0.0 to 1.0
red integer 255 how red the entity appears. valid range = 0 to 255
green integer 255 how green the entity appears. valid range = 0 to 255
blue integer 255 how blue the entity appears. valid range = 0 to 255
repeatX integer 1 how many times to repeat the texture associated with the entity along the x-axis of each face of the object. valid range = any positive number
repeatY integer 1 how many times to repeat the texture associated with the entity along the y-axis of each face of the object. valid range = any positive number
asset string 'None' the id (string) of the element that should be used as a texture for this entity. all textures should be set up in the 'index.html' file inside of the a-assets tag.
scaleX number 1.0 the scale of the object in the x-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleY number 1.0 the scale of the object in the y-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleZ number 1.0 the scale of the object in the z-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
rotationX number 0 the rotation of the object along the x-axis.
rotationY number 0 the rotation of the object along the y-axis.
rotationZ number 0 the rotation of the object along the z-axis.
visible boolean true determines whether the entity is visible in the scene.
solid boolean false (v2.4) solid entities block the user's movement and can be stood on when gravity is turned on (see world.setGravity and the physics example).
dynamicTexture boolean false sets whether the texture used on the entity is being drawn from a dynamically drawn canvas element. see these examples for more information: Dynamic textures, Multiple dynamic textures and Interactive dynamic textures
dynamicTextureHeight number 0 tells the entity the height of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
dynamicTextureWidth number 0 tells the entity the width of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
customData object undefined a custom object that can be used by the entity to keep track of user-specified data. example:
let b = new AFrameP5.Box({
   customData: {
      numClicks: 0
   },
   clickFunction: function(e) { 
      e.customData.numClicks++;
      console.log("This element has been clicked " + e.customData.numClicks + " times");
   }
});
clickFunction function undefined a custom function that will run every time the user clicks on the entity. this function receives a reference to the entity that was clicked, and (v2.4) a second argument with information about the click (see below). example:
let b = new AFrameP5.Box({
   clickFunction: function(e) { 
      e.setRed(random(255)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   clickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});


(v2.4) the second argument, often called hit, describes the click:
  • point3d : the exact point in the world where the click landed (an object with x, y and z)
  • distance : how far away that point is from the user, in meters
  • hand : what did the clicking: 'mouse' (the mouse, or the gaze cursor), 'left' or 'right' (the VR controllers)
  • uv : the raw texture coordinates of the click (x and y, from 0 to 1)
  • point2d : for entities that use a dynamic texture, where on the texture the click landed (x and y, in pixels)
  • voxel and voxelAdjacent : for voxel grids, the cube that was clicked and the empty space next to the face that was clicked
example:
let b = new AFrameP5.Box({
   clickFunction: function(e, hit) {
      console.log("clicked at " + hit.point3d.x + ", " + hit.point3d.y + ", " + hit.point3d.z + " with the " + hit.hand);
   }
});
see the click information example.
upFunction function undefined a custom function that will run every time the releases the mouse after the entity has been clicked. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   upFunction: function(e) { 
      e.spinX(random(360)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   upFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
enterFunction function undefined a custom function that will run every time the mouse hovers over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   enterFunction: function(e) { 
      e.setScale(2,2,2); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   enterFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
leaveFunction function undefined a custom function that will run every time the mouse stops hovering over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   leaveFunction: function(e) { 
      e.setScale(1,1,1); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   leaveFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
overFunction function undefined a custom function that will run continually whenever the mouse is hovering over the entity. this function should be implemented to accept two arguments - the first is a reference to the entity that was clicked, and the second is an object that contains information about the interaction that just occured. example:
let b = AFrameP5.Box({
   overFunction: function(e, intersectionInfo) { 
      console.log(intersectionInfo);
   }
});
intersectionInfo is an object that contains info about how the user is interacting with this entity. it contains the following properties:
  • distance : a float describing how far away the user is
  • point3d : an object with three properties (x, y & z) describing where the user is touching the entity
  • point2d : an object with two properites (x & y) describing where the user is touching the entity in 2D space (useful for determining where on a dynamic canvas the user is touching)
  • uv : an object with two properies (x & y) describing the raw textural offset (used to compute point2d)
  • hand : (v2.4) which pointer is hovering: 'mouse', 'left' or 'right'. Each VR controller calls overFunction separately, so check this if only one hand should do something (for example, only paint with the right hand).
For an example please see the Interactive dynamic textures sample program.

as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   overFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
dragFunction function undefined (v2.4) a custom function that runs every frame while the user holds the mouse button (or a VR controller trigger) down after pressing on this entity and keeps pointing at it - for example, to draw on a dynamic texture. A drag that starts somewhere else and moves onto the entity doesn't count. While the mouse is dragging on the entity, it doesn't turn the camera, so the view stays still while you draw. It takes the same two arguments as overFunction (the entity and hit), plus two more properties in hit:
  • previousPoint2d : where the user was pointing on the dynamic texture on the previous frame (x and y, in pixels). It is null when a new drag starts, and again when the pointer comes back onto the entity during a drag, so you can draw a line from it to point2d without joining separate strokes.
  • previousPoint3d : the same thing in the world (x, y and z)
example:
let canvas = new AFrameP5.Plane({
   asset: texture, dynamicTexture: true, dynamicTextureWidth: 512, dynamicTextureHeight: 512,
   dragFunction: function(e, hit) {
      if (hit.previousPoint2d) {
         buffer.line(hit.previousPoint2d.x, hit.previousPoint2d.y, hit.point2d.x, hit.point2d.y);
      }
   }
});
Each VR controller drags separately, so check hit.hand if only one hand should draw.

In VR, clickFunction runs as soon as the trigger is pressed (setClickOnRelease only changes mouse clicks), so avoid giving one entity both a clickFunction and a dragFunction if that matters. To do something at the start of each drag (for example, stamp a dot), check for hit.previousPoint2d === null inside dragFunction instead.
tickFunction function undefined a custom function that will run once per frame (like draw does for the main sketch). this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   tickFunction: function(e) { 
      e.setRed( random(255) ); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   tickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
Constructor Parameters (specific to this class)

new AFrameP5.Torus(options)

OptionTypeDefaultDescription
radius number 1 radius of the entity (in meters)
radiusTubular number 1 radius of the tubular portion of the entity (in meters)
segmentsRadial integer 36 number of segmented faces around the circumference of the torus.
segmentsTubular integer 18 number of segments along the circumference of the tube face. a higher number means the tube will be more round.
arc integer 360 central angle of the entity
Example
// sketch.js file

let world;
let torus;
			  		
function setup() {
   // no canvas needed
   noCanvas();
   
   // create a new VR World object
   world = new AFrameP5.World('VRScene');
   
   // construct a new Torus
   torus = new AFrameP5.Torus({
      x:0, 
      y:2, 
      z:0, 
      red:0, 
      green:255, 
      blue:0
   });
   
   // add the Torus to the world
   world.add(torus);
}
Methods (common to all entities)
MethodCategoryDescription
constrainPosition(xMin: number, xMax: number, yMin: number, yMax: number, zMin: number, zMax: number) Position ensures that the entity is constrained within the desired boundaries along all three axes. if an entity exceeds any of the constraints it is nudged back into position accordingly.
getX(): number Position returns the current x position of the entity. this is the entity's LOCAL position in relation to its container.
getY(): number Position returns the current y position of the entity. this is the entity's LOCAL position in relation to its container.
getZ(): number Position returns the current z position of the entity. this is the entity's LOCAL position in relation to its container.
nudge(x: number, y: number, z: number) Position nudges the element based on its current position. accepts three numeric values (i.e. myEntity.nudge(1,0,0); will nudge the entity 1 meter from its current position along the x-axis. this is the entity's LOCAL position in relation to its container.
setPosition(x: number, y: number, z: number) Position sets the position of the entity. this is the entity's LOCAL position in relation to its container.
setX(x: number) Position sets the x position of the entity. this is the entity's LOCAL position in relation to its container.
setY(y: number) Position sets the y position of the entity. this is the entity's LOCAL position in relation to its container.
setZ(z: number) Position sets the z position of the entity. this is the entity's LOCAL position in relation to its container.
getWorldPosition(): object Position returns the entity's WORLD position, not it's local position within its current container. this method is often used to compute the absolute position of an element in world space in order to deal with collisions of objects that may be nested inside of containers.
getRotationX(): number Rotation returns the current x rotation of the entity.
getRotationY(): number Rotation returns the current y rotation of the entity.
getRotationZ(): number Rotation returns the current z rotation of the entity.
rotateX(x: number) Rotation sets the x rotation of the entity
rotateY(y: number) Rotation sets the y rotation of the entity
rotateZ(z: number) Rotation sets the z rotation of the entity
setRotation(x: number, y: number, z: number) Rotation sets the rotation of the entity.
spinX(x: number) Rotation spins the entity along the x axis based on its current rotation. i.e. myEntity.spinX(1); // spin by 1 degree
spinY(y: number) Rotation spins the entity along the y axis based on its current rotation. i.e. myEntity.spinY(1); // spin by 1 degree
spinZ(z: number) Rotation spins the entity along the z axis based on its current rotation. i.e. myEntity.spinZ(1); // spin by 1 degree
lookAtUser(upright?: boolean) Rotation forces the entity to orient itself so that it is facing the user. (v2.4) lookAtUser(true) keeps the entity upright, so it only turns left and right - use this for billboards such as trees, which would otherwise tip over when the user walks up close.
getVisibility(): boolean Visibility returns the current visibility state of the entity
hide() Visibility hides the entity by setting its visible property to false
show() Visibility shows the entity by setting its visible property to true
toggleVisibility() Visibility hides the entity if it is current visible and shows the entity if it is current hidden
getScale(): object Scale returns the scale of the entity as an object (i.e. {x:0, y:0, z:0}
getScaleX(): number Scale returns the x scale of the entity
getScaleY(): number Scale returns the y scale of the entity
getScaleZ(): number Scale returns the z scale of the entity
setScale(x: number, y: number, z: number) Scale sets the scale of the object in all axes
setScaleX(x: number) Scale sets the x scale of the object
setScaleY(y: number) Scale sets the y scale of the object
setScaleZ(z: number) Scale sets the z scale of the object
getAsset(): string Material returns the current id of the asset being used to texture this entity
getBlue(): number Material returns the current blue color of the entity
getGreen(): number Material returns the current green color of the entity
getMetalness(): number Material returns the current metalness setting for the texture of the entity (range = 0.0 to 1.0)
getOpacity(): number Material returns the current opacity of the entity
getRed(): number Material returns the current red color of the entity
setRoughness(roughness: number) Material sets the roughness for the texture of the entity (range = 0.0 to 1.0)
getSide(): string Material returns which faces of the entity will be textured (valid values are front, back and double)
getTransparent(): boolean Material returns the current transparency of the entity
setAsset(asset: string) Material sets the id for the asset to texture this entity
setColor(red: number, green: number, blue: number) Material sets the color of the entity
setBlue(blue: number) Material sets the blue color of the entity
setGreen(green: number) Material sets the green color of the entity
setMetalness(metalness: number) Material sets the metalness for the texture of the entity (range = 0.0 to 1.0)
setOpacity(opacity: number) Material sets the opacity of the entity (range = 0.0 to 1.0)
setRed(red: number) Material sets the red color of the entity
getRoughness(): number Material returns the current roughness setting for the texture of the entity (range = 0.0 to 1.0)
setTransparent(transparent: boolean) Material sets whether the entity supports transparent textures
getAlphaTest(): number Material (v2.4) returns the entity's alphaTest value
setAlphaTest(alphaTest: number) Material (v2.4) sets the alphaTest value (see the alphaTest constructor option)
setSide(side: string) Material sets which faces of the entity will be textured (valid values are front, back and double)
getRepeatX(): number Material returns how many times the texture repeats across the entity horizontally
getRepeatY(): number Material (v2.4) returns how many times the texture repeats across the entity vertically
setRepeatX(times: number) Material sets how many times the texture repeats across the entity horizontally
setRepeatY(times: number) Material (v2.4) sets how many times the texture repeats across the entity vertically
getSolid(): boolean Physics (v2.4) returns whether the entity is solid
setSolid(solid: boolean) Physics (v2.4) makes the entity solid (true: it blocks the user and can be stood on) or not solid (false: the user can walk through it)
add(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity. alias for addChild.
addChild(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity.
getChildren(): Array Hierarchy returns an Array of all children of this entity
removeChild(entity: Entity) Hierarchy removes a child entity from this entity.
Methods (specific to this class)
MethodCategoryDescription
getRadius(): number Geometry returns the current radius of the entity
getRadiusTubular(): number Geometry returns the current radiusTubular of the entity
getSegmentsRadial(): number Geometry returns the current segmentsRadial value for the entity
getSegmentsTubular(): number Geometry returns the current segmentsTubular value for the entity
getArc(): number Geometry returns the current arc value for the entity
setRadius(radius: number) Geometry sets the radius value for the entity
changeRadius(amount: number) Geometry updates the radius by the value provided (i.e. entity.changeRadius(0.1); will increase the radius by 0.1 meters.
setRadiusTubular(radiusTubular: number) Geometry sets the radiusTublar value for the entity
setSegmentsRadial(segmentsRadial: number) Geometry sets the current segmentsRadial value for the entity
setSegmentsTubular(segmentsTubular: number) Geometry sets the current segmentsTubular value for the entity
setArc(arc: number) Geometry sets the current arc value for the entity

Class: TorusKnot (entity)

A torus three dimensional "pretzel" shape.

Constructor Parameters (common to all entities)

new AFrameP5.TorusKnot(options)

OptionTypeDefaultDescription
x number 0 x-position of the entity
y number 0 y-position of the entity
z number 0 z-position of the entity
opacity number 1.0 how transparent this entity is (0.0 = fully transparent, 1.0 = fully opaque)
transparent boolean false whether the texture associated with this entity supports transparency (i.e. a PNG file with an alpha channel)
alphaTest number 0 (v2.4) pixels less opaque than this value (0.0 to 1.0) are not drawn at all. Use 0.5 for cut-out pictures such as trees (PNGs with see-through parts), otherwise the see-through parts can hide whatever is behind them. 0 turns it off.
shader string 'standard' the ThreeJS shader to use to render this entity - other valid value is flat
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
roughness number 0.5 how 'rough' the material appears. valid range = 0.0 to 1.0
metalness number 0 how 'metallic' the material appears. valid range = 0.0 to 1.0
red integer 255 how red the entity appears. valid range = 0 to 255
green integer 255 how green the entity appears. valid range = 0 to 255
blue integer 255 how blue the entity appears. valid range = 0 to 255
repeatX integer 1 how many times to repeat the texture associated with the entity along the x-axis of each face of the object. valid range = any positive number
repeatY integer 1 how many times to repeat the texture associated with the entity along the y-axis of each face of the object. valid range = any positive number
asset string 'None' the id (string) of the element that should be used as a texture for this entity. all textures should be set up in the 'index.html' file inside of the a-assets tag.
scaleX number 1.0 the scale of the object in the x-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleY number 1.0 the scale of the object in the y-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleZ number 1.0 the scale of the object in the z-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
rotationX number 0 the rotation of the object along the x-axis.
rotationY number 0 the rotation of the object along the y-axis.
rotationZ number 0 the rotation of the object along the z-axis.
visible boolean true determines whether the entity is visible in the scene.
solid boolean false (v2.4) solid entities block the user's movement and can be stood on when gravity is turned on (see world.setGravity and the physics example).
dynamicTexture boolean false sets whether the texture used on the entity is being drawn from a dynamically drawn canvas element. see these examples for more information: Dynamic textures, Multiple dynamic textures and Interactive dynamic textures
dynamicTextureHeight number 0 tells the entity the height of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
dynamicTextureWidth number 0 tells the entity the width of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
customData object undefined a custom object that can be used by the entity to keep track of user-specified data. example:
let b = new AFrameP5.Box({
   customData: {
      numClicks: 0
   },
   clickFunction: function(e) { 
      e.customData.numClicks++;
      console.log("This element has been clicked " + e.customData.numClicks + " times");
   }
});
clickFunction function undefined a custom function that will run every time the user clicks on the entity. this function receives a reference to the entity that was clicked, and (v2.4) a second argument with information about the click (see below). example:
let b = new AFrameP5.Box({
   clickFunction: function(e) { 
      e.setRed(random(255)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   clickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});


(v2.4) the second argument, often called hit, describes the click:
  • point3d : the exact point in the world where the click landed (an object with x, y and z)
  • distance : how far away that point is from the user, in meters
  • hand : what did the clicking: 'mouse' (the mouse, or the gaze cursor), 'left' or 'right' (the VR controllers)
  • uv : the raw texture coordinates of the click (x and y, from 0 to 1)
  • point2d : for entities that use a dynamic texture, where on the texture the click landed (x and y, in pixels)
  • voxel and voxelAdjacent : for voxel grids, the cube that was clicked and the empty space next to the face that was clicked
example:
let b = new AFrameP5.Box({
   clickFunction: function(e, hit) {
      console.log("clicked at " + hit.point3d.x + ", " + hit.point3d.y + ", " + hit.point3d.z + " with the " + hit.hand);
   }
});
see the click information example.
upFunction function undefined a custom function that will run every time the releases the mouse after the entity has been clicked. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   upFunction: function(e) { 
      e.spinX(random(360)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   upFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
enterFunction function undefined a custom function that will run every time the mouse hovers over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   enterFunction: function(e) { 
      e.setScale(2,2,2); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   enterFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
leaveFunction function undefined a custom function that will run every time the mouse stops hovering over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   leaveFunction: function(e) { 
      e.setScale(1,1,1); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   leaveFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
overFunction function undefined a custom function that will run continually whenever the mouse is hovering over the entity. this function should be implemented to accept two arguments - the first is a reference to the entity that was clicked, and the second is an object that contains information about the interaction that just occured. example:
let b = AFrameP5.Box({
   overFunction: function(e, intersectionInfo) { 
      console.log(intersectionInfo);
   }
});
intersectionInfo is an object that contains info about how the user is interacting with this entity. it contains the following properties:
  • distance : a float describing how far away the user is
  • point3d : an object with three properties (x, y & z) describing where the user is touching the entity
  • point2d : an object with two properites (x & y) describing where the user is touching the entity in 2D space (useful for determining where on a dynamic canvas the user is touching)
  • uv : an object with two properies (x & y) describing the raw textural offset (used to compute point2d)
  • hand : (v2.4) which pointer is hovering: 'mouse', 'left' or 'right'. Each VR controller calls overFunction separately, so check this if only one hand should do something (for example, only paint with the right hand).
For an example please see the Interactive dynamic textures sample program.

as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   overFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
dragFunction function undefined (v2.4) a custom function that runs every frame while the user holds the mouse button (or a VR controller trigger) down after pressing on this entity and keeps pointing at it - for example, to draw on a dynamic texture. A drag that starts somewhere else and moves onto the entity doesn't count. While the mouse is dragging on the entity, it doesn't turn the camera, so the view stays still while you draw. It takes the same two arguments as overFunction (the entity and hit), plus two more properties in hit:
  • previousPoint2d : where the user was pointing on the dynamic texture on the previous frame (x and y, in pixels). It is null when a new drag starts, and again when the pointer comes back onto the entity during a drag, so you can draw a line from it to point2d without joining separate strokes.
  • previousPoint3d : the same thing in the world (x, y and z)
example:
let canvas = new AFrameP5.Plane({
   asset: texture, dynamicTexture: true, dynamicTextureWidth: 512, dynamicTextureHeight: 512,
   dragFunction: function(e, hit) {
      if (hit.previousPoint2d) {
         buffer.line(hit.previousPoint2d.x, hit.previousPoint2d.y, hit.point2d.x, hit.point2d.y);
      }
   }
});
Each VR controller drags separately, so check hit.hand if only one hand should draw.

In VR, clickFunction runs as soon as the trigger is pressed (setClickOnRelease only changes mouse clicks), so avoid giving one entity both a clickFunction and a dragFunction if that matters. To do something at the start of each drag (for example, stamp a dot), check for hit.previousPoint2d === null inside dragFunction instead.
tickFunction function undefined a custom function that will run once per frame (like draw does for the main sketch). this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   tickFunction: function(e) { 
      e.setRed( random(255) ); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   tickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
Constructor Parameters (specific to this class)

new AFrameP5.TorusKnot(options)

OptionTypeDefaultDescription
radius number 1 radius of the entity (in meters)
radiusTubular number 1 radius of the tubular portion of the entity (in meters)
segmentsRadial integer 36 number of segmented faces around the circumference of the torus.
segmentsTubular integer 18 number of segments along the circumference of the tube face. a higher number means the tube will be more round.
p integer 2 a number that helps define the pretzel shape. the particular shape of the pretzel is defined by a pair of coprime integers, p and q. If p and q are not coprime the result will be a torus link.
q integer 3 a number that helps define the pretzel shape. the particular shape of the pretzel is defined by a pair of coprime integers, p and q. If p and q are not coprime the result will be a torus link.
Example
// sketch.js file

let world;
let torusKnot;
			  		
function setup() {
   // no canvas needed
   noCanvas();
   
   // create a new VR World object
   world = new AFrameP5.World('VRScene');
   
   // construct a new TorusKnot
   torusKnot = new AFrameP5.TorusKnot({
      x:0, 
      y:2, 
      z:0, 
      red:0, 
      green:255, 
      blue:0
   });
   
   // add the TorusKnot to the world
   world.add(torusKnot);
}
Methods (common to all entities)
MethodCategoryDescription
constrainPosition(xMin: number, xMax: number, yMin: number, yMax: number, zMin: number, zMax: number) Position ensures that the entity is constrained within the desired boundaries along all three axes. if an entity exceeds any of the constraints it is nudged back into position accordingly.
getX(): number Position returns the current x position of the entity. this is the entity's LOCAL position in relation to its container.
getY(): number Position returns the current y position of the entity. this is the entity's LOCAL position in relation to its container.
getZ(): number Position returns the current z position of the entity. this is the entity's LOCAL position in relation to its container.
nudge(x: number, y: number, z: number) Position nudges the element based on its current position. accepts three numeric values (i.e. myEntity.nudge(1,0,0); will nudge the entity 1 meter from its current position along the x-axis. this is the entity's LOCAL position in relation to its container.
setPosition(x: number, y: number, z: number) Position sets the position of the entity. this is the entity's LOCAL position in relation to its container.
setX(x: number) Position sets the x position of the entity. this is the entity's LOCAL position in relation to its container.
setY(y: number) Position sets the y position of the entity. this is the entity's LOCAL position in relation to its container.
setZ(z: number) Position sets the z position of the entity. this is the entity's LOCAL position in relation to its container.
getWorldPosition(): object Position returns the entity's WORLD position, not it's local position within its current container. this method is often used to compute the absolute position of an element in world space in order to deal with collisions of objects that may be nested inside of containers.
getRotationX(): number Rotation returns the current x rotation of the entity.
getRotationY(): number Rotation returns the current y rotation of the entity.
getRotationZ(): number Rotation returns the current z rotation of the entity.
rotateX(x: number) Rotation sets the x rotation of the entity
rotateY(y: number) Rotation sets the y rotation of the entity
rotateZ(z: number) Rotation sets the z rotation of the entity
setRotation(x: number, y: number, z: number) Rotation sets the rotation of the entity.
spinX(x: number) Rotation spins the entity along the x axis based on its current rotation. i.e. myEntity.spinX(1); // spin by 1 degree
spinY(y: number) Rotation spins the entity along the y axis based on its current rotation. i.e. myEntity.spinY(1); // spin by 1 degree
spinZ(z: number) Rotation spins the entity along the z axis based on its current rotation. i.e. myEntity.spinZ(1); // spin by 1 degree
lookAtUser(upright?: boolean) Rotation forces the entity to orient itself so that it is facing the user. (v2.4) lookAtUser(true) keeps the entity upright, so it only turns left and right - use this for billboards such as trees, which would otherwise tip over when the user walks up close.
getVisibility(): boolean Visibility returns the current visibility state of the entity
hide() Visibility hides the entity by setting its visible property to false
show() Visibility shows the entity by setting its visible property to true
toggleVisibility() Visibility hides the entity if it is current visible and shows the entity if it is current hidden
getScale(): object Scale returns the scale of the entity as an object (i.e. {x:0, y:0, z:0}
getScaleX(): number Scale returns the x scale of the entity
getScaleY(): number Scale returns the y scale of the entity
getScaleZ(): number Scale returns the z scale of the entity
setScale(x: number, y: number, z: number) Scale sets the scale of the object in all axes
setScaleX(x: number) Scale sets the x scale of the object
setScaleY(y: number) Scale sets the y scale of the object
setScaleZ(z: number) Scale sets the z scale of the object
getAsset(): string Material returns the current id of the asset being used to texture this entity
getBlue(): number Material returns the current blue color of the entity
getGreen(): number Material returns the current green color of the entity
getMetalness(): number Material returns the current metalness setting for the texture of the entity (range = 0.0 to 1.0)
getOpacity(): number Material returns the current opacity of the entity
getRed(): number Material returns the current red color of the entity
setRoughness(roughness: number) Material sets the roughness for the texture of the entity (range = 0.0 to 1.0)
getSide(): string Material returns which faces of the entity will be textured (valid values are front, back and double)
getTransparent(): boolean Material returns the current transparency of the entity
setAsset(asset: string) Material sets the id for the asset to texture this entity
setColor(red: number, green: number, blue: number) Material sets the color of the entity
setBlue(blue: number) Material sets the blue color of the entity
setGreen(green: number) Material sets the green color of the entity
setMetalness(metalness: number) Material sets the metalness for the texture of the entity (range = 0.0 to 1.0)
setOpacity(opacity: number) Material sets the opacity of the entity (range = 0.0 to 1.0)
setRed(red: number) Material sets the red color of the entity
getRoughness(): number Material returns the current roughness setting for the texture of the entity (range = 0.0 to 1.0)
setTransparent(transparent: boolean) Material sets whether the entity supports transparent textures
getAlphaTest(): number Material (v2.4) returns the entity's alphaTest value
setAlphaTest(alphaTest: number) Material (v2.4) sets the alphaTest value (see the alphaTest constructor option)
setSide(side: string) Material sets which faces of the entity will be textured (valid values are front, back and double)
getRepeatX(): number Material returns how many times the texture repeats across the entity horizontally
getRepeatY(): number Material (v2.4) returns how many times the texture repeats across the entity vertically
setRepeatX(times: number) Material sets how many times the texture repeats across the entity horizontally
setRepeatY(times: number) Material (v2.4) sets how many times the texture repeats across the entity vertically
getSolid(): boolean Physics (v2.4) returns whether the entity is solid
setSolid(solid: boolean) Physics (v2.4) makes the entity solid (true: it blocks the user and can be stood on) or not solid (false: the user can walk through it)
add(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity. alias for addChild.
addChild(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity.
getChildren(): Array Hierarchy returns an Array of all children of this entity
removeChild(entity: Entity) Hierarchy removes a child entity from this entity.
Methods (specific to this class)
MethodCategoryDescription
getRadius(): number Geometry returns the current radius of the entity
getRadiusTubular(): number Geometry returns the current radiusTubular of the entity
getSegmentsRadial(): number Geometry returns the current segmentsRadial value for the entity
getSegmentsTubular(): number Geometry returns the current segmentsTubular value for the entity
getP(): number Geometry returns the current p value for the entity
getQ(): number Geometry returns the current q value for the entity
setRadius(radius: number) Geometry sets the radius value for the entity
changeRadius(amount: number) Geometry updates the radius by the value provided (i.e. entity.changeRadius(0.1); will increase the radius by 0.1 meters.
setRadiusTubular(radiusTubular: number) Geometry sets the radiusTublar value for the entity
setSegmentsRadial(segmentsRadial: number) Geometry sets the current segmentsRadial value for the entity
setSegmentsTubular(segmentsTubular: number) Geometry sets the current segmentsTubular value for the entity
setP(p: number) Geometry sets the current p value for the entity
setQ(q: number) Geometry sets the current q value for the entity

Class: Container3D (entity)

An empty "container" that can be used to hold other entities. Has no visual representation of its own.

(v2.4) A container can have the same interaction functions as any other entity (clickFunction, upFunction, enterFunction, leaveFunction, overFunction, dragFunction and tickFunction). Since the container has no shape of its own, pointing at or clicking on any entity inside it counts as pointing at the container, and hit describes the spot on the entity that was hit. Moving the pointer from one entity to another inside the same container does not run leaveFunction and enterFunction. If an entity inside the container has its own interaction function as well, both run: the entity's first, then the container's. See the container interaction example.

Constructor Parameters (common to all entities)

new AFrameP5.Container3D(options)

OptionTypeDefaultDescription
x number 0 x-position of the entity
y number 0 y-position of the entity
z number 0 z-position of the entity
opacity number 1.0 how transparent this entity is (0.0 = fully transparent, 1.0 = fully opaque)
transparent boolean false whether the texture associated with this entity supports transparency (i.e. a PNG file with an alpha channel)
alphaTest number 0 (v2.4) pixels less opaque than this value (0.0 to 1.0) are not drawn at all. Use 0.5 for cut-out pictures such as trees (PNGs with see-through parts), otherwise the see-through parts can hide whatever is behind them. 0 turns it off.
shader string 'standard' the ThreeJS shader to use to render this entity - other valid value is flat
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
roughness number 0.5 how 'rough' the material appears. valid range = 0.0 to 1.0
metalness number 0 how 'metallic' the material appears. valid range = 0.0 to 1.0
red integer 255 how red the entity appears. valid range = 0 to 255
green integer 255 how green the entity appears. valid range = 0 to 255
blue integer 255 how blue the entity appears. valid range = 0 to 255
repeatX integer 1 how many times to repeat the texture associated with the entity along the x-axis of each face of the object. valid range = any positive number
repeatY integer 1 how many times to repeat the texture associated with the entity along the y-axis of each face of the object. valid range = any positive number
asset string 'None' the id (string) of the element that should be used as a texture for this entity. all textures should be set up in the 'index.html' file inside of the a-assets tag.
scaleX number 1.0 the scale of the object in the x-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleY number 1.0 the scale of the object in the y-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleZ number 1.0 the scale of the object in the z-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
rotationX number 0 the rotation of the object along the x-axis.
rotationY number 0 the rotation of the object along the y-axis.
rotationZ number 0 the rotation of the object along the z-axis.
visible boolean true determines whether the entity is visible in the scene.
solid boolean false (v2.4) solid entities block the user's movement and can be stood on when gravity is turned on (see world.setGravity and the physics example).
dynamicTexture boolean false sets whether the texture used on the entity is being drawn from a dynamically drawn canvas element. see these examples for more information: Dynamic textures, Multiple dynamic textures and Interactive dynamic textures
dynamicTextureHeight number 0 tells the entity the height of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
dynamicTextureWidth number 0 tells the entity the width of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
customData object undefined a custom object that can be used by the entity to keep track of user-specified data. example:
let b = new AFrameP5.Box({
   customData: {
      numClicks: 0
   },
   clickFunction: function(e) { 
      e.customData.numClicks++;
      console.log("This element has been clicked " + e.customData.numClicks + " times");
   }
});
clickFunction function undefined a custom function that will run every time the user clicks on the entity. this function receives a reference to the entity that was clicked, and (v2.4) a second argument with information about the click (see below). example:
let b = new AFrameP5.Box({
   clickFunction: function(e) { 
      e.setRed(random(255)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   clickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});


(v2.4) the second argument, often called hit, describes the click:
  • point3d : the exact point in the world where the click landed (an object with x, y and z)
  • distance : how far away that point is from the user, in meters
  • hand : what did the clicking: 'mouse' (the mouse, or the gaze cursor), 'left' or 'right' (the VR controllers)
  • uv : the raw texture coordinates of the click (x and y, from 0 to 1)
  • point2d : for entities that use a dynamic texture, where on the texture the click landed (x and y, in pixels)
  • voxel and voxelAdjacent : for voxel grids, the cube that was clicked and the empty space next to the face that was clicked
example:
let b = new AFrameP5.Box({
   clickFunction: function(e, hit) {
      console.log("clicked at " + hit.point3d.x + ", " + hit.point3d.y + ", " + hit.point3d.z + " with the " + hit.hand);
   }
});
see the click information example.
upFunction function undefined a custom function that will run every time the releases the mouse after the entity has been clicked. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   upFunction: function(e) { 
      e.spinX(random(360)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   upFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
enterFunction function undefined a custom function that will run every time the mouse hovers over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   enterFunction: function(e) { 
      e.setScale(2,2,2); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   enterFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
leaveFunction function undefined a custom function that will run every time the mouse stops hovering over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   leaveFunction: function(e) { 
      e.setScale(1,1,1); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   leaveFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
overFunction function undefined a custom function that will run continually whenever the mouse is hovering over the entity. this function should be implemented to accept two arguments - the first is a reference to the entity that was clicked, and the second is an object that contains information about the interaction that just occured. example:
let b = AFrameP5.Box({
   overFunction: function(e, intersectionInfo) { 
      console.log(intersectionInfo);
   }
});
intersectionInfo is an object that contains info about how the user is interacting with this entity. it contains the following properties:
  • distance : a float describing how far away the user is
  • point3d : an object with three properties (x, y & z) describing where the user is touching the entity
  • point2d : an object with two properites (x & y) describing where the user is touching the entity in 2D space (useful for determining where on a dynamic canvas the user is touching)
  • uv : an object with two properies (x & y) describing the raw textural offset (used to compute point2d)
  • hand : (v2.4) which pointer is hovering: 'mouse', 'left' or 'right'. Each VR controller calls overFunction separately, so check this if only one hand should do something (for example, only paint with the right hand).
For an example please see the Interactive dynamic textures sample program.

as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   overFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
dragFunction function undefined (v2.4) a custom function that runs every frame while the user holds the mouse button (or a VR controller trigger) down after pressing on this entity and keeps pointing at it - for example, to draw on a dynamic texture. A drag that starts somewhere else and moves onto the entity doesn't count. While the mouse is dragging on the entity, it doesn't turn the camera, so the view stays still while you draw. It takes the same two arguments as overFunction (the entity and hit), plus two more properties in hit:
  • previousPoint2d : where the user was pointing on the dynamic texture on the previous frame (x and y, in pixels). It is null when a new drag starts, and again when the pointer comes back onto the entity during a drag, so you can draw a line from it to point2d without joining separate strokes.
  • previousPoint3d : the same thing in the world (x, y and z)
example:
let canvas = new AFrameP5.Plane({
   asset: texture, dynamicTexture: true, dynamicTextureWidth: 512, dynamicTextureHeight: 512,
   dragFunction: function(e, hit) {
      if (hit.previousPoint2d) {
         buffer.line(hit.previousPoint2d.x, hit.previousPoint2d.y, hit.point2d.x, hit.point2d.y);
      }
   }
});
Each VR controller drags separately, so check hit.hand if only one hand should draw.

In VR, clickFunction runs as soon as the trigger is pressed (setClickOnRelease only changes mouse clicks), so avoid giving one entity both a clickFunction and a dragFunction if that matters. To do something at the start of each drag (for example, stamp a dot), check for hit.previousPoint2d === null inside dragFunction instead.
tickFunction function undefined a custom function that will run once per frame (like draw does for the main sketch). this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   tickFunction: function(e) { 
      e.setRed( random(255) ); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   tickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
Constructor Parameters (specific to this class)

new AFrameP5.Container3D(options)

No entity-specific constructor parameters

Example
// sketch.js file

let world;
let container;
			  		
function setup() {
   // no canvas needed
   noCanvas();
   
   // create a new VR World object
   world = new AFrameP5.World('VRScene');
   
   // construct a new Container
   container = new AFrameP5.Container3D({
      x:0, 
      y:2, 
      z:0
   });
   
   // add two boxes to the container
   let b1 = new AFrameP5.Box({x:-2, red:255, green:0, blue:0});
   let b2 = new AFrameP5.Box({x:2, red:0, green:0, blue:255});
   container.addChild(b1);
   container.addChild(b2);
   
   // add the Container to the world
   world.add(container);
}

// slowly rotate the container
function draw() {
   container.spinY(1);
}
Methods (common to all entities)
MethodCategoryDescription
constrainPosition(xMin: number, xMax: number, yMin: number, yMax: number, zMin: number, zMax: number) Position ensures that the entity is constrained within the desired boundaries along all three axes. if an entity exceeds any of the constraints it is nudged back into position accordingly.
getX(): number Position returns the current x position of the entity. this is the entity's LOCAL position in relation to its container.
getY(): number Position returns the current y position of the entity. this is the entity's LOCAL position in relation to its container.
getZ(): number Position returns the current z position of the entity. this is the entity's LOCAL position in relation to its container.
nudge(x: number, y: number, z: number) Position nudges the element based on its current position. accepts three numeric values (i.e. myEntity.nudge(1,0,0); will nudge the entity 1 meter from its current position along the x-axis. this is the entity's LOCAL position in relation to its container.
setPosition(x: number, y: number, z: number) Position sets the position of the entity. this is the entity's LOCAL position in relation to its container.
setX(x: number) Position sets the x position of the entity. this is the entity's LOCAL position in relation to its container.
setY(y: number) Position sets the y position of the entity. this is the entity's LOCAL position in relation to its container.
setZ(z: number) Position sets the z position of the entity. this is the entity's LOCAL position in relation to its container.
getWorldPosition(): object Position returns the entity's WORLD position, not it's local position within its current container. this method is often used to compute the absolute position of an element in world space in order to deal with collisions of objects that may be nested inside of containers.
getRotationX(): number Rotation returns the current x rotation of the entity.
getRotationY(): number Rotation returns the current y rotation of the entity.
getRotationZ(): number Rotation returns the current z rotation of the entity.
rotateX(x: number) Rotation sets the x rotation of the entity
rotateY(y: number) Rotation sets the y rotation of the entity
rotateZ(z: number) Rotation sets the z rotation of the entity
setRotation(x: number, y: number, z: number) Rotation sets the rotation of the entity.
spinX(x: number) Rotation spins the entity along the x axis based on its current rotation. i.e. myEntity.spinX(1); // spin by 1 degree
spinY(y: number) Rotation spins the entity along the y axis based on its current rotation. i.e. myEntity.spinY(1); // spin by 1 degree
spinZ(z: number) Rotation spins the entity along the z axis based on its current rotation. i.e. myEntity.spinZ(1); // spin by 1 degree
lookAtUser(upright?: boolean) Rotation forces the entity to orient itself so that it is facing the user. (v2.4) lookAtUser(true) keeps the entity upright, so it only turns left and right - use this for billboards such as trees, which would otherwise tip over when the user walks up close.
getVisibility(): boolean Visibility returns the current visibility state of the entity
hide() Visibility hides the entity by setting its visible property to false
show() Visibility shows the entity by setting its visible property to true
toggleVisibility() Visibility hides the entity if it is current visible and shows the entity if it is current hidden
getScale(): object Scale returns the scale of the entity as an object (i.e. {x:0, y:0, z:0}
getScaleX(): number Scale returns the x scale of the entity
getScaleY(): number Scale returns the y scale of the entity
getScaleZ(): number Scale returns the z scale of the entity
setScale(x: number, y: number, z: number) Scale sets the scale of the object in all axes
setScaleX(x: number) Scale sets the x scale of the object
setScaleY(y: number) Scale sets the y scale of the object
setScaleZ(z: number) Scale sets the z scale of the object
getAsset(): string Material returns the current id of the asset being used to texture this entity
getBlue(): number Material returns the current blue color of the entity
getGreen(): number Material returns the current green color of the entity
getMetalness(): number Material returns the current metalness setting for the texture of the entity (range = 0.0 to 1.0)
getOpacity(): number Material returns the current opacity of the entity
getRed(): number Material returns the current red color of the entity
setRoughness(roughness: number) Material sets the roughness for the texture of the entity (range = 0.0 to 1.0)
getSide(): string Material returns which faces of the entity will be textured (valid values are front, back and double)
getTransparent(): boolean Material returns the current transparency of the entity
setAsset(asset: string) Material sets the id for the asset to texture this entity
setColor(red: number, green: number, blue: number) Material sets the color of the entity
setBlue(blue: number) Material sets the blue color of the entity
setGreen(green: number) Material sets the green color of the entity
setMetalness(metalness: number) Material sets the metalness for the texture of the entity (range = 0.0 to 1.0)
setOpacity(opacity: number) Material sets the opacity of the entity (range = 0.0 to 1.0)
setRed(red: number) Material sets the red color of the entity
getRoughness(): number Material returns the current roughness setting for the texture of the entity (range = 0.0 to 1.0)
setTransparent(transparent: boolean) Material sets whether the entity supports transparent textures
getAlphaTest(): number Material (v2.4) returns the entity's alphaTest value
setAlphaTest(alphaTest: number) Material (v2.4) sets the alphaTest value (see the alphaTest constructor option)
setSide(side: string) Material sets which faces of the entity will be textured (valid values are front, back and double)
getRepeatX(): number Material returns how many times the texture repeats across the entity horizontally
getRepeatY(): number Material (v2.4) returns how many times the texture repeats across the entity vertically
setRepeatX(times: number) Material sets how many times the texture repeats across the entity horizontally
setRepeatY(times: number) Material (v2.4) sets how many times the texture repeats across the entity vertically
getSolid(): boolean Physics (v2.4) returns whether the entity is solid
setSolid(solid: boolean) Physics (v2.4) makes the entity solid (true: it blocks the user and can be stood on) or not solid (false: the user can walk through it)
add(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity. alias for addChild.
addChild(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity.
getChildren(): Array Hierarchy returns an Array of all children of this entity
removeChild(entity: Entity) Hierarchy removes a child entity from this entity.
Methods (specific to this class)

No entity-specific methods


Class: OBJ (entity)

A Wavefront 3D model (.OBJ file format)

Constructor Parameters (common to all entities)

new AFrameP5.OBJ(options)

OptionTypeDefaultDescription
x number 0 x-position of the entity
y number 0 y-position of the entity
z number 0 z-position of the entity
opacity number 1.0 how transparent this entity is (0.0 = fully transparent, 1.0 = fully opaque)
transparent boolean false whether the texture associated with this entity supports transparency (i.e. a PNG file with an alpha channel)
alphaTest number 0 (v2.4) pixels less opaque than this value (0.0 to 1.0) are not drawn at all. Use 0.5 for cut-out pictures such as trees (PNGs with see-through parts), otherwise the see-through parts can hide whatever is behind them. 0 turns it off.
shader string 'standard' the ThreeJS shader to use to render this entity - other valid value is flat
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
roughness number 0.5 how 'rough' the material appears. valid range = 0.0 to 1.0
metalness number 0 how 'metallic' the material appears. valid range = 0.0 to 1.0
red integer 255 how red the entity appears. valid range = 0 to 255
green integer 255 how green the entity appears. valid range = 0 to 255
blue integer 255 how blue the entity appears. valid range = 0 to 255
repeatX integer 1 how many times to repeat the texture associated with the entity along the x-axis of each face of the object. valid range = any positive number
repeatY integer 1 how many times to repeat the texture associated with the entity along the y-axis of each face of the object. valid range = any positive number
asset string 'None' the id (string) of the element that should be used as a texture for this entity. all textures should be set up in the 'index.html' file inside of the a-assets tag.
scaleX number 1.0 the scale of the object in the x-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleY number 1.0 the scale of the object in the y-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleZ number 1.0 the scale of the object in the z-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
rotationX number 0 the rotation of the object along the x-axis.
rotationY number 0 the rotation of the object along the y-axis.
rotationZ number 0 the rotation of the object along the z-axis.
visible boolean true determines whether the entity is visible in the scene.
solid boolean false (v2.4) solid entities block the user's movement and can be stood on when gravity is turned on (see world.setGravity and the physics example).
dynamicTexture boolean false sets whether the texture used on the entity is being drawn from a dynamically drawn canvas element. see these examples for more information: Dynamic textures, Multiple dynamic textures and Interactive dynamic textures
dynamicTextureHeight number 0 tells the entity the height of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
dynamicTextureWidth number 0 tells the entity the width of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
customData object undefined a custom object that can be used by the entity to keep track of user-specified data. example:
let b = new AFrameP5.Box({
   customData: {
      numClicks: 0
   },
   clickFunction: function(e) { 
      e.customData.numClicks++;
      console.log("This element has been clicked " + e.customData.numClicks + " times");
   }
});
clickFunction function undefined a custom function that will run every time the user clicks on the entity. this function receives a reference to the entity that was clicked, and (v2.4) a second argument with information about the click (see below). example:
let b = new AFrameP5.Box({
   clickFunction: function(e) { 
      e.setRed(random(255)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   clickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});


(v2.4) the second argument, often called hit, describes the click:
  • point3d : the exact point in the world where the click landed (an object with x, y and z)
  • distance : how far away that point is from the user, in meters
  • hand : what did the clicking: 'mouse' (the mouse, or the gaze cursor), 'left' or 'right' (the VR controllers)
  • uv : the raw texture coordinates of the click (x and y, from 0 to 1)
  • point2d : for entities that use a dynamic texture, where on the texture the click landed (x and y, in pixels)
  • voxel and voxelAdjacent : for voxel grids, the cube that was clicked and the empty space next to the face that was clicked
example:
let b = new AFrameP5.Box({
   clickFunction: function(e, hit) {
      console.log("clicked at " + hit.point3d.x + ", " + hit.point3d.y + ", " + hit.point3d.z + " with the " + hit.hand);
   }
});
see the click information example.
upFunction function undefined a custom function that will run every time the releases the mouse after the entity has been clicked. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   upFunction: function(e) { 
      e.spinX(random(360)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   upFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
enterFunction function undefined a custom function that will run every time the mouse hovers over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   enterFunction: function(e) { 
      e.setScale(2,2,2); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   enterFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
leaveFunction function undefined a custom function that will run every time the mouse stops hovering over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   leaveFunction: function(e) { 
      e.setScale(1,1,1); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   leaveFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
overFunction function undefined a custom function that will run continually whenever the mouse is hovering over the entity. this function should be implemented to accept two arguments - the first is a reference to the entity that was clicked, and the second is an object that contains information about the interaction that just occured. example:
let b = AFrameP5.Box({
   overFunction: function(e, intersectionInfo) { 
      console.log(intersectionInfo);
   }
});
intersectionInfo is an object that contains info about how the user is interacting with this entity. it contains the following properties:
  • distance : a float describing how far away the user is
  • point3d : an object with three properties (x, y & z) describing where the user is touching the entity
  • point2d : an object with two properites (x & y) describing where the user is touching the entity in 2D space (useful for determining where on a dynamic canvas the user is touching)
  • uv : an object with two properies (x & y) describing the raw textural offset (used to compute point2d)
  • hand : (v2.4) which pointer is hovering: 'mouse', 'left' or 'right'. Each VR controller calls overFunction separately, so check this if only one hand should do something (for example, only paint with the right hand).
For an example please see the Interactive dynamic textures sample program.

as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   overFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
dragFunction function undefined (v2.4) a custom function that runs every frame while the user holds the mouse button (or a VR controller trigger) down after pressing on this entity and keeps pointing at it - for example, to draw on a dynamic texture. A drag that starts somewhere else and moves onto the entity doesn't count. While the mouse is dragging on the entity, it doesn't turn the camera, so the view stays still while you draw. It takes the same two arguments as overFunction (the entity and hit), plus two more properties in hit:
  • previousPoint2d : where the user was pointing on the dynamic texture on the previous frame (x and y, in pixels). It is null when a new drag starts, and again when the pointer comes back onto the entity during a drag, so you can draw a line from it to point2d without joining separate strokes.
  • previousPoint3d : the same thing in the world (x, y and z)
example:
let canvas = new AFrameP5.Plane({
   asset: texture, dynamicTexture: true, dynamicTextureWidth: 512, dynamicTextureHeight: 512,
   dragFunction: function(e, hit) {
      if (hit.previousPoint2d) {
         buffer.line(hit.previousPoint2d.x, hit.previousPoint2d.y, hit.point2d.x, hit.point2d.y);
      }
   }
});
Each VR controller drags separately, so check hit.hand if only one hand should draw.

In VR, clickFunction runs as soon as the trigger is pressed (setClickOnRelease only changes mouse clicks), so avoid giving one entity both a clickFunction and a dragFunction if that matters. To do something at the start of each drag (for example, stamp a dot), check for hit.previousPoint2d === null inside dragFunction instead.
tickFunction function undefined a custom function that will run once per frame (like draw does for the main sketch). this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   tickFunction: function(e) { 
      e.setRed( random(255) ); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   tickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
Constructor Parameters (specific to this class)

new AFrameP5.OBJ(options)

OptionTypeDefaultDescription
asset string undefined the id of the element in your HTML file that points to the OBJ file you wish to load. this element must be a a-asset-item tag included under the a-assets tag. see the example program below for more information.
mtl string undefined the id of the material file that should be used to texture the OBJ geometry file. this element must be a a-asset-item tag included under the a-assets tag. see the example program below for more information.
Example
// sketch.js file

let world;
let pikachuModel;
			  		
function setup() {
   // no canvas needed
   noCanvas();
   
   // create a new VR World object
   world = new AFrameP5.World('VRScene');
   
   // add a Wavefront (OBJ) model
   // you need to make sure to reference the ids of both the OBJ and MTL files here
   // these need to be loaded in your 'index.html' file inside of the
   // 'a-assets' tag
   pikachuModel = new AFrameP5.OBJ({
      asset: 'pika_obj',
      mtl: 'pika_mtl',
      x: 5,
      y: 4,
      z: 0,
      rotationX:180,
      scaleX:8,
      scaleY:8,
      scaleZ:8,
    });
    
    world.add(pikachuModel);	
}
<!-- index.html file -->
							
   <body>
      <a-scene id="VRScene">
         <a-assets id="VRAssets">
            <a-asset-item id="pika_obj" src="images/Model.obj"></a-asset-item>
            <a-asset-item id="pika_mtl" src="images/Model.mtl"></a-asset-item>
         </a-assets>
      </a-scene id="VRScene">
   </body>
Methods (common to all entities)
MethodCategoryDescription
constrainPosition(xMin: number, xMax: number, yMin: number, yMax: number, zMin: number, zMax: number) Position ensures that the entity is constrained within the desired boundaries along all three axes. if an entity exceeds any of the constraints it is nudged back into position accordingly.
getX(): number Position returns the current x position of the entity. this is the entity's LOCAL position in relation to its container.
getY(): number Position returns the current y position of the entity. this is the entity's LOCAL position in relation to its container.
getZ(): number Position returns the current z position of the entity. this is the entity's LOCAL position in relation to its container.
nudge(x: number, y: number, z: number) Position nudges the element based on its current position. accepts three numeric values (i.e. myEntity.nudge(1,0,0); will nudge the entity 1 meter from its current position along the x-axis. this is the entity's LOCAL position in relation to its container.
setPosition(x: number, y: number, z: number) Position sets the position of the entity. this is the entity's LOCAL position in relation to its container.
setX(x: number) Position sets the x position of the entity. this is the entity's LOCAL position in relation to its container.
setY(y: number) Position sets the y position of the entity. this is the entity's LOCAL position in relation to its container.
setZ(z: number) Position sets the z position of the entity. this is the entity's LOCAL position in relation to its container.
getWorldPosition(): object Position returns the entity's WORLD position, not it's local position within its current container. this method is often used to compute the absolute position of an element in world space in order to deal with collisions of objects that may be nested inside of containers.
getRotationX(): number Rotation returns the current x rotation of the entity.
getRotationY(): number Rotation returns the current y rotation of the entity.
getRotationZ(): number Rotation returns the current z rotation of the entity.
rotateX(x: number) Rotation sets the x rotation of the entity
rotateY(y: number) Rotation sets the y rotation of the entity
rotateZ(z: number) Rotation sets the z rotation of the entity
setRotation(x: number, y: number, z: number) Rotation sets the rotation of the entity.
spinX(x: number) Rotation spins the entity along the x axis based on its current rotation. i.e. myEntity.spinX(1); // spin by 1 degree
spinY(y: number) Rotation spins the entity along the y axis based on its current rotation. i.e. myEntity.spinY(1); // spin by 1 degree
spinZ(z: number) Rotation spins the entity along the z axis based on its current rotation. i.e. myEntity.spinZ(1); // spin by 1 degree
lookAtUser(upright?: boolean) Rotation forces the entity to orient itself so that it is facing the user. (v2.4) lookAtUser(true) keeps the entity upright, so it only turns left and right - use this for billboards such as trees, which would otherwise tip over when the user walks up close.
getVisibility(): boolean Visibility returns the current visibility state of the entity
hide() Visibility hides the entity by setting its visible property to false
show() Visibility shows the entity by setting its visible property to true
toggleVisibility() Visibility hides the entity if it is current visible and shows the entity if it is current hidden
getScale(): object Scale returns the scale of the entity as an object (i.e. {x:0, y:0, z:0}
getScaleX(): number Scale returns the x scale of the entity
getScaleY(): number Scale returns the y scale of the entity
getScaleZ(): number Scale returns the z scale of the entity
setScale(x: number, y: number, z: number) Scale sets the scale of the object in all axes
setScaleX(x: number) Scale sets the x scale of the object
setScaleY(y: number) Scale sets the y scale of the object
setScaleZ(z: number) Scale sets the z scale of the object
getAsset(): string Material returns the current id of the asset being used to texture this entity
getBlue(): number Material returns the current blue color of the entity
getGreen(): number Material returns the current green color of the entity
getMetalness(): number Material returns the current metalness setting for the texture of the entity (range = 0.0 to 1.0)
getOpacity(): number Material returns the current opacity of the entity
getRed(): number Material returns the current red color of the entity
setRoughness(roughness: number) Material sets the roughness for the texture of the entity (range = 0.0 to 1.0)
getSide(): string Material returns which faces of the entity will be textured (valid values are front, back and double)
getTransparent(): boolean Material returns the current transparency of the entity
setAsset(asset: string) Material sets the id for the asset to texture this entity
setColor(red: number, green: number, blue: number) Material sets the color of the entity
setBlue(blue: number) Material sets the blue color of the entity
setGreen(green: number) Material sets the green color of the entity
setMetalness(metalness: number) Material sets the metalness for the texture of the entity (range = 0.0 to 1.0)
setOpacity(opacity: number) Material sets the opacity of the entity (range = 0.0 to 1.0)
setRed(red: number) Material sets the red color of the entity
getRoughness(): number Material returns the current roughness setting for the texture of the entity (range = 0.0 to 1.0)
setTransparent(transparent: boolean) Material sets whether the entity supports transparent textures
getAlphaTest(): number Material (v2.4) returns the entity's alphaTest value
setAlphaTest(alphaTest: number) Material (v2.4) sets the alphaTest value (see the alphaTest constructor option)
setSide(side: string) Material sets which faces of the entity will be textured (valid values are front, back and double)
getRepeatX(): number Material returns how many times the texture repeats across the entity horizontally
getRepeatY(): number Material (v2.4) returns how many times the texture repeats across the entity vertically
setRepeatX(times: number) Material sets how many times the texture repeats across the entity horizontally
setRepeatY(times: number) Material (v2.4) sets how many times the texture repeats across the entity vertically
getSolid(): boolean Physics (v2.4) returns whether the entity is solid
setSolid(solid: boolean) Physics (v2.4) makes the entity solid (true: it blocks the user and can be stood on) or not solid (false: the user can walk through it)
add(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity. alias for addChild.
addChild(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity.
getChildren(): Array Hierarchy returns an Array of all children of this entity
removeChild(entity: Entity) Hierarchy removes a child entity from this entity.
Methods (specific to this class)

No entity-specific methods


Class: GLTF (entity)

A Graphics Language Transmission Format 3D model (.GLTF file format)

Constructor Parameters (common to all entities)

new AFrameP5.GLTF(options)

OptionTypeDefaultDescription
x number 0 x-position of the entity
y number 0 y-position of the entity
z number 0 z-position of the entity
opacity number 1.0 how transparent this entity is (0.0 = fully transparent, 1.0 = fully opaque)
transparent boolean false whether the texture associated with this entity supports transparency (i.e. a PNG file with an alpha channel)
alphaTest number 0 (v2.4) pixels less opaque than this value (0.0 to 1.0) are not drawn at all. Use 0.5 for cut-out pictures such as trees (PNGs with see-through parts), otherwise the see-through parts can hide whatever is behind them. 0 turns it off.
shader string 'standard' the ThreeJS shader to use to render this entity - other valid value is flat
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
roughness number 0.5 how 'rough' the material appears. valid range = 0.0 to 1.0
metalness number 0 how 'metallic' the material appears. valid range = 0.0 to 1.0
red integer 255 how red the entity appears. valid range = 0 to 255
green integer 255 how green the entity appears. valid range = 0 to 255
blue integer 255 how blue the entity appears. valid range = 0 to 255
repeatX integer 1 how many times to repeat the texture associated with the entity along the x-axis of each face of the object. valid range = any positive number
repeatY integer 1 how many times to repeat the texture associated with the entity along the y-axis of each face of the object. valid range = any positive number
asset string 'None' the id (string) of the element that should be used as a texture for this entity. all textures should be set up in the 'index.html' file inside of the a-assets tag.
scaleX number 1.0 the scale of the object in the x-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleY number 1.0 the scale of the object in the y-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleZ number 1.0 the scale of the object in the z-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
rotationX number 0 the rotation of the object along the x-axis.
rotationY number 0 the rotation of the object along the y-axis.
rotationZ number 0 the rotation of the object along the z-axis.
visible boolean true determines whether the entity is visible in the scene.
solid boolean false (v2.4) solid entities block the user's movement and can be stood on when gravity is turned on (see world.setGravity and the physics example).
dynamicTexture boolean false sets whether the texture used on the entity is being drawn from a dynamically drawn canvas element. see these examples for more information: Dynamic textures, Multiple dynamic textures and Interactive dynamic textures
dynamicTextureHeight number 0 tells the entity the height of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
dynamicTextureWidth number 0 tells the entity the width of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
customData object undefined a custom object that can be used by the entity to keep track of user-specified data. example:
let b = new AFrameP5.Box({
   customData: {
      numClicks: 0
   },
   clickFunction: function(e) { 
      e.customData.numClicks++;
      console.log("This element has been clicked " + e.customData.numClicks + " times");
   }
});
clickFunction function undefined a custom function that will run every time the user clicks on the entity. this function receives a reference to the entity that was clicked, and (v2.4) a second argument with information about the click (see below). example:
let b = new AFrameP5.Box({
   clickFunction: function(e) { 
      e.setRed(random(255)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   clickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});


(v2.4) the second argument, often called hit, describes the click:
  • point3d : the exact point in the world where the click landed (an object with x, y and z)
  • distance : how far away that point is from the user, in meters
  • hand : what did the clicking: 'mouse' (the mouse, or the gaze cursor), 'left' or 'right' (the VR controllers)
  • uv : the raw texture coordinates of the click (x and y, from 0 to 1)
  • point2d : for entities that use a dynamic texture, where on the texture the click landed (x and y, in pixels)
  • voxel and voxelAdjacent : for voxel grids, the cube that was clicked and the empty space next to the face that was clicked
example:
let b = new AFrameP5.Box({
   clickFunction: function(e, hit) {
      console.log("clicked at " + hit.point3d.x + ", " + hit.point3d.y + ", " + hit.point3d.z + " with the " + hit.hand);
   }
});
see the click information example.
upFunction function undefined a custom function that will run every time the releases the mouse after the entity has been clicked. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   upFunction: function(e) { 
      e.spinX(random(360)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   upFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
enterFunction function undefined a custom function that will run every time the mouse hovers over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   enterFunction: function(e) { 
      e.setScale(2,2,2); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   enterFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
leaveFunction function undefined a custom function that will run every time the mouse stops hovering over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   leaveFunction: function(e) { 
      e.setScale(1,1,1); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   leaveFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
overFunction function undefined a custom function that will run continually whenever the mouse is hovering over the entity. this function should be implemented to accept two arguments - the first is a reference to the entity that was clicked, and the second is an object that contains information about the interaction that just occured. example:
let b = AFrameP5.Box({
   overFunction: function(e, intersectionInfo) { 
      console.log(intersectionInfo);
   }
});
intersectionInfo is an object that contains info about how the user is interacting with this entity. it contains the following properties:
  • distance : a float describing how far away the user is
  • point3d : an object with three properties (x, y & z) describing where the user is touching the entity
  • point2d : an object with two properites (x & y) describing where the user is touching the entity in 2D space (useful for determining where on a dynamic canvas the user is touching)
  • uv : an object with two properies (x & y) describing the raw textural offset (used to compute point2d)
  • hand : (v2.4) which pointer is hovering: 'mouse', 'left' or 'right'. Each VR controller calls overFunction separately, so check this if only one hand should do something (for example, only paint with the right hand).
For an example please see the Interactive dynamic textures sample program.

as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   overFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
dragFunction function undefined (v2.4) a custom function that runs every frame while the user holds the mouse button (or a VR controller trigger) down after pressing on this entity and keeps pointing at it - for example, to draw on a dynamic texture. A drag that starts somewhere else and moves onto the entity doesn't count. While the mouse is dragging on the entity, it doesn't turn the camera, so the view stays still while you draw. It takes the same two arguments as overFunction (the entity and hit), plus two more properties in hit:
  • previousPoint2d : where the user was pointing on the dynamic texture on the previous frame (x and y, in pixels). It is null when a new drag starts, and again when the pointer comes back onto the entity during a drag, so you can draw a line from it to point2d without joining separate strokes.
  • previousPoint3d : the same thing in the world (x, y and z)
example:
let canvas = new AFrameP5.Plane({
   asset: texture, dynamicTexture: true, dynamicTextureWidth: 512, dynamicTextureHeight: 512,
   dragFunction: function(e, hit) {
      if (hit.previousPoint2d) {
         buffer.line(hit.previousPoint2d.x, hit.previousPoint2d.y, hit.point2d.x, hit.point2d.y);
      }
   }
});
Each VR controller drags separately, so check hit.hand if only one hand should draw.

In VR, clickFunction runs as soon as the trigger is pressed (setClickOnRelease only changes mouse clicks), so avoid giving one entity both a clickFunction and a dragFunction if that matters. To do something at the start of each drag (for example, stamp a dot), check for hit.previousPoint2d === null inside dragFunction instead.
tickFunction function undefined a custom function that will run once per frame (like draw does for the main sketch). this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   tickFunction: function(e) { 
      e.setRed( random(255) ); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   tickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
Constructor Parameters (specific to this class)

new AFrameP5.GLTF(options)

OptionTypeDefaultDescription
asset string undefined the id of the element in your HTML file that points to the GLTF file you wish to load. this element must be a a-asset-item tag included under the a-assets tag. see the example program below for more information.
Example
// sketch.js file

let world;
let dogModel;
			  		
function setup() {
   // no canvas needed
   noCanvas();
   
   // create a new VR World object
   world = new AFrameP5.World('VRScene');
   
   // add a GLTF model
   // you need to make sure to reference id of the GLTF file here
   // this need to be loaded in your 'index.html' file inside of the
   // 'a-assets' tag
   dogModel = new AFrameP5.GLTF({
      asset: 'dog',
      x: 5,
      y: 4,
      z: 0,
      rotationX:180,
      scaleX:8,
      scaleY:8,
      scaleZ:8,
    });
    
    world.add(dogModel);	
}
<!-- index.html file -->
							
   <body>
      <a-scene id="VRScene">
         <a-assets id="VRAssets">
            <a-asset-item id="dog" src="images/scene.gltf"></a-asset-item>
         </a-assets>
      </a-scene id="VRScene">
   </body>
Methods (common to all entities)
MethodCategoryDescription
constrainPosition(xMin: number, xMax: number, yMin: number, yMax: number, zMin: number, zMax: number) Position ensures that the entity is constrained within the desired boundaries along all three axes. if an entity exceeds any of the constraints it is nudged back into position accordingly.
getX(): number Position returns the current x position of the entity. this is the entity's LOCAL position in relation to its container.
getY(): number Position returns the current y position of the entity. this is the entity's LOCAL position in relation to its container.
getZ(): number Position returns the current z position of the entity. this is the entity's LOCAL position in relation to its container.
nudge(x: number, y: number, z: number) Position nudges the element based on its current position. accepts three numeric values (i.e. myEntity.nudge(1,0,0); will nudge the entity 1 meter from its current position along the x-axis. this is the entity's LOCAL position in relation to its container.
setPosition(x: number, y: number, z: number) Position sets the position of the entity. this is the entity's LOCAL position in relation to its container.
setX(x: number) Position sets the x position of the entity. this is the entity's LOCAL position in relation to its container.
setY(y: number) Position sets the y position of the entity. this is the entity's LOCAL position in relation to its container.
setZ(z: number) Position sets the z position of the entity. this is the entity's LOCAL position in relation to its container.
getWorldPosition(): object Position returns the entity's WORLD position, not it's local position within its current container. this method is often used to compute the absolute position of an element in world space in order to deal with collisions of objects that may be nested inside of containers.
getRotationX(): number Rotation returns the current x rotation of the entity.
getRotationY(): number Rotation returns the current y rotation of the entity.
getRotationZ(): number Rotation returns the current z rotation of the entity.
rotateX(x: number) Rotation sets the x rotation of the entity
rotateY(y: number) Rotation sets the y rotation of the entity
rotateZ(z: number) Rotation sets the z rotation of the entity
setRotation(x: number, y: number, z: number) Rotation sets the rotation of the entity.
spinX(x: number) Rotation spins the entity along the x axis based on its current rotation. i.e. myEntity.spinX(1); // spin by 1 degree
spinY(y: number) Rotation spins the entity along the y axis based on its current rotation. i.e. myEntity.spinY(1); // spin by 1 degree
spinZ(z: number) Rotation spins the entity along the z axis based on its current rotation. i.e. myEntity.spinZ(1); // spin by 1 degree
lookAtUser(upright?: boolean) Rotation forces the entity to orient itself so that it is facing the user. (v2.4) lookAtUser(true) keeps the entity upright, so it only turns left and right - use this for billboards such as trees, which would otherwise tip over when the user walks up close.
getVisibility(): boolean Visibility returns the current visibility state of the entity
hide() Visibility hides the entity by setting its visible property to false
show() Visibility shows the entity by setting its visible property to true
toggleVisibility() Visibility hides the entity if it is current visible and shows the entity if it is current hidden
getScale(): object Scale returns the scale of the entity as an object (i.e. {x:0, y:0, z:0}
getScaleX(): number Scale returns the x scale of the entity
getScaleY(): number Scale returns the y scale of the entity
getScaleZ(): number Scale returns the z scale of the entity
setScale(x: number, y: number, z: number) Scale sets the scale of the object in all axes
setScaleX(x: number) Scale sets the x scale of the object
setScaleY(y: number) Scale sets the y scale of the object
setScaleZ(z: number) Scale sets the z scale of the object
getAsset(): string Material returns the current id of the asset being used to texture this entity
getBlue(): number Material returns the current blue color of the entity
getGreen(): number Material returns the current green color of the entity
getMetalness(): number Material returns the current metalness setting for the texture of the entity (range = 0.0 to 1.0)
getOpacity(): number Material returns the current opacity of the entity
getRed(): number Material returns the current red color of the entity
setRoughness(roughness: number) Material sets the roughness for the texture of the entity (range = 0.0 to 1.0)
getSide(): string Material returns which faces of the entity will be textured (valid values are front, back and double)
getTransparent(): boolean Material returns the current transparency of the entity
setAsset(asset: string) Material sets the id for the asset to texture this entity
setColor(red: number, green: number, blue: number) Material sets the color of the entity
setBlue(blue: number) Material sets the blue color of the entity
setGreen(green: number) Material sets the green color of the entity
setMetalness(metalness: number) Material sets the metalness for the texture of the entity (range = 0.0 to 1.0)
setOpacity(opacity: number) Material sets the opacity of the entity (range = 0.0 to 1.0)
setRed(red: number) Material sets the red color of the entity
getRoughness(): number Material returns the current roughness setting for the texture of the entity (range = 0.0 to 1.0)
setTransparent(transparent: boolean) Material sets whether the entity supports transparent textures
getAlphaTest(): number Material (v2.4) returns the entity's alphaTest value
setAlphaTest(alphaTest: number) Material (v2.4) sets the alphaTest value (see the alphaTest constructor option)
setSide(side: string) Material sets which faces of the entity will be textured (valid values are front, back and double)
getRepeatX(): number Material returns how many times the texture repeats across the entity horizontally
getRepeatY(): number Material (v2.4) returns how many times the texture repeats across the entity vertically
setRepeatX(times: number) Material sets how many times the texture repeats across the entity horizontally
setRepeatY(times: number) Material (v2.4) sets how many times the texture repeats across the entity vertically
getSolid(): boolean Physics (v2.4) returns whether the entity is solid
setSolid(solid: boolean) Physics (v2.4) makes the entity solid (true: it blocks the user and can be stood on) or not solid (false: the user can walk through it)
add(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity. alias for addChild.
addChild(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity.
getChildren(): Array Hierarchy returns an Array of all children of this entity
removeChild(entity: Entity) Hierarchy removes a child entity from this entity.
Methods (specific to this class)

No entity-specific methods


Class: Sky (entity)

A large 'sky sphere' that surrounds the user. The sphere is textured using a specially prepared equirectangular image that provides a 360 display.

Constructor Parameters (specific to this class)

new AFrameP5.Sky(options)

OptionTypeDefaultDescription
radius number 500 radius of the sky sphere (in meters)
asset string 'None' the id (string) of the element that should be used as a texture for this entity. all textures should be set up in the 'index.html' file inside of the a-assets tag. note that images used on a sky sphere should be 'equirectangular' in nature - a standard rectangular image will appear distorted if projected onto a sphere.
dynamicTexture boolean false sets whether the texture used on the entity is being drawn from a dynamically drawn canvas element. see these examples for more information: Dynamic textures, Multiple dynamic textures and Interactive dynamic textures
dynamicTextureHeight number 0 tells the entity the height of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
dynamicTextureWidth number 0 tells the entity the width of a dynamic texture. this is used when computing intersection points with the entity and allows you to know the 2D position on the texture where the user is touching. this property must be used along with dynamicTexture and dynamicTextureHeight For more information see this example: Interactive dynamic textures
Example
// sketch.js file
				 			
// variable to hold a reference to our A-Frame world
let world;

function setup() {
   // no canvas needed
   noCanvas();
   
   // construct the A-Frame world
   // this function requires a reference to the ID of the 'a-scene' tag in our HTML document
   world = new AFrameP5.World('VRScene');
   
   // create a new 'sky' entity - this functions as a huge sphere (500 meter radius) that
   // is wrapped using an 'equirectangular' image (simliar to a "mercator projection" for a map)
   // the image is loaded in the 'index.html' file
   let sky = new AFrameP5.Sky({
      asset: 'sky1'
   });
   world.add(sky);
}
<!-- index.html file -->
							
   <body>
      <a-scene id="VRScene">
         <a-assets id="VRAssets">
            <img id="sky1" src="images/equirectangular_image.jpg"><
         </a-assets>
      </a-scene id="VRScene">
   </body>
Methods (specific to this class)
MethodCategoryDescription
getRadius(): number Geometry returns the current radius of the entity
setRadius(radius: number) Geometry sets the radius of the entity
changeRadius(amount: number) Geometry updates the radius by the value provided (i.e. entity.changeRadius(0.1); will increase the radius by 0.1 meters.
getAsset(): string Material returns the current id of the asset being used to texture this entity
setAsset(asset: string) Material sets the id for the asset to texture this entity

Class: Text (entity)

A 2D entity that renders arbitrary text.

Constructor Parameters (specific to this class)

new AFrameP5.Text(options)

OptionTypeDefaultDescription
text string "" the text to display
textAlign string "center" text alignment - accepted values are "center", "left" and "right"
font string "roboto" font to render text, either the name of one of A-Frame’s stock fonts or a URL to a font file.
red integer 128 how red the entity appears. valid range = 0 to 255
green integer 128 how green the entity appears. valid range = 0 to 255
blue integer 128 how blue the entity appears. valid range = 0 to 255
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
opacity number 1.0 how transparent this entity is (0.0 = fully transparent, 1.0 = fully opaque)
x number 0 x-position of the entity
y number 0 y-position of the entity
z number 0 z-position of the entity
side string 'front' which side of the entity should be set up with a visual material. default is the front of the entity - other valid values are back and double
scaleX number 1.0 the scale of the object in the x-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleY number 1.0 the scale of the object in the y-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
scaleZ number 1.0 the scale of the object in the z-axis. 1.0 means normal size - numbers smaller than 1.0 represent a smaller object (i.e. 0.5 means 50% of normal size). numbers larger than 1.0 represent a larger object (i.e. 2.0 means 200% of normal size).
rotationX number 0 the rotation of the object along the x-axis.
rotationY number 0 the rotation of the object along the y-axis.
rotationZ number 0 the rotation of the object along the z-axis.
visible boolean true determines whether the entity is visible in the scene.
solid boolean false (v2.4) solid entities block the user's movement and can be stood on when gravity is turned on (see world.setGravity and the physics example).
customData object undefined a custom object that can be used by the entity to keep track of user-specified data. example:
let b = new AFrameP5.Box({
   customData: {
      numClicks: 0
   },
   clickFunction: function(e) { 
      e.customData.numClicks++;
      console.log("This element has been clicked " + e.customData.numClicks + " times");
   }
});
clickFunction function undefined a custom function that will run every time the user clicks on the entity. this function receives a reference to the entity that was clicked, and (v2.4) a second argument with information about the click (see below). example:
let b = new AFrameP5.Box({
   clickFunction: function(e) { 
      e.setRed(random(255)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   clickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});


(v2.4) the second argument, often called hit, describes the click:
  • point3d : the exact point in the world where the click landed (an object with x, y and z)
  • distance : how far away that point is from the user, in meters
  • hand : what did the clicking: 'mouse' (the mouse, or the gaze cursor), 'left' or 'right' (the VR controllers)
  • uv : the raw texture coordinates of the click (x and y, from 0 to 1)
  • point2d : for entities that use a dynamic texture, where on the texture the click landed (x and y, in pixels)
  • voxel and voxelAdjacent : for voxel grids, the cube that was clicked and the empty space next to the face that was clicked
example:
let b = new AFrameP5.Box({
   clickFunction: function(e, hit) {
      console.log("clicked at " + hit.point3d.x + ", " + hit.point3d.y + ", " + hit.point3d.z + " with the " + hit.hand);
   }
});
see the click information example.
upFunction function undefined a custom function that will run every time the releases the mouse after the entity has been clicked. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   upFunction: function(e) { 
      e.spinX(random(360)); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   upFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
enterFunction function undefined a custom function that will run every time the mouse hovers over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   enterFunction: function(e) { 
      e.setScale(2,2,2); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   enterFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
leaveFunction function undefined a custom function that will run every time the mouse stops hovering over the entity. this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   leaveFunction: function(e) { 
      e.setScale(1,1,1); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   leaveFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
overFunction function undefined a custom function that will run continually whenever the mouse is hovering over the entity. this function should be implemented to accept two arguments - the first is a reference to the entity that was clicked, and the second is an object that contains information about the interaction that just occured. example:
let b = AFrameP5.Box({
   overFunction: function(e, intersectionInfo) { 
      console.log(intersectionInfo);
   }
});
intersectionInfo is an object that contains info about how the user is interacting with this entity. it contains the following properties:
  • distance : a float describing how far away the user is
  • point3d : an object with three properties (x, y & z) describing where the user is touching the entity
  • point2d : an object with two properites (x & y) describing where the user is touching the entity in 2D space (useful for determining where on a dynamic canvas the user is touching)
  • uv : an object with two properies (x & y) describing the raw textural offset (used to compute point2d)
  • hand : (v2.4) which pointer is hovering: 'mouse', 'left' or 'right'. Each VR controller calls overFunction separately, so check this if only one hand should do something (for example, only paint with the right hand).
For an example please see the Interactive dynamic textures sample program.

as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   overFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
dragFunction function undefined (v2.4) a custom function that runs every frame while the user holds the mouse button (or a VR controller trigger) down after pressing on this entity and keeps pointing at it - for example, to draw on a dynamic texture. A drag that starts somewhere else and moves onto the entity doesn't count. While the mouse is dragging on the entity, it doesn't turn the camera, so the view stays still while you draw. It takes the same two arguments as overFunction (the entity and hit), plus two more properties in hit:
  • previousPoint2d : where the user was pointing on the dynamic texture on the previous frame (x and y, in pixels). It is null when a new drag starts, and again when the pointer comes back onto the entity during a drag, so you can draw a line from it to point2d without joining separate strokes.
  • previousPoint3d : the same thing in the world (x, y and z)
example:
let canvas = new AFrameP5.Plane({
   asset: texture, dynamicTexture: true, dynamicTextureWidth: 512, dynamicTextureHeight: 512,
   dragFunction: function(e, hit) {
      if (hit.previousPoint2d) {
         buffer.line(hit.previousPoint2d.x, hit.previousPoint2d.y, hit.point2d.x, hit.point2d.y);
      }
   }
});
Each VR controller drags separately, so check hit.hand if only one hand should draw.

In VR, clickFunction runs as soon as the trigger is pressed (setClickOnRelease only changes mouse clicks), so avoid giving one entity both a clickFunction and a dragFunction if that matters. To do something at the start of each drag (for example, stamp a dot), check for hit.previousPoint2d === null inside dragFunction instead.
tickFunction function undefined a custom function that will run once per frame (like draw does for the main sketch). this function should be implemented to accept a single argument which is a reference to the entity that was clicked. example:
let b = new AFrameP5.Box({
   tickFunction: function(e) { 
      e.setRed( random(255) ); 
   }
});
as with the other interaction handler functions, this this function can access the customData property of the entity if desired. example:
let b = new AFrameP5.Box({
   customData: {
      currentRed: 0,
      colorChangeSpeed: 1
   },
   tickFunction: function(e) { 
      e.customData.currentRed += e.customData.colorChangeSpeed;
      if (e.customData.currentRed >= 255 || e.customData.currentRed <= 0) {
         e.customData.colorChangeSpeed *= -1;
      }
      e.setRed( e.customData.currentRed ); 
   }
});
Example
// sketch.js file
				 			
// variable to hold a reference to our A-Frame world
let world;

function setup() {
   // no canvas needed
   noCanvas();
   
   // construct the A-Frame world
   // this function requires a reference to the ID of the 'a-scene' tag in our HTML document
   world = new AFrameP5.World('VRScene');
   
   // text primitive
   // you can select a font from one on this list:  https://aframe.io/docs/1.2.0/components/text.html#stock-fonts
   // note that you can increase the text size using the 'scale' property
   let text = new AFrameP5.Text({
      text: 'Hello, World!',
      red: 128, green: 128, blue: 128,
      side: 'double',
      x: 0, y: 2, z: 0,
      scaleX: 5, scaleY: 5, scaleZ: 5
   });
   
   world.add(text);
}
Methods (specific to this class)
MethodCategoryDescription
setText(text: string) Text sets the text to display for this entity
getText(): string Text returns the current text being displayed by this entity
setFont(font: string) Text sets the font being used by this entity. can be either the name of one of A-Frame’s stock fonts or a URL to a font file.
getFont(): string Text returns the current font being used by this entity. can be either the name of one of A-Frame’s stock fonts or a URL to a font file.
setTextAlign(textAlign: string) Text sets the alignment of the text ('center', 'left' or 'right')
getTextAlign(): string Text returns the current alignment of the text ('center', 'left' or 'right')
lookAt(otherEntity: Entity) Rotation turns the text so that it faces another entity (to make text face the user, use lookAtUser())
constrainPosition(xMin: number, xMax: number, yMin: number, yMax: number, zMin: number, zMax: number) Position ensures that the entity is constrained within the desired boundaries along all three axes. if an entity exceeds any of the constraints it is nudged back into position accordingly.
getX(): number Position returns the current x position of the entity. this is the entity's LOCAL position in relation to its container.
getY(): number Position returns the current y position of the entity. this is the entity's LOCAL position in relation to its container.
getZ(): number Position returns the current z position of the entity. this is the entity's LOCAL position in relation to its container.
nudge(x: number, y: number, z: number) Position nudges the element based on its current position. accepts three numeric values (i.e. myEntity.nudge(1,0,0); will nudge the entity 1 meter from its current position along the x-axis. this is the entity's LOCAL position in relation to its container.
setPosition(x: number, y: number, z: number) Position sets the position of the entity. this is the entity's LOCAL position in relation to its container.
setX(x: number) Position sets the x position of the entity. this is the entity's LOCAL position in relation to its container.
setY(y: number) Position sets the y position of the entity. this is the entity's LOCAL position in relation to its container.
setZ(z: number) Position sets the z position of the entity. this is the entity's LOCAL position in relation to its container.
getWorldPosition(): object Position returns the entity's WORLD position, not it's local position within its current container. this method is often used to compute the absolute position of an element in world space in order to deal with collisions of objects that may be nested inside of containers.
getRotationX(): number Rotation returns the current x rotation of the entity.
getRotationY(): number Rotation returns the current y rotation of the entity.
getRotationZ(): number Rotation returns the current z rotation of the entity.
rotateX(x: number) Rotation sets the x rotation of the entity
rotateY(y: number) Rotation sets the y rotation of the entity
rotateZ(z: number) Rotation sets the z rotation of the entity
setRotation(x: number, y: number, z: number) Rotation sets the rotation of the entity.
spinX(x: number) Rotation spins the entity along the x axis based on its current rotation. i.e. myEntity.spinX(1); // spin by 1 degree
spinY(y: number) Rotation spins the entity along the y axis based on its current rotation. i.e. myEntity.spinY(1); // spin by 1 degree
spinZ(z: number) Rotation spins the entity along the z axis based on its current rotation. i.e. myEntity.spinZ(1); // spin by 1 degree
getVisibility(): boolean Visibility returns the current visibility state of the entity
hide() Visibility hides the entity by setting its visible property to false
show() Visibility shows the entity by setting its visible property to true
toggleVisibility() Visibility hides the entity if it is current visible and shows the entity if it is current hidden
getScale(): object Scale returns the scale of the entity as an object (i.e. {x:0, y:0, z:0}
getScaleX(): number Scale returns the x scale of the entity
getScaleY(): number Scale returns the y scale of the entity
getScaleZ(): number Scale returns the z scale of the entity
setScale(x: number, y: number, z: number) Scale sets the scale of the object in all axes
setScaleX(x: number) Scale sets the x scale of the object
setScaleY(y: number) Scale sets the y scale of the object
setScaleZ(z: number) Scale sets the z scale of the object
getRed(): number Material returns the current red color of the entity
getBlue(): number Material returns the current blue color of the entity
getGreen(): number Material returns the current green color of the entity
getOpacity(): number Material returns the current opacity of the entity
getSide(): string Material returns which faces of the entity will be textured (valid values are front, back and double)
setColor(red: number, green: number, blue: number) Material sets the color of the entity
setRed(red: number) Material sets the red color of the entity
setBlue(blue: number) Material sets the blue color of the entity
setGreen(green: number) Material sets the green color of the entity
setOpacity(opacity: number) Material sets the opacity of the entity (range = 0.0 to 1.0)
setSide(side: string) Material sets which faces of the entity will be textured (valid values are front, back and double)
getRepeatX(): number Material returns how many times the texture repeats across the entity horizontally
getRepeatY(): number Material (v2.4) returns how many times the texture repeats across the entity vertically
setRepeatX(times: number) Material sets how many times the texture repeats across the entity horizontally
setRepeatY(times: number) Material (v2.4) sets how many times the texture repeats across the entity vertically
getSolid(): boolean Physics (v2.4) returns whether the entity is solid
setSolid(solid: boolean) Physics (v2.4) makes the entity solid (true: it blocks the user and can be stood on) or not solid (false: the user can walk through it)
add(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity. alias for addChild.
addChild(entity: Entity) Hierarchy adds an entity as a child to this entity. this places the new entity into the coordinate space of this entity.
getChildren(): Array Hierarchy returns an Array of all children of this entity
removeChild(entity: Entity) Hierarchy removes a child entity from this entity.

Class: Light (entity)

Adds a light to the world. If you don't add any lights, A-Frame adds a default soft light so that everything is visible; adding your own light turns those default lights off (you can also remove them yourself with world.removeDefaultWorldLighting()). See the lighting example.

Constructor Parameters (specific to this class)

new AFrameP5.Light(options)

Lights also accept the position, rotation and visibility options listed under "Constructor Parameters (common to all entities)" (for example in the Box section), and have the common position, rotation and visibility methods.

OptionTypeDefaultDescription
type string 'directional' the kind of light: 'ambient' (lights everything evenly), 'directional' (like sunlight, coming from one direction), 'hemisphere' (a sky color from above and a ground color from below), 'point' (like a light bulb, shining in all directions from one spot) or 'spot' (a cone of light)
color string '#fff' the color of the light (any CSS color, e.g. '#ff0000' or 'rgb(255,0,0)')
intensity number 1.0 how bright the light is. (v2.4) A-Frame 1.7 changed how light brightness is measured; A-Frame P5 adjusts for this so that 1.0 looks the same on every version.
groundColor string '#fff' 'hemisphere' lights only: the color that comes from below
distance number 0 'point' and 'spot' lights only: how far the light reaches (0 = no limit). Note: since A-Frame 1.7, lights with a distance fade out a little differently than they did in older versions, so scenes that use distance may look slightly different.
decay number 1.0 'point' and 'spot' lights only: how quickly the light fades with distance (only used when distance is not 0)
angle number 60 'spot' lights only: how wide the cone of light is, in degrees
penumbra number 0.0 'spot' lights only: how soft the edge of the cone is (0 = sharp, 1 = very soft)
Example
// sketch.js file

let world;
let bulb;

function setup() {
   noCanvas();
   world = new AFrameP5.World('VRScene');

   // a dim ambient light so nothing is completely black
   world.add(new AFrameP5.Light({ type: 'ambient', intensity: 0.1 }));

   // a point light (like a light bulb) above the scene
   bulb = new AFrameP5.Light({ type: 'point', x: 0, y: 3, z: 0, intensity: 1.0 });
   world.add(bulb);

   world.add(new AFrameP5.Box({ x: 0, y: 1, z: -2, red: 255, green: 0, blue: 0 }));
}

function draw() {
   // lights can be moved like any other entity
   bulb.setX( sin(frameCount * 0.02) * 5 );
}

Class: Voxel (entity)

(v2.4) A voxel grid: a block of space that holds lots of little cubes (like building blocks). If you've played Minecraft, you already know the idea: its whole world is made of cubes ("voxels", short for volume pixels) sitting on a grid, and you build by adding and removing them one at a time. Every cube in the grid sits at a whole-number position from 0 to width - 1 (and the same for height and depth), and each cube can have its own color or texture. Thousands of cubes can be drawn quickly because the grid is drawn as a single shape. Clicking a grid tells you which cube was clicked (hit.voxel) and where a new cube should go (hit.voxelAdjacent). See the voxel example.

Constructor Parameters (specific to this class)

new AFrameP5.Voxel(options)

Voxel grids also accept the position, scale, rotation, visibility, solid, customData and interaction function options listed under "Constructor Parameters (common to all entities)". Each cube is 1 unit in size, so use scaleX / scaleY / scaleZ to make the cubes bigger or smaller. A solid grid can be walked on, cube by cube.

OptionTypeDefaultDescription
width integer 32 how many cubes the grid holds along the x-axis (each dimension must be less than 1024)
height integer 32 how many cubes the grid holds along the y-axis
depth integer 32 how many cubes the grid holds along the z-axis
Example
// sketch.js file

let world;

function setup() {
   noCanvas();
   world = new AFrameP5.World('VRScene');

   // a 16 x 16 x 16 grid, scaled so that each cube is 0.5 meters in size
   let voxels = new AFrameP5.Voxel({
      width: 16, height: 16, depth: 16,
      x: -4, y: 0, z: -6,
      scaleX: 0.5, scaleY: 0.5, scaleZ: 0.5,

      // click a cube to add a red cube next to it, shift-click to remove it
      clickFunction: function(grid, hit) {
         if (keyIsDown(SHIFT)) {
            grid.removeCube({ x: hit.voxel.x, y: hit.voxel.y, z: hit.voxel.z });
         }
         else {
            grid.addCube({ x: hit.voxelAdjacent.x, y: hit.voxelAdjacent.y, z: hit.voxelAdjacent.z, red: 255, green: 0, blue: 0 });
         }
      }
   });
   world.add(voxels);

   // a floor of grey cubes
   for (let x = 0; x < 16; x++) {
      for (let z = 0; z < 16; z++) {
         voxels.addCube({ x: x, y: 0, z: z, red: 128, green: 128, blue: 128 });
      }
   }
}
Methods (specific to this class)
MethodCategoryDescription
addCube(options: object) Cubes adds a cube (or replaces the cube already there). Options: x, y, z (the position in the grid), and either a color (red, green, blue), a texture (asset, the id of an image) or faces (a different color or texture for each side: an object with px, nx, py, ny, pz and nz for right, left, top, bottom, front and back, each like { red: 255, green: 255, blue: 255, asset: 'grass_top' })
removeCube(options: object) Cubes removes the cube at x, y, z

Class: VoxelField (entity)

(v2.4) An endless world made of voxel grids called "chunks" - the same trick Minecraft uses to make its worlds seem to go on forever. Only the chunks near the user exist: new chunks are created as the user walks towards them, and chunks that are far away are removed. Positions in a voxel field can be any whole number, including negative numbers. An optional generator function fills each new chunk with cubes the first time it's needed. See the voxel field example.

Constructor Parameters (specific to this class)

new AFrameP5.VoxelField(options)

Voxel fields also accept the position, scale, rotation and visibility options listed under "Constructor Parameters (common to all entities)".

OptionTypeDefaultDescription
chunkSize integer 32 how many cubes each chunk holds along each axis
renderDistance integer 2 how many chunks in each direction around the user are kept. New chunks are always created renderDistance × chunkSize × scale meters away from the chunk you're in, so to stop them from popping into view, add fog that hides everything by that distance, e.g. world.setFog({ near: 8, far: 16 }) for a render distance of 2 with 16-cube chunks scaled by 0.5 (see setFog in the World methods)
generator function null a function that runs once for each new chunk: function(cx, cy, cz, field). cx, cy, cz is the position of the chunk (counted in chunks, so it covers cubes cx * chunkSize up to cx * chunkSize + chunkSize - 1), and field is the voxel field (use field.setVoxel to add cubes)
solid boolean false whether the user can walk on the cubes and bump into them
clickFunction function undefined runs when a cube is clicked: function(chunk, hit). hit.voxel and hit.voxelAdjacent are positions inside the chunk that was clicked, so add the chunk's position to get the position in the field: chunk.x + hit.voxel.x (and the same for y and z). chunk.parentField is the voxel field.
Example
// sketch.js file

let world;

function setup() {
   noCanvas();
   world = new AFrameP5.World('VRScene');

   let field = new AFrameP5.VoxelField({
      chunkSize: 16,
      renderDistance: 2,
      scaleX: 0.5, scaleY: 0.5, scaleZ: 0.5,
      solid: true,

      // build a grass floor in every chunk at ground level
      generator: function(cx, cy, cz, field) {
         if (cy != 0) {
            return;
         }
         for (let x = cx * 16; x < cx * 16 + 16; x++) {
            for (let z = cz * 16; z < cz * 16 + 16; z++) {
               field.setVoxel(x, 0, z, 0, 180, 0);
            }
         }
      }
   });
   world.add(field);
}
Methods (specific to this class)
MethodCategoryDescription
setVoxel(x: number, y: number, z: number, red: number, green: number, blue: number, asset?: string) Cubes adds a cube at a position in the field (or replaces the cube already there), with a color and optionally a texture. You can also pass a faces object instead of the color (see Voxel.addCube): setVoxel(x, y, z, faces)
removeVoxel(x: number, y: number, z: number) Cubes removes the cube at a position in the field
getVoxel(x: number, y: number, z: number): object Cubes (v2.4) what is at a position in the field: an object with red, green, blue and asset (or faces for a cube with different faces), or null if the space is empty
save(options?: object): object Saving (v2.4) returns the field as plain data that you can store yourself, e.g. in the browser with p5's storeItem('myWorld', field.save()), or in a file with saveJSON(field.save(), 'level.json'). By default only the chunks that were changed by something other than the generator are saved (each one in full) - the other chunks are simply made again by the generator, so it should give the same result every time (use noise() with noiseSeed(), or randomSeed(), rather than plain random()). A world built with setVoxel in setup (no generator) is saved completely. save({ everything: true }) saves every chunk that has cubes in it. Browser storage holds about 5 MB.
load(data: object) Saving (v2.4) loads data made by save, e.g. let saved = getItem('myWorld'); if (saved) { field.load(saved); } or field.load(await loadJSON('level.json')); in an async setup. The loaded chunks replace whatever was there and the generator won't run for them; chunks you can see are rebuilt straight away. The field must use the same chunkSize as when it was saved. Call it in setup: a chunk that is being rebuilt isn't solid for a moment, so loading the chunk you're standing on during play can make you fall. See the saving a voxel field example.

(v2.4) Each chunk that the field creates (the entity your clickFunction receives) knows where it is: chunk.chunkX, chunk.chunkY and chunk.chunkZ (counted in chunks) and chunk.chunkId, a name like '0,0,-1'. chunk.x, chunk.y and chunk.z are the position of the chunk's first cube in the field, and chunk.parentField is the field itself.


License (MIT)

Copyright 2017-2026 Craig Kapp

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.