Understanding performance

If your game is running slow, the first step should be to understand why. Performance could relate to many things, however in this context it refers to rendering and efficient hardware utilization.

Show stats in game

You can show stats including by enabling the stats panel to get an initial understanding.

• FPS - How many frames are rendered per second. The upper limit is based on your monitor's refresh rate.

• MS - The number of milliseconds it takes to process each frame on the CPU. This includes your game play code as well as internal engine code. To achieve 60 FPS, you only have about 16 milliseconds to spare and some needs to be available for the GPU to render as well. Look out for spikes in this metric as it can result in dropping frames which leads to a bad player experience.

• MB - How much memory is currently being used for your rendered assets including geometries and textures.

• Calls - The number of draw calls each frame. A draw call is an instruction sent from the CPU to the GPU to draw something. Each mesh that needs to be rendered needs at least 1 draw call unless they are batched or instanced. This metric is likely related to the amount of objects in your scene and how varied geometries they have so it may not be related to your game play code unless you are creating a lot of objects. To ensure your game works well even on mid-tier mobile devices, try to aim for less than 150 draw calls.

• Triangles - The number of triangles rendered each frame. Similar to draw calls, this is mostly related to your scene and assets used, not necessarily your game play code.

Show the stats panel by settings showStats to true on the ViewController service.

@Service()
class Game extends GameInstance {
  private view = inject(ViewController)

  onStart(): void | Promise<void> {
    this.view.showStats = true
  }
}

Make sure to only enable this for testing so you don't include it in the released game. Alternatively, add a keyboard shortcut for showing or hiding the stats in the game.

An alternative is to use the web browser's console to enable it using the following code.

hology_view.showStats = true

CPU or GPU bottleneck

One of the first things to check when trying to understand performance problems is if it due to CPU or GPU usage. In the stats panel, you can see in the MS (CPU) metric if it is high. If you are dropping frames and this metric exceeds 16 ms (in case your target frame rate is 60 fps), then the problem is likely due to processing on the CPU and otherwise the GPU. You can also open the task manager (Windows) or activity monitor (MacOS) to check the usage of the CPU and GPU. If your GPU usage is 100%,

CPU problems

• Expensive geometry calculations - Game play code often involves a lot of geometry related math and algorithms, which can be expensive if done in excess. This includes for example raycasts and collision detection. Avoid doing this when necessary by adopting smarter algorithms and optimizations such as spatial partitioning to only process what is necessary for the player experience. If you absolutely need to do a lot of processing, you may choose to offload this to web workers or GPU compute.

• Garbage collection - If you are creating a lot of temporary objects in memory for every render update, they eventually have to be cleaned up which may block the main thread and therefore rendering and your game logic. However, this doesn't have to be an issue if you avoid making frequent new allocations. See Avoid unnecessary allocations to learn more.

GPU problems

• Unoptimized assets - Highly detailed 3D models and high resolution textures will increase the time required to render each frame. It also increases the time it takes to process and upload these assets to the GPU. Therefore, try to optimize these assets before importing them to Hology by lowering resolution of textures and using lowest acceptable compression quality.

• Draw calls - The amount of calls to render objects can reduces the workload for the GPU. The GPU works most efficiently if it can do a lot of the processing in parallel. This can be improved by reusing the same geometry with instancing or batching. Instancing is done automatically for all static objects added in a scene in Hology. However, objects that are added at runtime will not automatically be instanced for you.

• Integrated GPU - If your device is using an integrated GPU, it may not be capable of rendering highly detailed scenes at 60 FPS. If your device has both an integrated and dedicated, make sure to check that it is being used. Your web browser may choose to use the integrated GPU even if you have a dedicated GPU.