Resumen de las diferencias entre la guía para evitar pozos de actualización del proyecto 2.x 3.x y la API básica.

Algunos lectores encontraron muchos problemas al actualizar el proyecto Cocos Creator 2.x a 3.x, ¡lo cual fue muy doloroso!

Afortunadamente, Xiaoheng tuvo una experiencia similar el año pasado. Actualicé mi "Qiuqiu quiere ir a casa" en Cocos Store de Cocos Creator 2.2.2 a 2.4.10 y luego a 3.6.2.

Este artículo compartirá con ustedes algunos de los obstáculos que encontré en el proceso y algunos de los cambios en las interfaces más básicas del motor entre 2.xy 3.x.

Ya sea que esté actualizando un proyecto antiguo o quiera intentar iniciar un nuevo proyecto en Creator 3.x, ¡creo que este artículo puede resultarle útil!

01 proceso de actualización

1. Actualice el motor a 2.4.x

Si tiene un proyecto antiguo por debajo de 2.4.x, se recomienda actualizar primero el proyecto a la última versión del motor 2.4.x.

Si hay una advertencia o algo así, puede ignorarla por el momento. El motor le preguntará qué métodos y atributos están obsoletos y qué interfaz utilizar para reemplazarlos. Solo necesita cambiar las interfaces verdaderamente abandonadas para garantizar el funcionamiento normal del proyecto.

Según mi participación en el trabajo de revisión y prueba del listado de recursos de CocosStore en los últimos dos años, el 95% de los proyectos se pueden actualizar a 2.4.x sin ningún cambio.

2. Actualización del guión

Cocos Creator 3.x solo admite el uso de TypeScript como componente de script.

Por lo tanto, si anteriormente escribió scripts de componentes en JavaScript, también deberá traducirlos a TypeScript. Este paso es una actividad física:

Una es traducir el script de JS a TS.
El segundo es volver a montar el nodo con el script.

Mi enfoque es, por ejemplo, si veo un script: GameScene.jsprimero genere un script al lado GameSceneTS.ts, siga la lógica del código JS y reescriba el código de acuerdo con la sintaxis TS.

Aunque esta es una tarea laboriosa, sigue siendo muy divertido escribir código TS en VSCode y las indicaciones inteligentes son muy convenientes.

Si encuentra indicaciones de código, ¡no son tan amigables como dije! Tenga en cuenta que puede actualizar o importar el archivo de solicitud a través del motor 主菜单→ 开发者→ , como se muestra en la figura:VSCode 工作流creator.d.ts

Una vez traducido el script TS, es hora de reemplazarlo en el editor.

Pero, ¿cómo encontrar el script JS utilizado anteriormente y dónde se utilizó? Mira la foto de abajo:

En el administrador de recursos, haga clic con el botón derecho del mouse para seleccionar el archivo de secuencia de comandos y haga clic en el menú 找查使用para buscar los recursos utilizados 场景y 预制体.

Pero el problema vuelve a surgir: hay tantos nodos en la escena, ¿dónde están los scripts de los componentes? ¿Cómo encontrar esto?

Déjame compartirte un pequeño truco aquí, ingresa en la barra de búsqueda del administrador de niveles: ¡ t:组件名字saldrá!

Luego puede colgar el nuevo script TS en el nodo y configurar los parámetros del componente TS de acuerdo con los valores de propiedad del componente JS anterior.

Después de configurar las propiedades del componente TS, elimine la versión JS del componente para realizar pruebas. Esta operación puede garantizar que el proyecto sea coherente con la lógica anterior en la mayor medida y sea menos probable que cause problemas.

Después de reemplazar todos los componentes, elimine el script JS del administrador de recursos y luego elimine el sufijo xxxTS del nombre del script TS.

Durante la actualización de "Ball Going Home" de 2.2.2 a 2.4.10, además de migrar los scripts de código de JS a TS, también reescribí todas las acciones de cc.Action a cc.Tween para la posterior actualización 3. x Estar bien preparado.

3. Actualizar el proyecto Creator 3.x

