hilo3d 2.0.0-alpha.8 → 2.0.0-alpha.9

package/CHANGELOG.md

@@ -1,5 +1,148 @@
 # Unreleased
 
+# 2.0.0-alpha.9 (release candidate)
+
+This section describes the prepared release source; npm publication is pending.
+
+### Features
+
+- Add the standalone Hilo Studio scene editor with a Blender-inspired workspace, shared-engine
+  WebGL2/WebGPU viewport, picking, transform gizmos, multi-selection, material and GLB/image asset
+  authoring, prefab overrides, isolated script previews and animation timelines. Include durable
+  multi-scene projects, undo/redo and recovery, versioned JSON/offline schemas and portable AI
+  workspace ZIPs, a self-hosted capability-based collaboration service, and GitHub Pages deployment
+  with production checks for root and project-subpath URLs.
+
+- Add optional `@hilo/addon-audio`: bounded real/virtual voices, spatial attenuation/cones/Doppler,
+  budgeted occlusion, concurrency and weighted cues, hierarchical mixing/snapshots/ducking/reverb,
+  pinned decode caching, media streaming and Stage-owned lifecycle. Include real Chromium PCM,
+  transport/cache tests and installed-tarball streaming validation.
+
+- Add optional `@hilo/addon-assets`: KTX2 ETC1S/UASTC module-worker transcoding, versioned texture
+  leases, cancellation/priority, coarse-first mip residency, independent budgets, hidden-resource
+  eviction and budgeted recovery replay. This is the initial A0 texture slice; geometry pages and
+  sparse HTTP loading remain separate work.
+- Make renderer idle waits snapshot already submitted work so continuous rendering cannot starve
+  asset retirement; preserve complete fence settlement on failure.
+- Add `Renderer.uploadTextures()` for graph-validated, submission-fenced texture warming without
+  draws.
+- Add a texture residency lab and actual compressed texture/package coverage on both backends.
+- Add portable local specular reflection probes with box parallax correction, bounded per-pixel
+  blending and roughness filtering, shared by PBR/clearcoat and SSR fallback composition. Add
+  budgeted HDR dynamic captures with atomic publication, failure rollback and device recovery; the
+  Adjacent gallery demonstrates connected rooms, moving receivers and lighting updates.
+- Add `RenderPipelineContext.recordView()` for isolated auxiliary cameras in the same graph and
+  submission, and runtime-owned `RenderPipelineCreateContext.createRenderTarget()` recipes that
+  rebuild after explicit renderer resource release. Parent leases are suspended during callbacks;
+  nested/async callbacks and caught callback failures cannot produce partial frame submissions.
+
+- Add Live2DModel.load with SDK-independent motion, expression, parameter and effect controls; Stage
+  automatically advances and destroys owned sessions/assets. Add abortable complete loading, shared
+  bounded runtime initialization and explicit asset versioning. Runtime assets are included in the
+  addon and loaded locally on demand; applications need no SDK setup or runtimeUrl configuration.
+- Add portable render-node raster contributions automatically discovered by Forward, and
+  hierarchical transparent sorting groups with matching Camera2D pointer selection.
+- Add an official Hatsune Miku Live2D example with pointer tracking, motion controls and head
+  close-ups, preserved source/license records and an offline example runtime built from separately
+  licensed SDK inputs.
+
+- Add the optional `@hilo/addon-live2d` ESM package: application-owned Cubism source adaptation,
+  model3 assets, portable deforming meshes, basic blending, soft/inverted masks and explicit
+  lifetime. Core/Framework retain their separate licenses; character resources remain external and
+  advanced Cubism 5.3 composition is rejected.
+- Add `RenderPipelineContext.createOrderedRendererList()` for explicit ordered mesh membership,
+  including hidden mask sources and mixed material queues, through shared draw preparation and RHI.
+
+- Expose immutable render-pipeline invocation policies for camera type and per-frame call limits.
+  Forward supports arbitrary cameras and multiple invocations; Clustered declares its existing
+  single-perspective-camera limit. The shared host validates calls before recording and rejects
+  partial-frame submission after a policy violation. Custom factories without a policy retain their
+  previous behavior.
+- Add opt-in WebGPU dynamic diffuse global illumination to Clustered Forward+: camera-independent
+  rigid PBR BVH tracing, budgeted visibility-aware irradiance probes, dynamic lighting, bounded
+  bounce feedback, relocation, transactional history and device recovery. Both indirect and direct
+  clustered PBR sample the same field; hybrid SSGI replaces overlapping transport with a signed
+  correction. Add validated options, contribution control and submitted resource/coverage
+  diagnostics.
+- Add the original Blender-authored Afternoon Atelier, with warm oak and linen furniture, an
+  integrated up/down linen floor lamp, visible wall-color reflection across sofa and rug, dynamic
+  lamp/door/wall controls, live night/day environment changes, public OrbitControls, stable captures
+  and lifecycle-safe teardown.
+
+### Documentation
+
+- Extend the consumer game skill with exact-version audio, KTX2 residency and Live2D guidance. Check
+  synchronized package versions and skill regressions in ordinary CI preflight.
+
+- Separate current engineering/rendering contracts and the roadmap from archived implementation
+  plans. Correct prerelease installation, exposure, temporal, material ABI and SRP guidance.
+- Publish a concise llms.txt and source Markdown with build provenance; add source/anchor/command
+  checks and synchronized public-API recipes verified against packed core/addon packages.
+
+### Changes
+
+- Reserve uniform-block binding 10 for optional local reflection data; custom block allocation now
+  starts at 11. Existing material scalar/texture layouts and material sampler indices are unchanged.
+  Applications using explicit custom binding 10 must select an unreserved binding.
+
+- Keep Live2D build and package verification tooling inside the addon. Remove its obsolete public
+  SDK builder CLI/tools export, optional build-tool peers and unused standalone provider output;
+  examples reuse bundler-emitted runtime assets and copy only their license notices.
+
+- Separate SRP invocation context, resource/history ownership and pass execution, and register
+  built-in preparation adapters at pass construction instead of identifying pass classes in the
+  central setup path. Split Clustered shader, layout and parameter modules from frame orchestration
+  while preserving shader sources and the shared Render Graph/RHI path.
+- Replace quadratic Render Graph ready-pass scans with stable minimum-index heap scheduling and
+  reusable typed-array workspace, preserving existing dependency validation and pass order.
+
+### Fixes
+
+- Normalize ImageBitmap uploads explicitly on WebGL2, preserving row direction and low/zero-alpha
+  RGB bytes through cropping, cube/array uploads and recovery without Canvas2D conversion.
+- Dispatch nested non-Mesh destruction overrides and complete sibling/renderer cleanup after errors.
+
+- Detect native WebGL2 context loss before delayed browser notification, preserve lost queue state
+  through abort cleanup, and keep restoration enabled by preventing the eventual loss event.
+
+- Release final-owner vertex/index and uniform-buffer recipes when meshes are destroyed, while
+  preserving shared geometry aliases, custom UBOs and submission-aware native retirement.
+
+- Bound completed Render Graph transient-resource retention by idle count, estimated bytes and age
+  while preserving in-flight submission ownership and exact-descriptor reuse.
+- Recycle abandoned graph builders after recording/setup failures and reject stale references
+  without retaining every failed frame's parameters and resource providers.
+- Separate content liveness from ordering hazards so unused readers and fully overwritten writes are
+  culled. Preserve load/read-write/partial-clear dependencies and support complete then partial
+  clears of a new transient buffer in one pass.
+- Commit history validity from the final surviving store/discard operations. A discarded current
+  slot becomes invalid without replacing the last stored history.
+- Report timeline observer failures after committed GPU work without rolling back runtime/history
+  state; observe asynchronous diagnostic and runtime callbacks independently from GPU timestamps.
+- Honor `material-front-to-back` using cached view-space depth within opaque state groups, including
+  explicit instance batches. Keep mixed opaque/transparent sorting transitive so opaque entries
+  cannot obstruct transparent depth ordering.
+
+- Stabilize static DDGI with fixed per-probe quadrature, geometry-stable relocation and exact
+  submission-aware light revisions. Correct TAA/TAAU jitter-free history reprojection, neighborhood
+  shading-change detection and depth-checked one-pixel silhouette motion coverage, preventing
+  repeating edge shimmer while retaining camera-cut and moving-object rejection.
+
+- Reject unsupported or rapidly moving SSR missed-hit history, fade confidence-premultiplied
+  radiance together with confidence, and honor zero history weight on every resolve path. This
+  removes red reflection trails on empty floors during fast camera orbit.
+
+- Keep built-in scene vertex positions invariant across depth, motion, material-attributes and color
+  variants, eliminating jitter-dependent attribute holes and flickering SSR black speckles. Remove
+  the red and blue point fill lights that produced circular floor highlights in Afterimage.
+
+- Apply runtime normal-map scale in shared raster shading, restoring smooth Car Concept paint on
+  WebGL2 and WebGPU.
+- Traverse SSR Hi-Z cells conservatively and refine thin-surface crossings before rejecting hits.
+  Keep integer history counts separate from confidence during packing and bilinear reprojection.
+- Refine the Afterimage studio camera, paint, lighting, and polished floor reflection; fit portrait
+  viewports and cap physical rendering dimensions to the declared GPU budget.
+
 # 2.0.0-alpha.8 (2026-09-08)
 
 ### Breaking changes

