Melhor juntos: SwiftUI e RealityKit

Olá! Meu nome é Amanda. Sou engineer do RealityKit. Meu nome é Maks. Sou engineer da SwiftUI. Hoje mostraremos ótimas melhorias na SwiftUI e no RealityKit que os tornam ainda melhores juntos. Veja esta cena adorável. Temos um robô da SwiftUI flutuando e um robô do RealityKit fixo, ambos buscando conexão. Quando se aproximam, vemos faíscas. Mas como podem se aproximar o suficiente para interagir? Maks e eu vamos ensinar como combinar conteúdo de interface tradicional e 3D interativo. Primeiro, vou mostrar novidades do Model3D. Mostrarei como migrar do Model3D para o RealityView e quando escolher cada um. E apresentarei a nova API Object Manipulation.

O RealityKit ganhou novos tipos de componentes, integrando mais recursos da SwiftUI. As informações podem fluir nos dois sentidos entre a SwiftUI e o RealityKit. Vamos explicar. A conversão entre espaços de coordenadas ficou mais fácil. Controle componentes do RealityKit usando animações da SwiftUI. Vamos conectar tudo!

Mostre modelos 3D nos seus apps com apenas uma linha de código no Model3D. No visionOS 26, fizemos duas melhorias no Model3D: animações e carregamento via ConfigurationCatalog. Como o Model3D é uma view da SwiftUI, ele participa do sistema de layout da SwiftUI. Vou usar esse sistema de layout para criar uma placa com o nome do robô.

Agora, a placa mostra que o nome do robô é Sparky.

O Sparky também sabe dançar muito bem! O artista já incluiu essa animação no arquivo do modelo do robô. Uma novidade do visionOS 26 é o tipo Model3DAsset. Carregue e controle animações no conteúdo 3D criando um Model3D com um Model3DAsset. O modelo carrega as animações do ativo e permite escolher qual reproduzir. “Modelo” tem vários significados. Nesta sessão, há convergência entre um framework de interface com um framework de jogos 3D. Em frameworks de interface, modelo é à estrutura de dados que representa as informações usadas pelo app. O modelo armazena os dados e as regras de negócios para a view exibir essas informações. Em frameworks 3D, como o RealityKit, um modelo é um objeto 3D que pode ser colocado em uma cena. Você acessa esse objeto pelo ModelComponent, formado por um mesh resource que define o formato e os materiais que definem a aparência. Às vezes, isso acontece. Dois mundos se encontram, cada um com seus termos, e por vezes acabam se sobrepondo. Agora, vamos voltar ao Sparky e sua animação.

Coloquei o Model3D acima de um seletor, um botão de reprodução e um controle de tempo. Na RobotView, exibo o robô animado, e abaixo coloco um seletor para escolher a animação, junto com os controles de reprodução. Antes, inicializo um Model3DAsset com o nome da cena que quero carregar do pacote. Depois de carregar o recurso, passo para o inicializador do Model3D. Abaixo disso, no VStack, mostro um seletor personalizado que lista todas as animações disponíveis nesse ativo de modelo. Quando um item é escolhido na lista, o seletor define a selectedAnimation do ativo para o novo valor. O Model3DAsset cria um AnimationPlaybackController para controlar a reprodução da animação escolhida. O recurso fornece um animationPlaybackController. Esse objeto pausa, retoma e faz buscas na animação.

Eu passo esse animationController para a minha view RobotAnimationControls, que veremos a seguir. No visionOS 26, a classe atual do RealityKit, AnimationPlaybackController, agora é observável. Na view da SwiftUI, confiro o progresso da animação na propriedade “time”.

