Skip to main content

Components

A component gives an entity one ability. An entity with a camera component renders the scene, one with a light component lights it, and one with rigidbody and collision components falls, bounces and collides. Components hold the settings of their ability as properties, and an entity can have at most one component of each type.

Built-in Components​

Each name links to the component's reference on that surface. The engine name is the one you pass to addComponent(), and also the property that holds the component on its entity: entity.camera, entity.rigidbody and so on.

EngineEditorReactWeb ComponentsWhat it does
animAnim<Anim><pc-anim>Plays animations, blended by an anim state graph
animationAnimation--Legacy: plays animation clips. Use Anim
audiolistenerAudio Listener-<pc-audio-listener>The point that sounds are heard from
buttonButton-<pc-button>Makes a UI element respond to hovers and clicks
cameraCamera<Camera><pc-camera>Renders the scene from the entity's point of view
collisionCollision<Collision><pc-collision>Gives a rigid body or trigger volume its shape
elementElement<Element><pc-element>A rectangle of user interface: an image, text or group
gsplatGSplat<GSplat><pc-gsplat>Renders a 3D Gaussian splat
jointJoint-<pc-joint>Alpha: connects rigid bodies with a joint
layoutchildLayout Child-<pc-layout-child>Overrides how a layout group sizes its element
layoutgroupLayout Group-<pc-layout-group>Arranges child UI elements in rows, columns or grids
lightLight<Light><pc-light>A directional, omni or spot light
modelModel--Legacy: renders a model asset. Use Render
particlesystemParticle System-<pc-particle-system>Emits and draws particles
renderRender<Render><pc-render>Draws a primitive shape, or the meshes of a render asset
rigidbodyRigid Body<RigidBody><pc-rigid-body>Hands the entity to the physics simulation
screenScreen<Screen><pc-screen>The root of a user interface
scriptScript<Script><pc-script>Runs your scripts on the entity
scrollbarScrollbar-<pc-scrollbar>A scrollbar for a scroll view
scrollviewScroll View-<pc-scroll-view>A scrollable area of user interface
soundSound-<pc-sound>Plays sounds, optionally positioned in 3D
spriteSprite<Sprite><pc-sprite>Draws a 2D sprite or sprite animation

React and Web Components wrap the components that most applications use. A dash means there is no wrapper, but you can still add the component to the engine entity from code, as described below.

Adding a Component​

You add a component to an entity with the settings it should start with. Any setting you leave out takes its default value.

const lamp = new pc.Entity('lamp');
lamp.addComponent('light', {
    type: 'omni',
    color: new pc.Color(1, 0.8, 0.6),
    range: 10
});
app.root.addChild(lamp);

addComponent() returns the new component, which is also available as lamp.light. It returns null, and logs a warning in the debug engine, if the entity already has a light. It also returns null if the application has not registered the light component system; see Component Systems.

Components Without a Wrapper​

In React and Web Components, you can add a component that has no wrapper to the engine entity, from code.

Write a component that adds the engine component to the entity it is placed in, and removes it when it unmounts. useParent() returns the engine entity of the enclosing <Entity>:

import { useEffect } from 'react';
import { Entity } from '@playcanvas/react';
import { useParent } from '@playcanvas/react/hooks';

function AudioListener() {
  const entity = useParent();

  useEffect(() => {
    entity.addComponent('audiolistener');
    return () => {
      // unmounting the whole entity has already destroyed its components
      if (entity.audiolistener) entity.removeComponent('audiolistener');
    };
  }, [entity]);

  return null;
}

<Entity name="camera">
  <AudioListener />
</Entity>

Reading and Changing Properties​

A component's settings are properties that you can read and change at any time, and the component reacts straight away. To change a vector or color property, assign a new value to it.

lamp.light.intensity = 2;
lamp.light.color = new pc.Color(1, 0, 0);

console.log(lamp.light.range); // 10

Disabling and Removing a Component​

Every component has an enabled property. A disabled component stops working, so a disabled render component is not drawn and a disabled script component stops running its scripts, but it keeps its settings until you enable it again. Removing a component deletes it and its settings. Disabling the whole entity disables all of its components at once; see Enabling and Disabling.

box.render.enabled = false; // stop drawing the box
box.render.enabled = true;  // draw it again

box.removeComponent('render');

Adding Your Own Behavior​

The built-in components cover the abilities the engine provides. For everything else, from a door that opens to the rules of your game, write a script and attach it to an entity with a script component. A script component can run any number of scripts, and each one reaches its entity as this.entity. Here is a script that spins its entity around its vertical axis:

import { Script } from 'playcanvas';

export class Spin extends Script {
    static scriptName = 'spin';

    /**
     * How fast to spin, in degrees per second.
     *
     * @attribute
     */
    speed = 90;

    update(dt) {
        this.entity.rotate(0, this.speed * dt, 0);
    }
}
box.addComponent('script');
box.script.create(Spin, { properties: { speed: 45 } });

Component Systems​

For each type of component, the application has one component system, which creates every component of that type, updates them each frame and destroys them. Systems live in app.systems, under the same names as the components, and some of them hold settings that all of their components share:

// the gravity that pulls on every rigid body
app.systems.rigidbody.gravity = new pc.Vec3(0, -1.62, 0);

An application can only add components whose system it has registered. pc.Application registers every built-in system, as do the Editor, React and Web Components. pc.AppBase registers only the systems you list, so that a bundler can leave the others out of your build:

const options = new pc.AppOptions();
options.graphicsDevice = device;
options.componentSystems = [
    pc.RenderComponentSystem,
    pc.CameraComponentSystem,
    pc.LightComponentSystem,
    pc.ScriptComponentSystem
];

const app = new pc.AppBase(canvas);
app.init(options);

See Using the Engine Standalone for the rest of the setup.

See Also​