How to refer to different parts of the API while scripting

That_Guy · February 27, 2019, 7:30pm

I apologize for the imprecise nature of this question, but I can’t deny that I don’t understand the PlayCanvas API in any meaningful way. I can look up functions, commands, etc in the API with ease, but I don’t know how to apply this information practically.

As an example, in my ETA project, I want tiles to turn a different color and for their position to be saved to a variable if the ruler button has been selected. However,the ruler button doesn’t seem to have any appreciable effect on tile selection.

By using the console log, I can see that rulerActive is indeed being set (sort of; sometimes it is “undefined” and I don’t know why). I also know that wasPressed and pc.MOUSEBUTTON_RIGHT are reserved terms from the PlayCanvas API. However, I think I may be using them incorrectly. I think this is because the PlayCanvas API by itself doesn’t provide context or information on how to actually use various functions and such.

Rather than asking for help with each individual roadblock I run into, I need to know how to solve some of these problems myself. My question is: how do I practically apply the information found in the API? I know there are tutorials, but those don’t always tell me what I need to know. How can I learn how to use the API properly? If anyone can point to a resource that can help me learn how to structure and apply the info from the API in my project(s), I would very much appreciate it.

Also, thanks again to Yaustar and Swatty for their continuing help in making ETA a success.

EDIT: Because of my most recent question, it occurs to me that this may be a bad example for asking for help with the API. After all, my problem is with the rulerActive variable, not wasPressed or pc.MOUSEBUTTON_RIGHT. Although I suppose it is still possible that wasPressed and/or pc.MOUSEBUTTON_RIGHT are still incorrect ways of saying “if right-click”.

yaustar · February 27, 2019, 10:51pm

Looks like you are trying to use wasPressed function?

You are halfway there. The function is part of the pc.Mouse cIass (https://developer.playcanvas.com/en/api/pc.Mouse.html), however it’s not super clear where the mouse object instance is.

This is where the tutorials and project samples help: https://developer.playcanvas.com/en/tutorials/mouse-input/

SomeScript.prototype.update = function (dt) {
  if (this.app.mouse.wasPress(pc.MOUSEBUTTON_RIGHT)) {
    // Do stuff
  }
}

I appreciate that it’s can be difficult to apply the API if you don’t know where the objects are. The best I can suggest is either to comb the forums or the tutorial sections.

IIRC, most things are accessible through the application object (which can be accessed via the this.app in any pc.Script class), entities or components.

Taking the pc.Mouse.wasPressed example, the API for application has a property listed for pc.Mouse.

I also look through the engine code on GitHub to see how things are done under the hood as well as using the browser’s debugger to inspect the objects during runtime.

yaustar · February 27, 2019, 10:52pm

It looks like ruleActive is a global variable. It would be undefined if it hasn’t been given a value on initialisation/definition.

Edit: Oh, I see you have posted here: How to keep a boolean variable defined as true or false

yaustar · March 1, 2019, 12:50am

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 (https://developer.playcanvas.com/en/api/pc.ModelComponent.html) and can be accessed though this object.

For example, let’s disable the model from receiving shadows via the receiveShadows (https://developer.playcanvas.com/en/api/pc.ModelComponent.html#receiveShadows) 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)).

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 (https://developer.playcanvas.com/en/api/pc.html) object that it is attached and Application (https://developer.playcanvas.com/en/api/pc.Application.html) 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 (https://developer.playcanvas.com/en/api/pc.Mouse.html#wasPressed) can be done in the similar way via the mouse object in the Application (https://developer.playcanvas.com/en/api/pc.Application.html#mouse)

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.

wturber · March 1, 2019, 10:10pm

Thanks a bunch!!

Bookmarked for future reference.