Há uma propriedade @Bindable chamada “controller”, ou seja, eu uso o AnimationPlaybackController como modelo de dados. Quando o valor de isPlaying do controller muda, a SwiftUI reavalia a view RobotAnimationControls. Há um controle que exibe o tempo atual da animação em relação à duração total. Arraste esse controle deslizante para navegar pela animação. Veja o Sparky fazendo a animação de comemoração. Posso adiantar ou voltar a animação com o controle deslizante. Vamos, Sparky, é seu aniversário! Agora que o Sparky mostrou o que sabe fazer, ele quer se arrumar para conhecer o outro robô. Eu posso ajudar com as melhorias no tipo ConfigurationCatalog do RealityKit. Esse tipo armazena diferentes versões de uma entidade, como diferentes formas, valores de componentes ou propriedades de materiais. No visionOS 26, dá para inicializar um Model3D com um ConfigurationCatalog e mudar entre as representações.

Para que o Sparky troque de roupa, o artista incluiu um reality file com vários tipos de corpo. Carrego esse arquivo como um ConfigurationCatalog no pacote principal do app. Aí, crio o Model3D usando essa configuração. Esse popover mostra as opções de configuração. Quando escolho uma, a aparência do Sparky muda. Passos de dança? Ok. Roupas? Ok. O Sparky está pronto para conhecer seu novo amigo na estufa do RealityKit. Pode apostar: vai sair faísca! Para ver essas faíscas, vou usar um emissor de partículas. Mas não é algo que eu consiga fazer no tempo de execução com o Model3D. Um emissor de partículas é um componente que adiciono a uma entidade do RealityKit. Explico isso melhor a seguir. Um detalhe importante é que o Model3D não permite adicionar componentes. Por isso, para adicionar um emissor de partículas, vou trocar para o RealityView. Quero mostrar como substituir o Model3D pelo RealityView sem alterar o layout. Primeiro, mudo a view do Model3D para o RealityView. Carrego o modelo do botânico do pacote do app no make closure do RealityView, criando uma entidade. Adiciono a entidade ao RealityView, e o Sparky aparece na tela.

Mas... Agora, a placa de nome ficou muito longe. Isso não acontecia no Model3D. Isso acontece porque o RealityView ocupa todo o espaço disponibilizado pelo layout da SwiftUI. Já o Model3D usa o tamanho intrínseco do arquivo do modelo subjacente. Vou corrigir isso. Aplico o modificador .realityViewLayoutBehavior com .fixedSize para ajustar o RealityView aos limites do modelo. Bem melhor. O RealityView usa os limites visuais das entidades para identificar o tamanho. Esse cálculo é feito uma vez, logo após o make closure ser executado. As outras opções para realityViewLayoutBehavior são .flexible e .centered. Nestes três RealityViews, a base do Sparky fica na origem da cena, marcada por um gizmo, a cruz colorida que mostra os eixos e a origem. À esquerda, com .flexible, o RealityView ignora o modificador. A origem permanece centralizada na visualização. A opção ".centered" centraliza o conteúdo no RealityView. A opção .fixedSize ajusta o RealityView ao conteúdo, como ocorre com o Model3D.

Essas opções não reposicionam ou dimensionam entidades, apenas o ponto de origem do RealityView. Ajustei o tamanho do Sparky no RealityView. Agora vou animar o Sparky novamente. Vou migrar da API de animação do Model3D para a API de animação do RealityKi na entidade. Para saber como trabalhar com animação no RealityKit, veja a sessão “Compor conteúdo 3D interativo no Reality Composer Pro”. Troquei o Model3D pelo RealityView para incluir ParticleEmitterComponent ao Sparky para aparecem faíscas quando os robôs se aproximarem. Os emissores de partículas permitem criar efeitos com centenas de partículas, como fogos, chuva e brilhos. O RealityKit fornece valores predefinidos para eles, e você pode ajustar tudo para obter o efeito desejado. Use o Reality Composer Pro para criar emissores ou configure-os no código. Adicione o emissor de partículas como um componente na entidade. Esses componentes são essenciais no RealityKit e são baseados no paradigma Sistema de componentes de entidade. Cada objeto é uma entidade, e os components definem sua características e comportamentos. Um componente armazena dados sobre uma entidade. Um sistema processa entidades com certos componentes, aplicando lógicas a esses dados. Existem sistemas integrados para animar as partículas, aplicar a física, renderizar e muito mais. Você pode criar sistemas personalizados no RealityKit para a lógica do seu jogo ou app. Confira “Conhecer o RealityKit 2” para saber detalhes sobre o Sistema de componentes de entidade no RealityKit. Vou adicionar um emissor de partículas para cada lado da cabeça do Sparky. Primeiro, crio duas entidades invisíveis que servem como contêineres do efeito. Projetei o emissor para apontar à direita. Adiciono este emissor à entidade invisível do lado direito do Sparky.

