endset_three_editor 0.10.35 → 0.10.36

package/dist/three/index.d.ts

@@ -8,24 +8,31 @@ import { ScriptItem } from './scriptStore';
  */
 import * as THREE from "three";
 /**
- * 水体（Water.js 水体 / 标准材质水面）在透明队列中的绘制顺序。
+ * 水体（Water.js 水体 / 标准材质水面）在透明队列中的绘制顺序（1 = 最后绘制）。
  *
  * three 渲染器对透明物体按「groupOrder → renderOrder → 相机距离(z 大者先画)」排序，
  * 默认所有物体 renderOrder = 0：此时半透明模型（例如透明度 0.7 的外墙）与水体的
  * 先后完全取决于二者"物体原点"的相机距离。像墙体这种"几何很大、原点却偏离几何中心"
  * 的对象，距离排序会随相机移动而翻转 → 水体随视角时隐时现。
  *
- * 这里给水体一个更小的 renderOrder，让它**恒定在其它半透明模型之前绘制**：
- * 半透明模型（0.7 外墙等）便总是以自身 alpha 混合在"已经画好的水体"之上，
- * 于是墙体与水体重叠的部分、以及不重叠的部分，观感完全一致（都是同一个 0.7）。
- * 反之若让水体最后绘制，水体的像素会盖在墙上，把墙在水体范围内的像素"洗淡"，
- * 出现"只有与水体重叠的那块墙变透明，其余部分还是 0.7"的问题。
+ * ⚠️ 两个半透明面在屏幕上重叠时，像素只能"二选一"（谁后绘制谁就盖在对方之上，
+ *    这是光栅化 alpha 混合的固有取舍），两种取值各有利弊：
+ *
+ *   1（水体最后绘制，当前取值）＝"水体优先"：
+ *     水体保持自身 alpha，看起来清晰完整；
+ *     代价：与水体重叠的半透明模型会被水体的 alpha 压低
+ *          （墙的权重 ≈ 0.7 × (1 - 水体覆盖率)，水体叠两层时约 0.34，叠一层约 0.49）。
+ *
+ *   -1（水体最先绘制）＝"模型优先"：
+ *     半透明模型保持自身 alpha，墙在重叠 / 不重叠处观感一致（都是 0.7）；
+ *     代价：水体像素被模型的 alpha 盖住，重叠处水体会明显变淡甚至看不见
+ *          （墙 0.7 时水体只剩 0.3 × 0.3 ≈ 9%）。
  *
  * 注意：
  * - 只影响透明队列内部的先后，不改变不透明物体的遮挡关系（不透明物体先绘制）；
- * - 水体自身 depthWrite = false，不会把任何物体按深度剔除（不会出现整块消失）。
+ * - 半透明材质统一不写深度，因此不会出现"谁把谁按深度剔除、整块消失"。
  */
-export declare const WATER_RENDER_ORDER = -1;
+export declare const WATER_RENDER_ORDER = 1;
 /**
  * 初始化编辑器，挂载到指定 DOM 容器
  * @param container - 编辑器挂载的 DOM 元素