> 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/interatividade/player-physics.md).

# Física do Player

Aplique forças e impulsos ao avatar do jogador

Pode aplicar forças físicas ao avatar do jogador a partir do código da sua cena. Isto permite criar mecânicas de jogo como plataformas de lançamento, zonas de vento, efeitos de repulsão, explosões e muito mais.

Pode aplicar dois tipos de força:

* **Impulso**: um empurrão instantâneo aplicado uma única vez. Use-o para efeitos súbitos e pontuais, como lançar o jogador para o ar ou afastá-lo com um empurrão.
* **Força contínua**: um empurrão prolongado aplicado em cada tick enquanto estiver ativo. Use-a para efeitos contínuos, como zonas de vento, correntes de água ou campos gravitacionais.

Ambos são aplicados através do `Physics` auxiliar, importado de `@dcl/sdk/ecs`.

{% hint style="warning" %}
**📔 Nota**: estas forças afetam apenas o avatar do jogador local. Os outros jogadores veem as alterações nas posições dos jogadores, mas as próprias forças não são sincronizadas com os outros jogadores no modo multijogador. A física de cada jogador é executada localmente na respetiva instância.
{% endhint %}

## Aplicar um impulso

Use `Physics.applyImpulseToPlayer()` para dar ao jogador um empurrão único numa determinada direção.

* `vector`: direção e intensidade combinadas — o comprimento do vetor determina a magnitude do impulso.

```ts
import { Physics } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

// Launch the player straight up
Physics.applyImpulseToPlayer(Vector3.create(0, 50, 0))
```

Também pode passar a direção e a magnitude separadamente. Neste caso, o vetor de direção é normalizado automaticamente:

* `direction`: direção do empurrão — é normalizada automaticamente antes de ser escalada.
* `magnitude`: intensidade do impulso.

```ts
import { Physics } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

// Launch the player upward with a magnitude of 50
Physics.applyImpulseToPlayer(Vector3.create(0, 1, 0), 50)
```

Se chamar `applyImpulseToPlayer()` várias vezes no mesmo frame, os impulsos acumulam-se — são somados e aplicados como um único impulso combinado.

### Intensidade de um impulso

O avatar tem uma massa de 1, por isso a magnitude de um impulso corresponde à alteração da velocidade do avatar, em metros por segundo. Um impulso de `50` acrescenta 50 m/s nessa direção.

* A velocidade adicionada por um impulso diminui com o tempo. No ar, diminui a uma taxa de 1,5 por segundo, pelo que resta cerca de um quinto após um segundo. Diminui mais rapidamente quando o avatar está no chão.
* A velocidade adicionada por impulsos e forças está limitada a 50 m/s.
* Um impulso para cima anula primeiro qualquer velocidade descendente que o avatar tenha devido a uma queda. Assim, uma plataforma de lançamento funciona da mesma forma, quer o jogador caminhe sobre ela, quer aterre nela vindo de cima.

### Acionar um impulso quando o jogador entra

Um padrão comum consiste em acionar um impulso quando o jogador entra numa área. Use uma área de acionamento para detetar a entrada do jogador:

```ts
import { engine, Physics, TriggerArea, triggerAreaEventsSystem, ColliderLayer, MeshRenderer, Transform } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

const launchPad = engine.addEntity()
Transform.create(launchPad, { position: Vector3.create(8, 0, 8) })
MeshRenderer.setBox(launchPad)
TriggerArea.setBox(launchPad, ColliderLayer.CL_PLAYER)

triggerAreaEventsSystem.onTriggerEnter(launchPad, (result) => {
	if (result.trigger?.entity !== engine.PlayerEntity) return
	Physics.applyImpulseToPlayer(Vector3.create(0, 50, 0))
})
```

## Aplicar um impulso de repulsão

Use `Physics.applyKnockbackToPlayer()` para afastar o jogador de um ponto com um único impulso. É ideal para explosões, efeitos de impacto e outras rajadas direcionais pontuais. A direção é calculada automaticamente, do ponto de origem até à posição atual do jogador.

```ts
import { Physics } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

const explosionPosition = Vector3.create(8, 1, 8)

// Afasta o jogador do centro da explosão
Physics.applyKnockbackToPlayer(explosionPosition, 40)
```

Pode limitar a área de efeito com um `radius` e controlar como a magnitude diminui com a distância usando a opção `KnockbackFalloff` :

* `fromPosition`: origem no espaço do mundo da força de repulsão (centro da explosão, posição do inimigo, etc.).
* `magnitude`: intensidade base do impulso.
* `radius`: distância máxima do efeito (predefinição: `Infinity`).
* `falloff`: forma como a magnitude diminui com a distância (predefinição: `CONSTANT`).

