Decentraland SDK 6.0 Beta 升级指南

转发自Decentraland Official公众号

在 SDK 6.0 beta 中创建场景

要使用 SDK 6.0 beta 创建新场景,请确保您已安装最新版本的 CLI,然后使用 dcl init 创建新项目。

要确保使用最新版本的 CLI,请运行:

npm install -g decentraland
将现有项目迁移到 SDK 6.0 beta

迁移到新版本步骤:

  1. 删除升级项目中的 bin 和 node_modules 文件夹

  2. 删除 package-lock.json 文件

  3. 确保在 package.json 文件中,decentraland-ecs 值为 latest

  4. 在项目目录中运行 npm install

  5. 按照以下的迁移指南进行语法更改

一般语法更改

为了保持代码的清晰明确,以下用于处理组件的命令已经重新命名。您的场景最有可能至少使用了其中的几个,因此请仔细检查代码并确保更新任何过时的命令。

Old CommandNew Command
addaddComponent
setaddComponentOrReplace
getgetComponent
getOrNullgetComponentOrNull
getOrCreategetComponentOrCreate
removeremoveComponent
hashasComponent

Old code:

const ent = new Entity()
ent.add(new GLTFShape('models/Environment.glb'))
ent.add(new Transform({
position: new Vector3(5, 0, 5)
}))
engine.addEntity(ent)

New code:

const ent = new Entity()
ent.addComponent(new GLTFShape('models/Environment.glb'))
ent.addComponent(new Transform({
position: new Vector3(5, 0, 5)
}))
engine.addEntity(ent)

提示:您可以对项目使用查找和替换命令,以确保代码使用正确的命令和术语。不过要注意, set 也可以用于设置特定位置、旋转或缩放,该命令并没有改动。如:myTransformComponent.position.set(5, 0, 5)

更大的地块

Decentraland 的每块土地大小现在是 16米 x 16米(以前是 10 x 10)。所以有了更多的空间来容纳场景中的内容!请注意,最大多边形的限制是基于土地的数量,而不是面积,因此这些限制还是跟原来一样。

由于地块场景的尺寸为 16 x 16,因此现在场景的中心坐标为(8, 0, 8)。根据场景的内容,可以按 1.6 倍数缩放所有实体来填满整个空间。当然,您也可以增加新的内容来填充空白区域。

3D 模型旋转

我们更改了 SDK 内部所有 3D 模型的旋转设置,采用了跟大多数其他平台一致的标准。这意味着场景中的任何 3D 模型现在都将面向后渲染,沿 Y 轴旋转 180 度。所有必须重新定位或旋转实体以补偿这个旋转。

如果您使用 lookAt 函数来设置实体的旋转,请记住以前实体的前端现在在它的后面了。我们建议您在 Blender 等外部工具中编辑 3D 模型,使其面向 Y 轴的相反方向。

动画

3D 模型动画现在由单独的 Animator 组件处理,而不是由 GLTFModel 组件处理。

此外,我们已将 AnimationClip 对象重命名为 AnimationState,以避免与 glTF 文件中的动画片段混淆。

Old code:

let shark = new Entity()
shark.add(new GLTFShape("models/shark.gltf"))
let clipSwim = shark.get(GLTFShape).getClip("swim")
clipSwim.play()
engine.addEntity(shark)

New code:

let shark = new Entity()
shark.addComponent(new GLTFShape("models/shark.gltf"))
const animator = new Animator()
shark.addComponent(animator)
let clipSwim = new AnimationState("swim")
animator.addClip(clipSwim)
clipSwim.play()
engine.addEntity(shark)

请在开发文档中阅读有关此内容的更多信息,或查看使用此功能的示例场景。

声音

声音现在由必须添加到实体的 SoundSource 组件处理。您不再需要使用 executeTask 函数。

Old code:

executeTask(async () => {
try {
await playSound("sounds/Vexento.ogg", {
loop: true,
volume: 75,
})
} catch {
log('failed to play sound')
}
})

New code:

const ent = new Entity()
const audioClip = new AudioClip("sounds/Vexento.ogg")
const audioSource = new AudioSource(audioClip)
ent.addComponent(audioSource)
audioSource.playing = true
engine.addEntity(ent)

在开发文档中阅读有关此内容的更多信息,或查看使用此功能的示例场景。

Billboard 模式

Billboard 现在是一个单独的组件,而不是形状组件一项设置。

Old code:

let ent = new Entity()
ent.add(new BoxShape())
ent.get(BoxShape).billboard = BillboardMode.BILLBOARDMODE_ALL
engine.addEntity(ent)

New code:

let ent = new Entity()
ent.addComponent(new BoxShape())
ent.addComponent(new Billboard())
engine.addEntity(ent)

更多相关信息,请查看开发文档。

纹理

要添加纹理,您现在必须创建一个 Texture 组件,并将其添加到 Material 或 BasicMaterial 组件中。 Texture 组件公开了一些你可以设置的新参数,以便进行更好的控制。

Material 和 BasicMaterial 组件不再支持使用图像文件的路径,而是必须指向 Texture 组件。

Old code:

const woodMaterial = new Material()
woodMaterial.albedoTexture = "materials/wood.png"

let ent = new Entity()
ent.add(new PlaneShape())
ent.add(woodMaterial)
engine.addEntity(ent)

New code:

const woodTexture = new Texture("materials/wood.png")
const woodMaterial = new Material()
woodMaterial.albedoTexture = woodTexture

let ent = new Entity()
ent.addComponent(new PlaneShape())
ent.addComponent(woodMaterial)
engine.addEntity(ent)

更多相关信息,请查看开发文档。

点击事件

我们将 BUTTON_A_DOWN 和 BUTTON_A_UP 事件重命名为 BUTTON_DOWN 和 BUTTON_UP。 按下哪个按钮的信息现在作为事件参数传递。

Old code:

input.subscribe("BUTTON_A_DOWN", e => {
log("button Down", e)
})

New code:

input.subscribe("BUTTON_DOWN", e => {
log("button Down", e)
})
增强的点击功能

在 6.0 中我们添加了新的 OnPointerDown 组件,这个组件通常比 OnClick 更好。只有在指向同一实体的同时按下和放开按钮时,才会触发 OnClick 。OnPointerDown 则只需按下按钮即可触发。

现在仍然支持 OnClick 组件,但支持的功能比较少。 OnPointerDown 使用的事件携带有更多数据,包括光线距离,用户位置以及所点击的 3D 模型中特定网格的名称。

Old code:

ent.add(
new OnClick(e => {
log("event data: " + e)
})
)

New code:

ent.addComponent(
new OnPointerDown(e => {
log("event data: " + e)
})
)
分享你的喜悦!