Aquí viene el punto, nuestro objetivo es actualizar con éxito el proyecto 2.2.2 a 3.6.2.

Cree un nuevo proyecto Creator 3.x desde el menú principal del editor 文件→导入 Cocos Creator 2.x 项目

Busque el directorio del proyecto 2.x que desea actualizar y aparecerá un panel como el siguiente.

Nota: ¡Aquí hay un peligro! Inicialmente 球球要回家descubrí, después de importar el proyecto 2.4.10, que no se podía hacer clic en el botón Botón de la escena.

Para descartar el problema causado por el script, reconstruí un Hello Worldproyecto usando 2.4.10, agregué un botón y luego importé 3.6.2. Este problema aún existe.

Después de intentarlo muchas veces sin solución, me detuve a leer las instrucciones en el panel de importación y abrí un repositorio de Github, que es la versión complementaria de esta herramienta de importación.

Al observar las instrucciones de actualización en el archivo README, simplemente resuelve el problema de que no se puede hacer clic en el botón y corrige otros errores.

Descargue con decisión el complemento e instálelo, intente utilizar el proyecto Hello World nuevamente para importar el botón del motor 3.x y haga clic en el problema para resolverlo.

4. Actualice el código del script 3.x

Usando la herramienta de importación de versiones del complemento, una vez completada la importación, sentí que mi corazón latía un poco más rápido y abrí con cuidado varias escenas de juegos y casas prefabricadas. ¡conmocionado!

La interfaz de usuario se reproduce perfectamente... OK,
el nodo de script del componente está vinculado a... OK
propiedades del componente, referencias de nodos, llamadas a métodos de componentes, ¡todo está bien!
¿Es esto un éxito?

Reprimí mi emoción y traté de ejecutarlo, ¡y comenzó a funcionar!

¡Pero! Haga clic en el botón, simplemente se mueve, pero nada más.

Abrí rápidamente el script, eché un vistazo y encontré esta situación: ¡ todos los cuerpos de funciones en el código estaban comentados!

¡Solo entonces me di cuenta de que el verdadero trabajo de actualización a 3.x apenas ha comenzado ahora!

02 Ajuste del código de componente

1. Introducción al módulo

Esta forma de llamada API cc.Nodeestá obsoleta en Creator 3.x. cc.SpriteEn su lugar, primero cree importel módulo en la parte superior del script, con el siguiente código:

//从 cc 模块中解构出 Node、Sprite 变量
import { Node, Sprite } from 'cc'

De hecho, cuando usamos VSCode para escribir código, no necesitamos escribir manualmente los importmódulos importados uno por uno. Vea a continuación:

Cuando el módulo del motor se utiliza por primera vez en el script, se importará automáticamente. Si los trucos anteriores no le funcionan, puede intentar instalar el archivo de solicitud VSCode a través del menú principal del motor 3.x 开发者→ instalar.Export.d.ts

2. Cambios en los atributos del nodo

Las propiedades de Node en Creator 3.x se han vuelto extremadamente concisas y solo se conservan position, rotationy scale.

¿Qué pasa con los otros atributos? Agregamos un sprite 2D a la escena 3.x y puedes ver:

atributo de opacidad movido al cc.UIOpacitycomponente
atributo de color movido al cc.Spritecomponente
Los atributos de tamaño y punto de anclaje se mueven a cc.UITransformlos componentes.

Por lo tanto, las interfaces anteriores node.opacity, node.scale, node.color, node.width no se pueden utilizar y se reemplazan por el siguiente método de interfaz:

Establecer transparencia de nodo

//Creator 2.x
this.node.opacity = 200;

//Creator 3.x
this.node.getComponent(UIOpacity).opacity = 200;

Establecer color de nodo

//Creator 2.x 
this.node.color = cc.Color.RED;

//Creator 3.x
this.node.getComponent(Sprite).color = Color.RED;

Establecer tamaño de nodo

//Creator 2.x
this.node.setContentSize(100, 100);

