[原创]SAPI 基础教程 —— 第三期 认识更多的类
前言
上期，我们学校了SAPI的world与system类，比你简单地了解一下接口。
如何在SAPI中使用方块方法等？Block 类有什么方法与属性？
Entity类和Player类有什么内在联系？它们有共同的方法吗？它们之间又有什么不同的方法与属性？
ItemStack类是什么？怎么用SAPI创建一个物品？物品又有什么方法？
我们知道了类和其的方法，怎么使用它们呢？
本期是此教程系列的最后一期，将会讲解SAPI常用的类，并给出在编写SAPI时的一些建议。
Block类
表示世界维度中特定位置的方块，我们知道这个方块唯一的XYZ坐标值与所在维度，可用于读取或修改次位置的方块状态。
属性：
dimension：返回Dimension类，表示此方块所在的维度对象。
isAir：此方块是否为空气。返回布尔值。
isLiquid：此方块是否为流体。返回布尔值。
isSolid：此方块是否为固体，像圆石、木头这样不可以直接穿过去的就是固体，而像梯子这样就不是。返回布尔值。
isWaterlogged：此方块是否含水，比如像树叶、楼梯可含水的这样的方块。返回布尔值。
location：方块的坐标。返回Vector3类。
permutation：描述该方块的附加配置数据，即方块状态。返回BlockPermutation类
注：本段需要补充
方法：
canBeDestroyedByLiquidSpread：可以被流体破坏。参数：Water枚举，此枚举中Water: "Water"。
canContainLiquid：可包含液体。参数：Water枚举。
typeId：方块的id，返回字符串。
x/y/z分别对应方块的x y z坐标，返回整数。
方法
above：返回方块上面的方块，返回 Block类。
below：返回方块下面的方块，返回 Block类。
bottomCenter：返回此方块XZ中心的坐标，返回 Vector3。
center：返回此方块XYZ中心的坐标，返回 Vector3。
east/north/south/west：返回此方块东/北/南/西一格方块，返回 Block类。
offset：返回指定偏移处的方块。参数：Vector3偏移向量，比如偏移量为 0, 1, 0 将返回此方块上方的方块。
Entity 类与 Player 类
Entity类表示世界中一个实体的状态（一个生物、玩家或其他移动的对象例如矿车等）
Player类表示世界的一个玩家，在Entity类的基本含义中缩小范围为实体。
Entity 类与 Player 类的关系
Player类是继承于Entity类的。在Minecraft中，玩家本身就属于一种实体，有着其他很多实体一样的特性。这意味着很多方法和属性两类都可以使用。
Entity类属性：
无标注表示 Entity 类与 Player 类共有
*表示Player类特有
属性名用途返回
dimension当前实体的维度返回 Dimension类
isClimbing实体是否在攀爬返回布尔值
isFalling实体是否在坠落返回布尔值
isInWater实体是否在水中返回布尔值
isOnGround是否在实心方块上返回布尔值
isSleeping是否在睡眠返回布尔值
isSneaking是否在潜行返回布尔值
isSprinting是否在疾跑返回布尔值
isSwimming是否在游泳返回布尔值
typeId实体ID返回字符串
location实体位置返回Vector3
isEmoting*玩家是否在做表情返回布尔值
isFlying*玩家是否在飞（创造模式或旁观者模式）
isGliding*玩家是否在滑翔返回布尔值
isJumping*玩家是否在跳返回布尔值
level*玩家的等级返回整数
name*玩家的名称返回字符串
totalXpNeededForNextLevel*玩家到下一级需要的经验返回整数
xpEarnedAtCurrentLevel*玩家当前的经验返回整数
方法
Entity类具有丰富的方法，在一些方法中会有一些可选的接口选项，这些接口会在接口章详细讲解。
由于Entity类的方法很多，这里无法展示全部的方法，部分方法的解释可能不准确或在未来有所变动。
无标注表示 Entity 类与 Player 类共有
*表示Player类特有
addTag
addTag(tag: string): boolean
为实体添加标签，tag 为为实体添加的字符串
addEffect
addEffect(
effectType: string | EffectType,
duration: number,
options?: EntityEffectOptions,
): Effect
为实体添加效果。
effectType：效果名称，相关名称可见MC中文Wiki。
duration：时长，以刻为单位
options：可选的附加选项
实例：添加给实体十秒的速度一、无粒子效果
xxx.addEffect("speed", 200, {
amplifier: 1,
showParticles: false
});
applyDamage
applyDamage(
amount: number,
options?: EntityApplyDamageByProjectileOptions | EntityApplyDamageOptions,
): boolean
给予实体一定的伤害。该方法同时也可以返回实体是否可以被伤害。
amount：伤害的数值
options：可选的附加选项
实例：给予被命名为player的实体10伤害
player.applyDamage(10);
applyImpulse
applyImpulse(vector: Vector3): void
将冲量向量应用于实体的当前速度。
clearDynamicProperties
clearDynamicProperties(): void
清除实体的动态属性
clearVelocity
clearVelocity(): void
把实体的速度降为0
extinguishFire
extinguishFire(useEffects?: boolean): boolean
如果实体着火，则灭火。同时此属性也可以返回实体是否着火。
useEffects：是否显示与着火有关的动画，可选
实例：骷髅灭火
const skelly = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Skeleton, targetLocation);
skelly.setOnFire(20, true);
getTags
getTags(): string[]
获取实体的所有标签，返回字符串列表。
hasTag
hasTag(tag: string): boolean
实体是否有此标签，返回布尔值
tag：标签名
kill
kill(): boolean
杀死实体，此方法同时也可以返回实体是否不可杀死。
playAnimation
playAnimation(animationName: string, options?: PlayAnimationOptions): void
实体播放动画，动画id可以在中文Wiki中找到。
remove
remove(): void
立即将实体从世界中移除。被移除的实体不会在移除时播放死亡动画或掉落物品。
removeEffect
removeEffect(effectType: string | EffectType): boolean
移除实体的效果。如果效果已被移除，效果不存在或未找到，则返回布尔值。
effectType：效果名称
runCommand
runCommand(commandString: string): CommandResult
实体执行指令方法
commandString：指令字符串，注意：没有前面的正斜杠
setOnFire
setOnFire(seconds: number, useEffects?: boolean): boolean
设置实体着火的持续时间。
seconds：持续的秒数
实例：骷髅着火
const skelly = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Skeleton, targetLocation);
skelly.setOnFire(20, true);
teleport
teleport(location: Vector3, teleportOptions?: TeleportOptions): void
传送实体的目标位置。
location：Vector3坐标
addLevels*
addLevels(amount: number): number
为玩家添加等级。
amount：等级数值
getGameMode*
getGameMode(): GameMode
获得玩家的游戏模式，返回GameMode枚举。
getSpawnPoint*
getSpawnPoint(): DimensionLocation
获得玩家的出生点。返回Vector3
playMusic*
playMusic(trackId: string, musicOptions?: MusicOptions): void
播放音乐。
trackId：音乐ID
playSound*
playSound(soundId: string, soundOptions?: PlayerSoundOptions): void
播放音效。
soundId：音效ID
setSpawnPoint*
setSpawnPoint(spawnPoint?: DimensionLocation): void
设置玩家重生点。
spawnPoint：世界中的一个精确坐标，包括其维度和位置
以上就是实体的部分常用方法，使用这些方法，可以实现丰富的效果。
ItemStack 类
ItemStack 类定义了一组物品，可以用此类的方法来实现一些事件。
构造
当导入此类时，可初始化一个ItemStack 类，存为一个变量或存于一个需要ItemStack 类的方法。
new ItemStack(itemType: string | ItemType, amount?: number): ItemStack
itemType：物品的标识符
amount：可选，是物品的数量
当ItemStack 类被存在一个变量中，这个变量有着ItemStack 类的所有属性与方法。
属性
[世界修改]amount：物品的数量，设置为整数。
[只读]isStackable：是否可堆叠，返回布尔值。
[世界修改]keepOnDeath：死亡后保留此物品，设置为布尔值。
[只读]maxAmount：物品最大的堆叠数，比如像钻石这样的物品就会返回64，像镐子这样就会返回1。返回整数。
[世界修改]nameTag：这个物品的名称。当点击物品/鼠标悬在物品上，会显示此名称标签。
[只读]typeId：此物品的标识符。
方法
getCanPlaceOn：获取在冒险模式下此物品可以放置的方块类型列表，返回字符串列表。
getCanDestroy：获取此物品在冒险模式下可以破坏的方块类型列表，返回字符串列表。
hasTag：物品是否有某一个标签。
getTags：获得物品的所有标签，返回字符串列表，内有所有标签。
如何运用类
我们学习了类，怎么运用类呢？
我们已经知道，每个类都有一定的属性与方法。看一下以下的代码实例：
function givePlayerInSpawn(player, item) {
const pLocation = player.location;
const container1 = player.getComponent("minecraft:inventory")?.container;
if (container1?.emptySlotsCount && container1?.emptySlotsCount > 0) {
container1.addItem(item);
} else {
player.dimension.spawnItem(item, pLocation);
}
}
world.afterEvents.playerSpawn.subscribe((i3) => {
const player3 = i3.player;
givePlayerInSpawn(player3, new ItemStack("chsj:food_book", 1));
});
在这个实例事件playerSpawn初始化中，我们定义一个此事件数据事件的player，而存着i3.player 的player3，就是一个Player类。
因此，作为givePlayerInSpawn参数的player3就可以在执行函数中使用getComponent方法。
player.dimension.spawnItem 需要一个ItemStack 类，因此参数也是一个ItemStack。
在游一些方法的参数中可能会出现类作为参数，这是存这个类的变量，这个变量可能是其他类、初始化事件事件数据等的属性。部分类，比如ItemStack 类，可以直接初始化并运用在合适的方法中。
尾言
本篇教程为此系列的最后一章，有很多的SAPI知识没有讲到，因为如果都讲内容很多，本系列教程为让学习SAPI的基岩版附加包开发者更好的理解，在实际中仍需要查阅官方文档。
有一个有翻译的SAPI文档，实时更新，可见：https://projectxero.top/sapi/ 也可以用这个网站查阅。
SAPI使得Minecraft基岩版附加包实现了更多功能与特性，完成了无SAPI原版附加包添加更多的色彩。通过在自己的附加包项目中使用SAPI，为附加包添加更高级、更多的功能。
学习SAPI不是简单的，但使用它一定会使附加包更好。愿你使用SAPI创造更好的附加包！
页: [1]