> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md).

# Systems

Saiba como os systems são usados para atualizar o estado da scene

As scenes de Decentraland dependem de *systems* para atualizar quaisquer dados ao longo do tempo, incluindo as informações armazenadas nos [components](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md).

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-47dcd6cd9846e4d62d320e0ba061c9261d2e4f2a%2Fecs-big-picture.webp?alt=media)

*systems* são o que torna as scenes dinâmicas: são funções executadas periodicamente a cada tick do game loop da scene, alterando o que será renderizado.

O exemplo seguinte mostra uma declaração básica de system:

```ts
// Define the system
function mySystem() {
  console.log("Performed on every tick. My system is running")
}
// Add system to engine
engine.addSystem(mySystem)
```

A função de um system pode fazer tudo o que quiser. Normalmente, atua sobre todas as entities que correspondem a determinada [query](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/querying-components.md), seguindo uma lógica específica para alterar os valores armazenados nos components da entity.

```ts
function moveSystem(dt: number) {
  // iterate over all entiities with a Transform
  for (const [entity] of engine.getEntitiesWith(Transform)) {

  // fetch a mutable Transform component
  const transform = Transform.getMutable(entity)

  // update the position value
    transform.position.z += 0.01
  }
}

engine.addSystem(moveSystem)
```

No exemplo acima, o system `MoveSystem` é uma função executada a cada tick do game loop, alterando a posição de cada entity da scene que tenha um Transform.

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-c1624d9135ec9e49645467bbc9cf397b35a4f159%2Fecs-system-new.webp?alt=media)

Pode ter vários systems na sua scene para desacoplar diferentes comportamentos, tornando o seu código mais limpo e fácil de dimensionar e reutilizar. Por exemplo, um system pode tratar da física, outro pode fazer uma entity de obstáculo mover-se continuamente para a frente e para trás, e outro pode tratar da IA das personagens.

Vários systems podem atuar sobre uma única entity. Por exemplo, uma personagem não jogável pode mover-se autonomamente com base numa IA e também ser afetada pela gravidade se, por acidente, sair de um penhasco a caminhar. Neste cenário, os systems de física e de IA nem sequer precisam de ter conhecimento um do outro. Avaliam de forma independente o respetivo estado atual a cada tick do game loop e implementam a sua própria lógica.

## A função de um system

A função de um system é executada periodicamente, uma vez a cada tick do game loop. Isto acontece automaticamente; não precisa de chamar explicitamente esta função em nenhum ponto do seu código.

Numa scene de Decentraland, pode pensar no game loop como o conjunto de todas as funções dos systems da sua scene.

{% hint style="warning" %}
**📔 Nota**: não pode adicionar a mesma função de system ao engine mais do que uma vez. Se tentar adicionar um system que já foi adicionado, o engine apresenta um erro: `System "<name>" already added to the engine`.
{% endhint %}

## Tratar entities por referência

Alguns components e systems destinam-se a ser usados apenas numa entity da scene. Por exemplo, numa entity que armazene a pontuação de um jogo ou talvez num portão principal que seja único na scene. Para aceder a uma dessas entities dentro de um system, basta referenciar a entity ou os seus components pelo nome nas funções do system.

```ts
// declare the entity reference at module scope so systems can access it
let game: Entity

export function main(){
	// create a new entity
	game = engine.addEntity()

	// add component to that entity
	ScoreComponent.create(game)
}

// Define the system
export function UpdateScore() {

  // call reference to individual entity
  const points = ScoreComponent.get(game).points
  console.log(points)
}

// Add system to engine
engine.addSystem(UpdateScore)
```

Em projetos maiores, recomendamos que mantenha as definições dos systems em ficheiros separados daqueles em que instancia entities e components.

## Iterar sobre uma consulta de componentes

Muitas vezes, a sua cena terá várias entidades do mesmo tipo com comportamentos semelhantes. Por exemplo, muitas portas que podem ser abertas ou muitos inimigos que podem atacar o jogador. Faz sentido gerir todas estas entidades semelhantes num único sistema, percorrendo a lista e realizando as mesmas verificações em cada uma.

