Dados Mutáveis

Aprenda como lidar com dados somente leitura e mutáveis de componentes

Ao referenciar dados de um componente, você pode buscar a versão mutável ou a versão somente leitura (imutável).

Você deve sempre lidar com as versões somente leitura dos dados quando possível. Essa prática pode trazer uma melhoria muito significativa no desempenho da sua cena, em comparação com sempre lidar com versões mutáveis desses mesmos dados.

O .get() da entity função em um componente retorna uma versão somente leitura (imutável) do componente. Você só pode ler seus valores, mas não pode alterar nenhuma das propriedades nele.

O .getMutable() função retorna uma versão do componente que permite alterar seus valores. Use versões mutáveis apenas quando planejar fazer alterações em um componente; caso contrário, sempre use get().

// buscar uma versão somente leitura (imutável)
const immutableTransform = Transform.get(myEntity)

// o seguinte NÃO funciona:
// immutableTransform.position.y = 2

const mutableTransform = Transform.getMutable(myEntity)

// a linha a seguir ALTERA a posição da entidade
mutableTransform.position.y = 2

Uma boa prática é iterar sobre componentes somente leitura para verificar valores e então buscar a versão mutável de um componente individual somente quando for necessária uma alteração.

// altura máxima codificada
const MAX_HEIGHT = 10

// Defina o sistema
function HeightLimitSystem(dt: number) {
	// iterar sobre todas as entidades que têm um componente Transform
	for (const [entity] of engine.getEntitiesWith(Transform)) {
		// obter valores somente leitura
		const currentHeight = Transform.get(entity).position.y

		// comparar valores
		if (currentHeight > MAX_HEIGHT) {
			// buscar versão mutável para fazer uma alteração
			const mutableTransform = Transform.getMutable(entity)

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

// Adicionar sistema ao engine
engine.addSystem(HeightLimitSystem)

No exemplo acima, um sistema verifica os valores somente leitura do componente Transform de uma entidade. A cada tick ele verifica se o y da posição está acima de uma altura máxima codificada. Se a altura no transform estiver acima desse limite, então e somente então buscamos a versão mutável do Transform. Isso pode parecer trabalho extra para a cena, mas em uma cena onde verificamos valores a cada tick do loop do jogo e fazemos alterações apenas ocasionalmente, resulta em grandes ganhos de desempenho.

Essa prática segue os princípios de data oriented programming. Também está sendo gradualmente adotada como prática padrão na indústria de jogos, por causa do quanto ela melhora o desempenho.

📔 Nota: Nas versões mais antigas do SDK (6.x ou anteriores), os componentes eram sempre tratados como mutáveis. Esse padrão pode ser um pouco mais direto para aprender, mas era muito menos eficiente para executar.