Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,8 @@ jobs:
run: bash scripts/format.sh --check

# Linux regression gate: scripts/native-gate.sh (CI と手動 pre-push の単一ソース) で Release build -> C smoke tests -> C# runtime テスト -> サンプルの変換 -> 開発の道具の検査。
# 視覚 golden の byte 比較は --skip-golden で外している: lavapipe の出力は mesa の version に依存し、runner の mesa はローカル生成の golden と一致しない。
# CI の視覚 golden gate は windows job (WARP)、lavapipe golden はローカル pre-push の gate。
# 視覚 golden の byte 比較は --skip-golden で外している (理由は scripts/run-golden.sh の先頭のコメント)。
# CI の視覚 golden gate は windows job (WARP) と macos job、lavapipe golden はローカル pre-push の gate。
# mesa を container 等で pin できたら有効化する。
# native gate を部分 (--part) ごとの job に分けて並べる。lider の runtime テストは 2 つに分ける (LIDER_SHARD)。
linux:
Expand Down Expand Up @@ -372,7 +372,7 @@ jobs:
run: LUB_BACKEND=d3d12 LUB_D3D12_WARP=1 scripts/test-tcs-process-cleanup.sh ./build-release/lub.exe

# どの D3D12 runtime(Agility SDK か inbox か)と WARP が載ったか、backend が見る feature flag を log に残す。
# WARP は runner の inbox 版を使う (golden はその出力で撮ってある。NuGet 版は LSB が違う)。
# WARP は runner の inbox 版を使う (理由は scripts/run-golden.sh の先頭のコメント)。
- name: d3d12 runtime info
if: matrix.part == 'checks'
shell: bash
Expand Down
29 changes: 10 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,7 @@ runtime は C/C++ と既存ライブラリで組む。
特定のアセット形式や GUI editor に依存せず、ゲームを構成する状態、描画、
入力、物理、音、debug 情報をコードから制御できる環境を目指す。

現時点の実装は SDL3 + Slang + tcs VM を基盤にし、GPU backend は
native がプラットフォーム直接実装 (default — Windows: D3D12、
Linux: Vulkan、macOS / iOS: Metal) と SDL3 GPU API (`sdlgpu`)、web が
webgpu.h 直接実装。
現時点の実装は SDL3 + Slang + tcs VM を基盤にし、GPU backend は native がプラットフォームごとの直接実装 (D3D12、Vulkan、Metal) と SDL3 GPU API (`sdlgpu`)、web が webgpu.h 直接実装。
対応プラットフォームは Linux x86_64、Windows x86_64、macOS arm64、iOS arm64、Android arm64 (Meta Quest。tcs2c で C にしたゲームだけ。[docs/android.md](docs/android.md))、WebAssembly/WebGPU。

## ドキュメント
Expand Down Expand Up @@ -112,8 +109,7 @@ scripts/format.sh --check # 整形が必要か確認のみ (CI 向け / 非

依存:
- C# の変換は TinyC# (`tcs/`) が行う。
lub は実行ファイルの隣の `tcs/tcs` (`scripts/build-tcs-native.sh` が作る C の tcs) を最初に使い、無ければ PATH の dotnet SDK で `tcs/` の compiler を動かす。
C の tcs を使うなら実行に dotnet は要らない (作るのには dotnet SDK が要る)。
lub がどの tcs を使うか (dotnet が要るかどうか) は [docs/manual/08-csharp.md](docs/manual/08-csharp.md) の「dotnet の無い環境 (C の tcs)」にある。