Não quer que a função de um sistema percorra *todo o* conjunto de entidades da cena, pois isso pode ter um custo elevado em termos de capacidade de processamento. Para evitar isso, pode [consultar componentes](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/querying-components.md), para percorrer apenas as entidades relevantes.

Por exemplo, a sua cena pode ter um `PhysicsSystem` que calcula o efeito da gravidade nas entidades da sua cena. Algumas entidades da sua cena, como as árvores, não devem mover-se; por isso, seria sensato evitar calcular os efeitos da gravidade sobre elas. Pode definir um componente `HasPhysics` para assinalar as entidades que podem ser afetadas pela gravidade e, depois, fazer com que `PhysicsSystem` trate apenas das entidades devolvidas por esta consulta.

```ts
// Define the system
export function PhysicsSystem() {
  // iterar sobre todas as entidades com HasPhysics
  for (const [entity] of engine.getEntitiesWith(HasPhysics)) {

  // fetch a mutable Transform component
  const transform = Transform.getMutable(entity)

  // Calcular o efeito da física
  }
}

// Add system to engine
engine.addSystem(PhysicsSystem)
```

## Delta time entre frames

A função de um sistema pode incluir, opcionalmente, um argumento chamado `dt`, do tipo `number` (que representa *delta time*).

```ts
function MySystem(dt: number) {

  // Atualizar a cena
  console.log("time since last tick: ", dt)
}

engine.addSystem(MySystem)
```

*delta time* representa o tempo decorrido, em segundos, desde o último tick do loop do jogo.

O argumento `dt` é o tempo real decorrido desde o último tick do loop do jogo, medido em segundos. O SDK não impõe uma frequência fixa de ticks: o runtime anfitrião fornece este valor, que varia consoante a taxa de frames da cena.

Quanto mais fluida for a execução de uma cena, mais frequentemente ocorrem os ticks e menor é cada valor de `dt` Quando um tick demora mais tempo a processar, passa mais tempo até ao seguinte e o valor `dt` aumenta em conformidade.

O loop do jogo da cena é executado à mesma frequência com que o engine renderiza os frames. Por exemplo, se a máquina do jogador renderizar a 60 FPS, os seus sistemas são executados 60 vezes por segundo e o valor de `dt` é aproximadamente *1/60* (0.0166...). Isto aplica-se à cena onde o jogador se encontra. Outras cenas próximas que estejam carregadas são atualizadas com menos frequência.

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-44f419dd3f7e4e0252adc4a261aa01b85a4c1c18%2Fecs-framerate.webp?alt=media)

Quando a máquina do jogador demora mais tempo a processar um frame, a taxa de frames diminui: os ticks ocorrem com menos frequência e o valor de `dt` fornecido no tick seguinte reflete esse intervalo mais longo. O engine não compensa retroativamente o atraso; `dt` indica sempre o tempo real decorrido para que os seus sistemas se possam ajustar.

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-44cd0024898c7e90e34aabfc12c80032a586f11a%2Fecs-framerate-heavy.webp?alt=media)

Idealmente, deve evitar que a sua cena perca frames, pois isso afeta a qualidade da experiência do jogador. Como isto depende da capacidade de processamento da máquina do jogador, é sempre possível que aconteça, pelo que a sua cena deve estar preparada para lidar com a situação de forma adequada.

Como a taxa de frames varia entre máquinas e de momento para momento, use `dt` para ajustar qualquer alteração gradual. Multiplique uma alteração por `dt` expressa-o por segundo em vez de por frame, para que a taxa de variação se mantenha constante a qualquer taxa de frames.

Consulte [o posicionamento das entidades](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/entity-positioning.md) para ver exemplos de como usar `dt` para tornar o movimento mais suave.

## Repetir em intervalos de tempo

Se quiser que um sistema execute algo em intervalos regulares, pode fazê-lo combinando o argumento `dt` com um temporizador.

```ts
let timer: number = 10

function LoopSystem(dt: number) {
  timer -= dt
  if (timer <= 0) {
      timer = 10
      // DO SOMETHING
    }
}

engine.addSystem(LoopSystem)
```