No lado oposto, rotaciono a entidade 180° no eixo Y para apontar à esquerda.

Combinando tudo no RealityView, temos o Sparky e sua animação, sua placa de nome no lugar certo e muitas faíscas.

O RealityKit é excelente para criação detalhada. Para jogos, experiências lúdicas ou controle preciso de comportamentos 3D, escolha o RealityView. Use o Model3D para exibir um recurso 3D independente. Pense no Model3D como o Image da SwiftUI, mas para 3D.

Os novos catálogos de animação e configuração ampliam o que o Model3D pode fazer. Se precisar de acesso direto às entidades e sistemas, faça a transição do Model3D para o RealityView usando o realityViewLayoutBehavior. Agora vou detalhar a nova API Object Manipulation no visionOS 26, que permite pegar objetos virtuais no app. A manipulação funciona tanto no SwiftUI quanto no RealityKit. Com ela, mova o objeto com uma mão, gire com uma ou ambas e dimensione com movimento de abrir e fechar as mãos. Também é possível passar o objeto de uma mão para outra.

Há dois modos de ativar isso, dependendo se o objeto é uma entidade do RealityKit ou uma view da SwiftUI. Na SwiftUI, adicione o novo modificador manipulable. Para desativar o redimensionamento, mas permitir mover e girar, defino as Operations compatíveis.

Para dar sensação de peso ao robô, defino inertia como high.

O modificador .manipulable funciona quando o Sparky está em uma view do Model3D. Ele é aplicado ao Model3D inteiro ou a qualquer view à qual estiver anexado. No RealityView, prefiro ativar a manipulação só para o robô, não para todo o RealityView. No visionOS 26, o ManipulationComponent é um novo tipo para permitir a manipulação de objetos em uma entidade. A função estática configureEntity adiciona o ManipulationComponent à entidade. Ela também adiciona o CollisionComponent para que o sistema reconheça toques. E adiciona InputTargetComponent, indicando que a entidade responde a gestos. Por fim, um HoverEffectComponent aplica o efeito visual quando alguém olha para ele ou passa o mouse. Essa é a única linha necessária para ativar a manipulação em uma entidade. Para personalizar ainda mais, há vários parâmetros opcionais. Aqui, uso um efeito de holofote roxo. Permito todos os tipos de entrada: toque direto, olhar indireto e pinça. Defino formas de colisão que contornam o robô. Para responder à interação do usuário com um objeto no app, o sistema de manipulação dispara eventos em momentos importantes: quando a interação começa e termina, atualiza enquanto a entidade é movida, girada e redimensionada, quando é solta e quando é transferida de uma mão para outra. Assine esses eventos para atualizar o estado. Normalmente, sons padrão são reproduzidos quando a interação começa, ocorre uma transferência de mão ou o objeto é solto. Para aplicar sons personalizados, primeiro defini audioConfiguration como none. Isso desativa os sons padrão. Depois, assino o evento ManipulationEvent DidHandOff, disparado quando alguém passa o robô de uma mão para a outra. Nesse closure, toco o áudio personalizado. Bem, Maks. A jornada do Sparky tem sido emocionante: movendo-se no Model3D, buscando um lar em um RealityView, mostrando sua personalidade com faíscas e permitindo interação direta. Foi um grande avanço em direção à estufa do RealityKit. Sem dúvida. Mas para que o Sparky se conecte com o outro robô, os objetos no espaço virtual precisam de novos recursos. Eles devem reagir a gestos, mostrar informações sobre si e acionar ações de modo nativo na SwiftUI.

