跳到主要内容

记分板

本文主要记录记分板相关接口。

记分板​

Scoreboard 类​

1.4.0+
该特性在server模块脚本版本1.4.0+下可用。

表示该世界的记分板。可通过World的scoreboard属性获取。

class Scoreboard {
    private constructor();
    addObjective(objectiveId: string, displayName?: string): ScoreboardObjective;
    clearObjectiveAtDisplaySlot(displaySlotId: DisplaySlotId): ScoreboardObjective | undefined;
    getObjective(objectiveId: string): ScoreboardObjective | undefined;
    getObjectiveAtDisplaySlot(displaySlotId: DisplaySlotId): ScoreboardObjectiveDisplayOptions | undefined;
    getObjectives(): ScoreboardObjective[];
    getParticipants(): ScoreboardIdentity[];
    removeObjective(objectiveId: ScoreboardObjective | string): boolean;
    setObjectiveAtDisplaySlot(
        displaySlotId: DisplaySlotId,
        objectiveDisplaySetting: ScoreboardObjectiveDisplayOptions,
    ): ScoreboardObjective | undefined;
}

addObjective 方法​

受限执行
该属性/方法不能在受限执行模式下使用。

在记分板上新增一个记分项。

addObjective(objectiveId: string, displayName?: string): ScoreboardObjective
  • objectiveId: string，记分项的标识符。
  • displayName?: string，记分项的显示名称。若不传入则使用标识符。

返回值：ScoreboardObjective，新创建的记分项。

clearObjectiveAtDisplaySlot 方法​

受限执行
该属性/方法不能在受限执行模式下使用。

清除显示槽位中的记分项。

clearObjectiveAtDisplaySlot(displaySlotId: DisplaySlotId): ScoreboardObjective | undefined

返回值：ScoreboardObjective | undefined，原本位于该显示槽位的记分项；槽位为空时为undefined。

getObjective 方法​

按标识符返回指定的记分项。

getObjective(objectiveId: string): ScoreboardObjective | undefined
  • objectiveId: string，记分项的标识符。

返回值：ScoreboardObjective | undefined，指定的记分项；该记分项不存在时为undefined。

getObjectiveAtDisplaySlot 方法​

返回显示槽位中的记分项及显示设置。

getObjectiveAtDisplaySlot(
    displaySlotId: DisplaySlotId,
): ScoreboardObjectiveDisplayOptions | undefined

返回值：ScoreboardObjectiveDisplayOptions | undefined，该显示槽位的记分项及显示设置；槽位为空时为undefined。

getObjectives 方法​

返回全部已定义的记分项。

getObjectives(): ScoreboardObjective[]

返回值：ScoreboardObjective[]，全部记分项组成的数组；没有记分项时为空数组。

getParticipants 方法​

返回全部已定义的记分板身份。

getParticipants(): ScoreboardIdentity[]

返回值：ScoreboardIdentity[]，全部记分板身份组成的数组；没有身份时为空数组。

removeObjective 方法​

受限执行
该属性/方法不能在受限执行模式下使用。

从记分板上移除一个记分项。

removeObjective(objectiveId: ScoreboardObjective | string): boolean

返回值：boolean，true 表示移除成功；该记分项不存在时为false。

setObjectiveAtDisplaySlot 方法​

受限执行
该属性/方法不能在受限执行模式下使用。

将记分项放入显示槽位，并设置其显示方式。

setObjectiveAtDisplaySlot(
    displaySlotId: DisplaySlotId,
    objectiveDisplaySetting: ScoreboardObjectiveDisplayOptions,
): ScoreboardObjective | undefined

返回值：ScoreboardObjective | undefined，原本位于该显示槽位的记分项；槽位为空时为undefined。

ScoreboardObjective 类​

1.4.0+
该特性在server模块脚本版本1.4.0+下可用。

记分板上的一个记分项，包含显示名称与参与者的分数。

class ScoreboardObjective {
    private constructor();
    readonly displayName: string;
    readonly id: string;
    readonly isValid: boolean;
    addScore(participant: Entity | ScoreboardIdentity | string, scoreToAdd: number): number;
    getParticipants(): ScoreboardIdentity[];
    getScore(participant: Entity | ScoreboardIdentity | string): number | undefined;
    getScores(): ScoreboardScoreInfo[];
    hasParticipant(participant: Entity | ScoreboardIdentity | string): boolean;
    removeParticipant(participant: Entity | ScoreboardIdentity | string): boolean;
    setScore(participant: Entity | ScoreboardIdentity | string, score: number): void;
}

属性​

  • 只读 displayName: string，该记分项对玩家显示的名称。
  • 只读 id: string，该记分项的标识符。
  • 只读 isValid: boolean，该记分项的引用是否仍然有效。

addScore 方法​

受限执行
该属性/方法不能在受限执行模式下使用。

为指定参与者在该记分项上增加分数。

