English | 日本語

Rayは元々私が欲しかった他のシェーダーにない機能を全て詰め込んだプライベートに作られた Minecraft Java Edition - Iris 向けのシェーダーパックです
このシェーダーには、ボクセルレイトレースによる光源処理と実在レンズを再現するフィジカルレンズシミュレーションを搭載しています

日常利用よりも、リプレイMODやレンダリングMODを併用した撮影に向いていますが、設定を軽くすれば、普段のプレイで臨場感を高めることもできます
このシェーダーは、外部のCGツールを挟まずシネマティックルックをゲーム内だけで完結させるのが目的です

現在はナチュラル寄りの見た目で制作しています

たいまつやランタンの光は、カメラ周辺のワールドをボクセルに変えてレイトレースし、遮るものの形どおりの影を落とします
ブロックだけでなくプレイヤーやモブも光を遮るので、たいまつを持って歩くと自分やモブの影が壁に落ちます
手に持った光源、地面に落としたたいまつ、燃えているモブ、光の矢や火の玉も同じように光源として扱います

水面の下の景色は屈折してゆがんで見えます
水中の光芒が差し込み、光源のまわりのにじみは浅瀬でターコイズ、深い所で紺になります

ボケやブルームを足すだけではなく、ポストプロセスでフィジカルレンズシミュレーションを行い、実在するレンズの写りを再現します
Helios 44-2 や Sonnar のようなオールドレンズから、Hologon や Flektogon の超広角、魚眼までプリセットで選べます
プリセットのうち 12 本は、特許に載った実施例の処方から計算しています
ゴーストの色と形、歪曲、周辺減光、ボケの形、色収差はレンズごとに変わります

Releases の nightly から Ray-<バージョン>-<コミット>-nightly.zip をダウンロードして入れます。nightly は main の最新を反映したアルファ版で、shaders/ などが変わるたびに置き換わります

1. zip をダウンロードします (展開は不要です)
2. zip を <Minecraft のインスタンス>\shaderpacks\ に置きます
3. ゲーム内の ビデオ設定 -> シェーダーパック で Ray を選びます

不具合を報告するときは、入れた zip のファイル名を書いてください

リポジトリを clone して使う場合は、shaders/ を直接含むフォルダを shaderpacks\ に置きます。編集をそのまま反映したいときは、下の「開発」の「ジャンクションでつなぐ」を使います

各機能の手法と出典は docs/architecture.md と CREDITS.md にあります

設定画面のトップの「ルック」で、光と色の作り方をまとめて選べます。その下の「LUT」で、最後に色の LUT を重ねられます

3 以降のプリセットは、光の値 (下の表) に加えて、色と階調の多くをカラーグレーディング (下の「カラーグレーディング」) の基準として持ちます。値は shaders/lib/common/look_presets.glsl にあります

ナチュラルとビビッドが決める値は次のとおりです。「掛ける」の値は、既存の設定 (彩度・コントラスト・ブルーム・ブルーミーフォグ・空の光の遮蔽・空の環境光の彩度・フォグの濃さ) にさらに掛かります。露出補正は足されます。ナチュラルは明部の伸びだけが 1.1 で、ほかは掛ける値が 1、足す値が 0 なので、各設定の値がそのまま効きます

• ルックは品質プリセット (低〜極限) とは別に選べ、品質プリセットを変えても変わりません
• GI の方式 (RSM / SSGI / ボクセルレイトレース) で照り返しの出方が違います。RSM (「高」) は照り返しの色が濃く出るので、照り返しの色の濃さは半分だけ掛けます

LUT はトーンマップの後の表示の色 (sRGB) に掛かります。「LUT の強さ」で元の色と混ぜられます

フィルム風の LUT (4-9) は、各社が公開している技術資料の特性の説明 (コントラスト・彩度・色の傾向・色温度) から tools/gen_look_lut.py で作った近似です。メーカーの LUT やデータは使っていません

自分の LUT を使うには、shaders/textures/look/user_lut.png を置き換えて「LUT」を「ユーザーの LUT」にします。同梱の user_lut.png は何も変えない恒等の LUT です

• 画像編集ソフトで作る: user_lut.png (1024x32) を開き、色調補正 (トーンカーブ・色相・彩度など。ぼかしや変形はしない) を掛けて同じ名前で保存します。ゲームの撮影に同じ補正を掛けたときと同じ色になります
• .cube (DaVinci Resolve・Photoshop などの 3D LUT) から作る: uv run tools/gen_look_lut.py from-cube my.cube --out shaders/textures/look/user_lut.png。入力は sRGB の表示値 (0-1) の LUT を想定しています
• 画像の形式: 32x32x32 の LUT を、青の段ごとに 32x32 の板を横に 32 枚並べた 1024x32 の PNG です。各板の x が赤、y が緑 (上の行が緑 0)
• 撮影した画面に LUT を試す: uv run tools/gen_look_lut.py preview --lut my.cube --in shot.png --out out.png

