FloatSoda 0.4.0

FloatSoda: SteamVR Overlay UI Framework

FloatSoda is a UI framework for building SteamVR overlays with a Flutter-like declarative API in C# / .NET. It renders via SkiaSharp → OpenGL → OpenVR, and manages multiple overlays (dashboard, world-space, and device-tracked) in a unified way. Currently in alpha — APIs may change without notice.

📖 The documentation below is in Japanese. See the documentation site for details — LLM agents can read llms.txt or llms-full.txt — or check the minimal example; the code speaks for itself.

FloatSoda は、SteamVR Overlay を Flutter のような宣言的な書き心地 で作成できるように開発中の UI フレームワークです。SkiaSharp → OpenGL → OpenVR という流れでレンダリングし、複数のオーバーレイを統一的に管理できます。

特徴

• Flutter-like な開発体験: StatelessWidget / StatefulWidget による宣言的な UI 構築と SetState() による再ビルド
• 差分更新: BuildOwner による Widget の差分ビルドと、dirty フラグによる RenderObject の差分レイアウト・差分ペイント
• RenderObject ツリー: Flutter の RenderObject に相当するレイアウト・描画ツリーを実装
• 複数オーバーレイ対応: ダッシュボード・ワールド座標固定・デバイス追従を同時に管理
• Skia による描画: SkiaSharp を使用した高品質なレンダリング
• スレッドセーフ: メインスレッドとレンダースレッドをレイヤークローンで分離

Getting Started

動作環境

• .NET 10 / C# 14
• SteamVR（起動済みであること）
• SkiaSharp / OpenTK / OpenVR

サンプルアプリの起動

# SteamVR を起動してから実行する
dotnet run --project samples/FloatSoda.Samples.OverlayApp

SteamVR ダッシュボードにカラーボックスを表示するオーバーレイが起動します。

最小構成のコード

using FloatSoda;
using FloatSoda.Widgets;
using FloatSoda.Widgets.Layout;
using FloatSoda.Widgets.Paint;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using SkiaSharp;

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddFloatSoda();

using var host = builder.Build();
var app = host.Services.GetRequiredService<FloatSodaApp>();

Widget root = new Align
{
    Child = new SizedBox
    {
        Width = 100,
        Height = 100,
        Child = new ColoredBox
        {
            Color = SKColors.Tomato
        }
    }
};

// ダッシュボードオーバーレイ（サイズは root のレイアウト結果に自動追従）
app.CreateWindow(new DashboardWindow { Title = "MyDashboard", Child = root });

// ワールド座標固定（メートル単位。Position 省略時は前方1m・高さ1m）
// app.CreateWindow(new WorldSpaceWindow { Title = "MyWorld", Child = root });

// デバイス追従
// app.CreateWindow(new DeviceTrackedWindow { Title = "MyHand", Child = root, Target = TrackedDevice.LeftController });

await host.RunAsync();

レンダリングライフサイクル

sequenceDiagram
    participant Main as メインスレッド
    participant Pipeline as RenderPipeline
    participant RO as RenderObject 群
    participant Layer as レイヤーツリー
    participant RT as レンダースレッド
    participant GL as GLView (OpenGL)
    participant VR as OpenVR Compositor

    loop メインループ
        Main->>Main: VREventDispatcher.PollEvents()
        Main->>Pipeline: FlushLayout()
        Pipeline->>RO: Layout(BoxConstraints) [再帰]
        Note over RO: 制約↓ サイズ↑
        Main->>Pipeline: FlushPaint()
        Pipeline->>RO: Paint(PaintingContext, Offset) [再帰]
        Note over RO: Skia ドローコールを記録<br/>→ PictureLayer に格納
        Main->>Layer: Clone() — スレッドセーフコピー
        Main-->>RT: PostTask(layer)
        Main->>Main: FramePacer.WaitForNextFrame()
    end

    loop レンダースレッド
        RT->>GL: Clear()
        RT->>Layer: Layout(LayerContext)
        RT->>Layer: Paint(LayerContext)
        Note over Layer: DrawPicture / SaveLayer<br/>でレイヤーを合成
        RT->>GL: Flush()
        Note over GL: SKSurface → GRContext → GL テクスチャ
        RT->>VR: Overlay.Texture.FromTexture_t(GL texture handle)
    end