```ts
import { Physics, KnockbackFalloff } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

Physics.applyKnockbackToPlayer(
	Vector3.create(8, 1, 8),
	40,                          // magnitude
	10,                          // radius: sem efeito para além de 10 metros
	KnockbackFalloff.LINEAR      // a magnitude diminui até 0 no limite do raio
)
```

O `KnockbackFalloff` enum controla como a força diminui com a distância:

* `KnockbackFalloff.CONSTANT` — mantém a mesma magnitude a qualquer distância dentro do raio (predefinição)
* `KnockbackFalloff.LINEAR` — diminuição linear e suave até 0 no limite do raio
* `KnockbackFalloff.INVERSE_SQUARE` — diminuição acentuada, fisicamente realista

Se o jogador estiver exatamente na posição de origem, será empurrado diretamente para cima. Uma magnitude negativa atrai o jogador para o ponto, em vez de o afastar.

Os mesmos valores de `KnockbackFalloff` estão disponíveis para `applyRepulsionForceToPlayer()`.

## Aplicar uma força contínua

Use `Physics.applyForceToPlayer()` para aplicar uma força contínua ao jogador. Ao contrário de um impulso, esta força é aplicada em cada tick enquanto permanecer ativa.

* `source`: uma entidade que identifica esta origem de força — use-a para atualizar ou remover a força mais tarde.
* `vector`: direção e intensidade combinadas — o comprimento do vetor representa a magnitude da força.

A posição da entidade de origem não é relevante — é usada apenas como identificador.

```ts
import { engine, Physics } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

const windZoneEntity = engine.addEntity()

// Empurra o jogador continuamente para a direita
Physics.applyForceToPlayer(windZoneEntity, Vector3.create(10, 0, 0))
```

