SpatialCut

English | 中文

SpatialCut is an open-source XR large-space storytelling framework built on Unity. It combines a multiplayer runtime stack with a Timeline-first narrative toolset so artists and designers can create room-scale XR experiences without heavy engineering overhead.

SpatialCut 是一个基于 Unity 的 XR 大空间叙事开源框架。 它同时提供多人同步运行时栈与 Timeline 叙事工具，让美术/策划通过可视化方式创建大空间 XR 内容。

Core Value / 核心价值

• Full-stack XR runtime: multi-client sync, monitoring UI, optional backend integration.

• Narrative-first creation: Timeline tracks for story flow, subtitles, fades, anchors, lighting, and motion.

• Clean architecture: Contracts/Core/SDK separation, VContainer + Manifest, AssetReference-only, single-source config.

• XR 全栈运行时：多人同步、监控端、可选后端接入。

• 叙事优先：以 Timeline 轨道为核心的可视化创作流程。

• 架构清晰：Contracts/Core/SDK 分层、Manifest 装配、AssetReference-only、配置单一来源。

Architecture At A Glance / 架构一览

• com.spatialcut.contracts: data contracts and SDK interfaces / 数据契约与 SDK 接口
• com.spatialcut.core: domain services + Unity views (Two-Worlds) / 核心服务与视图
• com.spatialcut.sdk: external facade (single entry) / 对外统一入口
• com.spatialcut.narrative: Timeline track library / 叙事轨道库
• com.spatialcut.monitor: operations UI package / 运营监控包
• com.spatialcut.gameplay: optional gameplay modules / 可选玩法模块

Quick Start / 快速开始

1. Open with Unity 2022.3.x

2. Open Assets/Scenes/SampleScene.unity (placeholder) or Assets/StoryboardLab/Monitor/MonitorWeb.unity

3. Provide minimal config JSON in Application.persistentDataPath/Config:

   • AppConfig.json
   • LoggerConfig.json
   • NetworkConfig.json
   • ResourceConfig.json

4. Play in Editor

5. 使用 Unity 2022.3.x 打开工程

6. 打开 Assets/Scenes/SampleScene.unity（占位）或 Assets/StoryboardLab/Monitor/MonitorWeb.unity

7. 在 Application.persistentDataPath/Config 放置最小配置 JSON：

   • AppConfig.json
   • LoggerConfig.json
   • NetworkConfig.json
   • ResourceConfig.json

8. 运行

See / 详见：Docs/Core/Guides/Resource_Recovery.md

Optional Modules / 可选模块

• Narrative optional tracks: add SPATIALCUT_NARRATIVE_OPTIONAL

• Monitor UI (UniWebView): install plugin and add SPATIALCUT_UNIWEBVIEW

• 叙事可选轨道：添加 SPATIALCUT_NARRATIVE_OPTIONAL

• 监控端 WebView：安装 UniWebView 并添加 SPATIALCUT_UNIWEBVIEW

Repo Layout / 目录结构

• Assets/StoryboardLab: sample scenes and validation playground / 实验池与示例场景
• Assets/StoryboardLab/Monitor: monitor demo scene / 监控端示例
• Assets/StoryboardLab/VRClient: VR 客户端清单与入口
• Packages/com.spatialcut.*: core packages / 核心包
• Docs: architecture, decisions, and iteration index / 架构与决议

Docs / 文档

• Docs/Iteration_Index.md
• Docs/Core/Decisions/OpenSource_SpatialCut_Decision.md
• Docs/Core/Architecture/Core-Architecture.md
• Docs/Narrative/Backlog.md (narrative backlog / 叙事轨道候选清单)

Status / 状态

SpatialCut is in active consolidation. The goal is a minimal open-source loop that is stable, clean, and creator-friendly.

SpatialCut 正在收敛阶段，目标是建立稳定、简洁、面向创作者的最小开源闭环。

License / 许可

TBD