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 Galacean Engine, mainly including three major functions: 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 rendering execution/pause/resume, vertical synchronization, and other functions.
• Engine Subsystem Management:
  • Scene Management
  • Resource Management
  • Physics System
  • Interaction System
  • XR System
• Context Management for Execution Environment: Controls the context management of WebGL and other execution environments.

Initialization

To facilitate users in creating a web-based engine directly, Galacean provides WebGLEngine:

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

WebGLEngine.create not only instantiates the engine but also handles rendering context configuration and initialization of certain subsystems.

Rendering Context

Developers can set the context's rendering configuration in the Export Interface.

You can also manage this by setting the third parameter WebGLGraphicDeviceOptions of WebGLEngine, for example, to manage canvas transparency, the engine by default enables the canvas's alpha channel, meaning the canvas will blend with the elements behind it. If you need to disable transparency, you can do so like this:

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

Similarly, you can control WebGL1/2 with webGLMode, and attributes other than webGLMode will be passed to the context. For more details, refer to the getContext parameter interpretation.

Physics System

Refer to the Physics System documentation.

Interaction System

Refer to the Interaction System documentation.

XR System

Refer to the XR System documentation.

Properties

Property Name	Property Description
time	Information related to engine time.
vSyncCount	By default, the engine enables vertical synchronization with a refresh rate vSyncCount of 1, meaning it synchronizes with the screen refresh rate. If vSyncCount is set to 2, the engine updates every 2 frames.
resourceManager	Resource management.
sceneManager	Scene management. Engine serves as the main controller, Scene acts as a scene unit for easy entity management in large scenes; Camera is a component attached to a specific entity in Scene, similar to a real camera, allowing you to capture any entity in the Scene and render it to a screen area or off-screen rendering.
inputManager	Interaction management.

Refresh Rate

By default, the engine uses vertical synchronization mode and vSyncCount to control the rendering refresh rate. In this mode, the rendering frame waits for the vertical synchronization signal of the screen. vSyncCount represents the expected number of screen synchronization signals between rendering frames, with a default value of 1. The value of 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.

Users can also disable vertical synchronization by setting vSyncCount to 0 and then setting targetFrameRate to the desired frame rate value. In this mode, rendering does not consider vertical synchronization signals. For example, setting it to 120 means expecting 120 frames 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	Method Description
run	Execute engine frame loop
pause	Pause engine frame loop
resume	Resume engine rendering loop
destroy	Destroy the engine