SceneView – 适用于现代 UI 工具组的声明式 3D 与 AR

简介 – 这是一个开源 SDK，让您能够将实时 3D 渲染和增强现实 (AR) 体验加入使用 Jetpack Compose、SwiftUI、Web JavaScript、Flutter、React Native 或 Kotlin-Multiplatform 编写的应用程序中。它将原生图形引擎（Android/桌面上的 Filament、Apple 上的 RealityKit、Web 上的 Filament.js）封装在声明式、可组合的 API 之后，让您可以像处理 UI 布局一样处理 3D 场景。

为何“AI 优先”很重要 – 本项目提供了一个小型 Model-Context-Protocol (MCP) 服务器和一个描述完整公开 API 的纯文本 llms.txt 文件。AI 助手（Claude、Codex、Copilot、Gemini 等）可以查询服务器以验证代码片段、获取节点签名或列出示例代码，从而实现一种工作流程：您只需询问 LLM “Add a 3‑D model viewer to my Compose screen”，即可在第一次尝试时获得可运行的代码。

---

核心功能 (基于 README)

功能	运作方式	平台
声明式 3D 场景图	SceneView { … } 是一个托管 Filament/RealityKit 视口的组合项。您可以在其中放置节点组合项（ModelNode、CubeNode、LightNode 等），这些组件会在状态变更时自动重新计算。	Android (Compose), iOS/macOS/visionOS (SwiftUI), Web (JS/Kotlin-JS), Compose-Multiplatform, Flutter, React Native
AR 集成	ARSceneView 建立在相同的组合模型上，但从 ARCore (Android) 或 ARKit/RealityKit (Apple) 驱动相机。节点可以锚定到现实世界的表面（AnchorNode、PlaneNode、CloudAnchorNode、地理空间锚点等）。	Android, iOS/macOS/visionOS
跨平台渲染器	• Android 与桌面 – Filament (高性能 Vulkan/OpenGL)。 • Apple – RealityKit (Metal)。 • Web – Filament.js (WebGL2/WASM)。	所有列出的平台
丰富的节点库	27 个 3D 节点 + 15 个 AR 专用节点，涵盖模型、基本图形、几何、灯光、天空、物理、相机、3D 中的 UI、高斯泼溅 (Gaussian splats) 等。	所有平台 (原生节点；Flutter/React Native 仅公开部分)
物理与碰撞	纯 Kotlin-Multiplatform 刚体模拟、射线投射和碰撞检测，适用于任何运行核心库的平台。	Android, Compose-Multiplatform, Desktop
手势与动画	节点可标记为 isEditable 以获取拖拽、捏合缩放、旋转和点击处理。glTF/GLB 模型会自动动画化；并提供额外的弹簧/属性动画。	所有平台
环境与后处理	HDR IBL 灯光、天空盒、泛光 (bloom)、景深、SSAO、色调映射、自定义 Filament 材质。	Android, Web, Desktop
3D 中的 Compose	ViewNode 将任何 Compose UI 渲染到保持完全交互（按钮、滚动等）的纹理平面上。	Android Compose, Compose-Multiplatform
AR 录制与重播	rememberARRecorder() 捕捉会话；ARSceneView(playbackDataset = file) 进行 1:1 重播以进行调试。	Android AR
Rerun.io 实时调试桥接	将姿势、平面、点云流传输到 Rerun 查看器以进行可视化调试。	Android AR

---

入门指南 (来自 README 的快速入门代码片段)

Android (Jetpack Compose)

implementation("io.github.sceneview:sceneview:4.51.0")

@Composable
fun ModelScreen() {
    SceneView(modifier = Modifier.fillMaxSize()) {
        rememberModelInstance(modelLoader, "models/helmet.glb")?.let {
            ModelNode(modelInstance = it, scaleToUnits = 1f, autoAnimate = true)
        }
    }
}

辅助函数 rememberModelInstance 在主线程上加载 GLB，并在准备就绪时触发重组。

Android AR

implementation("io.github.sceneview:arsceneview:4.51.0")

@Composable
fun ARScreen() {
    var anchor by remember { mutableStateOf<Anchor?>(null) }
    ARSceneView(modifier = Modifier.fillMaxSize(), planeRenderer = true) { _, frame ->
        if (anchor == null) {
            anchor = frame.getUpdatedPlanes()
                .firstOrNull { it.type == Plane.Type.HORIZONTAL_UPWARD_FACING }
                ?.let { frame.createAnchorOrNull(it.centerPose) }
        }
    } {
        val helmet = rememberModelInstance(modelLoader, "models/helmet.glb")
        anchor?.let { AnchorNode(anchor = it) { helmet?.let { ModelNode(modelInstance = it, scaleToUnits = 0.5f) } } }
    }
}