「ポストプロセス」の「カラーグレーディング」で、DaVinci Resolve のカラーページのような調整ができます。既定値ではどれも何もせず、ルックのプリセットの上に重なって効きます (彩度は掛け算、色や明るさのずれは足し算)

掛ける順番は、ホワイトバランス -> ティント -> オフセット -> コントラスト -> シャドー・ミッド・ハイライト -> ハイライトの圧縮・シャドーの持ち上げ -> 彩度・バイブランス -> 色相ごと -> トーンマップ -> リフト・ガンマ・ゲイン -> トーンカーブ -> スプリットトーン -> LUT -> CDL です

• トーンマップ前の調整は、露出の段 (EV) の上で効きます。昼・夜・洞窟で明るさが変わっても同じように効き、トーンマップがはみ出しを畳むので色がクリップしにくくなります
• トーンマップ後の調整は、黒 0・白 1 の表示の値に掛かります。フィルム風の LUT はグレーディングの後に掛かるので、LUT の色の下でグレードを調整できます
• 「グレーディング」を切ると、この画面の調整とルックのプリセットのグレーディングをまとめて外せます (ホワイトバランス・コントラスト・彩度・LUT・CDL は残ります)
• 描画の重さはほとんど変わりません (最後のパスで計算するだけで、追加のテクスチャを使いません)

設定画面の「レンズ」で、実在のレンズの写りを選べます
レンズごとに、フレアのゴーストの色と形、光条の本数、ボケの形、にじみ、周辺の暗さ、歪曲が変わります。「カスタム」を選ぶと、各効果の強さを「カスタムレンズ」の画面で個別に決められます

7〜18 の 12 本は、特許に載った実施例の処方 (面の曲率半径・間隔・ガラスの屈折率と分散) を光線追跡して、ゴーストの位置と色、歪曲、周辺光量、像面湾曲と非点収差によるボケ、色収差を計算しています
処方から焦点距離を計算し直すと、どれも公称値と 1% 程度以内で一致します。コーティングと絞り羽根は処方に無いので、製品の資料と作例から決めています

「適した FOV」は、35mm 判の横幅 36mm を画面の横幅に合わせたときの実物の画角を、Minecraft の FOV (縦の画角) に直した値です。画面は 16:9 なので、35mm 判 (3:2) の上下が切れた構図になります。焦点距離 f (mm) のレンズでは 縦の FOV = 2 atan(18 / f x 9 / 16) で、35mm は 32、20mm は 54、15mm は 68 です 50mm 以上はゲームの FOV の下限 (30) より狭くなるので 30 にしています (実物より少し広い画角)

• レンズを足すときは後ろに足し、既存の番号は変えません (保存した設定が別のレンズを指さないように)
• 50mm 以上のレンズは FOV 30 でも実物より画角が広いので、どの FOV でも「そのレンズの写りの味付け」として掛かります。収差の強さは画面の隅を 35mm 判の隅に合わせて決めているので、FOV を変えても見た目の形は同じです (魚眼の写り方だけは角度で計算するので FOV で変わります)
• 超広角と魚眼は、表の FOV で使うと実物の画角に近くなります。ゲームの描画は直線写像なので、歪曲と魚眼の写り方は最後の段で画面を再投影して作ります。被写界深度・ブルーム・TAA は再投影の前の画面で計算し、太陽のフレアは再投影の後の画面で光源の位置に合わせて描きます
• 魚眼は、中心が 2 倍ほど引き伸ばされるので少し柔らかくなります。既定は画面の隅まで埋める合わせ方で、「魚眼の合わせ方」を「横幅を合わせる」にすると、実物に近い画角になる代わりに描画の範囲外になる四隅が黒くなります。実物の対角 180° はゲームが描ける範囲 (FOV 110 で対角 142°) を超えるので、魚眼の FOV は上限の 110 にしています。このとき「横幅を合わせる」の横の画角は 137° で、実物 (140°) とほぼ同じです
• 魚眼と歪曲の強い設定では、歪曲を TAA の中で組み立てます (「歪曲を TAA で組み立てる」、既定は自動)。ジッターで毎フレーム少しずつずれた画面から出力の画面を作るので、止まっている時やゆっくり動く時は、引き伸ばされた魚眼の中央も細かく写ります。速く動く時と TAA を切っている時は、最後の段で引き伸ばす方式と同じ写りです
• Gyogyotto は「魚眼の合わせ方」が「隅まで埋める」(既定) のとき FOV 107 で実物の 20mm になり (110 でもほぼ同じ)、Rokkor と違って実物の焦点距離のまま四隅まで描けます
• STF 135mm のアポダイゼーションは、被写界深度のボケの各点に、絞りの上の位置に応じた透過率 (中心ほど明るく縁ほど暗い) を掛けて作ります。製品の T 値 (開放 T4.5、F5.7 で T6.7) に合う透過率にしてあり、絞ると絞りの外側が切れて普通の円いボケに近づきます
• FA 28mm Soft の柔らかさは、処方から計算したピントの合った点の広がり (ハローの大きさと、芯の外に行く光の割合) を F 値ごとに持って、ブルームの縮小画像から作ります。開放で最も強く、F5.6 で消えます。F 値は被写界深度の「絞りの決め方」を「F 値を指定」にして変えます (「ボケの量」のままだと開放の F2.8)。Canon 50/0.95 のにじみも同じ仕組みで、開放だけに掛かります
• 補正不足の球面収差のレンズ (FA 28 Soft など) は、後ボケが中心の明るいにじんだ円、前ボケが縁の明るい輪になります (前と後で逆)
• 「歪曲収差の強さ」を上げると、処方どおりでは控えめな歪曲 (Flektogon の陣笠型など) を誇張できます。「歪曲収差」を OFF にすると、魚眼も含めてゲームの直線写像のままになります

