Create a new Application instance.
The canvas element.
Optional options: { The options object to configure the Application.
Prefix to apply to asset urls before loading.
Input handler for ElementComponents.
Gamepad handler for input.
The graphics device used by the application. If not provided, a WebGl graphics device will be created.
Options object that is passed into the GraphicsDevice constructor.
Keyboard handler for input.
Mouse handler for input.
Prefix to apply to script urls before loading.
Scripts in order of loading first.
TouchDevice handler for input.
// Engine-only example: create the application manually
const app = new pc.Application(canvas, options);
// Start the application's main loop
app.start();
The asset registry managed by the application.
// Search the asset registry for all assets with the tag 'vehicle'
const vehicleAssets = this.app.assets.findByTag('vehicle');
When true, the application's render function is called every frame. Setting autoRender to false is useful to applications where the rendered image may often be unchanged over time. This can heavily reduce the application's load on the CPU and GPU. Defaults to true.
// Disable rendering every frame and only render on a keydown event
this.app.autoRender = false;
this.app.keyboard.on('keydown', function (event) {
this.app.renderNextFrame = true;
}, this);
Used to handle input for ElementComponents.
Used to access GamePad input.
The graphics device used by the application.
Handles localization.
The keyboard device.
The run-time lightmapper.
The resource loader.
Clamps per-frame delta time to an upper bound. Useful since returning from a tab deactivation can generate huge values for dt, which can adversely affect game state. Defaults to 0.1 (seconds).
// Don't clamp inter-frame times of 200ms or less
this.app.maxDeltaTime = 0.2;
The mouse device.
Set to true to render the scene on the next iteration of the main loop. This only has an effect if AppBase#autoRender is set to false. The value of renderNextFrame is set back to false again as soon as the scene has been rendered.
// Render the scene only while space key is pressed
if (this.app.keyboard.isPressed(pc.KEY_SPACE)) {
this.app.renderNextFrame = true;
}
The root entity of the application.
// Return the first entity called 'Camera' in a depth-first search of the scene hierarchy
const camera = this.app.root.findByName('Camera');
The scene managed by the application.
// Set the tone mapping property of the application's scene
this.app.scene.toneMapping = pc.TONEMAP_FILMIC;
The scene registry managed by the application.
// Search the scene registry for a item with the name 'racetrack1'
const sceneItem = this.app.scenes.find('racetrack1');
// Load the scene using the item's url
this.app.scenes.loadScene(sceneItem.url);
The application's script registry.
The application's component system registry. The Application constructor adds the following component systems to its component system registry:
// Set global gravity to zero
this.app.systems.rigidbody.gravity.set(0, 0, 0);
// Set the global sound volume to 50%
this.app.systems.sound.volume = 0.5;
Scales the global time delta. Defaults to 1.
// Set the app to run at half speed
this.app.timeScale = 0.5;
Used to get touch events input.
The XR Manager that provides ability to start VR/AR sessions.
// check if VR is available
if (app.xr.isAvailable(pc.XRTYPE_VR)) {
// VR is available
}
The application's batch manager. The batch manager is used to merge mesh instances in the scene, which reduces the overall number of draw calls, thereby boosting performance.
The current fill mode of the canvas. Can be:
The current resolution mode of the canvas, Can be:
Apply scene settings to the current scene. Useful when your scene settings are parsed or generated from a non-URL source.
The scene settings to be applied.
The physics settings to be applied.
The rendering settings to be applied.
const settings = {
physics: {
gravity: [0, -9.8, 0]
},
render: {
fog_end: 1000,
tonemapping: 0,
skybox: null,
fog_density: 0.01,
gamma_correction: 1,
exposure: 1,
fog_start: 1,
global_ambient: [0, 0, 0],
skyboxIntensity: 1,
skyboxRotation: [0, 0, 0],
fog_color: [0, 0, 0],
lightmapMode: 1,
fog: 'none',
lightmapMaxResolution: 2048,
skyboxMip: 2,
lightmapSizeMultiplier: 16
}
};
app.applySceneSettings(settings);
Load the application configuration file and apply application properties and fill the asset registry.
The URL of the configuration file to load.
The Function called when the configuration file is loaded and parsed (or an error occurs).
Draws a single line. Line start and end coordinates are specified in world-space. The line will be flat-shaded with the specified color.
The start world-space coordinate of the line.
The end world-space coordinate of the line.
Optional color: ColorThe color of the line. It defaults to white if not specified.
Optional depthTest: booleanSpecifies if the line is depth tested against the depth buffer. Defaults to true.
Optional layer: LayerThe layer to render the line into. Defaults to LAYERID_IMMEDIATE.
// Render a 1-unit long white line
const start = new pc.Vec3(0, 0, 0);
const end = new pc.Vec3(1, 0, 0);
app.drawLine(start, end);
// Render a 1-unit long red line which is not depth tested and renders on top of other geometry
const start = new pc.Vec3(0, 0, 0);
const end = new pc.Vec3(1, 0, 0);
app.drawLine(start, end, pc.Color.RED, false);
// Render a 1-unit long white line into the world layer
const start = new pc.Vec3(0, 0, 0);
const end = new pc.Vec3(1, 0, 0);
const worldLayer = app.scene.layers.getLayerById(pc.LAYERID_WORLD);
app.drawLine(start, end, pc.Color.WHITE, true, worldLayer);
Renders an arbitrary number of discrete line segments. The lines are not connected by each subsequent point in the array. Instead, they are individual segments specified by two points.
An array of points to draw lines between. Each point is represented by 3 numbers - x, y and z coordinate.
A single color for all lines, or an array of colors to color the lines. If an array is specified, number of colors it stores must match the number of positions provided.
Optional depthTest: boolean = trueSpecifies if the lines are depth tested against the depth buffer. Defaults to true.
Optional layer: Layer = ...The layer to render the lines into. Defaults to LAYERID_IMMEDIATE.
// Render 2 discrete line segments
const points = [
// Line 1
0, 0, 0,
1, 0, 0,
// Line 2
1, 1, 0,
1, 1, 1
];
const colors = [
// Line 1
1, 0, 0, 1, // red
0, 1, 0, 1, // green
// Line 2
0, 0, 1, 1, // blue
1, 1, 1, 1 // white
];
app.drawLineArrays(points, colors);
Renders an arbitrary number of discrete line segments. The lines are not connected by each subsequent point in the array. Instead, they are individual segments specified by two points. Therefore, the lengths of the supplied position and color arrays must be the same and also must be a multiple of 2. The colors of the ends of each line segment will be interpolated along the length of each line.
An array of points to draw lines between. The length of the array must be a multiple of 2.
An array of colors or a single color. If an array is specified, this must be the same length as the position array. The length of the array must also be a multiple of 2.
Optional depthTest: boolean = trueSpecifies if the lines are depth tested against the depth buffer. Defaults to true.
Optional layer: Layer = ...The layer to render the lines into. Defaults to LAYERID_IMMEDIATE.
// Render a single line, with unique colors for each point
const start = new pc.Vec3(0, 0, 0);
const end = new pc.Vec3(1, 0, 0);
app.drawLines([start, end], [pc.Color.RED, pc.Color.WHITE]);
// Render 2 discrete line segments
const points = [
// Line 1
new pc.Vec3(0, 0, 0),
new pc.Vec3(1, 0, 0),
// Line 2
new pc.Vec3(1, 1, 0),
new pc.Vec3(1, 1, 1)
];
const colors = [
// Line 1
pc.Color.RED,
pc.Color.YELLOW,
// Line 2
pc.Color.CYAN,
pc.Color.BLUE
];
app.drawLines(points, colors);
Fire an event, all additional arguments are passed on to the event listener.
Name of event to fire.
Optional arg1: anyFirst argument that is passed to the event handler.
Optional arg2: anySecond argument that is passed to the event handler.
Optional arg3: anyThird argument that is passed to the event handler.
Optional arg4: anyFourth argument that is passed to the event handler.
Optional arg5: anyFifth argument that is passed to the event handler.
Optional arg6: anySixth argument that is passed to the event handler.
Optional arg7: anySeventh argument that is passed to the event handler.
Optional arg8: anyEighth argument that is passed to the event handler.
Self for chaining.
obj.fire('test', 'This is the message');
Test if there are any handlers bound to an event name.
The name of the event to test.
True if the object has handlers bound to the specified event name.
obj.on('test', function () { }); // bind an event to 'test'
obj.hasEvent('test'); // returns true
obj.hasEvent('hello'); // returns false
Initialize the app.
Options specifying the init parameters for the app.
Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.
Optional name: stringName of the event to unbind.
Optional callback: HandleEventCallbackFunction to be unbound.
Optional scope: objectScope that was used as the this when the event is fired.
Self for chaining.
const handler = function () {
};
obj.on('test', handler);
obj.off(); // Removes all events
obj.off('test'); // Removes all events called 'test'
obj.off('test', handler); // Removes all handler functions, called 'test'
obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this
Attach an event handler to an event.
Name of the event to bind the callback to.
Function that is called when event is fired. Note the callback is limited to 8 arguments.
Optional scope: object = ...Object to use as 'this' when the event is fired, defaults to current this.
Can be used for removing event in the future.
obj.on('test', function (a, b) {
console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
const evt = obj.on('test', function (a, b) {
console.log(a + b);
});
// some time later
evt.off();
Attach an event handler to an event. This handler will be removed after being fired once.
Name of the event to bind the callback to.
Function that is called when event is fired. Note the callback is limited to 8 arguments.
Optional scope: object = ...Object to use as 'this' when the event is fired, defaults to current this.
obj.once('test', function (a, b) {
console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
obj.fire('test', 1, 2); // not going to get handled
Load all assets in the asset registry that are marked as 'preload'.
Function called when all assets are loaded.
Resize the application's canvas element in line with the current fill mode.
Optional width: numberThe width of the canvas. Only used if current fill mode is FILLMODE_NONE.
Optional height: numberThe height of the canvas. Only used if current fill mode is FILLMODE_NONE.
A object containing the values calculated to use as width and height.
Controls how the canvas fills the window and resizes when the window changes.
The mode to use when setting the size of the canvas. Can be:
Optional width: numberThe width of the canvas (only used when mode is FILLMODE_NONE).
Optional height: numberThe height of the canvas (only used when mode is FILLMODE_NONE).
Change the resolution of the canvas, and set the way it behaves when the window is resized.
The mode to use when setting the resolution. Can be:
Optional width: numberThe horizontal resolution, optional in AUTO mode, if not provided canvas clientWidth is used.
Optional height: numberThe vertical resolution, optional in AUTO mode, if not provided canvas clientHeight is used.
Sets the skybox asset to current scene, and subscribes to asset load/change events.
Asset of type skybox to be set to, or null to remove skybox.
Start the application. This function does the following:
This function is called internally by PlayCanvas applications made in the Editor but you will need to call start yourself if you are using the engine stand-alone.
app.start();
Update the application. This function will call the update functions and then the postUpdate functions of all enabled components. It will then update the current state of all connected input devices. This function is called internally in the application's main loop and does not need to be called explicitly.
The time delta in seconds since the last frame.
Updates the GraphicsDevice canvas size to match the canvas size on the document page. It is recommended to call this function when the canvas size changes (e.g on window resize and orientation change events) so that the canvas resolution is immediately updated.
Static getGet the current application. In the case where there are multiple running applications, the function can get an application based on a supplied canvas id. This function is particularly useful when the current Application is not readily available. For example, in the JavaScript console of the browser's developer tools.
Optional id: stringIf defined, the returned application should use the canvas which has this id. Otherwise current application will be returned.
The running application, if any.
const app = pc.AppBase.getApplication();
An Application represents and manages your PlayCanvas application. If you are developing using the PlayCanvas Editor, the Application is created for you. You can access your Application instance in your scripts. Below is a skeleton script which shows how you can access the application 'app' property inside the initialize and update functions:
If you are using the Engine without the Editor, you have to create the application instance manually.