A jornada do Sparky rumo à estufa do RealityKit se resume a criar conexões. Conexões profundas exigem interações avançadas. É exatamente isso que os novos componentes da SwiftUI do RealityKit oferecem. Os novos componentes do visionOS 26 trazem ao RealityKit recursos eficientes e conhecidos do SwiftUI. O RealityKit apresenta três componentes principais: Primeiro, o ViewAttachmentComponent permite adicionar views da SwiftUI às suas entidades. Depois, o GestureComponent torna as entidades responsivas a toque e gestos. E o PresentationComponent, que mostra views da SwiftUI, como popovers, de dentro da sua cena do RealityKit.

No visionOS 1, você declarava attachments como parte do inicializador do RealityView. Após avaliar seu attachment view builder, o sistema chamava o update closure, entregando os resultados como entidades. Assim, você podia adicionar essas entidades à cena e posicioná-las no espaço 3D. No visionOS 26, isso foi simplificado. Agora, você cria attachments usando um componente do RealityKit de qualquer lugar do app. Basta criar um ViewAttachmentComponent informando qualquer view da SwiftUI. Depois, adicione-o aos componentes de uma entidade.

Assim, movi o NameSign da SwiftUI para o RealityKit facilmente. Vamos explorar gestos agora! Você já pode anexar gestos ao seu RealityView usando modificadores de gesto targetedToEntity. A novidade do visionOS 26 é o GestureComponent. Assim como com o ViewAttachmentComponent, adicione o GestureComponent às entidades, passando gestos do SwiftUI tradicionais. Os valores dos gestos, por padrão, são informados no espaço da entidade. Muito prático! Uso o GestureComponent com um toque para alternar a placa de nome.

Veja. O nome deste robô é... Bolts!

Dica: Em qualquer entidade-alvo de gestos, adicione o InputTargetComponent e o CollisionComponent. Essa dica vale para o GestureComponent e para a API de gestos.

GestureComponent e ViewAttachmentComponent facilitam criar uma placa de nome para o Bolts. Mas o Bolts está se preparando para uma visita especial: o Sparky! O Bolts quer estar impecável para o encontro deles na estufa. Hora de trocar de roupa. Vou substituir o nome por uma interface para escolher a roupa. Uma decisão muito importante.

Vou mostrar isso em um popover na interface, usando o PresentationComponent pelo RealityKit.

Primeiro, substituo o ViewAttachmentComponent pelo PresentationComponent. Esse componente recebe uma vinculação booleana para controlar quando o popover é exibido e para notificar quando ele for fechado. O parâmetro configuration define o tipo de apresentação desejada. Estou especificando o popover. Dentro do popover, apresento uma view com opções de um catálogo de configurações para vestir o Bolts. Assim, posso ajudar o Bolts a escolher sua melhor cor para receber a visita do Sparky.

Maks, você acha que o Bolts gosta do verão? Ou prefere o outono?

É uma piada sobre moda.

O Bolts está vestido para arrasar. Mas primeiro, ele precisa trabalhar. O Bolts rega as plantas ne cenário. Vou criar um minimapa, como os dos jogos, para rastrear a posição do Bolts na estufa. Para isso, preciso observar o componente de transformação do robô. No visionOS 26, as entidades são observáveis. Elas podem notificar outros códigos quando suas propriedades mudam. Para ser notificado, basta acessar a propriedade observable.

Nessa propriedade, você pode acompanhar mudanças na posição, tamanho e rotação, na coleções secundárias e até nos componentes, inclusive os personalizados. Observe essas propriedades utilizando um bloco withObservationTracking. Ou use o sistema de observação integrado da própria SwiftUI. Usarei a SwiftUI para implementar meu minimapa. Saiba mais sobre observação na sessão “Conhecer a observação ba SwiftUI”. Nesta view, mostro a posição da minha entidade em MiniMap. Acesso esse valor observável direto na entidade. Assim, informo à SwiftUI que minha view depende desse valor.

