Eventos de proximidade

Detete quando um player entra ou sai da proximidade de uma Entity.

As interações de proximidade permitem que entities reajam a eventos de botão quando um player entra, está perto e, de forma aproximada, está a encará-la, sem exigir que aponte o cursor para a entity.

Os eventos de ponteiro tradicionais usam ray-casting: o player precisa apontar o cursor para o collider de uma entity antes de poder pressionar um botão para disparar o evento. Os eventos de proximidade, por outro lado, verificam entities que estão dentro de uma determinada área ao redor do avatar, independentemente de para onde o cursor do player esteja apontando.

A área interativa considerada para interações de proximidade é uma larga fatia triangular de uma esfera, projetando-se para a frente a partir da posição do player. Ao contrário dos eventos de ponteiro, a direção para a qual o avatar está virado é importante, independentemente da direção para a qual a câmera está virada.

Para definir uma custom logic mais específica, talvez você queira lidar com os dados brutos e usar o Advanced abordagem.

Para que uma entity seja interativa, ela deve ter um collider. Veja obstacles para mais detalhes.

Registrar callbacks de proximidade

O pointerEventsSystem inclui funções auxiliares para eventos de proximidade, seguindo o mesmo padrão que callbacks de eventos de ponteiro.

Pressões de botão de proximidade

Use pointerEventsSystem.onProximityDown para detetar pressões de botão enquanto o player está dentro do alcance. Ao contrário de onPointerDown, isto não exige que o player aponte o cursor para a entity.

pointerEventsSystem.onProximityDown(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Press E',
            maxPlayerDistance: 5,
        },
    },
    function () {
        console.log('Player pressed button near entity')
    }
)

Use pointerEventsSystem.onProximityUp para detetar quando o player solta um botão enquanto está dentro do alcance.

pointerEventsSystem.onProximityUp(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Soltar E',
            maxPlayerDistance: 5,
        },
    },
    function () {
        console.log('Player soltou o botão perto da entity')
    }
)

📔 Nota: Apenas um onProximityDown e um onProximityUp podem ser registados por entity. Depois de adicionados, continuam a escutar até serem removidos. Não chame isto dentro de um loop de System, pois isso reescreveria o comportamento constantemente.

Tipos de eventos de proximidade

Foram adicionados dois novos valores ao PointerEventType enum:

• PET_PROXIMITY_ENTER: Disparado quando o player entra no alcance de proximidade da entity.

• PET_PROXIMITY_LEAVE: Disparado quando o player sai do alcance de proximidade da entity.

Estes podem ser usados com um PointerEvents component e a inputSystem para as abordagem baseada em system. Essa abordagem também suporta pressões de botão de proximidade usando o InteractionType.IT_PROXIMITY campo.

Prioridade

Quando várias entities estão dentro do alcance e podem responder à mesma entrada, apenas uma é ativada, por padrão a mais próxima. Use o prioridade campo para controlar qual tem precedência. Entities com um número maior como valor de prioridade respondem primeiro.

Se o player estiver ao mesmo tempo dentro do alcance de uma entity com interação de proximidade e o cursor do player estiver apontando para uma entity que tem uma interação de ponteiro, a entity com a interação de ponteiro recebe sempre prioridade. Novamente, apenas uma entity é ativada.

pointerEventsSystem.onProximityDown(
    {
        entity: doorEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Open door',
            maxPlayerDistance: 5,
            priority: 2,
        },
    },
    function () {
        console.log('Door activated')
    }
)

pointerEventsSystem.onProximityDown(
    {
        entity: floorEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Step here',
            maxPlayerDistance: 5,
            priority: 1,
        },
    },
    function () {
        console.log('Floor activated')
    }
)

No exemplo acima, se ambas as entities estiverem dentro do alcance, a entity da porta responde porque tem a prioridade mais alta.

O prioridade campo também pode ser definido nas propriedades de um PointerEvents component.

Opções

As funções auxiliares de proximidade aceitam as mesmas opções que as suas equivalentes de ponteiro:

• button: Qual botão ouvir. Veja Pointer buttons para opções suportadas.

• maxDistance: Distância máxima desde o camera do player até à entity, em metros.

• maxPlayerDistance: Distância máxima desde o avatar até à entity, em metros. Esta é a definição mais relevante para eventos de proximidade.

• hoverText: Texto a exibir na UI quando o player está perto da entity.

• showHighlight: Se verdadeiro, mostra um destaque na borda da entity quando o player está dentro do alcance. true por padrão.

• showFeedback: Se verdadeiro, mostra feedback de hover, pairando à volta do centro da entity. true por padrão.

• prioridade: Resolve conflitos quando várias entities estão em proximidade. Valores mais altos têm precedência. Se várias entities tiverem o mesmo valor de prioridade, é escolhida a mais próxima.

Remover callbacks

Para remover um callback de proximidade, use a função de remoção correspondente:

pointerEventsSystem.removeOnProximityDown(myEntity)
pointerEventsSystem.removeOnProximityUp(myEntity)
pointerEventsSystem.removeOnProximityEnter(myEntity)
pointerEventsSystem.removeOnProximityLeave(myEntity)

Depois de removida, a entity deixa de reagir a esse evento de proximidade.

Entrada e saída de proximidade

Use pointerEventsSystem.onProximityEnter para executar um callback quando o player entra no alcance de proximidade da entity, e pointerEventsSystem.onProximityLeave quando sai. Isto pode ser usado para mostrar dicas de feedback extra ao player, por exemplo um som ou uma animação quando um item pode ser interagido.

pointerEventsSystem.onProximityEnter(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_POINTER,
            hoverText: 'Perto',
            maxPlayerDistance: 5,
        },
    },
    function () {
        console.log('Player entered proximity')
    }
)

pointerEventsSystem.onProximityLeave(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_POINTER,
            hoverText: 'Perto',
            maxPlayerDistance: 5,
        },
    },
    function () {
        console.log('Player left proximity')
    }
)

Exemplo: porta por proximidade

O exemplo seguinte abre ou fecha uma porta quando o player pressiona um botão enquanto está perto, sem precisar apontar para a porta.

const doorPivot = engine.addEntity()
Transform.create(doorPivot, { position: Vector3.create(3, 0, 4) })

const door = engine.addEntity()
GltfContainer.create(door, { src: 'assets/door.glb' })
Transform.create(door, { position: Vector3.create(-1, 0, 0), parent: doorPivot })

let isDoorOpen = false
const closedRot = Quaternion.fromEulerDegrees(0, 0, 0)
const openRot = Quaternion.fromEulerDegrees(0, 90, 0)

pointerEventsSystem.onProximityDown(
    {
        entity: door,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Abrir / Fechar',
            maxPlayerDistance: 5,
            priority: 1,
        },
    },
    function () {
        if (isDoorOpen) {
            Tween.setRotate(doorPivot, openRot, closedRot, 700)
            isDoorOpen = false
        } else {
            Tween.setRotate(doorPivot, closedRot, openRot, 700)
            isDoorOpen = true
        }
    }
)