サンプルは `samples/<name>/` に 1 つずつ自己完結する形で置く
(`<Entry>.cs` + `<Entry>.csproj` + `data/`)。
Expand Down Expand Up @@ -174,25 +170,20 @@ scripts/run-golden.sh --update # golden 画像を再生成 (描画意図的
scripts/run-golden.sh --test TestIndexedDraw --backend sdlgpu
```

Linux と Windows は機材非依存の CPU rasterizer を強制するので capture が
確定的になり、`cmp -s` で完全一致判定する。Linux は lavapipe + xvfb で
sdlgpu と vulkan を、Windows (git bash) は WARP (`LUB_D3D12_WARP=1`) で
d3d12 をチェックする。macOS は metal を実 GPU で描くので、Linux の golden
(`*_sdlgpu.png`) と許容差で比べる (`scripts/png-diff.py`)。
OS ごとにどの backend をどう比べるか、byte 一致がどの条件で成り立つかは、`scripts/run-golden.sh` の先頭のコメントにある。

## Backend 切替

lub は 5 つの GPU backend を持ち、同一 API で動く:

- `d3d12` — Windows の既定。D3D12 直接実装
(設計は [docs/d3d12-backend.md](docs/d3d12-backend.md))
- `vulkan` — Linux の既定。Vulkan 直接実装 (`src/backend_vulkan.c`)。Windows でも
Vulkan SDK が見つかる build では選べる。
`LUB_BACKEND=openxr` はこの backend で OpenXR の headset に描く (Linux / Android。Android の既定。[docs/manual/07-xr.md](docs/manual/07-xr.md))
- `metal` — macOS / iOS の既定。Metal 直接実装
(設計は [docs/metal-backend.md](docs/metal-backend.md))
- `d3d12` — D3D12 直接実装 (設計は [docs/d3d12-backend.md](docs/d3d12-backend.md))
- `vulkan` — Vulkan 直接実装 (`src/backend_vulkan.c`)。
`openxr` はこの backend で OpenXR の headset に描く ([docs/manual/07-xr.md](docs/manual/07-xr.md))
- `metal` — Metal 直接実装 (設計は [docs/metal-backend.md](docs/metal-backend.md))
- `sdlgpu` — SDL3 GPU API 経由の実装 (Windows / Linux の代替 backend)
- `webgpu` — web build の実体 (webgpu.h 直接)。web では backend 指定は無視される
- `webgpu` — web build の実体 (webgpu.h 直接)

どの platform で選べるかと、未指定のときの既定は、API reference の `ConfigOpts.Backend` にある。

設計記録は [docs/log/2026-06-22-native-backend-design.md](docs/log/2026-06-22-native-backend-design.md)、
整理方針は [docs/log/2026-07-07-backend-consolidation.md](docs/log/2026-07-07-backend-consolidation.md)。
Expand Down
3 changes: 1 addition & 2 deletions cs-lib/lub_stub.cs
Original file line number Diff line number Diff line change
Expand Up @@ -2644,8 +2644,7 @@ public class ConfigOpts
{
/// <summary>
/// GPU backend。
/// native では "d3d12" (Windows の既定) / "vulkan" (Linux の既定。
/// Windows は Vulkan SDK がある build のみ) / "metal" (macOS / iOS の既定) / "sdlgpu"。
/// native では "d3d12" (Windows の既定) / "vulkan" (Linux の既定。Windows は Vulkan SDK がある build のみ) / "metal" (macOS / iOS の既定) / "openxr" (vulkan で OpenXR の headset に描く。Linux と Android の build のみで、Android の既定) / "sdlgpu"。
/// web (WASM) は webgpu のみで、指定は無視される。
/// 未指定 (null) なら既定のまま。
/// </summary>
Expand Down
2 changes: 1 addition & 1 deletion docs/api-glue.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ hot reload は `<Entry>.batch` (tcs vm の差分。`tvm_apply_batch` で当て
`OnQuit` の後に新しい VM で `OnInit` から始める。`<Entry>.errors` (通らなかった build の診断) があれば、読んで消し、`OnBuildFailed` に渡す (`App.Use` で開いた app では `App.Status` の `BuildError` に入る)。
web の player の page (`player.html`) はこの player (`build/wasm/vm/lub.js`) を使う。web のサイトの入口 (lider) では、lider が player に組み込んだ tcs でゲームを変換する。

`lub Game.csproj` は入力 (csproj のディレクトリと `Lub="Source"` の参照先の下の `*.cs`、cs-lib の実装。`*.ref.cs` は `--ref`) の一覧を `.lub/<Entry>.inputs` に書き、`tcs vm --watch --inputs-from` を背後に張る (`src/vm_project.c`)。
`lub Game.csproj` は入力 (何を読むかは `docs/manual/08-csharp.md` の「csproj から lub が読むもの」) の一覧を `.lub/<Entry>.inputs` に書き、`tcs vm --watch --inputs-from` を背後に張る (`src/vm_project.c`)。
一覧は 0.3 秒ごとに探し直すので、file を足すか消すとそのまま変換し直す。
差分は `@@tcs_vm_batch` の frame で届き、当ててから entry の `OnReload` を呼ぶ。
その差分に `@@tcs_reload_notes` の frame (生きている instance に入らない instance の field の初期化子の変更など) が先に届いていれば、`OnReload` の後に `OnReloadNotes(notes)` に渡す。
Expand Down
10 changes: 4 additions & 6 deletions docs/d3d12-backend.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@ descriptor heap・resource state など D3D12 固有の概念はすべて
Windows 10 1909 以降。起動時に `d3d12: runtime:` で載った runtime の path、
`d3d12: enhanced barriers:` で feature flag を log する。
- WARP: `-DLUB_FETCH_WARP=ON` で NuGet `Microsoft.Direct3D.WARP` の
`d3d10warp.dll` を exe の隣に置ける(新しい WARP を試すとき用)。CI と
golden は runner の inbox WARP で、NuGet 版とは出力の LSB が違う。
`d3d10warp.dll` を exe の隣に置ける(新しい WARP を試すとき用)。
golden との関係は `scripts/run-golden.sh` の先頭のコメント。
- HWND は SDL3 window の `SDL_PROP_WINDOW_WIN32_HWND_POINTER`。
- Debug build または `LUB_D3D12_DEBUG=1` で debug layer を有効化(Agility SDK
の device factory にも設定する)。WARNING 以上の validation メッセージを
Expand Down Expand Up @@ -122,8 +122,6 @@ descriptor heap・resource state など D3D12 固有の概念はすべて

## Golden test

`scripts/run-golden.sh` は Windows (git bash) では d3d12 backend を
WARP(`LUB_D3D12_WARP=1`、Microsoft のソフトウェアラスタライザ)で回し、
`tests/golden/<name>_d3d12.png` と byte 比較する。lavapipe と同じく
機材・ドライバ非依存の CPU rasterizer なので `cmp -s` の完全一致が成立する。
`scripts/run-golden.sh` は Windows (git bash) では d3d12 backend を WARP (`LUB_D3D12_WARP=1`、Microsoft のソフトウェアラスタライザ) で回し、`tests/golden/<name>_d3d12.png` と byte 比較する。
byte 一致が成り立つ条件は `scripts/run-golden.sh` の先頭のコメントにある。
実 GPU での動作確認は別途 capture 目視で行う。
13 changes: 4 additions & 9 deletions docs/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ tcs2c は tcs2c で C にしたゲームを lub と静的に link する経路 (
数値は両方 f32 で、Math の超越関数も同じ実装 (次の段落) なので絵も揃う。
golden 画像 (`tests/golden/<name>_<backend>.png`) は tcs VM の player で撮る。

ゲームの論理の計算は OS をまたいで決定的にする。数値は f32 で、四則演算と sqrt / floor / fmod などは IEEE-754 で結果が決まる。結果が実装で変わる超越関数 (sin / cos / tan / atan2 / exp / log / pow) は tcs が 1 つの実装 (`tcs/runtime/math`、三角関数系と log10 は CORE-MATH、exp / log / log2 / pow は musl の Arm 由来) を持つ。tcs2c の生成 C はそれを埋め込み、tcs VM は lub が link する同じ実装 (CMake の `tcs_runtime`) を呼び、.NET 実行は TinySystem.Math (同じ手順の C# 版) を呼ぶ。.NET の project は tcs の `TinySystem.props` を Import して、`Math` / `MathF` を TinySystem.Math にする。C のソースは FMA への融合などで結果が変わらないようにコンパイルを固定する。CI は決まった入力列の結果の hash を、Windows / Linux / macOS / iOS / web と tcs2c と .NET の経路で 1 つの期待値と比べる (`tests/cs/TestMathDeterminism.cs`)。
ゲームの論理の計算は OS をまたいで決定的にする。数値は f32 で、四則演算と sqrt / floor / fmod などは IEEE-754 で結果が決まる。結果が実装で変わる超越関数 (一覧は tcs の `doc/il-spec.md` の 13 節) は tcs が 1 つの実装 (`tcs/runtime/math`。元にしたライブラリは各 file の先頭に書く) を持つ。tcs2c の生成 C はそれを埋め込み、tcs VM は lub が link する同じ実装 (CMake の `tcs_runtime`) を呼び、.NET 実行は TinySystem.Math (同じ手順の C# 版) を呼ぶ。.NET の project は tcs の `TinySystem.props` を Import して、`Math` / `MathF` を TinySystem.Math にする。C のソースは FMA への融合などで結果が変わらないようにコンパイルを固定する。CI は決まった入力列の結果の hash を、Windows / Linux / macOS / iOS / web と tcs2c と .NET の経路で 1 つの期待値と比べる (`tests/cs/TestMathDeterminism.cs`)。

## Non-Goals

Expand Down Expand Up @@ -109,14 +109,9 @@ log、capture、resource dump、runtime state dump のような情報取得は

## Current Constraints

- backend は `d3d12` (Windows) / `vulkan` (Linux、Android、SDK が見つかる Windows) /
`metal` (macOS / iOS) / `sdlgpu` (Windows / Linux の代替) / `webgpu`
(web のみ)。未指定時の既定は Windows: d3d12、Linux: vulkan、
macOS / iOS: metal、Android (Meta Quest): openxr (vulkan で OpenXR の headset に描く。`docs/android.md`)、web: webgpu。golden は Windows は WARP、Linux は
lavapipe で撮る (`docs/d3d12-backend.md`)。macOS と iOS simulator は
runner の GPU で描き、Linux の golden と許容差で比べる
(`docs/metal-backend.md`)。backend 構成の整理方針は
`docs/log/2026-07-07-backend-consolidation.md`。
- backend の値と、platform ごとの未指定のときの既定は、API reference の `ConfigOpts.Backend` (`cs-lib/lub_stub.cs`)。
golden の撮り方と比べ方は `scripts/run-golden.sh` の先頭のコメント。
backend 構成の整理方針は `docs/log/2026-07-07-backend-consolidation.md`。
- iOS の player は shader compiler と transpiler を持たない。
生成済みの bytecode (`.tcsb`) と shader cache を同梱した app として動く (`docs/metal-backend.md`)。
- swapchain capture (`--capture`) は native と web の両方にある。ゲームが任意の render target を読むのは `Gfx.Readback()`。
Expand Down
8 changes: 4 additions & 4 deletions docs/manual/06-lub-lubx.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,14 @@ core API にしない方針。既存エンジンとの API 互換も目標にし

## lubx — C# ライブラリ層

`lubx`(`cs-lib/lubx`、namespace `Lubx`)は `Lub.*` の上に純粋な C# で書かれた便利層。
`lubx`(`cs-lib/lubx`、namespace `Lubx`)は `Lub.*` の上に C# で書かれた便利層。
C のライブラリが要る所 (Ogg Vorbis の decode など) だけは C の実装を持つ (`docs/api-glue.md` の「lubx の C の面」)。
`SpriteBatch` / `Atlas` / `Shapes` / `Text`(2D 描画)、
`Renderer3d` / `Mesh3d` / `Shapes3d` / `Bones`(3D レンダラ。設計記録は `docs/log/2026-07-12-renderer3d-design.md`)、
`Camera2d` / `Camera3d`、`Assets`、`Rand`、`Sfx` など。

runtime の機能ではないので、ソースを読めばすべて `Lub.*` の呼び出しに
分解できる。挙動を変えたければ自分のプロジェクトに写して改造してよい
層であり、lubx に無い機能は同じやり方で自作できる。
runtime の機能ではないので、C の実装を持つ所を除けば、ソースを読むと `Lub.*` の呼び出しに分解できる。
挙動を変えたければ自分のプロジェクトに写して改造してよい層であり、lubx に無い機能は同じやり方で自作できる。

## key の付け方

Expand Down
33 changes: 23 additions & 10 deletions docs/manual/08-csharp.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
lub のゲームコードは C# で書く。
使うのは [tcs (TinyC#)](https://github.com/neguse/lub/tree/master/tcs) — C# のサブセットを tcs VM の bytecode (`.tcsb`) に変換するコンパイラ (release 向けに C にも変換できる) で、web のサイトの入口ではエディタ (lider) の player に組み込んだ tcs (tcs2c で C にした tcs) がブラウザ内で、native では lub が `tcs` を動かす。
dotnet が無い環境では、tcs2c で C にした tcs (C の tcs) を使う。
実行ファイルの隣に C の tcs があれば、dotnet があってもそちらを先に使う (後述)。
実行ファイルの隣に C の tcs があれば、dotnet があってもそちらを先に使う (探す順は後述)。
tcs の compiler は TinyC# 自身で書いた 1 つの実装で、dotnet、C の tcs、ブラウザのどれで動かしても同じ出力になる。

「フル C# が動く」わけではない。TinyC# は C# 構文の DSL であり、モダンな C# の書き味 (record / pattern / lambda / LINQ メソッドチェーン / nullable 型チェック) を保ちつつ、tcs VM と C に素直に落ちる小さな核だけをサポートする。
Expand Down Expand Up @@ -141,29 +141,42 @@ scripts/run-cs-sample.sh 09_breakout --check # 診断のみ (警告があ
scripts/run-cs-sample.sh 09_breakout --vm # bytecode にする (samples/09_breakout/.lub/Breakout09.tcsb)
```

