<hr>
<p>首页：<a href="https://xz3t11cmy1.feishu.cn/wiki/WqkRwxn9Vi4e5ikSVp8cJTPxnje">漫游Apple Vision Pro</a></p>
<p>Code Repo: https://github.com/xuchi16/vision-os-workshop/tree/main</p>
<p>Project Path: https://github.com/xuchi16/vision-os-workshop/tree/main/9_CarControl</p>
<hr>
<p>本文主要包含以下内容：</p>
<ul>
<li>加载实体的基本操作和阴影设置</li>
<li>基本的小车移动逻辑</li>
<li>UI 和手柄操控物体移动</li>
</ul>
<p><img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f9e37b8f5b524dd59b59e2a60aa76b73~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=2762&h=1536&s=4804990&e=png&b=99938b" alt="" referrerpolicy="no-referrer"></p>
<h1>目标及设计</h1>
<p>这个应用我们希望实现如下基本功能</p>
<ul>
<li>主页面：控制打开和关闭 Immsersive Space，在打开的情况下控制小车移动</li>
<li>游戏场景：包含地板和小车，实现基本的光影。小车可以在地板上移动，超过边界后会掉落</li>
<li>手柄控制：通过手柄控制小车移动</li>
</ul>
<p>小车是否移动依赖于用户输入，而 ECS 系统中，由 System 控制对应的 Component 移动。因此需要让不同的控制器、页面、组件等通过一个 model 共享状态，输入源（UI/手柄）更改状态，而 System 根据当前的状态控制物体移动：</p>
<ul>
<li>数据传递：定义一个 ViewModel 用于存储当前用户的输入状态，在 App 中初始化，并将其传递给各页面和组件（蓝色部分）</li>
<li>控制流：<code>ContentView</code>和<code>GameController</code>作为输入源，将用户动作（图中绿色部分，如按下了前进/后退键）更新到 ViewModel 中，这样负责控制的<code>MoveSystem</code>就能够读取到，并相应地控制小车移动</li>
</ul>
<p><img src="https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/5c64d8180e804e249fa3ea3a0a370d5d~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1672&h=596&s=55546&e=png&b=ffffff" alt="design_graph.png" referrerpolicy="no-referrer"></p>
<h1>基本实现</h1>
<h2>ViewModel</h2>
<p>ViewModel 是这个应用同步状态的核心数据结构，需要记录当前用户按住了哪些按键。基本的按键包括上下左右，此外，还有左上、左下、右上、右下几个方向。但只需要定义上下左右四个方向，当用户按下左上这类复合按键时，同时将左和上置为 true 即可。</p>
<pre><code class="language-swift">@Observable
class ViewModel {
var forward = false
var backward = false
var left = false
var right = false
}
</code></pre>
<h2>CarControlApp</h2>
<p>CarControlApp 作为入口，初始化 model 并传递给下一级组件。</p>
<ul>
<li>通过环境变量传递给<code>ContentView</code>和<code>ImmersiveView</code></li>
<li>初始化时通过显式<code>register()</code>传递给手柄控制器</li>
</ul>
<pre><code class="language-swift"> @main
struct CarControlApp: App {
@State var model = ViewModel()
@ObservedObject var gameControllerManager = GameControllerManager()
init() {
MoveComponent.registerComponent()
MoveSystem.registerSystem()
gameControllerManager.register(model: model)
}
var body: some Scene {
WindowGroup {
ContentView()
.environment(model)
}
.defaultSize(CGSize(width: 300, height: 400))
ImmersiveSpace(id: "ImmersiveSpace") {
ImmersiveView()
.environment(model)
}
}
}
</code></pre>
<h2>ContentView</h2>
<p>ContentView 主要包含 2 部分功能：</p>
<ul>
<li>控制打开和关闭 Immsersive Space：可参考<a href="https://xz3t11cmy1.feishu.cn/wiki/UaYSw4pyniTSeWkMk4ScJUS0nbb">1. 窗口，空间容器和空间</a> ，这里不再赘述</li>
<li>控制小车移动：绘制方向按钮，并将用户输入同步到 Model 中</li>
</ul>
<p>在控制物体移动时，通常的按键习惯是长按。比如用户一直按着向前的箭头，那么小车就应该一直前进，直到用户松开，因此这里使用<code>onLongPressGesture</code>控制。当用户按下/松开按键时，相应地设置 Model 状态。</p>
<pre><code class="language-swift">struct ContentView: View {
// ...
@Environment(ViewModel.self) var model
var body: some View {
// ...
VStack {
HStack {
arrowButton(systemName: "arrow.up.left", directions: [.up, .left])
arrowButton(systemName: "arrow.up", directions: [.up])
arrowButton(systemName: "arrow.up.right", directions: [.up, .right])
}
HStack {
arrowButton(systemName: "arrow.down.left", directions: [.down, .left])
arrowButton(systemName: "arrow.down", directions: [.down])
arrowButton(systemName: "arrow.down.right", directions: [.down, .right])
}
}
}
// ...
}
private func arrowButton(systemName: String, directions: [Direction]) -> some View {
Button(action: {}) {
Image(systemName: systemName)
}
.onLongPressGesture(minimumDuration: .infinity, pressing: { isPressing in
print("direction: (directions), pressed: (isPressing)")
for direction in directions {
move(direction: direction, press: isPressing)
}
}, perform: {})
}
func move(direction: Direction, press: Bool) {
switch direction {
case .up:
model.forward = press
case .down:
model.backward = press
case .left:
model.left = press
case .right:
model.right = press
}
}
enum Direction {
case up, down, left, right
}
}
</code></pre>
<h2>ImmersiveView</h2>
<p>ImmersiveView 主要功能是：</p>
<ul>
<li>加载汽车和地板实体，赋予对应的初始位置、材料、物理实体信息等特性</li>
<li>为汽车增加光影效果</li>
<li>为汽车增加<code>MoveComponent</code>，并传递 ViewModel，后续供 MoveSystem 使用</li>
</ul>
<p>如果只是加载汽车和地板实体，并没有实际的重力和碰撞效果，因此需要给这些实体添加对应的物理实体<code>PhysicsBodyComponent</code>，并且赋予其对应的碰撞体形状<code>CollisionComponent</code>，这样才能产生类似真实世界的碰撞、重力等效果。</p>
<pre><code class="language-swift">struct ImmersiveView: View {
@State var floor = Entity()
@State var car = Entity()
@Environment(ViewModel.self) var model
var body: some View {
RealityView { content in
// Car
car = try! await Entity(named: "toy_car")
car.transform.rotation = simd_quatf(angle: .pi, axis: [0, 1, 0])
car.components[CollisionComponent.self] = CollisionComponent(shapes: [.generateBox(size: SIMD3(repeating: 1.0))])
car.position = SIMD3(x: 0, y: 0.95, z: -2)
let carBody = PhysicsBodyComponent()
car.components[PhysicsBodyComponent.self] = carBody
car.enumerateHierarchy { entity, stop in
if entity is ModelEntity {
entity.components.set(GroundingShadowComponent(castsShadow: true))
}
}
car.components[MoveComponent.self] = MoveComponent(model: model)
content.add(car)
// Floor
let floorMaterial = SimpleMaterial(color: .white, roughness: 1, isMetallic: false)
floor = ModelEntity(
mesh: .generateBox(width: 3, height: 0.01, depth: 2),
materials: [floorMaterial],
collisionShape: .generateBox(width: 3, height: 0.01, depth: 2),
mass: 0.0
)
floor.position = SIMD3(x: 0.0, y: 0.9, z: -2)
var floorBody = PhysicsBodyComponent()
floorBody.isAffectedByGravity = false
floorBody.mode = .static
floor.components[PhysicsBodyComponent.self] = floorBody
content.add(floor)
}
.shadow(radius: 12)
}
}
</code></pre>
<p>另外可以注意到，在为小汽车增加光影效果时，并不是简单地为实体增加<code>GroundingShadowComponent</code>。因为小汽车是从 USDZ 文件中加载而来，并非<code>ModelEntity</code>，如果只是简单添加阴影会发现并不会产生预期的效果。因此可以给<code>Entity</code>类型扩展一个<code>enumerateHierarchy</code>方法，递归地迭代其中的子结构，并且为每个<code>ModelEntity</code>类型的子结构添加阴影，这样就能获得预期的效果。<a href="https://forums.developer.apple.com/forums/thread/733918">参考文档</a></p>
<pre><code class="language-swift">extension Entity {
func enumerateHierarchy(_ body: (Entity, UnsafeMutablePointer<Bool>) -> Void) {
var stop = false
func enumerate(_ body: (Entity, UnsafeMutablePointer<Bool>) -> Void) {
guard !stop else {
return
}
body(self, &stop)
for child in children {
guard !stop else {
break
}
child.enumerateHierarchy(body)
}
}
enumerate(body)
}
}
</code></pre>
<p>效果：</p>
<p><img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/a4d58465541547eb8edfd9407b8483bd~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1016&h=848&s=614852&e=png&b=cbcac2" alt="" referrerpolicy="no-referrer"></p>
<h2>GameController</h2>
<p>手柄控制主要功能：</p>
<ul>
<li>监控手柄连接和断开</li>
<li>监控手柄输入：这部分上述 UI 控制类似，需要判断用户的输入并且映射到 ViewModel 中</li>
</ul>
<pre><code class="language-swift">func handleGamepadInput(_ gamepad: GCExtendedGamepad) { let leftThumbstickX = gamepad.leftThumbstick.xAxis.value let leftThumbstickY = gamepad.leftThumbstick.yAxis.value if model == nil { return } if leftThumbstickX != 0 || leftThumbstickY != 0 { print("Left Thumbstick Moved: (leftThumbstickX), (leftThumbstickY)") if leftThumbstickX < -sensitivity { model?.left = true } if leftThumbstickX > sensitivity { model?.right = true } if leftThumbstickY > sensitivity { model?.forward = true } if leftThumbstickY < -sensitivity { model?.backward = true } } else { model?.reset() print("Left Thumbstick Released") } }
</code></pre>
<h2>MoveComponent</h2>
<p>MoveComponent 作为 Component，主要定义了运动对象相关的一些性质，如速度、转弯速度等。同时为了语义上的清晰，还定义了左和右对应的向量。</p>
<pre><code class="language-swift">public struct MoveComponent: Component {
let model: ViewModel
let speed: Float = 0.3
let turnSpeed: Float = 1.0
private let left = SIMD3<Float>(0, 1, 0)
private let right = SIMD3<Float>(0, -1, 0)
func getDirection() -> SIMD3<Float> {
if model.left {
return left
}
if model.right {
return right
}
return SIMD3<Float>(0, 0, 0)
}
}
</code></pre>
<h2>MoveSystem</h2>
<p>MoveSystem 主要用于识别包含了<code>MoveComponent</code>的对象，并控制其移动。</p>
<ul>
<li>当用户控制小车<strong>前后移动</strong>时，是向小车的前方/后方而非镜头的前方/后方移动。此外，还需要根据 Component 中定义的速度，这样才能决定小车的移动</li>
<li>当用户控制小车<strong>左右移动</strong>时，其实并非是线性的左右移动，而是控制的小车的转向</li>
</ul>
<p>前后移动：</p>
<ol>
<li>根据当前用户输入是向前还是向后决定移动向量<code>forward(0, 0, 1)</code>还是<code>backward(0, 0, -1)</code></li>
<li>获取小车当前的方向角度将上述向量转向，从而决定移动方向。这里使用的是<a href="https://developer.apple.com/documentation/accelerate/simd_quatf/2914940-act"> act（_:）</a>方法。</li>
<li>将方向向量乘以标量速度，从而得到最终的移动向量</li>
</ol>
<pre><code class="language-swift">private let forward = SIMD3<Float>(0, 0, 1)
private let backward = SIMD3<Float>(0, 0, -1)
// ...
let deltaTime = Float(context.deltaTime)
if moveComponent.model.forward {
let forwardDirection = entity.transform.rotation.act(forward)
entity.transform.translation += forwardDirection * moveComponent.speed * deltaTime
}
if moveComponent.model.backward {
let backwardDirection = entity.transform.rotation.act(backward)
entity.transform.translation += backwardDirection * moveComponent.speed * deltaTime
}
</code></pre>
<p>如果用户输入同时还包含了左右移动，则需要</p>
<ul>
<li>获取期望的转向角度：<code>simd_quatf(angle: moveComponent.turnSpeed * deltaTime, axis: moveComponent.getDirection())</code></li>
<li>根据物体当前的方向<code>entity.orientation</code>，乘以上述转向角度，获得最终的转向方向</li>
</ul>
<pre><code class="language-swift">if moveComponent.model.left || moveComponent.model.right {
entity.orientation = simd_mul(entity.orientation,
simd_quatf(angle: moveComponent.turnSpeed * deltaTime, axis: moveComponent.getDirection()))
}
</code></pre>
<p>上述两组移动中还有一个共同点需要注意，当我们乘以移动或旋转速度时，都同时乘以了<code>context.deltaTime</code>。它指的是上次更新到这次更新之间的间隔时间。应用运行时每秒钟会有很多帧，每一帧（frame）都会调用一次 update 方法，两帧之间的间隔就是这里的<code>deltaTime</code>。通常我们设定的移动速度是物体每秒移动速度，如果不做上述乘法，每一帧之间都会移动我们原本预期 1 秒钟移动的距离，远超预期，因此需要在计算速度时额外乘以<code>deltaTime</code>来达到预期效果。</p>
<p>也许有同学会有疑问，那我们是否可以减小速度，将其设置为“每帧速度”呢？这里存在一个问题，帧和帧之间的间隔并不总是均匀的，而对于用户而言“秒”才是绝对的单位，因此为了让用户体感上获得一个较为稳定的速度，需要通过将速度乘以<code>deltaTime</code>从而获得移动距离的方式移动物体。</p>
<p>MoveSystem 完整的代码如下：</p>
<pre><code class="language-swift">public struct MoveSystem: System {
private let forward = SIMD3<Float>(0, 0, 1)
private let backward = SIMD3<Float>(0, 0, -1)
static let moveQuery = EntityQuery(where: .has(MoveComponent.self))
public init(scene: RealityKit.Scene) {
}
public func update(context: SceneUpdateContext) {
let entities = context.scene.performQuery(Self.moveQuery)
for entity in entities {
guard let moveComponent = entity.components[MoveComponent.self] else {
continue
}
let deltaTime = Float(context.deltaTime)
if moveComponent.model.forward {
let forwardDirection = entity.transform.rotation.act(forward)
entity.transform.translation += forwardDirection * moveComponent.speed * deltaTime
}
if moveComponent.model.backward {
let backwardDirection = entity.transform.rotation.act(backward)
entity.transform.translation += backwardDirection * moveComponent.speed * deltaTime
}
if moveComponent.model.left || moveComponent.model.right {
entity.orientation = simd_mul(entity.orientation,
simd_quatf(angle: moveComponent.turnSpeed * deltaTime, axis: moveComponent.getDirection()))
}
}
}
}
</code></pre>
<h1>最终效果</h1>
<p><a href="https://www.ixigua.com/7324371046890078774?utm_source=xiguastudio">jvideo</a></p>