Optimizing PlayCanvas Performance

Profile with the Built-In Profiler

PlayCanvas includes a profiler overlay that displays real-time performance metrics during gameplay. Access it by adding ?profile=true to your game's URL or pressing the tilde key in development builds. The profiler shows frame time (the total time to process and render each frame), draw call count, shader compilation count, triangle count, texture memory usage, and a frame time graph that visualizes performance over time.

The frame time is the single most important metric. To achieve 60fps, each frame must complete in under 16.67 milliseconds. For 30fps, the budget is 33.33ms. The profiler breaks frame time into categories: update (your scripts and physics), render (draw calls and GPU work), and other (asset loading, event processing). If update time dominates, your bottleneck is CPU-side and you need to optimize scripts or physics. If render time dominates, the GPU is the constraint and you need to reduce draw calls, simplify shaders, or lower resolution.

The browser's built-in developer tools complement the PlayCanvas profiler with detailed JavaScript profiling. Chrome DevTools' Performance tab records a timeline showing exactly which functions consume CPU time each frame. The Memory tab reveals allocation patterns and helps identify memory leaks where objects accumulate without being released. Use these tools alongside the PlayCanvas profiler for a complete picture of where time and memory are spent.

Profile on actual target devices, not just your development machine. A game that runs at 120fps on a desktop with a dedicated GPU might struggle at 20fps on a mid-range phone. Connect your mobile device to your desktop via USB and use Chrome's remote debugging feature (chrome://inspect) to profile the game running on the phone while viewing the timeline on your desktop's larger screen.

Reduce Draw Calls with Batching and Instancing

Draw calls are the most common GPU-side bottleneck in 3D web games. Each draw call is a command from the CPU to the GPU to render a specific mesh with specific settings. The overhead comes from state changes (switching shaders, textures, and uniform values), driver validation, and CPU-GPU synchronization. A desktop browser can handle 500 to 2000 draw calls at 60fps depending on the GPU, but mobile browsers often struggle above 100 to 200.

Static batching merges multiple meshes that share the same material into a single large mesh at load time. If your scene has 100 trees that all use the same bark material, static batching combines them into one mesh and renders them in a single draw call instead of 100 separate calls. Enable static batching by marking entities as "static" in the editor. The entities cannot move, rotate, or scale after batching, so use this only for environment geometry that remains fixed during gameplay.

Dynamic batching applies to small meshes that share a material but need to move independently. PlayCanvas automatically combines these into temporary batches each frame, reducing draw calls while preserving per-object transforms. Dynamic batching has a vertex count limit per batch (typically a few thousand vertices), so it works best for small objects like particles, debris, collectibles, and UI elements. Very large meshes exceed the vertex limit and render individually.

Instanced rendering handles the case where many copies of the same mesh appear in the scene with different transforms. Instead of issuing a separate draw call for each copy, instancing sends all the transform data to the GPU in a single buffer and draws every copy in one call. This is ideal for forests, grass fields, rock scattering, and crowd scenes. Enable instancing on the Render component and the engine handles the buffer management automatically.

Material consolidation reduces draw calls by sharing materials between meshes that have similar visual properties. Instead of five slightly different brown materials for different wood objects, create one wood material with subtle variation achieved through vertex colors or a tiled texture. Each unique material requires its own draw call (or batch), so fewer unique materials means fewer calls.

Optimize Textures and Materials

Textures typically account for the majority of a game's download size and GPU memory consumption. Unoptimized textures waste bandwidth, increase load times, and can push mobile devices past their VRAM limits, causing the browser to crash. Apply these optimizations systematically to every texture in your project.

Basis Universal compression reduces texture file size by 4 to 6 times compared to PNG and reduces GPU memory by 4 to 8 times compared to uncompressed RGBA. The browser decompresses Basis textures on the GPU, so the compressed data goes directly from download to GPU memory without an expensive CPU-side decompression step. Enable Basis compression in the texture asset settings for every texture that does not require exact pixel-level precision.

Texture resolution should match the visual importance and screen coverage of each asset. Hero objects that the player examines up close need 1024x1024 or 2048x2048 textures. Background elements at medium distance work fine at 512x512. Distant terrain and skybox elements rarely need more than 256x256. Review each texture's resolution relative to how it actually appears in-game and downscale oversized textures without hesitation.