//Creator 3.x 
let transform = this.node.getComponent(UITransform);
//使用方法设置节点大小
transform.setContentSize(100, 100)
//也可以使用contentSize属性
transform.contentSize = Size(100, 100);
//还可以使用width、height属性
transform.width = 100;
transform.height = 100;

Aunque los atributos de posición, escala y rotación de Node en 3.x todavía están ahí, la interfaz del código también ha cambiado, echemos un vistazo a sus diferencias.

Establecer la posición del nodo

//Creator 2.x
this.node.position = v2(100, 100)
this.node.x = 100;  //3.x中不可用
this.node.y = 100;  //3.x中不可用

//Creator 3.x 中不能使用x、y、z分量设置节点位置
//需要使用 position 属性或 setPosition 方法
this.node.position = v3(100, 100, 100);
//注意需要同时设置 xyz 三个分量
this.node.setPosition(100, 100, 100);

Establecer escala de nodo

//Creator 2.x
this.node.scale = 1.5;

//Creator 3.x 
//注意 scale 不在是一个 number 而是 Vec3
this.node.scale = v3(1.5, 1.5, 1.5);
//注意 需要同时设置 xyz 三个分量
this.node.setScale(1,1,1);

Establecer la rotación del nodo en dos dimensiones.

//Creator 2.x rotation 属性在 2.3.x 之后是使用 angle 属性
this.node.angle = 1.5;

//Creator 3.x
//节点的 rotation 属性其实是一个 Quat 类型
//2D节点在属性检查器中的 rotation 
//对应的是节点的 angle 属性
this.node.angle = 10
//也可以使用 eulerAngles 来设置，注意它是设置的Z轴的旋转
this.node.eulerAngels = v3(0, 0, 10);

Conversión de coordenadas de nodo

Además, las interfaces comúnmente utilizadas de conversión de coordenadas de nodo convertToNodeSpaceAR, convertToWorldSpaceAR y getBoundingBox en 2D se han movido al objeto del componente UITransform; consulte el código:

//Creator 2.x 
let p = this.node.convertToNodeSpaceAR(eventTouch.location)；

//Creator 3.x
let transform = this.node.getComponent(UITransform);
let location = eventTouch.location;
//注意 3.x 中convertToNodeSpaceAR的参数为 Vec3 类型
//但 location 为 Vec2 类型
let p = transform.convertToNodeSpaceAR(v3(location.x, location.y));

animación entre

En Creator 2.x, la animación Tween controla principalmente el desplazamiento, la rotación, la escala, la transparencia, el color y otros atributos de los nodos. Cosas a tener en cuenta después de migrar a Creator 3.x:

Algunas propiedades ya no están en el objeto Nodo y deben controlarse obteniendo los componentes relevantes.
Los atributos de desplazamiento, rotación y escala utilizan el tipo Vec3 en lugar de Vec2; de lo contrario, se producirán algunos problemas inesperados.

Al igual que en la escena siguiente, cuando aparece el botón de nivel, se realiza una animación de zoom.

El código está escrito así:

...
let node = item.node;
tween(node)
  .to(0.1, { sacle: v2(1.1, 1.1) }) //放大
  .to(0.1, { sacle: v2(1, 1)})      //还原
  .start();

Los resultados operativos también son normales, ¡pero! El botón no puede responder al evento de clic... Después de varias soluciones de problemas, descubrí que fue causado por la animación Tween escrita, así que la cambié a lo siguiente:

...
let node = item.node;
tween(node)
  .to(0.1, { sacle: v3(1.1, 1.1) }) //放大
  .to(0.1, { sacle: v3(1, 1)})      //还原
  .start();

Después de cambiar v2 a v3, todo volvió a la normalidad de inmediato, me tomó mucho tiempo resolver un problema tan pequeño.

nivel de nodo

En 2.x, Node.zIndexse utiliza para controlar el nivel de visualización del nodo: cuanto mayor sea el valor, menor será el nivel.

En 3.x, Node.zIndexla interfaz se abandonó y Node.setSiblingIndex() es necesario utilizar métodos, lo que es lo opuesto a 2.x, el valor más pequeño está en la parte inferior.

ganarTamaño

