I want to give this explanation another try as I think it helps to grok the engine and the API documentation becomes easier to use.
PlayCanvas uses an Entity Component system where the behaviours of each Entity is made up a of multiple Components attached to it. E.g a Model Component to render a mesh to the scene, Rigidbody Component and Collision Components to give the Entity physics behaviour.
Here’s an example of an Entity with a Model Component attached in the editor.
Every Component added to the Entity is accessible via the Entity object in code and the editor does a pretty good job of reflecting what is accessible via code and how (more on this in a later example).
In this case, the Model Component accessed via the following code:
anEntity.model
All the properties and functions that of the Model Component can be found in the API documentation (ModelComponent | PlayCanvas API Reference) and can be accessed though this object.
For example, let’s disable the model from receiving shadows via the receiveShadows (ModelComponent | PlayCanvas API Reference) property which is a boolean:
anEntity.model.receiveShadows = false;
Sometimes, you would want to change an attribute that can be seen in the editor but have trouble finding the name of the property to use in code.
If you mouse over the name of the attribute or a tickbox in the editor, a tickbox will show giving the name of the attribute in code, the data type and a link to the API documentation.
Getting the name of the Component on the Entity object is more difficult unfortunately and it’s usually a case of looking at the engine source code, tutorials, user manual or API documentation to find out.
To find out the name of the Component in the engine source code, look at the list in GitHub (https://github.com/playcanvas/engine/tree/master/src/framework/components) and find the Component you need.
Open the folder (e.g let’s find the name of the particle component) and the system.js file.
Finally, find the id which will be the name of the component in code.
This means that the Particles Component is accessible via the following code.
anEntity.particlesystem
Alternatively, I would log the Entity to the console and inspect it (e.g console.log(anEntity);) there or use the debugger.
Taking another example of the issue in the following thread where the poster had trouble changing the text of the Element Component for the UI system (Euclidean TRPG Assistant (ETA) - #10 by That_Guy).
The Entity would look like the following in the editor:
The name of the Component in code is element as found in the engine source code:
And using the editor tooltip, the property name for the text is text.
Put it all together, changing the text can be done with the following code:
anEntity.element.text = "Hello World";
The user created scripts (known as pc.Script) are different in the sense that they can provide behaviours to Entities but are not Components are therefore accessed differently in code.
As mentioned above, the editor does a good job of representing the Entity code composition and will help explain how to access an attached pc.Script.
To attach a pc.Script, first a Script Component needs to be added:
And then the pc.Script can be added (in this case, sandbox):
This shows that the pc.Script is actually attached to the Script Component and not the Entity itself. Therefore, accessing the sandbox pc.Script object is done via the Script Component as shown in following code:
anEntity.script.sandbox
Where script is the name of the Script Component object and sandbox is the name of the the pc.Script object as given in the code by the user.
And like the Model and Element Components above, properties and functions of the pc.Script object can be accessed in the same way.
Every pc.Script object will also have the Entity (Entity | PlayCanvas API Reference) object that it is attached and Application (Application | PlayCanvas API Reference) object assigned as properties to it by the engine when it is created at runtime.
So if we wanted to change the text of the Element Component that is attached to the Entity via the pc.Script, the code would be:
this.entity.element.text = "Hello World";
The Entity in editor for reference:
And the pc.Script of sandbox:
And checking if a mouse button was pressed in the current frame (Mouse | PlayCanvas API Reference) can be done in the similar way via the mouse object in the Application (Application | PlayCanvas API Reference)
if (this.app.mouse.wasPressed(pc.MOUSEBUTTON_LEFT) {
// Do something
}
Hopefully that covers most of accessing the different objects, components and pc.Scripts and the properties and functions that are listed in the API documentation.