engine/docs/en/core/engine.md

order, title, type, label

order	title	type	label
0	Engine	Core	Core

Engine plays the role of the main controller in the Galacean Engine, mainly including functions such as canvas, render control, and engine subsystem management:

• Canvas: Operations related to the main canvas, such as modifying the canvas width and height.
• Render Control: Controls the execution/pause/resume of rendering, vertical synchronization, and other functions.
• Engine Subsystem Management:
  • Scene Management
  • Resource Management
  • Physics System
  • Interaction System
  • XR System
• Execution Environment Context Management: Controls the context management of execution environments such as WebGL.

Initialization

To facilitate users to directly create a web engine, Galacean provides WebGLEngine:

const engine = await WebGLEngine.create({ canvas: "canvas" });

WebGLEngine supports WebGL1.0 and WebGL2.0. It can control all behaviors of the canvas, as well as resource management, scene management, execution/pause/resume, vertical synchronization, and other functions. WebGLEngine.create. Below is the type description of the configuration passed in when creating the engine:

---
title: WebGLEngineConfiguration Interface
---
classDiagram
    EngineConfiguration <|-- WebGLEngineConfiguration
    class EngineConfiguration {
       <<interface>>
       +IPhysics physics
       +IXRDevice xrDevice
       +ColorSpace colorSpace
       +IShaderLab shaderLab
       +IInputOptions input
    }

    class WebGLEngineConfiguration{
        <<interface>>
        +HTMLCanvasElement | OffscreenCanvas | string canvas
        +WebGLGraphicDeviceOptions graphicDeviceOptions
    }

Projects exported by the editor usually automatically set the relevant options configured by the editor. For example, developers can set the rendering configuration of the context in the export interface:

Or select the physics backend and XR backend in the project settings interface of the editor:

You can also modify the code to change the engine configuration. Take canvas transparency as an example. By default, the engine enables the transparency channel of the canvas, which means the canvas will blend with the elements behind it. If you need to disable transparency, you can set it like this:

const engine = await WebGLEngine.create({
  canvas: htmlCanvas,
  graphicDeviceOptions: { alpha: false }
});

Similarly, you can use webGLMode to control WebGL1/2. Properties other than webGLMode will be passed to the context. For details, refer to getContext parameter explanation.

For more related configuration information, refer to Physics System, Interaction System, XR System.

Properties

Property Name	Property Description
time	Engine time-related information. For details, refer to Time
vSyncCount	Vertical synchronization refresh rate. The engine enables vertical synchronization by default, and the refresh rate vSyncCount is 1 (consistent with the screen refresh rate). If vSyncCount is set to 2, the engine updates once every 2 frames of screen refresh.
resourceManager	Resource manager, generally used for loading and releasing assets
sceneManager	Scene manager. Galacean supports rendering multiple scenes simultaneously. The scene manager can be used to conveniently manage the addition, deletion, modification, and query of the current scene. For details, refer to Scene
inputManager	Interaction manager, generally used to obtain keyboard, touch, and scroll information. For details, refer to Interaction

Refresh Rate

By default, the engine uses vertical synchronization mode and controls the rendering refresh rate with vSyncCount. In this mode, the rendered frame will wait for the screen's vertical sync signal. vSyncCount represents the desired number of screen sync signals between rendered frames. The default value is 1, and this property must be an integer. For example, if we want to render 30 frames per second on a device with a screen refresh rate of 60 frames, we can set this value to 2.

Additionally, users can disable vertical synchronization by setting vSyncCount to 0 and then setting targetFrameRate to the desired frame rate. In this mode, rendering does not consider the vertical sync signal. For example, 120 means 120 frames, i.e., the expectation is to refresh 120 times per second.

// 垂直同步
engine.vSyncCount = 1;
engine.vSyncCount = 2;

// 非垂直同步
engine.vSyncCount = 0;
engine.targetFrameRate = 120;

⚠️ It is not recommended to use non-vertical synchronization

Methods

Method Name	Description
run	Execute engine rendering frame loop
pause	Pause engine rendering frame loop
resume	Resume engine rendering loop
destroy	Destroy the engine