Project Template Selection

When initiating a new project, opt for the UI template rather than the game template. The game template omits theme configurations and certain EUI components. To implement custom UI elements with the game template, you must manually create a default.thm.json file, which follows a specific format. The UI template provides the same game development capabilities while including necessary UI infrastructure.

Main Class Implementation Details

The UI project's main class extends eui.UILayer, whereas the game project's main class extends egret.DisplayObjectContainer. This architectural difference means the game project uses event listeners to monitor when the scene is added to the stage:

this.once(egret.Event.ADDED_TO_STAGE, this.onAddToStage, this);

In contrast, UI projects utilize the createChildren method for initialization.

Lifecycle Management

The lifecycle management code should not be removed. It's essential for pausing engine updates when the application moves to the background:

egret.lifecycle.addLifecycleListener((context) => {
  // Custom lifecycle handling
});

egret.lifecycle.onPause = () => {
  egret.ticker.pause();
};

egret.lifecycle.onResume = () => {
  egret.ticker.resume();
};

Resource Mapping Configuration

Resource mapping registration is mandatory for establishing connections between string identifiers and file paths in default.res.json:

const resourceHandler = new AssetAdapter();
egret.registerImplementation("eui.IAssetAdapter", resourceHandler);
egret.registerImplementation("eui.IThemeAdapter", new ThemeAdapter());

Removing these registrations breaks EUI and EXML functionality, causing resource loading sequence issues.

Asynchronous Programming Patterns

The async and await keywords must be used together to transform asynchronous operations into sequential execution flows. This approach ensures APIs requiring event validation execute in order, continuing only after successful completion or failure.

EUI Component and EXML Creation

Egret Wing provides a visual editor accessible through EXML file creation. Creating EUI components can include associated EXML files, automatically linking them in default.thm.json. This eliminates the need to manually set skinName properties.

EXML Resource Integration

EXML visual editing supports both individual images and texture atlases. Resources are sourced from the preload group defined in default.res.json. While manual source assignment is possible (source = "image-name"), drag-and-drop functionality from the resource panel is more convenient.

Common issues include invisible resources due to collapsed panel views and loading failures from missing resource mapping configurations.

Component ID Referencing

Component IDs defined in EXML become accessible as class variables in corresponding EUI classes. The partAdded method executes after childrenCreated, ensuring proper internal object handling. Incorrect timing can be temporarily mitigated with delayed execution timers, though proper resource mapping resolves the root cause.

Display Object Positioning

Creating numerous DisplayObjectContainer and Bitmap instances may cause rendering anomalies or interfere with other display elements. Delaying object creation until the final scene setup phase can prevent these conflicts.

Library Architecture

Egret represents the core library foundation, while EUI extends Egret with EXML component skinning capabilities. All EUI objects support addChild operations.

Tween Animation Behavior

Although the heartbeat mechanism pauses updates during suspension, Tween animations may continue internally in certain scenarios, resulting in unexpected animation states upon resumption. This behavior may vary between desktop and mobile environments.

Event-Tween Integration

When using Tweens within event handlers with completion callbacks, event parameters are not persistently available. By the time the callback executes, the event object has been garbage collected. To access event data in callbacks, pass required values through the callback's parameter arguments rather than attempting to reference the event object directly.