状态 (anchor) 是普通的 Kotlin 状态 – 当它变更时，UI 会重新组合，模型就会出现。

iOS / macOS / visionOS (SwiftUI)

import SceneViewSwift

struct ModelScreen: View {
    @State private var model: ModelNode?
    var body: some View {
        SceneView { root in
            if let model { root.addChild(model.entity) }
        }
        .contentID(model != nil)
        .cameraControls(.orbit)
        .task { model = try? await ModelNode.load("helmet.usdz") }
    }
}

.contentID 强制构建器在异步加载完成后再次执行。

Web (纯 HTML/JS)

<canvas id="viewer" style="width:100%;height:480px"></canvas>
<script src="https://cdn.jsdelivr.net/gh/sceneview/sceneview@v4.51.0/website-static/js/filament/filament.js"></script>
<script src="https://cdn.jsdelivr.net/gh/sceneview/sceneview@v4.51.0/website-static/js/sceneview.js"></script>
<script>SceneView.modelViewer("viewer", "model.glb")</script>

建立 Filament 查看器并加载 GLB 模型的一行代码。

Flutter

final controller = SceneViewController();
SceneView(
  controller: controller,
  onViewCreated: () => controller.loadModel(
    const ModelNode(modelPath: 'models/helmet.glb'),
  ),
);

React Native (TypeScript)

<SceneView
  style={{flex:1}}
  modelNodes={[{src:'models/helmet.glb', position:[0,0,-2]}]}
  cameraControlMode="orbit"
/>

---

AI 优先工作流程

1. API 参考 – llms.txt 将每个组合项、节点和线程规则包含在单个可搜索文件中。CI 会编译这些代码片段，确保它们保持同步。
2. MCP 服务器 – 一个小型本地服务器 (sceneview-mcp)，LLM 插件可以调用：
   • validate_code – 根据真实公开 API 检查代码片段。
   • list_samples / get_sample – 获取 38 个现成演示中的一个。
   • get_setup – 返回平台所需的 Gradle/Swift/JS 样板代码。
3. 插件支持 – OpenAI 插件、Claude Code 插件和 Copilot CLI 集成已在仓库中预先配置，因此助手可以自动发现这三项技能 (sceneview, sceneview-ios, sceneview-web)。
4. 提示示例 – 安装 MCP 服务器 (npx -y sceneview-mcp) 后，您可以询问 LLM：

   “Add a 3‑D model viewer to my Compose screen.” 助手将：

   • 查询 MCP 以获取正确的组合项名称，
   • 生成快速入门中显示的最小代码，并
   • 在您粘贴之前选择性地执行 validate_code。

---

项目健康度与社区

指标	数值
授权	Apache 2.0 (宽松，商业友好)
最新稳定版本	Android 3D 4.51.0, AR 4.51.0, Swift 4.39.0, Web 4.51.0
包发布	Maven Central, Swift Package Registry, npm, pub.dev, Android AR 的 Maven Central 等。
CI	GitHub Actions 在每次推送时执行；CI 也会编译 llms.txt 代码片段。
社区	Discord 服务器、用于资助的 Open Collective、GitHub 星数以及活跃的插件生态系统。
文档	包含平台特定快速入门的 README、包含 38 个演示的 samples/ 文件夹以及实时 Web 游乐场。

---

谁应该使用它？

• 应用开发人员：想要 3D 或 AR 功能但不想学习完整游戏引擎的人。
• 产品团队：希望快速制作沉浸式功能原型，并将代码库保持在相同 UI 语言（Compose, SwiftUI 等）中的团队。
• AI 增强开发工作流程：已经使用 LLM 助手的团队可以插入 MCP 服务器，并获得自动验证、最新的代码片段。

---

总结

SceneView 是一个真正、生产就绪的 SDK，将声明式 3D 渲染和 AR 带入当今主要的 UI 工具组。它将原生图形引擎抽象化在组合 API 之后，提供全文本 API 规范 (llms.txt) 和用于 LLM 集成的 MCP 服务器，并在所有主要包注册表中发布。如果您需要放置模型查看器、将虚拟对象放置在现实世界中，或让 AI 为您编写代码，SceneView 就是为此而生的。