Conforme o Bolts se move pela estufa, regando as plantas, sua posição muda. Cada vez que isso acontece, a SwiftUI chama o body da minha view, movendo o símbolo no minimapa. Para entender o fluxo de dados da SwiftUI, confira “Fundamentos sobre dados na SwiftUI”. Nossos amigos robôs estão tomando forma. É isso que queremos! Gostei da sua explicação sobre as diferenças de significado do termo “modelo”. Às vezes, você precisa passar dados do seu modelo de dados para o modelo 3D, e vice-versa. No visionOS 26, entidades observáveis são uma nova ferramenta para isso. Desde o início, já era possível passar informações da SwiftUI para o RealityKit no fechamento update do RealityView. Agora, a propriedade observable da entidade permite enviar informações no sentido contrário. Entidades do RealityKit podem atuar como objetos do modelo para atualizar views da SwiftUI. Então, agora o fluxo de dados é bidirecional: do SwiftUI para a RealityKit e do RealityKit para a SwiftUI. Mas... será que isso pode criar um loop infinito? Sim. Vejamos como evitar loops infinitos entre a SwiftUI e o RealityKit. Ao ler uma propriedade observable dentro do body de uma view, a view passa a depender dessa propriedade. Se o valor da propriedade mudar, a SwiftUI atualiza a view e executa o body novamente. O RealityView tem um comportamento especial. Pense no fechamento update como uma extensão do corpo da view que o contém.

A SwiftUI chama o fechamento sempre que um estado da view muda, não só quando o estado explicitamente observado naquele fechamento muda. No fechamento update do meu RealityView, vou alterar essa posição. Isso gravará no valor da posição, o que faz com que a SwiftUI atualize a view e reexecute o body, criando um loop infinito.

Para evitar o loop infinito, não modifique um estado observado dentro do seu fechamento update.

Você pode modificar entidades que não estão sendo observadas. Isso não cria o loop, porque as mudanças nelas não vão disparar uma reavaliação do body da view pela SwiftUI. Se precisar modificar uma propriedade observada, verifique antes o valor atual e evite regravar o mesmo valor. Isso quebra o ciclo e impede o loop infinito. Note que o make closure do RealityView é especial. Acessar uma propriedade observável dentro do make closure não cria dependência. Ela não é incluída no escopo de observação da view. O make closure não é executado novamente nas alterações. Ele só é executado quando a view que o contém aparece pela primeira vez. Você também pode atualizar propriedades de uma entidade observada dentro do seu sistema personalizado. A função de update de um sistema não está no escopo de avaliação do body da SwiftUI, então é um ótimo lugar para modificar valores observados de entidades.

Os fechamentos de gestos também não estão no escopo a avaliação do body da SwiftUI. Eles são chamados em resposta à interação do usuário. Você também pode modificar os valores das entidades observadas aqui. Em resumo, é seguro modificar as entidades observadas em lugares específicos.

