目录

gamePerformance (Game Scene Perception)

This module provides the game scene perception capability of Game Service Kit.

Model restriction: APIs of this module can be used only in the stage model.

Since: 5.0.0(12)

Modules to Import

import { gamePerformance } from '@kit.GameServiceKit';

DeviceInfo

Device information class.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.0(12)

Name Type Read-Only Optional Description
tempLevel number No No

Temperature control level. The suggestions for different levels are as follows:

1: No action is required.

2: You are advised to lower the specifications for services that are not perceivable to users, such as slowing down background updates or deferring execution.

3: You are advised to suspend services that are not perceivable to users and lower the specifications for the game's non-core services, such as slowing down foreground updates.

4: You are advised to lower the game effects, resolution, and image quality.

5: You are advised to lower the specifications in all scenes, and further lower the resolution and image quality.

6: You are advised to lower the game specifications to the minimum level.
gpuInfo GpuInfo No Yes GPU performance information.
thermalInfo ThermalInfo No Yes

Temperature change trend data.

Since: 5.0.1(13)

GpuInfo

GPU performance information class.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.0(12)

Name Type Read-Only Optional Description
gpuLoadLevel number No Yes Overall GPU load level. There are 10 levels from 1 to 10. The greater the value, the higher the load level.
vertexLoadLevel number No Yes Vertex processing load level. There are 10 levels from 1 to 10. The greater the value, the higher the load level.
fragmentLoadLevel number No Yes Fragment processing load level. There are 10 levels from 1 to 10. The greater the value, the higher the load level.
textureLoadLevel number No Yes Texture processing load level. There are 10 levels from 1 to 10. The greater the value, the higher the load level.
bandwidthLoadLevel number No Yes Bandwidth load level. There are 10 levels from 1 to 10. The greater the value, the higher the load level.
currentFrequency number No Yes

Current frequency of the GPU, in kHz.

Since: 5.0.2(14)

ThermalInfo

Temperature change trend data class.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.1(13)

Name Type Read-Only Optional Description
thermalMargin number No Yes

Time margin, that is, the time required to reach a specified temperature control level, in seconds.

NOTE

- If the value exceeds 60, the reliability decreases.

- 0: The specified temperature control level is reached.

- -1: The specified level cannot be reached.

- -2: The specified level is lower than the current level.
thermalTrend number No Yes Temperature trend. The value range is [–100, 100]. A negative value indicates a decrease in temperature, and a larger absolute value indicates a faster rate of temperature change.

BaseGameInfo

Basic game information class.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.0(12)

Name Type Read-Only Optional Description
messageType number No No

Message type.

0: a game package message, corresponding to GamePackageInfo.

1: a game configuration message, corresponding to GameConfigInfo.

2: a game scene message, corresponding to GameSceneInfo.

3: a game network status message, corresponding to GameNetInfo.

4: a game player message, corresponding to GamePlayerInfo.
extra string No Yes Extended parameter, which is a JSON character string and is used to transfer extended game information. The value length range is [0, 128].

GamePackageInfo

Game package information class, which is inherited from BaseGameInfo.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.0(12)

Name Type Read-Only Optional Description
bundleName string No No Game package name. The value can contain a maximum of 128 characters and cannot be empty.
appVersion string No No Game version number. The value length range is [1, 64].
engineType number No Yes

Game engine type.

1: Unity

2: Unreal4

3: Messiah

4: Cocos

200: others
engineVersion string No Yes Game engine version number. The value length range is [0, 64].
gameType number No Yes

Game type.

1: multiplayer online battle arena (MOBA)

2: role-playing game (RPG)

3: first-person shooter (FPS)

4: fight technology game (FTG)

5: racing game (RAC)

200: others
vulkanSupported boolean No Yes

Indicates whether Vulkan is supported.

- true: yes

- false: no

The default value is false.

GameConfigInfo

Game configuration class, which is inherited from BaseGameInfo.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.0(12)

Name Type Read-Only Optional Description
maxPictureQualityLevel number No No

Supported highest image quality level.

1: smooth

2: balancing

3: HD

4: HDR

5: UHD
currentPictureQualityLevel number No No

Current level of the image quality.

1: smooth

2: balancing

3: HD

4: HDR

5: UHD
maxFrameRate number No No Maximum frame rate, in fps.
currentFrameRate number No No Current frame rate, in fps. The value range is [1, 144].
maxResolution string No No Supported maximum resolution, which is in AxB format, for example, 1260x1980. The value length range is [1, 32].
currentResolution string No No Current resolution, which is in AxB format, for example, 1260x1980. The value length range is [1, 32].
antiAliasing boolean No No

