macbear_3d
RELEASE NOTES · 2026.07.15
把點光源，
做到位。
0.9.3 沒有加新的光源類型，只把點光源的衰減公式、除錯輔助線到座標正確性，一路重新校準了一遍——外加一支遲來已久的 console logger。
dependencies:
macbear_3d: ^0.9.3
macbear_3d: ^0.9.3
example/ · per-pixel lighting demo scene
// 前情提要
先講清楚，這次在修什麼
從 0.9.1 開始的三個版本，其實一直在為同一件事鋪路。
0.9.1
著色器管線模組化shader refactor
Fog / Shadow / Water 拆成獨立
.glsl 檔案，各自配上型別安全的 Dart wrapper（M3FogShader、M3ShadowShader…）。0.9.2
光源系統換骨架light system
M3Light / M3DirectionalLight 改用內部 viewer 委派，不再直接繼承 M3Camera——多光源前必須先解開的耦合。0.9.3
點光源全面校準← 這個版本
骨架搭好了，這次輪到點光源本身：衰減公式、輔助線、座標系統的正確性。
// 效能與精度
先解決最基本的問題：距離的平方根
教科書式的點光源衰減，得先開根號算出實際距離，再拿去做反平方——sqrt 在單次呼叫不貴，但乘上場景裡每個像素、每一顆點光源，就開始有感。0.9.3 直接比較距離平方跟半徑平方，省掉開根號；衰減公式也換成 UE4 那套 windowed inverse-square：光源在有效半徑邊界會平滑收斂到 0，不像傳統反平方公式在近距離爆掉、在邊界外也停不下來。
傳統反平方（無邊界）
windowed inverse-square（0.9.3 採用）
// 兩條線都正規化到 d=0 時強度為 1，純比較衰減的「形狀」——傳統反平方在邊界外仍大於 0，windowed 版本會準時收斂到 0
// 除錯輔助線
燈泡跟它的射程，現在分開畫
編輯器裡的光源輔助線工具，原本 drawBulb（燈泡本體）跟 drawHelper（有效範圍球）是綁在一起的邏輯；這次拆開，兩者可以獨立控制是否顯示。場景裡光源一多，只想看射程或只想看燈泡位置時會方便不少。
// 座標正確性
位置跟法線，現在是明確傳進去的
LightFS 裡的點光源計算，更新成接收明確的位置與法向量兩個輸入，並處理物體空間縮放的校正（uInvObjScale）。如果 mesh 做了非等比縮放，點光源的照射方向跟法線計算才不會跟著跑掉。
概念示意 · 非實際原始碼
// before — 隱含依賴外部狀態
vec3 lit = pointLight(worldPos);
// after — 明確傳入位置、法線與物體縮放校正
vec3 lit = pointLight(worldPos, worldNormal, uInvObjScale);
vec3 lit = pointLight(worldPos);
// after — 明確傳入位置、法線與物體縮放校正
vec3 lit = pointLight(worldPos, worldNormal, uInvObjScale);
// 新工具
終於有一支像樣的 logger
在這之前，debug 訊息大概就是散落各處的 debugPrint。lib/src/util/log.dart 現在多了 M3Log，統一處理 debug / info / warning / error / system / highlight 六個層級，帶 ANSI 顏色——終端機裡一眼就能分辨層級。
[DEBUG]M3Log initialized · ANSI: enabled
[INFO]Scene loaded · 5 490 verts
[WARNING]Light count (33) exceeds recommended budget
[ERROR]Texture not found: water_normal_02.png
[SYSTEM]ANGLE backend: Metal · ES 3.0
[HIGHLIGHT]macbear_3d 0.9.3 ready
接下來
這個版本刻意把範圍收窄，只做點光源這一件事——夠小，才敢一次校準這麼多細節。下一步繼續往多光源前進，shadow-per-light 的策略也還在想怎麼決定，才不會之後又要重拆一次介面。
dependencies:
macbear_3d: ^0.9.3
macbear_3d: ^0.9.3