詳細は docs/Architecture.md を参照。

実装済みの Widget

レイアウト系

描画系

入力系

ウィンドウ系

自作 Widget の基底クラス

• StatelessWidget — Build() をオーバーライドして UI を宣言
• StatefulWidget<T> + State<T> — SetState() で状態変更と再ビルド
• InheritedWidget — ツリー下方向へのコンテキスト伝播
• ParentDataWidget<T> — 親レイアウトだけが解釈する子ごとの情報を渡す（Expanded / Positioned の基盤）

まだ使えないもの: スクロール系の ListView / GridView / SingleChildScrollView と、 画像とアイコンには公開APIの Paint.Image / Paint.Icon を使用します。 Button などの UI コンポーネントはまだ提供していません。 用意する予定の3層構成 （FloatSoda.UI / FloatSoda.UI.Cream / FloatSoda.UI.FizzyPop）は Phase 5 で、 現時点では NuGet 未配布・押下も未反応です。ボタンは GestureDetector で組み立ててください。 Container は使えますが、Padding の合成にはまだ対応していません。余白は Padding を入れ子にしてください。

ドキュメント

公開サイトは floatsoda.sumx21t.com です。ソースは docs/Home.md 以下の Markdown で、サイトはリリースごとに、GitHub Wiki は main への push ごとに更新されます。コーディングエージェントに読ませるときは llms.txt(索引)か llms-full.txt(全文)を渡してください。

コントリビュータ向けの規約はリポジトリルートにあります(公開サイトと Wiki には載りません)。

開発ステータス

本プロジェクトは現在 Alpha 段階・Phase 1(入力基盤)と Phase 2(表示系ウィジェット)が並行して進行中 です。簡単なアプリケーションは動作しますが、API は予告なく変更されます。

開発は Phase 単位で進めています。Phase は「フレームワークとして何ができる段階か」を表す機能上の到達点で、NuGet のバージョン番号とは対応しません。バージョンはリリースの通し番号として独立に上がり、同じ Phase 中に複数のバージョンが公開されることがあります(バージョン番号から Phase を推定することはできません。1.0.0 のみ Phase 7 に対応)。各 Phase の詳細スコープは GitHub マイルストーン を参照してください。

⚠️ ユーザー操作が動くのはダッシュボードオーバーレイだけです。 ヒットテストとジェスチャ認識は実装済みで、 GestureDetector でタップとパンを受け取れます。ただしポインタ座標の供給元(SteamVR のレーザーポインター)が ダッシュボードオーバーレイにしか接続されていないため、WorldSpaceWindow と DeviceTrackedWindow は表示専用です。

• RenderObject ツリー（レイアウト・描画・クリップ・画像・差分更新）
• レイヤーツリー（ContainerLayer / PictureLayer / ClipLayer / OpacityLayer）
• 複数オーバーレイ（ダッシュボード / ワールド座標 / デバイス追従）
• Widget → RenderObject への inflate パイプライン（StatelessWidget / StatefulWidget）
• BuildOwner による Widget 差分ビルド（Key による子リストの差分更新を含む）
• InheritedWidget によるコンテキスト伝播
• ParentDataWidget による親固有レイアウト情報の伝達（Expanded / Positioned）
• アニメーションシステム（AnimationController / Ticker / FadeTransition）
• ヒットテストとジェスチャ認識（GestureDetector / Listener / タップ・パン）
• 非ダッシュボードオーバーレイへのポインタ接続（コントローラーレイからの入力）
• スクロール（ListView / GridView / SingleChildScrollView）
• マニフェストファイルの自動生成（検討中）