Datos mutables

Aprende cómo manejar datos de solo lectura y datos mutables de componentes

Al hacer referencia a datos desde un componente, puedes obtener la versión mutable o la versión de solo lectura (inmutable).

Siempre debes trabajar con las versiones de solo lectura de los datos cuando sea posible. Esta práctica puede aportar una mejora muy significativa en el rendimiento de tu escena, en comparación con estar siempre manejando versiones mutables de esos mismos datos.

El .get() function en un componente devuelve una versión de solo lectura (inmutable) del componente. Solo puedes leer sus valores, pero no puedes cambiar ninguna de sus propiedades.

El .getMutable() function devuelve una versión del componente que te permite cambiar sus valores. Usa las versiones mutables solo cuando planees hacer cambios en un componente; de lo contrario, usa siempre get().

// obtener una versión de solo lectura (inmutable)
const immutableTransform = Transform.get(myEntity)

// lo siguiente NO funciona:
// immutableTransform.position.y = 2

const mutableTransform = Transform.getMutable(myEntity)

// la siguiente línea SÍ cambia la posición de la entidad
mutableTransform.position.y = 2

Una buena práctica es iterar sobre componentes de solo lectura para comprobar valores y luego obtener la versión mutable de un componente individual solo cuando se requiera un cambio.

// altura máxima codificada
const MAX_HEIGHT = 10

// Definir el sistema
function HeightLimitSystem(dt: number) {
	// iterar sobre todas las entidades que tienen un componente Transform
	for (const [entity] of engine.getEntitiesWith(Transform)) {
		// obtener valores de solo lectura
		const currentHeight = Transform.get(entity).position.y

		// comparar valores
		if (currentHeight > MAX_HEIGHT) {
			// obtener la versión mutable para hacer un cambio
			const mutableTransform = Transform.getMutable(entity)

			// cambiar transform
			mutableTransform.position.y = MAX_HEIGHT
		}
	}
}

// Añadir sistema al engine
engine.addSystem(HeightLimitSystem)

En el ejemplo anterior, un sistema comprueba los valores de solo lectura del componente Transform de una entidad. En cada tick comprueba si la y de la posición es mayor que una altura máxima codificada. Si la altura en el transform está por encima de este límite, entonces y solo entonces obtenemos la versión mutable del Transform. Esto puede parecer trabajo adicional para la escena, pero en una escena donde comprobamos valores en cada tick del bucle del juego y solo realizamos cambios ocasionalmente, resulta en grandes ganancias de rendimiento.

Esta práctica sigue los principios de data oriented programming. También se está adoptando gradualmente como una práctica estándar en la industria del gaming, debido a la gran mejora que aporta.

📔 Nota: En versiones antiguas del SDK (6.x o anteriores), los componentes siempre se trataban como mutables. Ese patrón puede ser un poco más sencillo de aprender, pero era mucho menos eficiente en ejecución.