Se você encontrar um loop infinito no app, aqui vai uma dica para corrigir: Divida as views maiores em views menores e independentes, cada uma apenas com o estado necessário. Assim, uma mudança em uma entidade não relacionada não fará com que a view menor seja reavaliada. Isso também é ótimo para o desempenho! Maks, pode ser que você nem precise usar mais o fechamento update. Já que sua entidade pode ser o estado da view, você pode modificá-la nos lugares em que já muda o estado e ignorar o fechamento update. É verdade. Evitar loops infinitos é algo que sempre preciso reaprender. Mas sem o update closure, é menos provável que eu crie um. Acho que é hora de reunir o Bolts e o Sparky. O Bolts finalmente acabou o trabalho e pode encontrar o Sparky. Enquanto levo o Sparky até o outro robô e os dois se aproximam, quero que faíscas comecem a surgir conforme eles se aproximam. Vou usar a nova API Unified Coordinate Conversion para isso. O Sparky está em uma view da SwiftUI do Model3D, e o Bolts é uma entidade na estufa do RealityKit. Preciso da distância absoluta entre eles, mesmo estando em espaços de coordenadas diferentes. Para resolver isso, o framework Spatial define agora um protocolo CoordinateSpace3D, que representa um espaço de coordenadas abstrato. Você pode facilmente converter valores entre tipos que adotam o CoordinateSpace3D, até entre diferentes frameworks. Os tipos Entity e Scene do RealityKit agora adotam o CoordinateSpace3D. No lado da SwiftUI, o GeometryProxy3D possui agora a função .coordinateSpace3D(), que retornará seu espaço de coordenadas. Além disso, vários tipos de gesto podem fornecer valores relativos a qualquer CoordinateSpace3D informado. O protocolo CoordinateSpace3D funciona convertendo um valor do espaço do Sparky para um espaço compartilhado entre o RealityKit e a SwiftUI. Depois disso, ele converte do espaço compartilhado para o do Bolts, considerando detalhes como conversão de pontos para metros e direção dos eixos. Na view do Model3D do Sparky, sempre que a geometria da view muda, o sistema chama a função onGeometryChange3D. Ela recebe um GeometryProxy3D, que uso para obter o espaço de coordenadas. Assim posso converter a posição da view para um ponto no espaço da entidade e saber a distância real entre os dois robôs. Agora, quando Amanda aproxima o Bolts e o Sparky, as faíscas aumentam. Quando se afastá-os, as faíscas diminuem.

A seguir, vou ensinar esses robôs a se moverem juntos e coordenarem suas ações. Vou usar a animação feita pela SwiftUI para componentes do RealityKit. A SwiftUI já oferece ótimas APIs para animar mudanças em propriedades das views. Neste exemplo, animo a view do Model3D onde o Sparky está: Mando ele para a esquerda ao alternar, e ele quica de volta para a posição original ao alternar novamente. Adiciono uma animação à vinculação isOffset, pedindo uma animação de quicar. No visionOS 26, é possível usar a animação da SwiftUI implicitamente nas mudanças de componentes do RealityKit. Basta definir um componente compatível na entidade em um bloco de animação RealityKit, e o framework cuida do restante. Há duas formas de associar animação a uma mudança de estado. Dentro de um RealityView, use o content.animate() para definir novos valores dos componentes dentro do bloco de animação. O RealityKit usará a animação associada à transação da SwiftUI que acionou o fechamento update, neste caso, a ação de quicar.

A outra forma é chamar Entity.animate(), passando uma animação da SwiftUI e um fechamento que modifica os componentes. Assim, sempre que a propriedade isOffset mudar, mando o Sparky para a esquerda ou a direita usando a posição da entidade. Ao definir a posição dentro do bloco animate, inicio uma animação implícita de transformação, mudando a posição da entidade suavemente. A força da animação implícita se destaca quando combino com a API Object Manipulation apresentada pela Amanda. Posso usar uma animação da SwiftUI para personalizar o comportamento de soltar ao Bolts. Primeiro, desativo o comportamento padrão de soltar ao definir para .stay. Depois, assino o evento WillRelease na interação de manipulação. Quando o objeto estiver para ser solto, mudo o transform do Sparky para identity, redefinindo o tamanho, a translação e a rotação. Como modifiquei o transform do Sparky no bloco animate, ele quica de volta para o lugar. Agora, a animação de retorno do Sparky ficou bem mais divertida! Esses componentes integrados do RealityKit têm animações implícitas, incluindo o transform, o componente Audio e os componentes Model e Light, que têm propriedades de cor. O Sparky e o Bolts tiveram uma jornada e tanto. É ótimo ver o poder da SwiftUI e do RealityKit juntos. Com essa integração, você pode criar apps espaciais realmente excepcionais, impulsionando a conexão entre o virtual e o físico. Imagine as possibilidades ao integrar os componentes da SwiftUI nas cenas do RealityKit e permitir que entidades mudem dinamicamente o estado da SwiftUI. Assim como o Sparky e o Bolts, esperamos inspirar você a conectar a SwiftUI e o RealityKit com ainda mais criatividade. Vamos construir o futuro juntos!