Портал, манулы и мячи: опыт разработки для Apple Vision Pro. Часть 1

В статье описан мой опыт разработки мини-игр для Apple Vision Pro в условиях жёсткого ограничения во времени. Расскажу, с какими сложностями я столкнулся в ходе работы с 3D-моделями, и поделюсь способами их преодоления. Лайфхаки для упрощения работы с RealityViewContent и Reality Composer Pro прилагаются.

Об авторе

Илья Проскуряков – iOS-разработчик в компании Effective, опыт работы 1,5 года. Участник конференций KODE Waves и DevFest.

Предыстория: хакатон

13–14 апреля 2024 г. Омск принял участие в 55-м Ludum Dare – всемирном двухдневном хакатоне по разработке игр. Мы с коллегами выбрали для работы нетипичный объект – очки Apple Vision Pro, которые незадолго до этого появились у нас в компании. Очки одни, нас трое – позже объясню, почему это уточнение важно.

Технология для рынка новая, информации для разработчика о ней немного – но тем интереснее!

У нас было полторы недели, чтобы придумать, с какой идеей мы придём на хакатон. В итоге остановились на ОСУ, но для глаз. ОСУ – это тип игр на скорость, в которых пользователь кликает по простой движущейся цели. Вместо мышки у нас были глаза, потому что Apple Vision Pro умеет отслеживать их движение. 

Однако нашу идею нужно было связать и с общей идеей хакатона, которая становится известна только в день старта. В этот раз ей стал summoning – призыв. Нас вдохновил один из конкурентов, решивший сделать игру о коте, которого нужно звать к миске. Что бы мы делали без котов (на самом деле, о таком варианте событий я тоже расскажу)! 

Мы запланировали создать мини-игру, в центре которой будет – хороший, я считаю, маркетинговый ход! – мемный манул. Стек: Swift, фреймворки SwiftUI, ARKit и RealityKit. 

• RealityKit позволяет рендерить 3D-объекты и взаимодействовать с их физикой, геометрией и другими свойствами;

• ARKit помогает отслеживать всё происходящее вокруг: движения рук пользователя, различные плоскости и мир в целом. ARKit можно назвать подспорьем RealityKit на visionOS.

Начинаем с меню

Дизайн главного меню скромный, но примерно так выглядит любой 2D-экран под visionOS. Зато его можно менять в размерах или перемещать в пространстве. Например, перенести из комнаты в комнату, где экран и останется даже в следующих сеансах.