Indicates whether to enable anti-aliasing.

- true: yes

- false: no

The default value is false.
shadow boolean No No

Indicates whether to enable the shadow effect.

- true: yes

- false: no

The default value is false.
multithreading boolean No No

Indicates whether to enable multi-threading.

- true: yes

- false: no

The default value is false.
particle boolean No No

Indicates whether to enable the particle effect.

- true: yes

- false: no

The default value is false.
hdMode boolean No No

Indicates whether to enable the HD mode.

- true: yes

- false: no

The default value is false.

GameSceneInfo

Game scene information class, which is inherited from BaseGameInfo.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.0(12)

Name Type Read-Only Optional Description
sceneID number No No

Game scene ID.

0: scene switchback, indicating the end of the current scene

1: game startup

2: in-game update

3: sign-in

4: home screen

5: game loading (performed by the player)

6: game loading (waiting for others after the user has finished loading)

7: gaming

8: onlooker mode

(Special game scenes are custom-coded from 100 onward.)

Note: You are advised to use subSceneID to specify custom game scenes.
description string No Yes Custom game scene description. The value length range is [0, 128].
subSceneID number No Yes Custom game sub-scene ID.
subDescription string No Yes Custom sub-scene description. The value length range is [0, 128].
importanceLevel number No No Importance of a game scene. The value ranges from 1 to 5. The greater the value, the higher the importance level.
sceneFrequency number No Yes Number of times a scene occurs in a round of a game.
sceneTime number No Yes Duration of a scene, in milliseconds.
recommendedCpuLevel number No Yes

CPU level recommended by the game in a scene.

1: low

2: middle

3: high
recommendedGpuLevel number No Yes

GPU level recommended by the game in a scene.

1: low

2: middle

3: high
recommendedDdrLevel number No Yes

DDR level recommended by the game in a scene.

1: low

2: middle

3: high
recommendedFps number No Yes Target frame rate recommended by the game in a scene, in fps.
maxFps number No Yes Maximum frame rate of a scene, in fps.
currentFps number No Yes Current frame rate of a scene, in fps.
keyThread string No Yes

Key thread of a scene.

- render: render thread

- logic: logic thread

- net: network thread

The value is in render|xxx|logic|xxx format. The value length range is [0, 32].
drawCallCount number No Yes Average number of draw calls per frame in a scene.
vertexCount number No Yes Average number of model vertices per frame in a scene.
triangleCount number No Yes Average number of model triangles per frame in a scene.
shaderCount number No Yes Average number of shaders per frame in a scene.
textureCount number No Yes Average number of textures per frame in a scene.
meshCount number No Yes Average number of meshes per frame in a scene.
channelCount number No Yes Number of render channels per frame in a scene.
participantCount number No Yes Number of players on the same screen in a scene.

GameNetInfo

Game network information class, which is inherited from BaseGameInfo.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.0(12)

Name Type Read-Only Optional Description
netLatency string No No

Network latency in a game scene, including the overall, uplink, downlink, and server processing time.

The unit is ms. The value length range is [1, 128].

The value should be in the format 10,20,30,40 (formats 10, 10,20, or 10,20,30 are also allowed) and will be parsed in a fixed sequence, corresponding to the overall, uplink, downlink, and server processing time.
netLoad number No Yes

Game network load level.

1: light load

2: medium load

3: heavy load

GamePlayerInfo

Game player information class, which is inherited from BaseGameInfo.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.0(12)

gamePlayerId, teamPlayerId, and thirdOpenId cannot be empty at the same time.

Name Type Read-Only Optional Description
gamePlayerId string No Yes Game player ID. The value length range is [0, 256].
teamPlayerId string No Yes Team player ID. The value length range is [0, 256].
thirdOpenId string No Yes Official game account ID. The value length range is [0, 128].

DeviceInfoParameter

Device status information parameter class.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.1(13)

Name Type Read-Only Optional Description
deviceInfoType DeviceInfoType No No Device status information type.
parameters Record<string, string> No Yes

Device status information parameter.

NOTE

This parameter can be passed only when deviceInfoType is set to DeviceInfoType.THERMAL.

- This parameter must be empty when deviceInfoType is set to DeviceInfoType.GPU.

- This parameter can be empty or set to a value when deviceInfoType is set to DeviceInfoType.THERMAL.

- The value of key is fixed at DeviceInfoParameterKey.THERMAL_TEMP_LEVEL.

- value indicates the specified temperature control level. For details, please refer to Temperature Control Level. If no value is passed to this parameter, the default temperature control level is used.

DeviceInfoType

Enumeration object of the device status information type.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.1(13)