設定画面の一番上で、品質プリセットを 9 段階から選べます。並びは軽い順で、既定は「高」です。プリセットを選んだあとに個別の項目を変えても構いません

• 高 (最軽量) / 高 (軽量): 高と同じ手法と見た目のまま、内部の解像度 (光源のトレース・ボリューメトリックライト、最軽量では雲も) とサンプル数 (影のぼかし・GI・光源・反射) を下げ、時間方向の積み重ねとデノイズで補います
• 極限 (軽量): 極限の手法 (ボクセルレイトレースの GI・ボクセル補完の反射など) のまま、範囲と解像度を最高にそろえます
• 極限 (バランス): 極限の範囲のまま、光源のトレース・GI・雲・ボリューメトリックライトを半分の解像度にします
• 雲の形と陰影は中以上のどのプリセットでも同じです。変わるのは細かいノイズの量と重さだけです

自動露出は、屋外の夜を月の満ち欠けと天気で変えます。月が照らす晴れた夜は暗い所に合わせて強めに持ち上げ、新月・雨の夜・水中は持ち上げを弱くして暗さを残します。「平均」の露出は暗い所の計測を使わず、持ち上げの傾きだけ月の満ち欠けで変わります。マニュアル露出には掛かりません。「夜の持ち上げ」で持ち上げの量に倍率を掛けられ、0 で持ち上げなしの暗い夜になります

重さの目安は、RTX 2080 Ti・1297x803 で 4 つの場面 (晴れの正午の屋外・森・洞窟のたいまつ・夕方の水辺) のフレーム時間を平均し、「高」を 1.0 にした比です。高・最高・極限 (軽量) の差は測定のばらつきと同じくらいです。「低」は測っていません

光源まわりの重い機能は、プリセットとは別に個別で切り替えられます。どれも設定画面の「ブロックライト」の中にあります

開発中は shaderpacks\ にコピーせず、ジャンクションでリポジトリにつなぐと編集がそのまま反映されます。ゲーム内で R キーを押すとシェーダーが再読み込みされます

New-Item -ItemType Junction -Path "<Minecraft のインスタンス>\shaderpacks\Ray" -Target "<このリポジトリのパス>"

cmd なら mklink /J "<インスタンス>\shaderpacks\Ray" "<リポジトリ>" です。ジャンクションは管理者権限なしで作れます

ゲームを起動せずにコンパイルエラーを調べられます。スクリプトの Python 環境は uv で管理しているので、最初にリポジトリ直下で uv sync を実行してください。glslang の入手方法やオプションは tools/README.md にあります

uv sync                                   # 初回だけ。.venv/ に Python 3.11 と numpy・glfw・PyOpenGL が入ります
uv run tools/validate_shaders.py          # Iris の前処理を再現して glslang でコンパイル (既定値・オーバーワールド)
uv run tools/validate_shaders.py --full   # 既定値を 3 ディメンションで、全プロファイルをオーバーワールドで
uv run tools/gl_compile_check.py          # 手元の GPU ドライバで compile + link

Minescript (Python スクリプトを動かすクライアント mod) を使い、ゲームの外から「設定変更 -> シェーダー再読み込み -> 定点シーンの撮影 -> ログ確認」を回せるようにしています
コマンドはすべて CLI なので、コーディングエージェントにシェーダーを編集させ、撮影したスクリーンショットとログを見て直させる、というループをそのまま回せます