`lub check <entry>.csproj` は `lub <entry>.csproj` と同じ入力 (entry のディレクトリの `*.cs` + cs-lib の実装 + stub) を tcs の `check` に渡す。
`lub check <entry>.csproj` は `lub <entry>.csproj` と同じ入力 (下の「csproj から lub が読むもの」) と stub を tcs の `check` に渡す。
診断が無ければ終了コード 0、あれば診断を出して 1 で終わる。
画面が無い環境でも使える。

### dotnet の無い環境 (C の tcs)

tcs は compiler も CLI も TinyC# 自身で書いてあり、tcs2c で C にした実行ファイル (C の tcs) にできる。
C の tcs は dotnet の tcs と同じ実装で、変換の結果も hot reload の差分も同じになる。
lub は実行ファイルの隣の `tcs/tcs` を最初に使う。
release の一式は `bin/tcs/` に入っていて、dotnet は要らない。
lub が使う tcs は次の順に探す。

1. 環境変数 `LUB_TCS` (tcs を動かす command。空白で区切り、quote は読まない)
2. 実行ファイルの隣の `tcs/tcs` (C の tcs)
3. PATH に dotnet があれば、checkout の `tcs/` の compiler を `dotnet run` で動かす
4. PATH に dotnet が無ければ、checkout の `tcs/SelfHost/out/native/tcs` (tcs の `SelfHost/native.sh` の出力)