Texture atlasing combines multiple small textures into a single large texture, reducing the number of texture bind operations. If multiple objects in a scene use different 256x256 textures, pack them into a single 1024x1024 atlas and adjust UV coordinates accordingly. This lets the GPU render all those objects without switching textures between draw calls, which pairs well with batching to combine both mesh and texture state changes into fewer calls.

Shader complexity affects both compilation time and per-pixel rendering cost. PlayCanvas's standard material handles most use cases with configurable feature flags. Disable material features you do not need: turn off refraction if the material is opaque, disable heightmap if you are not using parallax mapping, and skip ambient occlusion maps for objects that receive lightmaps instead. Each disabled feature removes shader instructions that would otherwise run for every pixel the material covers.

Implement Level of Detail and Culling

Level of Detail (LOD) replaces high-polygon models with simpler versions as they move farther from the camera. A character model might use 10,000 triangles at close range, 3,000 triangles at medium range, and 500 triangles in the distance. The player cannot perceive the geometric detail difference at distance, but the GPU processes fewer triangles and vertices, improving framerate in scenes with many objects.

Create LOD levels by exporting multiple versions of each model at different polygon counts from your 3D modeling tool. In PlayCanvas, use a script or the engine's LOD capabilities to swap between model assets based on the entity's distance from the camera. Calculate distance each frame (or every few frames for efficiency), and when a LOD threshold is crossed, switch the Render component's mesh asset. Add a transition zone where the current and next LOD levels overlap with alpha blending to hide the visual pop of an instant switch.

Frustum culling is enabled by default in PlayCanvas and requires no configuration. It automatically skips rendering for any entity whose bounding box falls entirely outside the camera's view frustum. Verify it is working by checking the draw call count in the profiler as you rotate the camera. The count should decrease when large portions of the scene are out of view. If it does not, check that your entities have correct bounding volumes, large models with incorrectly sized bounds may never be culled.

Draw distance limits provide a simple but effective optimization. Set a maximum distance beyond which entities are hidden entirely, either by disabling their Render component or by placing them in a group that is disabled based on camera distance. This prevents the engine from processing and rendering distant objects that contribute nothing to the player's visual experience. Combine draw distance with fog to mask the boundary where objects appear and disappear, making the transition invisible.

Optimize CPU-Side Script Performance

JavaScript's garbage collector pauses execution to reclaim unused memory, causing frame time spikes that the player perceives as stuttering. The most effective way to prevent garbage collection pauses is to avoid creating temporary objects during the update loop. Instead of creating new Vec3 or Quat objects every frame for calculations, allocate them once during initialize and reuse them. Store scratch vectors and matrices as script properties rather than local variables that get discarded each frame.

Throttle expensive calculations that do not need to run every frame. An NPC's vision check might run every 5 frames instead of every frame, since the player's position changes incrementally. Stagger calculations across entities so that not all NPCs check vision on the same frame, distributing the CPU load evenly. Use a frame counter modulo the throttle interval to determine which entities update on which frames.

Object pooling reuses entity instances instead of creating and destroying them repeatedly. Projectiles, particles, enemies, and collectibles that spawn and despawn frequently should be pooled. Create a fixed number of entities at startup, deactivate them in the pool, and reactivate them when needed. When they are no longer needed, deactivate and return them to the pool. This eliminates both the allocation cost of creating entities and the garbage collection cost of destroying them.

Physics optimization reduces CPU time for collision detection and simulation. Limit the number of active rigid bodies to what the scene actually needs. Disable physics on entities that are too far from the player to matter. Use the simplest collision shapes that produce acceptable gameplay (boxes and spheres are much faster than mesh collisions). Reduce the physics simulation rate in settings if your game does not require the default 60Hz precision, as 30Hz provides acceptable results for many game types while halving the physics CPU cost.

Event listener cleanup prevents accumulating stale callbacks that continue executing after the subscribing entity is logically done with them. Always remove event listeners in the script's destroy method. Leaked listeners not only waste CPU time on callbacks that serve no purpose but can also cause errors when they reference entities that no longer exist in the scene.