Getting Started

前提条件

.NET 10 SDK
SteamVR がインストール済みで、アプリ実行前に起動していること
OpenVR ランタイム（SteamVR に同梱）

サンプルアプリを動かす（最速）

リポジトリをクローンしたらまずサンプルアプリを起動してフレームワークの動作を確認できます。

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

起動すると SteamVR ダッシュボードに、レイアウト、時計、アニメーション、カウンターのデモ用タブが追加されます。左コントローラー追従とワールド座標固定の時計オーバーレイも生成されます(samples/FloatSoda.Samples.OverlayApp/Program.cs)。

SteamVR を終了するか VREvent_Quit を受信するとアプリも自動終了します。

サンプルには StatefulWidget を使った時計ウィジェット(WatchWidget.cs)が含まれており、SetState() による毎秒の再ビルドで時刻が更新されます。

用途別のサンプル一覧

samples/ には目的の異なる5つのプロジェクトがあります。

プロジェクト	内容	SteamVR
`FloatSoda.Samples.OverlayApp`	レイアウト・時計・アニメーション・カウンター・ドラッグの総合デモ。3種のオーバーレイを同時に生成する	必要
`FloatSoda.Samples.GettingStarted`	下の「最小構成のコード」とほぼ同じ最小アプリ	必要
`FloatSoda.Samples.PointerRegion`	ホバー・押下・取り消しの状態を画面に出す入力デモ。`PointerRegion` と `Listener` の挙動を目で確かめられる	必要
`FloatSoda.Samples.PrimitiveOverlay`	ウィジェット層を使わず、`FloatSoda.OVR` の低レベル API だけでオーバーレイを出す	必要
`FloatSoda.Samples.PaintingSample`	Widget / RenderObject / Layer の各ツリーを PNG へ書き出す	不要

PaintingSample だけは SteamVR も HMD もいりません。 FloatSoda.Testing のヘッドレスレンダラーでツリーを画像化し、デスクトップへ widget_tree_output.png などを保存します。レイアウトの結果だけを確かめたいときは、HMD をかぶらずにこれで見られます。

dotnet run --project samples/FloatSoda.Samples.PaintingSample

新しいアプリを作る

1. プロジェクトを作成する

dotnet new console -n MyOverlayApp
cd MyOverlayApp
dotnet add reference ../path/to/FloatSoda/src/FloatSoda/FloatSoda.csproj

2. 最小構成のコードを書く

Program.cs を以下のように書き換えます。Widget ベースの書き方が推奨です。

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 Center
{
    Child = new ColoredBox
    {
        Color = SKColors.CornflowerBlue,
        Child = new SizedBox { Width = 400, Height = 200 }
    }
};

// オーバーレイのサイズは root ウィジェットのレイアウト結果に自動追従します。
app.CreateWindow(new DashboardWindow { Title = "HelloWorld", Child = root });

await host.RunAsync();

# SteamVR を起動してから実行
dotnet run

Window の作成は Host 側で行います。host.RunAsync() は SteamVR が終了するまで待機し、SteamVR の終了イベント、Ctrl+C、または Host の停止要求を受けると正常終了します。

Widget の実装状況: レイアウト系(Center, Align, Row, Column, Padding, Container, Stack, Wrap, Expanded, AspectRatio など)、描画系(ColoredBox, DecoratedBox, Opacity, Transform, Clip*)、入力系(GestureDetector, Listener)は使用可能で、StatefulWidget / InheritedWidget も動作します。 internal のため公開 API から使えないのは、スクロール系の ListView / GridView / SingleChildScrollView です。画像とアイコンには描画系の Paint.Image / Paint.Icon を使用できます。 Button などの UI コンポーネントはまだ提供していません。 用意する予定の3層構成(FloatSoda.UI / Cream / FizzyPop)は Phase 5 で、現時点では NuGet 未配布・押下も未反応です(→ UILayering)。ボタンは GestureDetector で組み立ててください(→ WidgetSystem.md)。

RenderObject レベルの直接操作（低レベル API）

using FloatSoda;
using FloatSoda.Geometrics;
using FloatSoda.RenderObjects.Layout;
using FloatSoda.RenderObjects.Painting;
using FloatSoda.Widgets;
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>();

var root = new RenderPositionedBox
{
    Child = new RenderConstrainedBox
    {
        AdditionalConstraints = BoxConstraints.Tight(400, 200),
        Child = new RenderColoredBox { Color = SKColors.CornflowerBlue }
    }
};

// CreateWindow の Child は Widget を要求するため、RenderObjectWidget でラップします。
Widget widgetRoot = new RawRootWidget { Root = root };
app.CreateWindow(new DashboardWindow { Title = "LowLevel", Child = widgetRoot });
await host.RunAsync();

// 既存の RenderObject を Widget ツリーのルートへ接続する最小ラッパー。
public sealed record RawRootWidget : SingleChildRenderObjectWidget<RenderPositionedBox>
{
    public required RenderPositionedBox Root { get; init; }

    public override RenderPositionedBox CreateRenderObject() => Root;
}

オーバーレイ種別の選び方

app.CreateWindow(...) に渡すウィンドウ定義 WindowWidget の種類でオーバーレイ種別を選びます。 Size を指定しない場合、オーバーレイのサイズは Child ウィジェットのレイアウト結果に追従します（Size を指定するとそのサイズで固定されます）。

ウィンドウ定義	オーバーレイ種別	位置の管理	ポインタ入力
`DashboardWindow { Title, Child, Size? }`	`DashboardOverlay`	SteamVR ダッシュボードが管理（ユーザーが開くタブ）	✓ 届く
`WorldSpaceWindow { Title, Child, Size?, Position, Rotation }`	`WorldSpaceOverlay`	ワールド座標で固定（`Vector3 Position`、既定は前方1m・高さ1m）	✗ 届かない
`DeviceTrackedWindow { Title, Child, Size?, Target, Offset, Rotation }`	`DeviceTrackedOverlay`	トラッキングデバイスに追従（`TrackedDevice` 列挙体）	✗ 届かない

ポインタ入力が届くのはダッシュボードオーバーレイだけです。 SteamVR はダッシュボード上のレーザーポインターをマウスイベントとして送ってくるため、FloatSoda はそれをそのままヒットテストへ流せます。ワールド座標固定とデバイス追従のオーバーレイには、コントローラーレイからポインタ座標を作る経路がまだありません。これらのウィンドウに GestureDetector を置いてもコンパイルは通り、例外も出ませんが、コールバックは呼ばれません。

Title は SteamVR 上の表示名（ダッシュボードタブ名など）です。OpenVR のオーバーレイキーは「エントリアセンブリ名 + Title のスネークケース」から自動生成されます（例: アセンブリ MyOverlayApp + Title = "My Dashboard" → my_overlay_app.my_dashboard）。

// ダッシュボード
app.CreateWindow(new DashboardWindow { Title = "MyDashboard", Child = root });

// ワールド座標固定。Position 省略時はプレイエリア中央から前方1m・高さ1m (0, 1, -1)
app.CreateWindow(new WorldSpaceWindow { Title = "MyWorld", Child = root });

// 左コントローラーに追従
app.CreateWindow(new DeviceTrackedWindow { Title = "MyHand", Child = root, Target = TrackedDevice.LeftController });

フレームレート設定

FloatSodaOptions でフレームレートを制御できます。

// 固定 FPS
var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddFloatSoda(new FloatSodaOptions
{
    TargetFrameRate = 90
});

TargetFrameRate を指定しない場合のデフォルトは 60fps です。オーバーレイアプリはシーンアプリではないため、WaitGetPoses によるフレーム同期は利用できません。