Também existe uma função abreviada, `setInterval` e `clearInterval` que utiliza Systems em segundo plano. Isto permite uma versão mais simples e curta quando se pretende executar uma determinada função a cada X intervalo de tempo.

```ts
import { timers } from '@dcl/sdk/ecs'

const intervalId = timers.setInterval(() => {
    console.log('Printing this every 10 seconds')
}, 10000)
```

O primeiro argumento, `callback`, é a função a executar (neste caso, `console.log()`) e o segundo argumento, `ms`(10000 neste caso), corresponde ao número de milissegundos a aguardar entre cada execução da função.

Para parar a função `setInterval` , utiliza-se `clearInterval` .

```
timers.clearInterval(intervalId)
```

Em que `intervalId` é a referência ao valor devolvido por `setInterval` definido anteriormente.

Para casos de utilização mais complexos, em que podem ser criados dinamicamente vários atrasos e ciclos, pode ser útil definir um componente personalizado para armazenar um valor de temporizador individual para cada entidade. Consulte [Componentes personalizados](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/custom-components.md).

## Ordem de execução dos Systems

Em alguns casos, quando tem vários Systems em execução, pode ser importante saber qual deles é executado primeiro pela sua cena.

Por exemplo, pode ter um sistema de *física* que atualiza a posição das entidades na cena e outro *limites* sistema que garante que nenhuma das Entity fique posicionada fora dos limites da Scene. Neste caso, pretende garantir que o *limites* sistema é executado em último lugar. Caso contrário, o *física* sistema poderá mover Entity para fora dos limites da Scene, mas o *limites* sistema só se aperceberá disso quando for executado novamente no frame seguinte.

Ao adicionar um sistema ao Engine, defina um campo opcional `priority` para determinar quando o sistema é executado em relação aos outros sistemas.

```ts
engine.addSystem(PhysicsSystem, 5)
engine.addSystem(BoundariesSystem, 1)
```

Os sistemas com um número de prioridade mais elevado são executados primeiro, por isso um sistema com prioridade *5* é executado antes de um com prioridade *1*.

Os sistemas aos quais não é atribuída uma prioridade explícita têm uma prioridade predefinida de *100000*. Como os números mais elevados são executados primeiro, estes sistemas são executados antes dos que têm uma prioridade explícita mais baixa.

Se dois sistemas tiverem o mesmo número de prioridade, não é possível saber ao certo qual deles será executado primeiro.

## Remover um sistema

É possível adicionar ou remover uma instância de um sistema do Engine para o ativar ou desativar.

Se um sistema estiver definido, mas não for adicionado ao Engine, a sua função não será chamada pelo Engine.

Para remover um sistema, tem primeiro de lhe atribuir um nome ao adicioná-lo ao Engine, para poder referir-se a ele mais tarde.

```ts
// declarar o sistema
function mySystem(dt: number){
  console.log("delay since last tick: ", dt)
}

// adicionar o sistema (atribuindo-lhe uma prioridade e um nome)
engine.addSystem(mySystem, 1, "DelaySystem")

// remover o sistema
engine.removeSystem("DelaySystem")
```

A string que passar a `engine.removeSystem()` tem de corresponder ao nome que atribuiu ao sistema quando o adicionou.

Outra forma de remover um sistema é passar a própria função do sistema ao método `engine.removeSystem()` . Assim, não precisa de atribuir um nome ao sistema quando o adiciona.

```ts
// declarar o sistema
function mySystem(dt: number){
  console.log("delay since last tick: ", dt)
}

// adicionar o sistema
engine.addSystem(mySystem)

// remover o sistema passando a sua função
engine.removeSystem(mySystem)
```

`engine.removeSystem()` aceita a string com o nome que atribuiu ao sistema ao adicioná-lo ou uma referência à própria função do sistema.

Pode utilizar o método abaixo para fazer com que um sistema termine por si próprio quando concluir a sua função.

```ts
   const mySystem = function(dt: number){
        time += dt
        if(time > 3){
		engine.removeSystem(mySystem)
        }
    }
    engine.addSystem(mySystem)
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