Name Value Description
THERMAL 1 Temperature change trend data.
GPU 2 GPU load.

DeviceInfoParameterKey

Enumeration object of the device status information parameter key value.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.1(13)

Name Value Description
THERMAL_TEMP_LEVEL 'tempLevel' Temperature control level.

GameCustomTag

Enumeration object of the tags of custom game data.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.1.0(18)

Name Value Description
CRASH 1 Crash.

GamePerformanceErrorCode

Game Service Kit error code class.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.0(12)

For details about the error codes, please refer to ArkTS API Error Codes.

Name Value Description
INTERNAL_ERROR 1010300001 Internal system error.
AUTH_FAILED 1010300002 Authentication failure.
INVALID_REQUEST 1010300003 Invalid request.

gamePerformance.init

init(gamePackageInfo: GamePackageInfo): Promise<void>

Initializes the game scene perception module when a game is launched. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
gamePackageInfo GamePackageInfo Yes Game package information class.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

ID Error Message
401 The parameter check failed.
1010300002 Auth failed.

Example:

import { gamePerformance } from '@kit.GameServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

let gamePackageInfo: gamePerformance.GamePackageInfo = {
  messageType: 0,
  bundleName: 'com.example.demo', // Replace it with the actual game package name.
  appVersion: '1.0'
};
try {
  gamePerformance.init(gamePackageInfo).then(() => {
    // Initialization succeeded.
    hilog.info(0x0001, 'demo', `Succeeded in initializing.`);
  });
} catch (error) {
  // Initialization failed.
  let err = error as BusinessError;
  hilog.error(0x0001, 'demo', `Failed to initialize. Code: ${err.code}, message: ${err.message}`);
}

gamePerformance.updateGameInfo

updateGameInfo<T extends BaseGameInfo>(gameInfo: T): Promise<void>

Updates game information. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
gameInfo T Yes Basic game information. T is the component attribute type inherited from BaseGameInfo.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

ID Error Message
401 The parameter check failed.
1010300003 Invalid request.

Example:

// Updating game scene information is used as an example.
import { gamePerformance } from '@kit.GameServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

let gameSceneInfo: gamePerformance.GameSceneInfo = {
  messageType: 2,
  sceneID: 7,
  importanceLevel: 4
};
try {
  gamePerformance.updateGameInfo(gameSceneInfo).then(() => {
    // The game scene information is successfully updated.
    hilog.info(0x0001, 'demo', `Succeeded in updating.`);
  });
} catch (error) {
  // Failed to update the game scene information.
  let err = error as BusinessError;
  hilog.error(0x0001, 'demo', `Failed to update. Code: ${err.code}, message: ${err.message}`);
}

gamePerformance.on('deviceStateChanged')

on(type: 'deviceStateChanged', callback: Callback<DeviceInfo>): void

Subscribes to device status changes. This API uses an asynchronous callback to return the result.

Mali series GPUs do not support GPU performance information collection.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Type of the event to listen for. Currently, only deviceStateChanged event is supported.
callback Callback<DeviceInfo> Yes Callback used to return device information.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

ID Error Message
401 The parameter check failed.

Example:

import { gamePerformance } from '@kit.GameServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

function onDeviceStateChange(data:gamePerformance.DeviceInfo) {
  // Device details.
  hilog.info(0x0001, 'demo', `device state changed. tempLevel is ${data.tempLevel}`);
}

// Subscribe to the deviceStateChanged event.
try {
  gamePerformance.on('deviceStateChanged', onDeviceStateChange);
} catch (error) {
  // Subscription failed.
  let err = error as BusinessError;
  hilog.error(0x0001, 'demo', `Failed to subscribe. Code: ${err.code}, message: ${err.message}`);
}

gamePerformance.on('deviceStateChanged')

on(type: 'deviceStateChanged', callback: Callback<DeviceInfo>, scope: Array<DeviceInfoType>): void

Subscribes to device status changes as required. This API uses an asynchronous callback to return the result.

Mali series GPUs do not support GPU performance information collection.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.1(13)

Parameters

Parameter Type Mandatory Description
type string Yes Type of the event to listen for. Currently, only deviceStateChanged event is supported.
callback Callback<DeviceInfo> Yes Callback used to return device information.
scope Array<DeviceInfoType> Yes Type of the device status information to be subscribed to.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

ID Error Message
401 The parameter check failed.
1010300003 Invalid request.

Example:

import { gamePerformance } from '@kit.GameServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

function onDeviceStateChange(data:gamePerformance.DeviceInfo) {
  // Device details.
  hilog.info(0x0001, 'demo', `device state changed. tempLevel is ${data.tempLevel}`);
}