По факту, вы пишете на обычном фреймворке SwiftUI. Кодить в нём под visionOS – всё равно что писать под iOS: такие же VStack, модификаторы, паддинги и спейсеры.

    var body: some View {         NavigationStack {             VStack {                 CenteredTitle("Summon a Cat!")                     .padding(.vertical, 10)                 Spacer()                 VStack {                      CatTypeSelection(viewModel: viewModel)                      PlayButton(showImmersiveSpace: $showImmersiveSpace)                      AboutButton {                          isShowingAboutView = true                      }                  }                  .padding(.bottom, 20)                  .frame(maxHeight: 540)                 Spacer()             }

struct PlayButton: View {     @Binding var showImmersiveSpace: Bool     var body: some View {         VStack {             Text(showImmersiveSpace ? "Stop" : "Play")                 .font(.title)                 .fontWeight(.bold)                 .foregroundColor(.white)                 .frame(width: 340, height: 110)                 .background(showImmersiveSpace ? Color.red : Color.green)                 .cornerRadius(20)         }         .onTapGesture {             showImmersiveSpace.toggle()         }         .hoverEffect()         .clipShape(RoundedRectangle(cornerRadius: 20))         .padding(.top, 50)     } }

Чтобы окончательно убедиться в верности своих наблюдений, я запустил этот код на iOS – и ничего не сломалось! Получается, если написать один код под разные платформы, можно получить функционально одинаковый результат.

Мини-игра № 1 «Впылесось манула»

Надев гарнитуру, пользователь обнаруживает себя с пылесосом в руке. Вокруг него вокруг своей оси вращается множество манулов – их-то и нужно втянуть в пылесос.

Счёт идёт до десяти манулов, после чего перед пользователем из ниоткуда возникает гигантский – и очень недовольный – манул. 

Вообще, изначально мы хотели, чтобы манул появлялся из портала, но на реализацию этой идеи немного не хватило времени. Дальше объясню почему.

Создаём и наполняем пространство

Разработку мини-игры мы начали с создания пространства для дополненной реальности.

Для этого в первую очередь нужно объявить ImmersiveSpace, дополненное пространство, и задать ему ID.

struct LudumDare55App: App {          @StateObject private var foodEncounterViewModel = FoodEncounterView.ViewModel()     @StateObject private var viewModel = AppViewModel()     @State private var immersionStyle: ImmersionStyle = .mixed     @State var audioPlayer: AVAudioPlayer!     var body: some Scene {         WindowGroup {             ScrollView {                 ContentView(viewModel: viewModel)                     .frame(minWidth: 640, minHeight: 500)                     .onAppear() {                         let sound = Bundle.main.path(forResource: "ДИКИЕ РЫСИ[music]", ofType: "mp3")                         self.audioPlayer = try! AVAudioPlayer(contentsOf: URL(fileURLWithPath: sound!))                         self.audioPlayer.numberOfLoops = -1                         self.audioPlayer.volume = 0.3 // Set the volume to half the maximum volume                         self.audioPlayer.play()                     }                 FoodEncounterView()                     .environmentObject(foodEncounterViewModel)             }         }         ImmersiveSpace(id: "ImmersiveSpace") {             ImmersiveView(viewModel: viewModel)         }

За время работы в visionOS я сделал следующее наблюдение: единовременно в приложении может быть отображено только одно ImmersiveSpace. Environment-переменные – openImmersiveSpace и dismissImmersiveSpace – открывают и закрывают это пространство. Эти функции асинхронные, потому их нужно вызывать через await. Также в функцию нужно передать ID – и готово!

@Environment(\.openImmersiveSpace) private var openImmersiveSpace @Environment(\.dismissImmersiveSpace) private var dismissImmersiveSpace

.onChange(of: showImmersiveSpace) { _, newValue in                 Task {                     if newValue {                         switch await openImmersiveSpace(id: "PortalSpace") {                         case .opened:                             immersiveSpaceIsShown = true                         case .error, .userCancelled:                             fallthrough                         @unknown default:                             immersiveSpaceIsShown = false                             showImmersiveSpace = false                         }                     } else if immersiveSpaceIsShown {                         await dismissImmersiveSpace()                         immersiveSpaceIsShown = false                     }                 }             }

Следующий шаг – наполнить созданное пространство контентом. 

В closure ImmersiveSpace находим ImmersiveView – стандартную вьюшку SwiftUI, в которую нужно положить RealityView. У RealityView в closure есть content – inout-параметр типа RealityViewContent (в него помещаются 3D-модели), а также attachments – 2D-вьюшки, которые прикрепляются к 3D-объектам. Так, счётчик впылесошенных манулов, расположенный на ручке пылесоса, сделан через attachments.

Здесь же находится важная функция update, которая вызывается на смену кадра, позволяя изменять пространство с течением времени.

RealityView { content, attachments in             await realityKitSceneController.firstInit(&content, attachments: attachments, catType: viewModel.catType)         } update: { content, attachments in             realityKitSceneController.updateView(&content, attachments: attachments)         } placeholder: {             ProgressView()         } attachments: {             let _ = print("--attachments")             Attachment(id: "score") {                 let goodScore = forTrailingZero(realityKitSceneController.score)                 Text("\(goodScore)")                     .font(.system(size: 100))                     .foregroundColor(.white)                     .fontWeight(.bold)             }         }

RealityViewContent – это структура, которая может отвечать за всё наполнение вашего пространства. Наполнять её приходится из разных частей кода, что неудобно: для этого нужно передавать эту структуру как inout.

Я нашёл решение, позволяющее вынести логику заполнения в отдельную сущность и упростить процесс.

В realityKit есть class Entity, который выполняет похожие функции по заполнению пространства контентом. Алгоритм такой:

1. Создать корневую пустую 3D-вьюшку rootEntity;

2. Положить её в контент с помощью метода add(content.add(rootEntity));

3. Положить в rootEntity непустые Entity, которые будут содержать ваши 3D-модели:

rootEntity.addChild(entity)

Сотворение мира

Прежде чем создать портал, мы создали мир, который будет виден за ним. Это первый элемент, а всего их три:

1. Мир, который будет отображаться внутри портала;

2. Сущность портала – чёрный круг;

3. Якорь – сущность, к которой прикрепляются все объекты. Им могут быть руки пользователя, стены помещения, пол, столы и т.д. 

Дальше как в сказке: разработчик кладёт мир в портал, портал – в якорь, а потом все три сущности кладёт в контент.

Чтобы появился мир, нужно создать сущность и задать ей соответствующее свойство. За него отвечает компонент World Component. Он отделяет всё, что лежит снаружи портала, от того, что находится у него внутри. С этим компонентом мир будет лежать именно в портале. 

public func makeWorld() -> Entity {     let world = Entity()     world.components[WorldComponent.self] = .init()     let earth = try! Entity.load(named: "solarSystem", in: realityKitContentBundle)     world.addChild(earth)     return world }

Чтобы добавить контент, функция load загружает ассет Solar System, заранее настроенный  в Reality Composer Pro.

У Apple есть инструмент Reality Composer Pro, помогающий упростить подготовку 3D-контента для приложений под visionOS. Он напоминает редактор сцен Unity.

Сначала нам понадобятся объекты, которые нужно отобразить: 3D-модели в формате USD. 

На этом этапе мы столкнулись с одной из существенных проблем при разработке игр под visionOS – с поиском 3D-моделей. Вариантов их получения немного: купить готовую (диапазон цен от 2 до 2000 долларов), создать самому (если умеешь) или поискать бесплатные. В Reality Composer Pro есть небольшой набор бесплатных ассетов, но я сосредоточил поиск на сообществах, сайте TurboSqiud и телеграм-чатах.

Когда 3D-модели найдены, их нужно импортировать в сцену: просто перетащить либо на панель слева, либо прямо на сцену. Затем – расположить на сцене. 

Положение объекта задается координатами на трех осях – x, y, z.

Неочевидный момент: чтобы понять, куда направлена каждая из координат, сделайте такой жест: большой палец – ось x, указательный – ось y, и средний – ось z.

Я не знал об этом жесте, поэтому поначалу действовал наугад, постоянно перезапуская проект для проверки.

Также в Reality Composer Pro можно менять размер 3D-модели, вращать и разворачивать её. Можно добавлять к объекту компоненты: освещение, тени, коллизии, физику, звуки. Например, от большого манула может идти рычание, а от портала – трансовая музыка.

Открываем портал

Чтобы создать портал, нужно сделать сущность и настроить у неё Portal Component, в который мы поместим мир, и Model Component – внешний вид этой сущности, то есть чёрный круг. Этого достаточно для его работы. 

public func makePortal(world: Entity) -> Entity {     let portal = Entity()     let emitters = try! Entity.load(named: "Particle", in: realityKitContentBundle)     emitters.scale = SIMD3(x: 1, y: 1, z: 1)     portal.components[ModelComponent.self] = .init(mesh: .generatePlane(width: 1,                                                                         height: 1,                                                                         cornerRadius: 0.5),                                                    materials: [PortalMaterial()])     portal.components[PortalComponent.self] = .init(target: world)     portal.addChild(emitters)     return portal }

Изначально портал был горизонтальным, а потом я повернул его на 90 градусов. Это повлекло за собой разворот всей системы координат для мира внутри портала, поэтому для «правила трёх пальцев»‎ положение руки изменилось соответственно повороту портала. 

Однако просто чёрный портал – это скучно. Нам хотелось красоты, и через Reality Composer Pro мы добавили её с помощью Particles.

В Particles можно настроить, как часто будут пульсировать частицы, их вид, количество, форму и цвет.

Вручение пылесоса

Ещё одна интересная задача в этой мини-игре – прикрепление пылесоса к руке пользователя. Также пылесос должен взаимодействовать с вращающимися манулами.

Начинаем с загрузки ассетов. Настраиваем коллизии через Collision-компоненту – маску и группу. Маска отвечает за то, с какими группами будет взаимодействовать пылесос, а группа – за то, к какой группе относится объект. Collision-компонента задается битовой маской. 

if let handlePart = scene.findEntity(named: "handlePart") {                 handlePart.components[CollisionComponent.self]?.filter.mask = manulCollisionGroup                 handlePart.components[CollisionComponent.self]?.filter.group = vacuumCollisionGroup    if let headPart = scene.findEntity(named: "headPart") {                 headPart.components[CollisionComponent.self]?.filter.mask = manulCollisionGroup                 headPart.components[CollisionComponent.self]?.filter.group = vacuumCollisionGroup

Создаём Collision Group, куда передаётся битовая операция, – и получается битовая маска.

    private var manulCollisionGroup = CollisionGroup(rawValue: 1 << 0)     private var vacuumCollisionGroup = CollisionGroup(rawValue: 1 << 1)

Чтобы рука игрока могла «‎взять»‎ пылесос, первым делом нужно научиться следить за руками пользователя. Для этого создаём сессию ARKit session.

  private var worldTracking = WorldTrackingProvider()   private var handTracking = HandTrackingProvider()   private var sceneReconstruction = SceneReconstructionProvider(modes: [.classification])   private var session = ARKitSession()

Следите за руками! 

У сессии есть метод run, который в качестве параметра принимает массив DataProvider. Для отслеживания движений рук используется Hand Tracker Provider.

 setupTask = Task {             do {                 try await session.run([worldTracking, handTracking, sceneReconstruction])             } catch {                 print("Error Can't start ARKit \(error)")             }         }

Выбираем правую руку и получаем её якорь с параметром originFromAnchorTransform – локацию руки относительно мира. Её мы присвоили ручке пылесоса. 

        if handTracking.state == .running,            let rightHand = handTracking.latestAnchors.rightHand,            rightHand.isTracked,  let transform = Transform(matrix: rightHand.originFromAnchorTransform) handlePartModel?.position = transform.translation

Также через метод Look нужно настроить, куда будет смотреть ручка пылесоса: позиция объекта задаётся через поле position, а метод look настраивает то, куда будет направлен объект.

handlePartModel?.look(at: globalDirectionPoint3, from: transform.translation, relativeTo: controllerRoot)

Кот, который не гуляет сам по себе

И вообще не гуляет, а вращается вокруг своей оси. Как мы закрутили манулов?

1. Создали собственный кастомный компонент – структуру, которая будет конформить протокол Component, – задали в нём нужные поля и зарегистрировали. 

struct RotateComponent: Component {     var isCollecting: Bool = false     var animationProgress: Float  = 0.0     var startPositionY: Float?     var endPositionY: Float? }

2. Для взаимодействия с этим компонентом нужна система. Поэтому мы создали класс, законформили протокол System, – и у него появилась возможность переопределить метод Update.
   Update вызывается каждый раз на обновление фрейма, а частота его вызова зависит от частоты обновления кадров в visionOS. Для очков это ~90 Гц, соответственно, обновление будет происходить 90 раз в секунду. 

3. Нужно найти сущность, которая соответствует определённому параметру (у нас это та, у которой есть компонент Rotate Component), изменить значение её поля orientation – и объект начнёт вращаться.

 func update(context: SceneUpdateContext) {         let results = context.entities(matching: Self.query, updatingSystemWhen: .rendering)         for result in results {             if var component = result.components[RotateComponent.self] {                 let speedMultiplier: Float = component.isCollecting ? 10.0 : 1.0                 result.orientation = result.orientation * simd_quatf(angle: speedMultiplier * Float(context.deltaTime), axis: .init(x: 0.0, y: 0.0, z: 1.0))

Важно не забыть зарегистрировать и компонент, и систему! Для этого нужно где-нибудь вызвать соотвествующие функции.

RotateSystem.registerSystem() RotateComponent.registerComponent()

На этом наша работа над первой мини-игрой завершилась.

Мини-игра № 2: «Покорми манула (не собой)!» 

Во второй игре пользователю нужно задобрить большого манула. Сделать это несложно, ведь манул, как и все коты, любит вкусно поесть. 

Механика простая: в пространстве вокруг игрока летают бургеры и помидоры, и он специальным жестом ловит бургеры. Помидоры ловить нельзя, иначе манул разозлится и съест игрока.

С точки зрения кода эта мини-игра проще игры про манулов и пылесос. Чтобы наполнить мир вокруг игрока бургерами и помидорами, нужно вызвать функции Add Burger и Add Tomatoes столько раз, сколько бургеров или помидоров в пространстве мы хотим.

var body: some View {         // RealityView to display augmented reality content         RealityView { content in             // Add immersive scene to the content             if let scene = try? await Entity(named: "ImmersiveScene", in: realityKitContentBundle) {                 content.add(scene)             }                          // Add content entities and food             content.add(foodModel.setupContentEntity())                          // Add food  based on foodMax             for index in 0..<viewModel.foodMax {                 cubeList.append(foodModel.addBurger(name: "Burger\(index + 1)"))             }                          for index in 0..<50 {                 cubeList.append(foodModel.addTomato(name: "Tomato\(index + 1)"))             }         }         // Add tap gesture to interact with entities         .gesture(             SpatialTapGesture()                 .targetedToAnyEntity()                 .onEnded { value in                     print(value.entity.name)                     if value.entity.name.hasPrefix("Object_0") {                         incorrect()                     } else {                         correct()                     }                     foodModel.removeModel(entity: value.entity)                                      }         )

Также нужно задать стандартный жест для Apple Vision Pro, при котором указательный и большой пальцы касаются друг друга. Это легко делается через SpatialTapGesture() (строка 23). Его модификатор .targetedToAnyEntity() позволяет этому жесту взаимодействовать с любыми объектами, которые находятся в Immersive View.

Функция Add Burger простая: грузим ассет с моделью бургера и добавляем компоненты:

• Input target component, который позволяет пользователю взаимодействовать с объектом, у которого есть этот компонент;

• Hover эффект, выделяющий объект, на который смотрит пользователь. Что-то вроде кнопки, на которую наведён курсор.

func addBurger(name: String) -> Entity {         do {             let entity = try ModelEntity.load(named: "burger.usdz", in: realityKitContentBundle)             entity.generateCollisionShapes(recursive: true)             entity.name = name             entity.components.set(InputTargetComponent(allowedInputTypes: .indirect))             entity.components.set(HoverEffectComponent())                          entity.position = getRandomPosition()                          contentEntity.addChild(entity)                          return entity         } catch {             return Entity()         }     }

Также объекту нужно задать позицию. Её можно сгенерировать рандомно – через функцию, которая возвращает структуру SIMD3, отвечающую за координатную сетку. В ней и генерируются рандомные значения.

    private func getRandomPosition() -> SIMD3<Float> {         return SIMD3(             x: Float.random(in: -10...10),             y: Float.random(in: -10...10),             z: Float.random(in: -10...10)         )     }

На этом этапе работа над мини-игрой была завершена. Вообще, запылесошивание маленьких манулов и задабривание большого изначально предполагались этапами одной игры. Но нам не хватило времени, чтобы собрать их в один сценарий, поэтому мы сделали две отдельные мини-игры, которые можно запустить из общего меню.

Звуковое сопровождение

Во время первой мини-игры звучит синтезированный голос, подсчитывающий котов, – почти как в знаменитом десятичасовом меме!   

private var manulSounds: [AudioFileResource?] = []

Для этого заполняем массив аудиоресурсами.

manulSounds.append(try? await AudioFileResource.load(named: "1 манул.mp3", in: Bundle.main)) manulSounds.append(try? await AudioFileResource.load(named: "2 манула.mp3", in: Bundle.main)) manulSounds.append(try? await AudioFileResource.load(named: "3 манула.mp3", in: Bundle.main)) manulSounds.append(try? await AudioFileResource.load(named: "4 манула.mp3", in: Bundle.main))

У каждой сущности есть готовая функция playAudio, в которую нужно прокинуть аудиоресурс.

        case 1:             event.entityA.playAudio(manulSounds[0]!)         case 2:             event.entityA.playAudio(manulSounds[1]!)         case 3:             event.entityA.playAudio(manulSounds[2]!)

Такими были главные этапы работы нашей команды на хакатоне. Готов обсудить их и ответить на ваши вопросы. А во второй части статьи я расскажу об опыте разработки игры, требующей тщательной работы с физикой.