También hay una interfaz de alta frecuencia en 2.x cc.winSizeque no existe en 3.x, y la API correspondiente es para view.getContentSize()obtener el tamaño de resolución del diseño de la ventana.

import { view } form 'cc'
view.getVisibleSize()

El editor carga recursos

En proyectos a veces utilizamos la carga de recursos en el editor ¿Qué significa?

Es decir, espero poder ver algunos efectos de la interfaz en el estado del editor sin ejecutar la vista previa H5. Además, los recursos de imagen utilizados no se arrastran y sueltan manualmente en el editor, sino que se cargan con código.

En la figura, puede ver directamente los cambios de escena cambiando el número de nivel a través de las propiedades GameBoarddel componente . LevelLos estudiantes que no sepan cómo hacerlo pueden preguntar, ¿cómo se hace?

executeInEditModeAgregar decoradores a los scripts de componentes

import { _decorator } from 'cc';
const {ccclass, executeInEditMode} = _decorator;

@ccclass('GameBoard')
@executeInEditMode //添加编辑器模式执行
export default class GameBoard extends Component {
  onLoad() {
    //代码将在编辑器状态执行
  }
  start() {
    //代码将在编辑器状态执行
  }
  update() {
    //代码将在编辑器状态执行
  }
}

Tenga en cuenta que la ejecución de código en el editor puede provocar algunos efectos secundarios, como que los objetos no se inicialicen y que se soliciten actualizaciones con frecuencia. 2.x En este momento, puede usar CC_EDITORvariables para verificar, el código es el siguiente:

//Creator 2.x 使用 CC_EDIDTO 全局变量检查
update() {
  if (CC_EDITOR) {
    return；
  }
  ...
}

No hay global en 3.x CC_EDITOR, pero cc/envel código bajo el módulo es el siguiente:

//Creator 3.x 使用 EDITOR 变量检查
import { EDITOR } from 'cc/env';
...
update() {
  if (EDITOR) {
    return；
  }
  ...
}

Cargar recursos en el editor

//Creator 2.4.x 加载图集中的图片
//注意'path'为resouces目录文件路径
cc.resources.load(path, SpriteAtlas, (err, res) => {
  let sprite = this.getComponent(Sprite);
  sprite.spriteFrame = res.getSpriteFrame(this.imageName);
});

Los recursos en el directorio en 3.x Bundleno se pueden cargar en el estado del editor, por lo que debe mover el archivo fuera del resoucesdirectorio y usar assetManager.loadAnyesta API de carga universal. El código es el siguiente:

//Creator 3.x 加载图集中的图片
assetManager.loadAny({uuid:'xxx', type: SpriteAtlas}, (err, res) => {
  let sprite = this.getComponent(Sprite);
  sprite.spriteFrame = res.getSpriteFrame(this.imageName);
})

En mi prueba, se utilizó el formulario de interfaz activeManager.loadAny({ {uuid:...}}) para cargar correctamente. Si obtiene el UUID del recurso, mire la imagen a continuación:

03 Resumen

El proceso general de migración de Creator 2.x a 3.x consta aproximadamente de los siguientes tres pasos:

Migre el código a TS y actualícelo a 2.4.x. Si el proyecto ya es 2.4.x TS, felicidades, puede omitir este paso;
Utilice la función de importación de proyectos 2.x en el editor 3.x (tenga en cuenta que debe usar un complemento) para actualizar 2.x a 3.x. Este paso resuelve principalmente el problema de rehacer la interfaz de usuario;
Modifique las interfaces relevantes en 3.x que no son compatibles con 2.x. Es básicamente una traducción uno a uno. Tenga en cuenta que 3.x es primero un motor 3D y una gran cantidad de interfaces se han cambiado a Vec3. .

Espero que la actualización de 2.x anterior al contenido de 3.x le sea útil "Qiuqiu quiere irse a casa"

Enlace de experiencia:
http://gameview.creator-star.cn/zxh/ball-game-ccc3.6.2/index.html

Dirección de descarga:
https://store.cocos.com/app/detail/2648

Aspectos destacados del pasado