release の一式は `bin/tcs/` に C の tcs が入っていて、dotnet は要らない。
手元の build では `scripts/build-tcs-native.sh <build-dir>` が `<build-dir>/tcs` に作る (作るのに dotnet SDK と C compiler が要る)。
`tcs/tcs` が無いときは、PATH に dotnet があれば `tcs` を `dotnet run` で動かし、無ければ `tcs/SelfHost/out/native/tcs` (tcs の `SelfHost/native.sh` の出力) を使う。

web のサイトの入口の変換も、同じ C の tcs をエディタ (lider) の player に組み込んだもの (`lider/README.md`) が行い、同じ増分 session で hot reload する。
何が生きたまま反映されて何が作り直しになるかは「ライフサイクルと hot reload」
の章を参照。

csproj は lub にとっては entry 指定 (basename = entry class、入力 = 同
ディレクトリ以下の全 `*.cs`。`bin/` `obj/` と `.` で始まるディレクトリは
除く) でしかないが、dotnet 側 (Rider / VS Code) では本物のプロジェクトとして
機能する: stub と TinySystem を参照し、TinyC#
サブセット逸脱は Roslyn Analyzer が IDE 上で TCS 診断として出す。
## csproj から lub が読むもの

lub は MSBuild で csproj を評価せず、次のものだけを読む。

- csproj の file 名の basename が entry class (`Breakout09.csproj` なら `Breakout09`)
- 入力は、csproj のディレクトリの下の `*.cs` 全部 (`bin/`、`obj/` と `.` で始まるディレクトリは除く) と、cs-lib の実装 (`cs-lib/lub/*.cs`、`cs-lib/lubx/*.cs`)
- `Lub="Source"` を付けた `ProjectReference` の参照先のディレクトリの下の `*.cs` も入力に足す (参照先の参照も辿る。`$(...)` の property を含む path は読まない)
- `*.ref.cs` は宣言だけの参照 (tcs の `--ref`) として渡す (隣に native の library を置いた native の拡張は `docs/api-glue.md`)

```xml
<ProjectReference Include="../shared/Shared.csproj" Lub="Source" />
```

dotnet 側 (Rider / VS Code) では csproj は本物のプロジェクトとして働く: stub と TinySystem を参照し、TinyC# のサブセットから外れた書き方は Roslyn Analyzer が IDE 上で TCS 診断として出す。

## .NET で実行する

Expand Down
Loading
Loading