addScore(participant: Entity | ScoreboardIdentity | string, scoreToAdd: number): number
  • participant: Entity | ScoreboardIdentity | string，要增加分数的参与者，可以是实体、记分板身份或参与者名称。
  • scoreToAdd: number，要增加的分数，可以为负数。

返回值：number，增加后的分数。

getParticipants 方法​

返回该记分项的全部参与者身份。

getParticipants(): ScoreboardIdentity[]

返回值：ScoreboardIdentity[]，该记分项的参与者身份数组。

getScore 方法​

返回指定参与者在该记分项上的分数。

getScore(participant: Entity | ScoreboardIdentity | string): number | undefined
  • participant: Entity | ScoreboardIdentity | string，要查询的参与者，可以是实体、记分板身份或参与者名称。

返回值：number | undefined，该参与者的分数；该参与者不是本记分项的参与者时为undefined。

getScores 方法​

返回该记分项上所有参与者的分数。

getScores(): ScoreboardScoreInfo[]

返回值：ScoreboardScoreInfo[]，各参与者的分数信息数组。

hasParticipant 方法​

指定身份是否是该记分项的参与者。

hasParticipant(participant: Entity | ScoreboardIdentity | string): boolean
  • participant: Entity | ScoreboardIdentity | string，要检查的参与者，可以是实体、记分板身份或参与者名称。

返回值：boolean，true 表示该身份是本记分项的参与者。

removeParticipant 方法​

受限执行
该属性/方法不能在受限执行模式下使用。

从该记分项中移除一个参与者。

removeParticipant(participant: Entity | ScoreboardIdentity | string): boolean
  • participant: Entity | ScoreboardIdentity | string，要移除的参与者，可以是实体、记分板身份或参与者名称。

返回值：boolean，true 表示移除成功；该参与者不存在时为false。

setScore 方法​

受限执行
该属性/方法不能在受限执行模式下使用。

设置指定参与者在该记分项上的分数。

setScore(participant: Entity | ScoreboardIdentity | string, score: number): void
  • participant: Entity | ScoreboardIdentity | string，要设置分数的参与者，可以是实体、记分板身份或参与者名称。
  • score: number，要设置的分数。

ScoreboardScoreInfo 类​

1.4.0+
该特性在server模块脚本版本1.4.0+下可用。

某一参与者在某个记分项上的分数信息。

class ScoreboardScoreInfo {
    private constructor();
    readonly participant: ScoreboardIdentity;
    readonly score: number;
}

属性​

  • 只读 participant: ScoreboardIdentity，该分数对应的参与者身份。
  • 只读 score: number，该参与者的分数。

ScoreboardIdentity 类​

1.4.0+
该特性在server模块脚本版本1.4.0+下可用。

记分板中的一个身份，对应实体、玩家或虚拟玩家。

class ScoreboardIdentity {
    private constructor();
    readonly displayName: string;
    readonly id: number;
    readonly isValid: boolean;
    readonly "type": ScoreboardIdentityType;
    getEntity(): Entity | undefined;
}

属性​

  • 只读 displayName: string，该身份对玩家显示的名称。
  • 只读 id: number，该身份的标识符。
  • 只读 isValid: boolean，该身份的引用是否仍然有效。
  • 只读 "type": ScoreboardIdentityType，该身份的类型。

getEntity 方法​

若该身份是实体或玩家，返回它对应的实体。

getEntity(): Entity | undefined

返回值：Entity | undefined，该身份对应的实体；身份类型为虚拟玩家时为undefined。

ScoreboardObjectiveDisplayOptions 接口​

1.4.0+
该特性在server模块脚本版本1.4.0+下可用。

记分项在显示槽位中的显示方式。

interface ScoreboardObjectiveDisplayOptions {
    objective: ScoreboardObjective;
    sortOrder?: ObjectiveSortOrder;
}

属性​

DisplaySlotId 枚举​

1.4.0+
该特性在server模块脚本版本1.4.0+下可用。

记分项的显示位置。

enum DisplaySlotId {
    BelowName = "BelowName", // 显示在玩家名称下方
    List = "List", // 在暂停界面的玩家列表中显示
    Sidebar = "Sidebar", // 显示在屏幕右侧
}

ScoreboardIdentityType 枚举​

1.4.0+
该特性在server模块脚本版本1.4.0+下可用。

记分板身份的类型。

enum ScoreboardIdentityType {
    Entity = "Entity", // 普通实体
    FakePlayer = "FakePlayer", // 虚拟玩家，由命令创建
    Player = "Player", // 真实玩家
}

ObjectiveSortOrder 枚举​

1.4.0+
该特性在server模块脚本版本1.4.0+下可用。

记分项中条目的排列顺序。

enum ObjectiveSortOrder {
    Ascending = 0, // 升序，分数从小到大
    Descending = 1, // 降序，分数从大到小
}

参考文档​

本文主要参考文档如下，读者可以在这些文档获得更多信息。