O vetor de força está sempre no **espaço global**. Se precisar de uma direção relativa a uma entidade rotacionada, use `Transform.localToWorldDirection()` para convertê-la primeiro — consulte [Converter uma direção local para o espaço global](#convert-a-local-direction-to-world-space).

Assim como em `applyImpulseToPlayer()`, também é possível passar `direction` e `magnitude` separadamente — consulte [Aplicar um impulso](#apply-an-impulse):

```ts
Physics.applyForceToPlayer(windZoneEntity, Vector3.create(0, 1, 0), 50)
```

Se chamar `applyForceToPlayer()` novamente com a mesma entidade de origem, a força anterior dessa origem será substituída. Se várias origens de força forem acumuladas, seus vetores serão somados a cada tick.

### Remover uma força contínua

Para parar de aplicar uma força, chame `Physics.removeForceFromPlayer()` com uma referência à entidade de origem usada para criar a força. Se a entidade não estiver aplicando uma força no momento, a chamada será ignorada com segurança.

* `source`: A entidade usada ao aplicar a força.

```ts
Physics.removeForceFromPlayer(windZoneEntity)
```

### Aplicar uma força por tempo limitado

Use `Physics.applyForceToPlayerForDuration()` para aplicar uma força durante um período específico. A duração é expressa em segundos. A força é removida automaticamente quando o tempo termina. Chamar essa função novamente com a mesma entidade de origem reinicia o temporizador.

* `source`: Uma entidade que identifica esta origem de força.
* `duration`: Por quanto tempo a força dura, em segundos.
* `vector`: direção e intensidade combinadas — o comprimento do vetor representa a magnitude da força.

```ts
import { engine, Physics } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

const gustEntity = engine.addEntity()

// Aplica uma forte força ascendente por 1.5 segundos
Physics.applyForceToPlayerForDuration(gustEntity, 1.5, Vector3.create(0, 50, 0))
```

A sobrecarga de `direction` + `magnitude` também está disponível — consulte [Aplicar um impulso](#apply-an-impulse):

```ts
Physics.applyForceToPlayerForDuration(gustEntity, 1.5, Vector3.create(0, 1, 0), 50)
```

### Exemplo de zona de vento

Este exemplo cria um túnel de vento que empurra o jogador enquanto ele está dentro dele e para quando ele sai:

```ts
import { engine, Physics, TriggerArea, triggerAreaEventsSystem, ColliderLayer, MeshRenderer, MeshCollider, Transform } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

const windTunnel = engine.addEntity()
Transform.create(windTunnel, {
	position: Vector3.create(8, 1, 8),
	scale: Vector3.create(4, 3, 4),
})
MeshRenderer.setBox(windTunnel)
TriggerArea.setBox(windTunnel, ColliderLayer.CL_PLAYER)

triggerAreaEventsSystem.onTriggerEnter(windTunnel, (result) => {
	if (result.trigger?.entity !== engine.PlayerEntity) return
	Physics.applyForceToPlayer(windTunnel, Vector3.create(15, 0, 0))  // empurra lateralmente ao longo do eixo X
})

triggerAreaEventsSystem.onTriggerExit(windTunnel, (result) => {
	if (result.trigger?.entity !== engine.PlayerEntity) return
	Physics.removeForceFromPlayer(windTunnel)
})
```

## Aplicar uma força de repulsão

Utilize `Physics.applyRepulsionForceToPlayer()` para afastar continuamente o jogador de um ponto fixo no espaço. Esta opção é adequada para efeitos como um campo de repulsão magnética, uma barreira de força ou um objeto suspenso que mantém os jogadores à distância. Ao contrário de `applyKnockbackToPlayer()`, esta força é recalculada a cada tick à medida que o jogador se move. A intensidade diminui com a distância, de acordo com o raio e a atenuação — consulte [Aplicar um impulso de repulsão](#apply-a-knockback-impulse) para ver as opções de `KnockbackFalloff` . Uma intensidade negativa inverte o efeito, puxando continuamente o jogador para o ponto, como num vórtice ou poço gravitacional.

{% hint style="warning" %}
**📔 Nota**: A origem da repulsão é o vetor `fromPosition` que transmite — **não** a posição da entidade `source` . A entidade `source` é utilizada apenas como identificador, para que possa atualizar ou remover a força mais tarde. A sua posição, rotação e escala são completamente ignoradas.
{% endhint %}

* `source`: Uma entidade utilizada como identificador desta força — a sua posição não é utilizada.
* `fromPosition`: O ponto no espaço do mundo de onde o jogador é afastado.
* `magnitude`: Intensidade base da força. Os valores negativos atraem em vez de repelir.
* `radius`: distância máxima do efeito (predefinição: `Infinity`).
* `falloff`: forma como a magnitude diminui com a distância (predefinição: `CONSTANT`).

```ts
import { engine, Physics, Transform, timers } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

const repulsionSource = engine.addEntity()
Transform.create(repulsionSource, { position: Vector3.create(8, 1, 8) })

// Transmite explicitamente a posição da entidade como origem da repulsão
Physics.applyRepulsionForceToPlayer(
	repulsionSource,
	Transform.get(repulsionSource).position,  // origem da repulsão — transmitida explicitamente, não obtida automaticamente
	50,                                         // intensidade
	10,                                         // raio de efeito em metros
)

// Remove a força após meio segundo
timers.setTimeout(() => {
    Physics.removeForceFromPlayer(repulsionSource)
}, 500)
```

## Forças durante o voo planado

Enquanto o jogador está a planar, as forças contínuas comportam-se de forma diferente:

* Forças contínuas — de `applyForceToPlayer()`, `applyForceToPlayerForDuration()`, ou `applyRepulsionForceToPlayer()` — são **1,5 vezes mais fortes**, uma vez que o planador aberto capta o fluxo de ar. As zonas de vento e as correntes parecem mais responsivas para um jogador a planar.
* A componente ascendente de uma força contínua pode **elevar** um jogador a planar. O limite da velocidade de queda do planador apenas limita a velocidade a que o jogador desce; não anula o movimento ascendente. Por isso, uma corrente de vento inclinada ou vertical empurra o jogador em toda a direção da força.

Os impulsos únicos — de `applyImpulseToPlayer()` ou de `applyKnockbackToPlayer()` — não são afetados por planar. Comportam-se da mesma forma quer o planador esteja aberto ou fechado.

Pode combinar estes comportamentos para criar mecânicas como correntes térmicas ascendentes que elevam jogadores a planar ou corredores de vento que são mais fáceis de atravessar com o planador aberto. Para ajustar a velocidade de queda ou a velocidade para a frente do planador, use o componente `AvatarLocomotionSettings` , consulte [Definições de locomoção](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/locomotion.md#locomotion-settings).

## Converter uma direção local para o espaço global

Use `Transform.localToWorldDirection()` para transformar um vetor de direção do espaço de coordenadas local de uma Entity para o espaço global, tendo em conta toda a hierarquia de entidades parent. Isto é útil ao aplicar forças em relação a uma Entity rodada — por exemplo, para empurrar o jogador para longe de uma face específica de um obstáculo rotativo.

* `entity`: A Entity de origem cujo espaço local define a direção.
* `localDirection`: Vetor de direção nas coordenadas locais da Entity.

Devolve o vetor de direção em coordenadas globais.

Isto aplica apenas a **rotação** — não tem em conta a translação nem a escala —, tornando-o diretamente adequado para vetores de direção transmitidos às funções de força e impulso.

```ts
import { Physics, Transform } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

// Empurra o jogador na direção em que o eixo +Z local da entidade aponta no espaço global
const worldDir = Transform.localToWorldDirection(myEntity, Vector3.create(0, 0, 1))
Physics.applyImpulseToPlayer(worldDir, 20)
```


---

# 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/interatividade/player-physics.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.
