ClothSim

ClothSim is a visionOS 27 RealityKit demo that explores the new cloth simulation APIs through an interactive flag scene. The demo focuses on a horizontally mounted flag that reacts to a fan-driven wind source and experimental hand-tracking interaction.

中文文档

Features

• RealityKit cloth flag built from a generated mesh and ClothBodyComponent.
• Fan-based wind source using ClothForceVolumeComponent and global cloth wind.
• Adjustable wind strength, Y-axis direction, lift, turbulence, and cloth mesh quality.
• Flag texture compositing with a purple fallback background, two-sided rendering, and light emissive fill for readability.
• Animated Old_Table_Fan.usdz model used as the visual wind source.
• Experimental hand tracking with ARKit HandTrackingProvider, cloth colliders, and pinch-driven grab interaction.
• Mixed immersive space so the flag and fan appear in the user's real environment.

Requirements

• Xcode 27 beta or newer.
• visionOS 27 SDK.
• Apple Vision Pro for hand tracking. The visionOS Simulator can build and run the scene, but hand tracking may be unavailable.

This project currently targets:

• Platform: visionOS / xrOS
• Deployment target: visionOS 27.0
• UI: SwiftUI + RealityView
• 3D runtime: RealityKit
• Tracking: ARKit hand tracking

Getting Started

1. Open ClothSim.xcodeproj in Xcode 27 beta.
2. Select the ClothSim scheme.
3. Choose an Apple Vision Pro device or a visionOS Simulator.
4. Build and run.
5. Press Show Immersive Space to enter the mixed immersive scene.

Command-line build:

DEVELOPER_DIR=/path/to/Xcode-beta.app/Contents/Developer \
xcodebuild \
  -project ClothSim.xcodeproj \
  -scheme ClothSim \
  -configuration Debug \
  -destination 'generic/platform=visionOS Simulator' \
  -derivedDataPath Build \
  build

Controls

• Mode: Switch between wind and hand-interaction modes.
• Quality: Change the cloth mesh density.
• Strength: Wind intensity, scaled internally for cloth stability.
• Y Rotation: Rotate the fan and wind direction around the Y axis.
• Lift: Add upward or downward wind elevation.
• Turbulence: Add noise to the force volume.
• Reset Cloth: Rebuild and reset the cloth deformation.

Replacing the Flag Image

The flag image is loaded from the asset catalog image set named FlagTexture.

1. Open ClothSim/Assets.xcassets/FlagTexture.imageset.
2. Replace the existing image with your own flag image.
3. Keep the asset name FlagTexture.
4. Use a transparent PNG if you want the app to composite it over the built-in purple background.
5. Rebuild the app.

The app detects the image aspect ratio and clamps it to a practical flag range to avoid extreme stretching.

Key Files

• ClothSim/AppModel.swift: Shared app state and simulation settings.
• ClothSim/ContentView.swift: Control panel UI.
• ClothSim/ImmersiveView.swift: RealityKit scene, cloth mesh, wind, fan placement, and hand tracking.
• ClothSim/Resources/Old_Table_Fan.usdz: Fan model asset.
• ClothSim/Assets.xcassets/FlagTexture.imageset: Flag texture asset.
• docs/DEVELOPMENT.md: Implementation notes and tuning guide.

Known Limitations

• The project depends on visionOS 27 beta cloth APIs, so behavior may change between SDK releases.
• Hand tracking requires a real device and user permission.
• ClothGrabComponent.volume can trigger a RealityKit beta runtime assertion in this scene, so the demo currently uses ray grabbing plus cloth collider spheres.
• The included fan and flag artwork should be reviewed for license compatibility before publishing publicly.

License

No license has been added yet. Choose and add a license before publishing this repository as open source.