// Subscribe to the deviceStateChanged event.
try {
  let types:Array<gamePerformance.DeviceInfoType> = [gamePerformance.DeviceInfoType.GPU];
  gamePerformance.on('deviceStateChanged', onDeviceStateChange, types);
} catch (error) {
  // Subscription failed.
  let err = error as BusinessError;
  hilog.error(0x0001, 'demo', `Failed to subscribe. Code: ${err.code}, message: ${err.message}`);
}

gamePerformance.off('deviceStateChanged')

off(type: 'deviceStateChanged', callback?: Callback<DeviceInfo>): void

Unsubscribes from device status changes. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Type of the event to listen for. Currently, only deviceStateChanged event is supported.
callback Callback<DeviceInfo> No

Callback used to return device information.

If this parameter is specified, the corresponding callback subscription will be canceled. If this parameter is empty, all callback subscriptions for the deviceStateChanged event will be canceled.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

ID Error Message
401 The parameter check failed.

Example:

import { gamePerformance } from '@kit.GameServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

function onDeviceStateChange(data:gamePerformance.DeviceInfo) {
  // Device details.
  hilog.info(0x0001, 'demo', `device state changed. tempLevel is ${data.tempLevel}`);
}

// Unsubscribe from the deviceStateChanged event.
try {
  gamePerformance.off('deviceStateChanged', onDeviceStateChange);
} catch (error) {
  // Unsubscription failed.
  let err = error as BusinessError;
  hilog.error(0x0001, 'demo', `Failed to unsubscribe. Code: ${err.code}, message: ${err.message}`);
}

// Cancel all callback subscriptions for the deviceStateChanged event.
try {
  gamePerformance.off('deviceStateChanged');
} catch (error) {
  // Unsubscription failed.
  let err = error as BusinessError;
  hilog.error(0x0001, 'demo', `Failed to unsubscribe. Code: ${err.code}, message: ${err.message}`);
}

gamePerformance.getDeviceInfoByScope

getDeviceInfoByScope(scope: Array<DeviceInfoParameter>): Promise<DeviceInfo>

Device status query. This API uses a promise to return the result.

Mali series GPUs do not support GPU performance information collection.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.0.1(13)

Parameters

Parameter Type Mandatory Description
scope Array<DeviceInfoParameter> Yes Device status information parameter.

Return value

Type Description
Promise<DeviceInfo> Promise used to return the device status information.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

ID Error Message
401 The parameter check failed.
1010300003 Invalid request.

Example:

import { gamePerformance } from '@kit.GameServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

// Query device status.
try {
  let gpuParam: gamePerformance.DeviceInfoParameter = {
    deviceInfoType: gamePerformance.DeviceInfoType.GPU
  };
  let thermalParam: gamePerformance.DeviceInfoParameter = {
    deviceInfoType: gamePerformance.DeviceInfoType.THERMAL
  };
  let gameInfos: Array<gamePerformance.DeviceInfoParameter> = [gpuParam, thermalParam];
  gamePerformance.getDeviceInfoByScope(gameInfos).then((deviceInfo:gamePerformance.DeviceInfo) => {
    hilog.info(0x0001, 'demo', `Succeeded in querying device info. tempLevel is ${deviceInfo.tempLevel}`);
  });
} catch (error) {
  // Query failed.
  let err = error as BusinessError;
  hilog.error(0x0001, 'demo', `Failed to query. Code: ${err.code}, message: ${err.message}`);
}

gamePerformance.addGameCustomData

addGameCustomData(data: Record<string, string>, tag: GameCustomTag): void

Reports the game's custom data with tags.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.GameService.GamePerformance

Since: 5.1.0(18)

Parameters

Parameter Type Mandatory Description
data Record<string, string> Yes

Custom data. The value length range of the key is [0, 128], the value length range of the value is [0, 1024], and the number of records reported at a time can range from 1 to 100.

Data can be reported multiple times, but the total length of keys and values that have already been reported must not exceed 128,000 characters.
tag GameCustomTag Yes Custom tag.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 3. Parameter verification failed.
1010300003 Invalid request.

Example:

import { gamePerformance } from '@kit.GameServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

// Report the game's custom data with the crash tag.
try {
  let data:Record<string, string> = {'custom':'gaming'};
  gamePerformance.addGameCustomData(data, gamePerformance.GameCustomTag.CRASH);
} catch (error) {
  // Failed to report custom data.
  let err = error as BusinessError;
  hilog.error(0x0001, 'demo', `Failed to add custom data. Code: ${err.code}, message: ${err.message}`);
}