sceneview-mcp 3.4.12 → 3.4.13

package/dist/platform-setup.js

@@ -0,0 +1,787 @@
+/**
+ * platform-setup.ts
+ *
+ * Setup guides for every supported SceneView platform.
+ * Consolidates Android, iOS, Web, Flutter, React Native, Desktop, and TV.
+ */
+export const PLATFORM_IDS = ["android", "ios", "web", "flutter", "react-native", "desktop", "tv"];
+const ANDROID_3D = `## SceneView Android — 3D Setup
+
+### 1. Gradle Dependencies
+
+\`\`\`kotlin
+// build.gradle.kts (app module)
+dependencies {
+    implementation("io.github.sceneview:sceneview:3.3.0")
+}
+\`\`\`
+
+### 2. Minimum SDK
+
+\`\`\`kotlin
+android {
+    defaultConfig {
+        minSdk = 24
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+}
+\`\`\`
+
+### 3. Basic 3D Scene
+
+\`\`\`kotlin
+@Composable
+fun My3DScreen() {
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+    val environmentLoader = rememberEnvironmentLoader(engine)
+
+    Scene(
+        modifier = Modifier.fillMaxSize(),
+        engine = engine,
+        modelLoader = modelLoader,
+        environment = rememberEnvironment(environmentLoader) {
+            environmentLoader.createHDREnvironment("environments/sky_2k.hdr")
+                ?: createEnvironment(environmentLoader)
+        }
+    ) {
+        rememberModelInstance(modelLoader, "models/chair.glb")?.let { instance ->
+            ModelNode(
+                modelInstance = instance,
+                scaleToUnits = 1.0f,
+                centerOrigin = Position(0f, 0f, 0f)
+            )
+        }
+
+        LightNode(
+            engine = engine,
+            type = LightManager.Type.DIRECTIONAL,
+            apply = {
+                intensity(100_000f)
+                castShadows(true)
+            }
+        )
+    }
+}
+\`\`\`
+
+### 4. Asset Location
+
+Place 3D assets in \`src/main/assets/\`:
+\`\`\`
+app/src/main/assets/
+  models/         # GLB/glTF files
+  environments/   # HDR environment maps
+  materials/      # Custom .filamat materials
+\`\`\`
+
+### 5. No Manifest Changes Required
+
+3D-only scenes need no special permissions or manifest entries.`;
+const ANDROID_AR = `## SceneView Android — AR Setup
+
+### 1. Gradle Dependencies
+
+\`\`\`kotlin
+// build.gradle.kts (app module)
+dependencies {
+    implementation("io.github.sceneview:arsceneview:3.3.0")
+    // arsceneview includes sceneview transitively
+}
+\`\`\`
+
+### 2. AndroidManifest.xml
+
+\`\`\`xml
+<uses-permission android:name="android.permission.CAMERA" />
+<uses-feature android:name="android.hardware.camera.ar" android:required="true" />
+
+<application>
+    <meta-data android:name="com.google.ar.core" android:value="required" />
+</application>
+\`\`\`
+
+### 3. Camera Permission at Runtime
+
+\`\`\`kotlin
+val cameraPermission = rememberLauncherForActivityResult(
+    ActivityResultContracts.RequestPermission()
+) { granted -> if (granted) showAR = true }
+
+LaunchedEffect(Unit) {
+    cameraPermission.launch(Manifest.permission.CAMERA)
+}
+\`\`\`
+
+### 4. Basic AR Scene
+
+\`\`\`kotlin
+@Composable
+fun MyARScreen() {
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+    var anchor by remember { mutableStateOf<Anchor?>(null) }
+
+    val modelInstance = rememberModelInstance(modelLoader, "models/robot.glb")
+
+    ARScene(
+        modifier = Modifier.fillMaxSize(),
+        engine = engine,
+        modelLoader = modelLoader,
+        planeRenderer = true,
+        sessionConfiguration = { session, config ->
+            config.depthMode =
+                if (session.isDepthModeSupported(Config.DepthMode.AUTOMATIC))
+                    Config.DepthMode.AUTOMATIC else Config.DepthMode.DISABLED
+            config.lightEstimationMode = Config.LightEstimationMode.ENVIRONMENTAL_HDR
+            config.planeFindingMode = Config.PlaneFindingMode.HORIZONTAL_AND_VERTICAL
+        },
+        onTouchEvent = { event, hitResult ->
+            if (event.action == MotionEvent.ACTION_UP && hitResult != null) {
+                anchor = hitResult.createAnchor()
+            }
+            true
+        }
+    ) {
+        anchor?.let { a ->
+            AnchorNode(anchor = a) {
+                modelInstance?.let { instance ->
+                    ModelNode(
+                        modelInstance = instance,
+                        scaleToUnits = 0.5f,
+                        isEditable = true
+                    )
+                }
+            }
+        }
+    }
+}
+\`\`\`
+
+### 5. Session Configuration Options
+
+| Option | Values | Default |
+|--------|--------|---------|
+| \`depthMode\` | \`DISABLED\`, \`AUTOMATIC\` | \`DISABLED\` |
+| \`lightEstimationMode\` | \`DISABLED\`, \`AMBIENT_INTENSITY\`, \`ENVIRONMENTAL_HDR\` | \`ENVIRONMENTAL_HDR\` |
+| \`planeFindingMode\` | \`DISABLED\`, \`HORIZONTAL\`, \`VERTICAL\`, \`HORIZONTAL_AND_VERTICAL\` | \`HORIZONTAL_AND_VERTICAL\` |
+| \`instantPlacementMode\` | \`DISABLED\`, \`LOCAL_Y_UP\` | \`DISABLED\` |
+| \`cloudAnchorMode\` | \`DISABLED\`, \`ENABLED\` | \`DISABLED\` |`;
+const IOS_3D = `## SceneViewSwift — iOS/macOS/visionOS 3D Setup
+
+### 1. SPM Dependency
+
+In Xcode: **File > Add Package Dependencies** > paste:
+\`\`\`
+https://github.com/SceneView/sceneview
+\`\`\`
+Set version rule to **"from: 3.3.0"**.
+
+Or in Package.swift:
+\`\`\`swift
+// swift-tools-version: 5.10
+import PackageDescription
+
+let package = Package(
+    name: "MyApp",
+    platforms: [.iOS(.v17), .macOS(.v14), .visionOS(.v1)],
+    dependencies: [
+        .package(url: "https://github.com/SceneView/sceneview", from: "3.3.0")
+    ],
+    targets: [
+        .executableTarget(
+            name: "MyApp",
+            dependencies: [
+                .product(name: "SceneViewSwift", package: "sceneview")
+            ]
+        )
+    ]
+)
+\`\`\`
+
+### 2. Minimum Platform Versions
+
+| Platform | Minimum |
+|----------|---------|
+| iOS      | 17.0    |
+| macOS    | 14.0    |
+| visionOS | 1.0     |
+
+### 3. Basic SwiftUI Integration
+
+\`\`\`swift
+import SwiftUI
+import SceneViewSwift
+import RealityKit
+
+struct ContentView: View {
+    @State private var model: ModelNode?
+
+    var body: some View {
+        SceneView { root in
+            if let model {
+                root.addChild(model.entity)
+            }
+        }
+        .cameraControls(.orbit)
+        .task {
+            do {
+                model = try await ModelNode.load("models/car.usdz")
+                model?.scaleToUnits(1.0)
+            } catch {
+                print("Failed to load model: \\(error)")
+            }
+        }
+    }
+}
+\`\`\`
+
+### 4. Model Formats
+
+| Format | Support |
+|--------|---------|
+| USDZ   | Native — recommended for iOS |
+| .reality | Native — RealityKit format |
+| glTF/GLB | Not natively supported (use Android/Web) |`;
+const IOS_AR = `## SceneViewSwift — iOS AR Setup
+
+### 1. SPM Dependency
+
+\`\`\`swift
+.package(url: "https://github.com/SceneView/sceneview", from: "3.3.0")
+\`\`\`
+
+### 2. Info.plist — Camera Permission (Required)
+
+\`\`\`xml
+<key>NSCameraUsageDescription</key>
+<string>This app uses the camera for augmented reality.</string>
+\`\`\`
+
+### 3. Minimum Platform
+
+AR requires **iOS 17.0+**. Not available on macOS or visionOS via \`ARSceneView\`.
+
+### 4. Basic AR Integration
+
+\`\`\`swift
+import SwiftUI
+import SceneViewSwift
+import RealityKit
+
+struct ARContentView: View {
+    @State private var model: ModelNode?
+
+    var body: some View {
+        ARSceneView(
+            planeDetection: .horizontal,
+            showCoachingOverlay: true,
+            onTapOnPlane: { position, arView in
+                guard let model else { return }
+                let anchor = AnchorNode.world(position: position)
+                let clone = model.entity.clone(recursive: true)
+                clone.scale = .init(repeating: 0.3)
+                anchor.add(clone)
+                arView.scene.addAnchor(anchor.entity)
+            }
+        )
+        .edgesIgnoringSafeArea(.all)
+        .task {
+            model = try? await ModelNode.load("models/robot.usdz")
+        }
+    }
+}
+\`\`\`
+
+### 5. AR Configuration
+
+| Parameter | Options | Default |
+|-----------|---------|---------|
+| \`planeDetection\` | \`.none\`, \`.horizontal\`, \`.vertical\`, \`.both\` | \`.horizontal\` |
+| \`showPlaneOverlay\` | \`true\` / \`false\` | \`true\` |
+| \`showCoachingOverlay\` | \`true\` / \`false\` | \`true\` |`;
+const WEB_3D = `## SceneView Web — Browser 3D Setup
+
+SceneView Web uses **Filament.js** — the same rendering engine as Android, compiled to WebAssembly (WebGL2).
+
+### 1. Install
+
+\`\`\`bash
+npm install @sceneview/sceneview-web
+\`\`\`
+
+Or in a Kotlin/JS Gradle project:
+\`\`\`kotlin
+kotlin {
+    js(IR) { browser(); binaries.executable() }
+    sourceSets {
+        jsMain.dependencies {
+            implementation("@sceneview/sceneview-web")
+        }
+    }
+}
+\`\`\`
+
+### 2. HTML
+
+\`\`\`html
+<canvas id="scene-canvas" style="width:100%;height:100vh"></canvas>
+<script src="your-app.js"></script>
+\`\`\`
+
+### 3. Kotlin/JS Code
+
+\`\`\`kotlin
+import io.github.sceneview.web.SceneView
+import kotlinx.browser.document
+import org.w3c.dom.HTMLCanvasElement
+
+fun main() {
+    val canvas = document.getElementById("scene-canvas") as HTMLCanvasElement
+    canvas.width = canvas.clientWidth
+    canvas.height = canvas.clientHeight
+
+    SceneView.create(
+        canvas = canvas,
+        configure = {
+            camera {
+                eye(0.0, 1.5, 5.0)
+                target(0.0, 0.0, 0.0)
+                fov(45.0)
+            }
+            light {
+                directional()
+                intensity(100_000.0)
+            }
+            model("models/DamagedHelmet.glb")
+            autoRotate()
+        },
+        onReady = { sceneView ->
+            sceneView.startRendering()
+        }
+    )
+}
+\`\`\`
+
+### 4. Supported Features
+
+- Same Filament PBR renderer as Android (WASM)
+- glTF 2.0 / GLB model loading
+- IBL environment lighting (KTX)
+- Orbit camera with mouse/touch/pinch
+- Auto-rotation, directional/point/spot lights
+
+### 5. Limitations
+
+- No AR (requires native sensors)
+- WebGL2 required (~95% of browsers)
+- glTF/GLB format only`;
+const FLUTTER_3D = `## SceneView Flutter — 3D Setup
+
+SceneView Flutter uses **PlatformView** to embed native SceneView (Android: Filament, iOS: RealityKit).
+
+### 1. Dependencies
+
+\`\`\`yaml
+# pubspec.yaml
+dependencies:
+  sceneview_flutter: ^3.3.0
+\`\`\`
+
+### 2. Android Setup
+
+Add to \`android/app/build.gradle\`:
+\`\`\`groovy
+android {
+    defaultConfig {
+        minSdkVersion 24
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+}
+\`\`\`
+
+### 3. iOS Setup
+
+In \`ios/Podfile\`:
+\`\`\`ruby
+platform :ios, '17.0'
+\`\`\`
+
+### 4. Basic 3D Scene
+
+\`\`\`dart
+import 'package:sceneview_flutter/sceneview_flutter.dart';
+
+class My3DScreen extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return SceneView(
+      modelUrl: 'assets/models/chair.glb',  // Android: GLB, iOS: USDZ
+      environment: 'assets/environments/sky_2k.hdr',
+      cameraOrbit: true,
+      scaleToUnits: 1.0,
+      onModelLoaded: (controller) {
+        print('Model loaded');
+      },
+    );
+  }
+}
+\`\`\`
+
+### 5. Platform Differences
+
+| Feature | Android | iOS |
+|---------|---------|-----|
+| Renderer | Filament | RealityKit |
+| Model format | GLB/glTF | USDZ/.reality |
+| Environment | HDR | Built-in IBL |`;
+const FLUTTER_AR = `## SceneView Flutter — AR Setup
+
+### 1. Dependencies
+
+\`\`\`yaml
+dependencies:
+  sceneview_flutter: ^3.3.0
+\`\`\`
+
+### 2. Android Manifest
+
+\`\`\`xml
+<uses-permission android:name="android.permission.CAMERA" />
+<uses-feature android:name="android.hardware.camera.ar" android:required="true" />
+<application>
+    <meta-data android:name="com.google.ar.core" android:value="required" />
+</application>
+\`\`\`
+
+### 3. iOS Info.plist
+
+\`\`\`xml
+<key>NSCameraUsageDescription</key>
+<string>This app uses the camera for augmented reality.</string>
+\`\`\`
+
+### 4. Basic AR Scene
+
+\`\`\`dart
+import 'package:sceneview_flutter/sceneview_flutter.dart';
+
+class MyARScreen extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return ARSceneView(
+      modelUrl: 'assets/models/robot.glb',
+      planeDetection: PlaneDetection.horizontal,
+      tapToPlace: true,
+      scaleToUnits: 0.5,
+      onAnchorCreated: (anchor) {
+        print('Object placed at: \${anchor.position}');
+      },
+    );
+  }
+}
+\`\`\``;
+const REACT_NATIVE_3D = `## SceneView React Native — 3D Setup
+
+SceneView React Native uses **Fabric/Turbo** to bridge to native SceneView.
+
+### 1. Install
+
+\`\`\`bash
+npm install @sceneview/react-native
+cd ios && pod install
+\`\`\`
+
+### 2. Android Setup
+
+In \`android/app/build.gradle\`:
+\`\`\`groovy
+android {
+    defaultConfig {
+        minSdkVersion 24
+    }
+}
+\`\`\`
+
+### 3. iOS Setup
+
+In \`ios/Podfile\`:
+\`\`\`ruby
+platform :ios, '17.0'
+\`\`\`
+
+### 4. Basic 3D Scene
+
+\`\`\`tsx
+import { SceneView } from '@sceneview/react-native';
+
+export default function My3DScreen() {
+  return (
+    <SceneView
+      style={{ flex: 1 }}
+      modelUrl={require('./assets/models/chair.glb')}
+      environment={require('./assets/environments/sky_2k.hdr')}
+      cameraOrbit={true}
+      scaleToUnits={1.0}
+      onModelLoaded={() => console.log('Model loaded')}
+    />
+  );
+}
+\`\`\`
+
+### 5. Platform Differences
+
+| Feature | Android | iOS |
+|---------|---------|-----|
+| Renderer | Filament | RealityKit |
+| Model format | GLB/glTF | USDZ/.reality |
+| Bridge | Fabric component | Fabric component |`;
+const REACT_NATIVE_AR = `## SceneView React Native — AR Setup
+
+### 1. Install
+
+\`\`\`bash
+npm install @sceneview/react-native
+cd ios && pod install
+\`\`\`
+
+### 2. Android Permissions
+
+Add to \`AndroidManifest.xml\`:
+\`\`\`xml
+<uses-permission android:name="android.permission.CAMERA" />
+<uses-feature android:name="android.hardware.camera.ar" android:required="true" />
+<application>
+    <meta-data android:name="com.google.ar.core" android:value="required" />
+</application>
+\`\`\`
+
+### 3. iOS Permissions
+
+Add to \`Info.plist\`:
+\`\`\`xml
+<key>NSCameraUsageDescription</key>
+<string>This app uses the camera for augmented reality.</string>
+\`\`\`
+
+### 4. Basic AR Scene
+
+\`\`\`tsx
+import { ARSceneView } from '@sceneview/react-native';
+
+export default function MyARScreen() {
+  return (
+    <ARSceneView
+      style={{ flex: 1 }}
+      modelUrl={require('./assets/models/robot.glb')}
+      planeDetection="horizontal"
+      tapToPlace={true}
+      scaleToUnits={0.5}
+      onAnchorCreated={(anchor) => console.log('Placed:', anchor)}
+    />
+  );
+}
+\`\`\``;
+const DESKTOP_3D = `## SceneView Desktop — Setup
+
+SceneView Desktop uses **Compose Desktop** with a software 3D renderer (wireframe). A Filament JNI backend is planned for full PBR rendering.
+
+### 1. Gradle Dependencies
+
+\`\`\`kotlin
+// build.gradle.kts
+plugins {
+    kotlin("jvm")
+    id("org.jetbrains.compose")
+}
+
+dependencies {
+    implementation(compose.desktop.currentOs)
+    implementation("io.github.sceneview:sceneview-desktop:3.3.0") // when published
+}
+\`\`\`
+
+### 2. Basic Desktop Scene
+
+\`\`\`kotlin
+import androidx.compose.ui.window.Window
+import androidx.compose.ui.window.application
+
+fun main() = application {
+    Window(
+        onCloseRequest = ::exitApplication,
+        title = "SceneView Desktop"
+    ) {
+        // Current: software wireframe renderer
+        DesktopScene(
+            modifier = Modifier.fillMaxSize(),
+            shapes = listOf(
+                WireframeCube(position = Float3(0f, 0f, 0f), size = 1f),
+                WireframeSphere(position = Float3(2f, 0f, 0f), radius = 0.5f)
+            ),
+            cameraOrbit = true,
+            backgroundColor = Color(0xFF1A1A2E)
+        )
+    }
+}
+\`\`\`
+
+### 3. Current Status
+
+| Feature | Status |
+|---------|--------|
+| Software wireframe renderer | Alpha |
+| Filament JNI (full PBR) | Planned (18-29 day effort) |
+| GLB/glTF loading | Planned (needs Filament JNI) |
+| Windows / macOS / Linux | Alpha |
+
+### 4. Limitations
+
+- Currently wireframe only (no PBR, no textures)
+- No AR support (desktop has no camera/sensor API)
+- Model loading requires Filament JNI (not yet available)`;
+const TV_3D = `## SceneView Android TV — Setup
+
+SceneView on Android TV uses the same Filament renderer as mobile Android, with D-pad navigation support.
+
+### 1. Gradle Dependencies
+
+\`\`\`kotlin
+dependencies {
+    implementation("io.github.sceneview:sceneview:3.3.0")
+    implementation("androidx.leanback:leanback:1.0.0")
+    implementation("androidx.tv:tv-foundation:1.0.0-alpha10")
+}
+\`\`\`
+
+### 2. Manifest
+
+\`\`\`xml
+<uses-feature android:name="android.software.leanback" android:required="true" />
+<uses-feature android:name="android.hardware.touchscreen" android:required="false" />
+\`\`\`
+
+### 3. Basic TV Scene with D-pad Controls
+
+\`\`\`kotlin
+@Composable
+fun TVModelViewer() {
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+    var rotation by remember { mutableFloatStateOf(0f) }
+
+    // D-pad rotation control
+    val focusRequester = remember { FocusRequester() }
+    LaunchedEffect(Unit) { focusRequester.requestFocus() }
+
+    Box(
+        modifier = Modifier
+            .fillMaxSize()
+            .focusRequester(focusRequester)
+            .focusable()
+            .onKeyEvent { event ->
+                when (event.key) {
+                    Key.DirectionLeft -> { rotation -= 15f; true }
+                    Key.DirectionRight -> { rotation += 15f; true }
+                    else -> false
+                }
+            }
+    ) {
+        Scene(
+            modifier = Modifier.fillMaxSize(),
+            engine = engine,
+            modelLoader = modelLoader
+        ) {
+            rememberModelInstance(modelLoader, "models/car.glb")?.let { instance ->
+                ModelNode(
+                    modelInstance = instance,
+                    scaleToUnits = 2.0f
+                )
+            }
+        }
+    }
+}
+\`\`\`
+
+### 4. TV-Specific Considerations
+
+- **No touch** — use D-pad for rotation, Select for actions
+- **10-foot UI** — larger models, simpler scenes, bolder text
+- **No AR** — Android TV has no camera/sensors for AR
+- **Performance** — TV SoCs are weaker than phones; limit to <50K triangles`;
+const SETUPS = {
+    android: {
+        name: "Android (Jetpack Compose)",
+        renderer: "Filament (OpenGL ES / Vulkan)",
+        status: "Stable (v3.3.0)",
+        guide3d: ANDROID_3D,
+        guideAr: ANDROID_AR,
+    },
+    ios: {
+        name: "iOS / macOS / visionOS (SwiftUI)",
+        renderer: "RealityKit (Metal)",
+        status: "Alpha (v3.3.0)",
+        guide3d: IOS_3D,
+        guideAr: IOS_AR,
+    },
+    web: {
+        name: "Web (Kotlin/JS + Filament.js)",
+        renderer: "Filament.js (WebGL2 / WASM)",
+        status: "Alpha",
+        guide3d: WEB_3D,
+        guideAr: null,
+    },
+    flutter: {
+        name: "Flutter (PlatformView bridge)",
+        renderer: "Filament (Android) / RealityKit (iOS)",
+        status: "Alpha",
+        guide3d: FLUTTER_3D,
+        guideAr: FLUTTER_AR,
+    },
+    "react-native": {
+        name: "React Native (Fabric bridge)",
+        renderer: "Filament (Android) / RealityKit (iOS)",
+        status: "Alpha",
+        guide3d: REACT_NATIVE_3D,
+        guideAr: REACT_NATIVE_AR,
+    },
+    desktop: {
+        name: "Desktop (Compose Desktop)",
+        renderer: "Software wireframe (Filament JNI planned)",
+        status: "Alpha",
+        guide3d: DESKTOP_3D,
+        guideAr: null,
+    },
+    tv: {
+        name: "Android TV",
+        renderer: "Filament (OpenGL ES)",
+        status: "Alpha",
+        guide3d: TV_3D,
+        guideAr: null,
+    },
+};
+export function getPlatformSetup(platform, type) {
+    const setup = SETUPS[platform];
+    if (!setup) {
+        return `Unknown platform "${platform}". Available: ${PLATFORM_IDS.join(", ")}`;
+    }
+    if (type === "ar" && !setup.guideAr) {
+        return `# ${setup.name}\n\n**Status:** ${setup.status}\n**Renderer:** ${setup.renderer}\n\n> AR is not supported on ${setup.name}. Only 3D scenes are available on this platform.\n\nUse \`get_platform_setup\` with \`type: "3d"\` for 3D setup instructions.`;
+    }
+    const guide = type === "ar" ? setup.guideAr : setup.guide3d;
+    return `# ${setup.name}\n\n**Status:** ${setup.status} | **Renderer:** ${setup.renderer}\n\n${guide}`;
+}
+export function listPlatforms() {
+    const header = `## SceneView — Supported Platforms\n\n| Platform | Renderer | Status | 3D | AR |\n|----------|----------|--------|-----|-----|\n`;
+    const rows = PLATFORM_IDS.map((id) => {
+        const s = SETUPS[id];
+        return `| ${s.name} | ${s.renderer} | ${s.status} | Yes | ${s.guideAr ? "Yes" : "No"} |`;
+    }).join("\n");
+    return header + rows + "\n\nUse `get_platform_setup` with a specific platform for full setup instructions.";
+}