Datos mutables

Aprende a manejar datos de solo lectura y mutables desde components

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

Siempre que sea posible, deberías trabajar con las versiones de solo lectura de los datos. Esta práctica puede traer una mejora muy significativa en el rendimiento de tu scene, en comparación con trabajar siempre con versiones mutables de esos mismos datos.

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

El .getMutable() function devuelve una versión del component que te permite cambiar sus valores. Usa versiones mutables solo cuando planees hacer cambios en un component; 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 entity
mutableTransform.position.y = 2

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

// altura máxima codificada
const MAX_HEIGHT = 10

// Definir el system
function HeightLimitSystem(dt: number) {
	// iterar sobre todas las entities que tienen un component 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 el system al engine
engine.addSystem(HeightLimitSystem)

En el ejemplo anterior, un system comprueba los valores de solo lectura del Transform component de una entity. En cada tick comprueba si la posición y es mayor que una altura máxima codificada. Si la altura en el Transform resulta estar por encima de este límite, entonces y solo entonces obtenemos la versión mutable del Transform. Esto puede parecer trabajo extra para la scene, pero en una scene donde comprobamos valores en cada tick del game loop, y solo hacemos cambios ocasionalmente, se traduce en enormes mejoras de rendimiento.

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

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