package/README.md

@@ -24,7 +24,9 @@
 </div>
 
 > Hilo3D 2.0 is currently in alpha. Existing projects should review the
-> [breaking changes](./CHANGELOG.md#breaking-changes) before upgrading.
+> [breaking changes](./CHANGELOG.md#breaking-changes) before upgrading. Repository and website
+> documentation may include Unreleased APIs; match [version boundaries](./documentation/VERSIONS.md)
+> to the installed package.
 
 ## Why Hilo3D
 
@@ -50,9 +52,14 @@ WebGPU path or a production WebGL 2 compatibility path.
 ## Install
 
 ```sh
-npm install hilo3d
+npm install --save-exact hilo3d@next
 ```
 
+`next` selects the 2.0 prerelease; `--save-exact` pins the resolved version. The unqualified
+`latest` channel may still select 1.x. Match optional addon versions to the installed core. See
+[version boundaries](./documentation/VERSIONS.md) and the
+[complete quickstart](./documentation/GETTING_STARTED.md).
+
 Hilo3D is ESM-only. It targets modern browsers with WebGPU or WebGL 2; WebGL 1 and legacy global
 builds are outside the 2.0 contract.
 
@@ -85,11 +92,19 @@ const stage = await Hilo3d.Stage.create({
 new Hilo3d.Mesh({
     geometry: new Hilo3d.BoxGeometry(),
     material: new Hilo3d.PBRMaterial({
-        baseColor: new Hilo3d.Color(0.83, 0.12, 0.09)
+        baseColor: new Hilo3d.Color(0.83, 0.12, 0.09),
+        metallic: 0.1,
+        roughness: 0.6
     })
 }).addTo(stage);
 
 stage.addChild(new Hilo3d.AmbientLight({ amount: 1 }));
+stage.addChild(
+    new Hilo3d.DirectionalLight({
+        amount: 3,
+        direction: new Hilo3d.Vector3(-1, -1, -1)
+    })
+);
 
 const ticker = new Hilo3d.Ticker(60);
 ticker.addTick(stage);
@@ -188,6 +203,11 @@ resource, shader, and recovery contracts.
 
 ## Documentation
 
+- [Getting started](./documentation/GETTING_STARTED.md) and
+  [checked recipes](./documentation/RECIPES.md)
+- [AI documentation index](./llms.txt) and [version policy](./documentation/VERSIONS.md)
+- [Roadmap](./documentation/ROADMAP.md)
+
 - [Getting started and API documentation](https://hilo3d.js.org/docs/)
 - [Example gallery](https://hilo3d.js.org/examples/list.html)
 - [`hilo3d-game` Agent Skill](https://github.com/hiloteam/Hilo3d/tree/dev/skills/hilo3d-game)
@@ -195,13 +215,13 @@ resource, shader, and recovery contracts.
 - [Rendering architecture](./documentation/RENDERING_ARCHITECTURE.md)
 - [PBR, HDR, and post-processing](./documentation/PBR_AND_POST_PROCESSING.md)
 - [Modern WebGPU rendering roadmap](./documentation/MODERN_WEBGPU_RENDERING_ROADMAP.md)
-- [Material system modernization](./documentation/MATERIAL_SYSTEM_MODERNIZATION.md)
-- [Temporal rendering](./documentation/TEMPORAL_RENDERING_REMEDIATION.md)
+- [Material system](./documentation/MATERIAL_SYSTEM.md)
+- [Temporal rendering](./documentation/TEMPORAL_RENDERING.md)
 - [Screen-space global illumination](./documentation/SCREEN_SPACE_GLOBAL_ILLUMINATION.md)
 - [Froxel volumetric lighting](./documentation/VOLUMETRIC_LIGHTING.md)
 - [Physical atmosphere and weather](./documentation/PHYSICAL_ATMOSPHERE_AND_WEATHER.md)
 - [2D rendering and multi-camera composition](./documentation/2D_RENDERING.md)
-- [Scriptable render pipeline](./documentation/SCRIPTABLE_RENDER_PIPELINE_PLAN.md)
+- [Scriptable render pipeline](./documentation/SCRIPTABLE_RENDER_PIPELINE.md)
 - [Breaking changes](./CHANGELOG.md#breaking-changes)
 
 ## Develop locally

package/README_ZH.md

@@ -26,6 +26,9 @@
 > Hilo3D 2.0 目前处于 alpha 阶段。现有项目升级前应先查看
 > [破坏性变更](./CHANGELOG.md#breaking-changes)。
 
+源码与网站文档可能包含 Unreleased API；请按 [版本边界](./documentation/VERSIONS.md)
+核对已安装包的类型声明。
+
 ## 为什么选择 Hilo3D
 
 Hilo3D 在同一引擎中兼顾高层场景创作和底层 GPU 控制。应用始终使用同一套场景、材质、渲染目标与 shader 契约，渲染器则选择原生 WebGPU 路径或生产级 WebGL
@@ -49,9 +52,15 @@ Hilo3D 在同一引擎中兼顾高层场景创作和底层 GPU 控制。应用
 ## 安装
 
 ```sh
-npm install hilo3d
+npm install --save-exact hilo3d@next
 ```
 
+`next` 选择 2.0 预发布版本，`--save-exact`
+锁定解析后的版本；不带 tag 的安装可能仍选择 1.x。可选 addon 必须与核心版本一致。参阅
+[版本边界](./documentation/VERSIONS.md)、
+[完整快速开始](./documentation/GETTING_STARTED.md)、[可编译 recipes](./documentation/RECIPES.md) 和
+[AI 文档索引](./llms.txt)。
+
 Hilo3D 只提供 ESM。目标环境是支持 WebGPU 或 WebGL 2 的现代浏览器；WebGL
 1 和旧式全局构建不属于 2.0 契约。
 
@@ -82,11 +91,19 @@ const stage = await Hilo3d.Stage.create({
 new Hilo3d.Mesh({
     geometry: new Hilo3d.BoxGeometry(),
     material: new Hilo3d.PBRMaterial({
-        baseColor: new Hilo3d.Color(0.83, 0.12, 0.09)
+        baseColor: new Hilo3d.Color(0.83, 0.12, 0.09),
+        metallic: 0.1,
+        roughness: 0.6
     })
 }).addTo(stage);
 
 stage.addChild(new Hilo3d.AmbientLight({ amount: 1 }));
+stage.addChild(
+    new Hilo3d.DirectionalLight({
+        amount: 3,
+        direction: new Hilo3d.Vector3(-1, -1, -1)
+    })
+);
 
 const ticker = new Hilo3d.Ticker(60);
 ticker.addTick(stage);
@@ -187,13 +204,13 @@ compute 使用引擎经过验证的 `ComputeShader` 契约。
 - [渲染架构](./documentation/RENDERING_ARCHITECTURE.md)
 - [PBR、HDR 与后处理](./documentation/PBR_AND_POST_PROCESSING.md)
 - [现代 WebGPU 渲染路线图](./documentation/MODERN_WEBGPU_RENDERING_ROADMAP.md)
-- [材质系统现代化](./documentation/MATERIAL_SYSTEM_MODERNIZATION.md)
-- [时域渲染](./documentation/TEMPORAL_RENDERING_REMEDIATION.md)
+- [材质系统现代化](./documentation/MATERIAL_SYSTEM.md)
+- [时域渲染](./documentation/TEMPORAL_RENDERING.md)
 - [屏幕空间全局光照](./documentation/SCREEN_SPACE_GLOBAL_ILLUMINATION.md)
 - [Froxel 体积光](./documentation/VOLUMETRIC_LIGHTING.md)
 - [物理大气与天气](./documentation/PHYSICAL_ATMOSPHERE_AND_WEATHER.md)
 - [2D 渲染与多相机合成](./documentation/2D_RENDERING.md)
-- [可脚本化渲染管线](./documentation/SCRIPTABLE_RENDER_PIPELINE_PLAN.md)
+- [可脚本化渲染管线](./documentation/SCRIPTABLE_RENDER_PIPELINE.md)
 - [破坏性变更](./CHANGELOG.md#breaking-changes)
 
 ## 本地开发