flowchart LR
    agent["AI エージェント<br/>(シェーダーを編集)"] -- "uv run tools/mc.py<br/>uv run tools/run_scene.py" --> cli["tools/*.py"]
    cli -- "cmd.json (手順)" --> ray["ray_agent.py<br/>(ゲーム内に常駐)"]
    ray -- "コマンド実行・視点・撮影<br/>シェーダー再読み込み" --> mc["Minecraft + Iris"]
    ray -- "status.json (結果)" --> cli
    mc -- "screenshots/ と latest.log" --> agent

$env:RAY_MC_DIR = "<ゲームディレクトリ>"
uv run tools/shader_options.py set GI_MODE=0 LIGHT_SHADOWS=false   # 設定を書き換える
uv run tools/run_scene.py --all --reload --tag v2                  # 再読み込みして全シーンを撮影 -> <game>/screenshots/v2_<シーン>.png

ゲーム側の準備 (Minescript の導入、ray_agent.py の常駐、定点シーン scenes.json の作り方) は tools/README.md にあります

Iris の実行順に沿った処理の流れです。パスごとの入出力とバッファの割り当ては docs/architecture.md の「レンダーパイプライン」 にあります

flowchart TD
    setup["setup<br/>光源テーブルを SSBO に構築<br/>大気 LUT (透過率・多重散乱)"]
    begin["begin<br/>光源リストのクリア"]
    shadow["shadow<br/>太陽の影マップ<br/>地形とエンティティのボクセル化<br/>画面外のエンティティ光源を登録"]
    prepare["prepare<br/>太陽・月の照度と空の SH<br/>SkyView LUT / 雲の天気マップと雲影"]
    gbuf["gbuffers (不透明)<br/>G バッファ<br/>画面内のエンティティ光源を登録"]
    subgraph deferred["deferred"]
        direction TB
        flood["floodfill 1 ステップ<br/>光源をライトビンへ振り分け"]
        trace["光源シャドウ<br/>選んだ N 光源を DDA でトレース<br/>時空間デノイズ"]
        gi["GI / AO"]
        cloud["体積雲"]
        shade["不透明シェーディング + 空"]
        flood --> trace --> gi --> cloud --> shade
    end
    translucent["gbuffers (半透明)<br/>水・ガラスの前方シェーディング"]
    subgraph composite["composite"]
        direction TB
        refl["反射と半透明の合成"]
        fog["ボリューメトリックライト / フォグ"]
        post["TAA / モーションブラー / DoF / ブルーム / 自動露出"]
        refl --> fog --> post
    end
    final["final<br/>AgX トーンマップ・色調整・CAS"]

    setup --> begin --> shadow --> prepare --> gbuf --> deferred --> translucent --> composite --> final

• 公開・配布
  • プリセットごとに必要な GPU 性能を測る
  • Linux での動作確認
• 光源の問題
  • 光源が密集した場所のちらつきを抑える (ライトビン 1 つに 64 個までしか入らず、上位から漏れた光源は毎フレーム確率で選んでいるため。時間方向の再利用を入れる)
  • 半透明の面にも光源の影を付ける (いまは floodfill だけで照らすので暗め)
  • エンダーチェストなどブロックエンティティの光をボクセルの光源に登録する
  • ライトブロック (minecraft:light) の光レベルを正しく読む
  • 階段を向きどおりの形で遮る (いまはハーフブロックとして近似)
  • MOD の光るブロックに対応する
• 最適化
  • 光源の多い場面での光源トレースを軽くする
  • 体積雲とボリューメトリックライトを軽くする
  • 計測した結果からプリセットの割り当てを見直す
• カメラ・レンズ
  • レンズのプリセットを増やす
  • 広角 (高い FOV) ゆがみ実装
• Distant Horizons 対応

Ray の開発を支援していただけると大変励みになります！

• GitHub Sponsors
• Ko-fi

他のシェーダーパックのコードは使っていません
実装の参考にした論文・手法とシェーダーパックは CREDITS.md に載せています

ライセンスは LICENSE (Ray Shader License 1.0) です。要点は次のとおりです

• プレイ・配信・動画・スクショ・映像作品は、収益化の有無を問わず自由です
• modpack への同梱は、有料の modpack でも、modpack 自体に実質的な中身があり、内容を変えずクレジットと公式リンクを添えてなら自由です(直接 zip に入れても構いません)
• 改変版フォークを公開する場合は、フォーク元明記と、見た目または機能の差別化が必要です。改変版もこのライセンスを継承します(ただの丸コピのリネームはダメ)
• 無改変の再配布は自由です。作者と公式へのリンクを添えてください
• 本体及び改変版フォークの販売や課金、広告を通した配布はできません(有料 modpack への同梱は除く)

このライセンスは、このファイルを含む版にのみ適用されます