Compare commits

...

48 Commits

Author SHA1 Message Date
zxx43 b01aabdf57 add .meta for particle_normal.chunk (#436) 2026-11-19 11:14:12 +08:00
ChiaNing 7995924100 fix(2d): preserve simple font aliases in canvas descriptors (#428)
* fix(2d): preserve simple font aliases in canvas descriptors

Use bare identifiers for simple generated _LABEL aliases in Label rendering and Web font loading. Keep quoting and escaping complex family names, and preserve system font expressions.

* test(2d): cover font aliases from Web registration to Label descriptors
2026-11-18 18:37:21 +08:00
ChiaNing af2b9e9ed9 fix(2d): apply cascaded opacity to retained Graphics draws (#421)
* fix(2d): apply cascaded opacity to retained Graphics draws

Use the per-instance Graphics effect on Web and Native so a parent fade scales the original fill and stroke alpha at draw time. Rebind retained geometry when its material changes and synchronize Graphics color on enable or assignment. Covers the Graphics behavior reported in #14868 and #17917.

* fix(2d): apply Graphics cascade opacity to CPU vertex colors

* fix(2d): preserve wide strokes and reuse Graphics opacity buffers

Reserve stroke vertices using the emitted caps and joins and split at independent subpath boundaries. Reuse Web upload storage across immediate redraws and use the shared draw-info dirty bit to synchronize only changed Native geometry blocks. Release empty caches on the subsequent renderer update or disable.

* fix(2d): handle passless Graphics materials and release empty paint buffers

* fix(2d): scope Graphics opacity updates and trim unused buffers

* fix(2d): limit the Graphics change to cascaded opacity

* fix(2d): preserve Graphics.color behavior during parent opacity fades

* fix(2d): use emitted Graphics counts for native opacity uploads
2026-11-18 18:30:48 +08:00
Ming 229ad74757 Fix/rendering/per pass ubo upload (#432)
* fix(rendering): track UBO upload state per buffer and isolate layout UBO state

* fix(rendering): deduplicate bound UBO buffers and release on pipeline destroy

* refactor(rendering): simplify per-pass UBO helpers and reduce bundle size

---------

Co-authored-by: vanitynie <vanitynie@qq.com>
2026-11-18 18:12:23 +08:00
yangchao 5313b86ed1 feat: expose screen keep-on control (#413) 2026-11-18 17:28:15 +08:00
zxx43 7fb5ae075b Particle normal map (#418)
* add particle normal map support

* add meta file

* fix shader error

* add render pass

* remove warn when set particle texture

* fix shader define bug

* revert default material

* revert material

* do not need new material

* do not add new effect

* revert chunk

* rename ApplyParticleNormalLighting function

* fix switch render mode bug
2026-11-18 12:31:21 +08:00
Cocos Robot 1b0455e10e Merge pull request #426 from cocos-robot/t/bot/genbindings-714bd9d
[ci skip][AUTO]: Automated PR to generate code
2026-11-16 16:59:23 +08:00
hyde zhou 714bd9d3e2 Merge pull request #422 from cocos/v4.0.0-beta.2
fix(input): restore mouse-to-touch simulation in Game View (#419)
2026-11-16 16:49:39 +08:00
hyde zhou 6ccf1cf9a8 Reapply "Feat/plugin support, allow third_party feat(spine) to create plugin f…" (#403) (#424)
This reverts commit 5bcfb9fa04.
2026-11-16 16:33:05 +08:00
Cocos Robot 1df519e248 [ci skip][AUTO]: Automated clang-format update: 81c80668ca (#417) (#423)
Co-authored-by: cocos-robot <cocos-robot@cocos.com>
2026-11-16 16:30:33 +08:00
hyde zhou aaa3a9168b add CUSTOM residency type (#417)
* add CUSTOM residency type

* revert settings
2026-11-16 12:08:06 +08:00
qiuguohua 178b9edca9 fix(input): restore mouse-to-touch simulation in Game View (#419) 2026-11-13 16:19:26 +08:00
qiuguohua 8e62e7e044 fix(input): restore mouse-to-touch simulation in Game View (#416) 2026-11-13 15:12:42 +08:00
Tianze-Chen 62bd937e7e fix(ui): convert viewport sizes with the exact scale ratio (#405)
`View.setDesignResolutionSize` regenerated the visible size with
`viewport / scale`. Because `scale` is itself the rounded `container / design`
quotient, that round trip loses one ULP: a 1080x1920 design on a 1532x1532
viewport produces `1919.9999999999998` instead of `1920`.

Those values are written by `Widget` into `UITransform._contentSize` and
`Node._lpos`, and by `Canvas` into `Camera._orthoHeight`, so the error ends up
in the saved `.scene`/`.prefab` files and makes the editor produce diff churn
whenever it recomputes the layout.

A resolution policy now reports the pair of lengths its scale was derived from
(`pixels`: the container length in device pixels, `units`: the same length in
UI units) instead of the rounded scale, and the viewport is converted with
those two lengths. EXACT_FIT, SHOW_ALL, NO_BORDER, FIXED_HEIGHT and FIXED_WIDTH
all report their pair in place.

The scale is no longer stored anywhere: `AdaptResult` carries `ratioX` /
`ratioY` only, and `getScaleX()` / `getScaleY()` derive `pixels / units` on
demand, so the ratio and the scale cannot diverge.

`toUISpace()` / `toPixelSpace()` are exported next to `ScaleRatio`, and
`View.getRatioX()` / `View.getRatioY()` expose the pair, so any caller can
convert lengths without the lossy `pixels / scale` round trip.

The camera still frames the whole window (`windowSize.height / scaleY / 2`),
but now converts through `toUISpace(size.height, view.getRatioY())`, so a
1532px tall viewport produces exactly 960 instead of 959.9999999999999. No
adaptation, layout or rendering semantics change.

Note for custom resolution policies: `AdaptResult` no longer carries `scale`.
A custom content strategy has to report `ratioX` / `ratioY`; when it does not,
the ratios of the previous policy application are kept and the scale is not
updated. `AdaptResult` and `ContentStrategy` are engine-private classes, so
this only affects strategies passed to `new ResolutionPolicy(...)`.

Co-authored-by: Tianze-Chen <tianze@local>
2026-11-13 11:00:11 +08:00
qiuguohua 990e3b09aa fix: handle oversized native callback arguments (#409) 2026-11-12 10:49:03 +08:00
llsansun 111fe1755d Origin/bugfix (#408)
* The final `set skeleton` call destroys and rebuilds the GPU bone resources that were bound in the previous two steps. However, the descriptor set is not rebound. As a result, the draw call for this subModel cannot access the bone matrices, so the entire character fails to render (this is not vertex deformation; the character does not appear at all). The fix should replace the reference in `descriptor.buffer` with the new buffer, mark it dirty, and lazily rebuild the descriptor before the next draw.

* opt

* fix: retain negative scale signs in Node.setWorldScale

* test: retain negative scale signs in Node.setWorldScale

* fix
2026-11-12 09:48:55 +08:00
zxx43 4a0dbc977a fix get angle problem (#399)
* fix get angle problem

* fix eslint

* use new function to get angle

* fix eslint error
2026-11-11 16:04:02 +08:00
zxx43 7037052b40 optimize trail (#402)
* optimize trail

* do not create at runtime

* do not draw if resize failed
2026-11-11 14:17:28 +08:00
Ming e78ad4d759 fix(rendering): 修复 addShadingRateTexture 重复注册时的无限递归 (#406)
同名资源已存在时调用 updateShadingRateTexture 更新尺寸,保留资源 ID 和资源数量。

Co-authored-by: vanitynie <vanitynie@qq.com>
2026-11-10 18:43:19 +08:00
hyde zhou 25026f9edd bump version to 4.0.0-beta.2 (#404) 2026-11-10 17:16:48 +08:00
hyde zhou 5bcfb9fa04 Revert "Feat/plugin support, allow third_party feat(spine) to create plugin f…" (#403)
This reverts commit a56706c9ad.
2026-11-10 17:04:32 +08:00
Tianze-Chen a56706c9ad Feat/plugin support, allow third_party feat(spine) to create plugin for creator. (#306)
* Add UIMesh component for custom 2D mesh rendering

- Add UIMesh component consuming pre-baked vertex/index/segment data, enabling custom renderers (e.g. spine plugin) to batch through the 2D batcher.
- Export UIMesh from the 2d components index.
- Validate setMeshData input at the boundary (stride, buffer lengths, index values, segment ranges, accessor caps) via engine-standard errorIDs 9010-9017, documented in EngineErrorMap.md.
- Expose StaticVBAccessor per-chunk caps as maxVertexCount/maxIndexCount getters and clamp the 10% reserve to them, so meshes that fit (e.g. 30000 vertices) allocate instead of silently failing.
- Add tests/ui/ui-mesh.test.ts covering the 32767 cap boundary, setMeshData validation, and accessor lifetime.

Also takes over node transform and cascaded opacity: vertices are now always
node-local — UIMesh applies the node's world matrix (unbatched via the
per-draw GPU transform the 2D batcher already maintains for middleware,
batched by baking into the shared chunk copy so draws still merge) and folds
the cascaded UIOpacity into the copied vertex colors itself. The legacy
switches (USE_LOCAL / useLocalData / RenderEntity.setUseLocal) are all derived
internally; consumers never touch them. A JSB staleness poll re-prepares the
native draw infos in the same frame on transform/opacity changes, and a
premultipliedAlpha format declaration drives the opacity fold and the builtin
material's blend factors.

Follow-ups folded in: the opacity fold reads the light color at byte offset 20
(the pos*3f + uv*2f header is 20 bytes), not 16; and UIMesh notifies data
producers through the new onPremultipliedAlphaChanged() hook so subclasses
(e.g. the spine plugin) forward the declared format to their baker instead of
redeclaring the field.

Co-Authored-By: Claude Code <noreply@anthropic.com>

* Disable built-in spine by default; minor editor/build fixes

- Default the built-in Spine feature (spine-3.8) to off in feature cropping, so it is only included when enabled in the editor.
- Recognize scale as a valid spine atlas page attribute in the texture inspector.
- Skip incomplete platform dirs when bundling runtime adapters.

Co-Authored-By: Claude <noreply@anthropic.com>
(cherry picked from commit 7f7922aaf42ff1857f0a6d38970a75d303032f57)

* Export WebAssembly interface under cc.wasm namespace

- Add exports/webassembly.ts re-exporting pal/wasm (instantiateWasm, fetchBuffer, fetchUrl, ensureWasmModuleReady) as the public cc.wasm namespace, so extensions/game code can load their own .wasm files through the engine's platform-adaptive path.
- Expose it as a croppable feature rather than an unconditional export from exports/base.ts: cc.config.json declares a `webassembly` feature and editor/engine-features/render-config.json adds the panel entry (default on, required), so it appears under Project Settings -> Feature Cropping. The label/description are plain text on purpose — i18n:ENGINE.* keys live in the editor package and a custom engine cannot add them.

(cherry picked from commit 92003ab4a21b6ee753cf3ba2ca0f4767658e9cdc)

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* feat(simulator): generic native plugin discovery opt-in

The generic plugin discovery chain (cc_gen_plugin_cmake_hook ->
plugins_parser.js -> Pre-AutoLoadPlulgins.cmake -> find_package ->
plugin_registry) already exists and is what native device builds use; the
simulator never invoked it. Wire it in behind an opt-in cache variable, with
no plugin names or plugin logic in the engine — the plugin set is always just
the scan result:

- templates/cmake/common.cmake: cc_gen_plugin_cmake_hook()'s scan roots
  (CC_PLUGIN_PATH) may now be pre-set by the caller; the native-build
  project-layout defaults are unchanged when nobody pre-defines it
- simulator runtime-src CMakeLists.txt: -DSIMULATOR_PLUGIN_SCAN_DIRS="<dir>
  [;<dir>]" scans those roots for cc_plugin.json through the same chain as
  device builds (CC_PROJECT_DIR points into the build tree so the generated
  hook lands there, satisfying the parser's output-dir invariant); unset
  keeps the stock plugin-less simulator, and a cache variable means plain
  `cmake --build` reuses the configured scan
- simulator Game.cpp: call cc_load_all_plugins() after init, mirroring
  BaseGame::init(), so registered plugins' JSB bindings exist before any
  script runs (no-op when no plugins are linked)
- libsimulator protobuf config.h: skip the <hash_map>/<hash_set> defines on
  MSVC >= 1950 (headers removed); stubs fall back to the std::map emulation
  path

Verified end-to-end: a project extensions/ tree scanned at configure time
produces a simulator exe whose plugins register their JSB bindings at startup
(observed live in the simulator's JS context).

Co-Authored-By: Claude Code <noreply@anthropic.com>

---------

Co-authored-by: Developer <developer@cocos.com>
Co-authored-by: Claude Code <noreply@anthropic.com>
Co-authored-by: Engineer <engineer@cocos.com>
2026-11-04 16:41:54 +08:00
Cocos Robot 022be418f9 [ci skip][AUTO]: Automated clang-format update: 9d12fd846b (#390) (#392)
Co-authored-by: cocos-robot <cocos-robot@cocos.com>
2026-11-04 15:05:56 +08:00
Zachary Alexander 86fe5f41cd ci: run the native Linux, OpenHarmony and ClangTidy jobs on ubuntu-24.04 (#398)
ubuntu-latest is moving to Ubuntu 26.04, and three native jobs fail
there for reasons outside the engine change under test: GCC 15 no
longer pulls <cstdint> and <algorithm> into EventBus.h/.cpp, 7-Zip 26
refuses the OH SDK archive's relative symlinks, and python3.8 from the
deadsnakes PPA has no candidate for the runner's amd64v3 apt index.
Run those three jobs on ubuntu-24.04, where all three passed on
2026-10-28. The Android, Windows, macOS and iOS jobs are unchanged.
2026-11-04 11:02:54 +08:00
zxx43 a69be8d0a7 add AlignToDirection implement (#394)
* add AlignToDirection implement

* fix eslint

* fix max line error

* fix ParticleSpace world condition
2026-11-03 11:45:39 +08:00
llsansun b9f9e95b9b up (#395) 2026-11-02 14:45:04 +08:00
Cocos Robot 7ef2d0a772 [ci skip][AUTO]: Automated code generating update: 9031c05b96 (#389) (#390)
Co-authored-by: cocos-robot <cocos-robot@cocos.com>
2026-10-30 19:31:26 +08:00
Cocos Robot fcdc4333b7 [ci skip][AUTO]: Automated code generating update: 926ed1a9ad (#322) (#388)
Co-authored-by: cocos-robot <cocos-robot@cocos.com>
2026-10-30 19:30:36 +08:00
Ming 60a24625b2 fix(webgl): sync buffer size with actual GL BUFFER_SIZE on resize (#389)
* fix(webgl): sync buffer size with actual GL BUFFER_SIZE on resize

* fix(webgl): move buffer update size check to CmdFuncUpdateBuffer

* fix(webgl): add buffer resize failure warning and fallback strategy

* fix(2d): guard MeshBuffer upload and IA draw when buffer resize fails

* fix(gfx): update EmptyBuffer size on resize for unit tests

---------

Co-authored-by: vanitynie <vanitynie@qq.com>
2026-10-30 17:39:22 +08:00
llsansun 2157fd176d Multithreading (#322)
* worker pool

* opt

* backup

* worker and worker backend

* worker fallback

* opt

* opt

* remove meta

* opt

* worker export

* testcase fix

* worker js template

* worker pal

* worker opt

* test

* Replace error messages with error codes

* Package size reduction

* Package size reduction

* revert

* Restore editor asset .meta files to the base branch state

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014HAtWwr4dy5azfpccweh1g

* bugfix

* Split into two features: Worker and Worker Pool

* worker option

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 16:35:14 +08:00
MagicX 5e627951a0 fix(render-texture): use GPU max texture size instead of 2048. (#385)
* Changed the GeometryRenderer and DebugRenderer from using intrusive calls to registering callbacks (custom pipeline).

* Changed the GeometryRenderer and DebugRenderer from using intrusive calls to registering callbacks. (old pipeline)

* CI error: Function parameter names cannot be omitted.

* Move the devil string to macro

* fix(mesh): hoose index format by max index value in createMesh

* perf(pipeline): reduce render queue sort to two packed key compares (native platform).

* fix CI error caused by native/cocos/base/Utils.h

* fix(scene): LOD screen usage distance truncated to int (native platform)

* fix: prevent accessor recursion in SkinnedMeshBatchRenderer.

* fix: destroy index buffer in MeshRenderData.clear() to prevent GPU leak.

* fix: use GPU max texture size for render texture resizing.
2026-10-28 18:00:11 +08:00
ChiaNing 2c632d6dd6 fix(2d): serialize custom font families and restore native font aliases (#382)
* refactor(2d): share font family and descriptor helpers

Extract the existing TTF and CHAR font family selection and font description
construction into shared helpers. Preserve raw family values, the Arial
fallback, and the existing size and style formatting.

* fix(2d): serialize custom font families at CSS boundaries

Quote and escape raw custom font names before Canvas and DOM consumption,
while preserving system family expressions. Keep Web-loaded aliases raw
and share the serialized expression across registration and loading.

Carry CssFontFamily through Label consumers and cover serialization,
TTF/CHAR selection, EditBox styles, and Web FontFaceSet loading in tests.

* fix(2d): preserve font names during scaling and refresh load metrics

Build CHAR draw descriptors from the scaled size and serialized family,
so unit-like substrings in font names are not rewritten by scaling.

Set the font before baseline measurement and read live Canvas metrics
during Web font polling instead of reusing cached fallback widths.
Add regression tests for the actual CHAR draw path and load completion.

* refactor(native): extract canvas font parsing

Move the existing platform-specific parsing into an internal helper and
return the family, size, and style flags to CanvasRenderingContext2D.
Preserve the existing matching rules, conversions, fallbacks, and update order.

Validated 12,650 comparisons with the original setFont implementation
across five platform macro variants.

* fix(native): restore serialized font aliases within legacy policy

Decode a single quoted CSS family into the descriptor used before TS
serialization. Adopt the result only when the existing platform parser
recognizes the complete registered alias; retain legacy fallbacks otherwise.

Cover existing aliases, escaped encodings, platform name restrictions,
style and size policies, and malformed inputs without expanding font support.

* fix(native): preserve size when a quoted font name falls back

Keep a valid requested px size when a well-formed quoted font family is
rejected on Apple or QNX, while retaining the existing fallback font and
style flags. Leave malformed prefixes, lists, and unsafe sizes unchanged.

Preserve the existing size conversion on other native platforms.

* fix(2d): resolve font family types in bundled declarations

* test(2d): cover explicit native font alias compatibility

* fix(2d): resolve font CI lint diagnostics

Allow implicit move of the native font parsing result and wrap EditBox placeholder CSS without changing its output.

Validation: targeted clang-tidy check, ESLint with zero warnings, 13 native parser tests, and 2062 font policy comparisons.
2026-10-27 10:06:11 +08:00
qiuguohua 4f6479f083 fix(input): avoid duplicate WeChat touch events (#381)
* fix(input): avoid duplicate WeChat touch events

* update pal version

* update pal version
2026-10-23 19:11:29 +08:00
Cocos Robot 142c7ec6aa [ci skip][AUTO]: Automated code generating update: c6af33ac9d (#373) (#378)
Co-authored-by: cocos-robot <cocos-robot@cocos.com>
2026-10-23 15:10:26 +08:00
MagicX 7302715a18 fix: destroy index buffer in MeshRenderData.clear() to prevent GPU leak. (#379)
* Changed the GeometryRenderer and DebugRenderer from using intrusive calls to registering callbacks (custom pipeline).

* Changed the GeometryRenderer and DebugRenderer from using intrusive calls to registering callbacks. (old pipeline)

* CI error: Function parameter names cannot be omitted.

* Move the devil string to macro

* fix(mesh): hoose index format by max index value in createMesh

* perf(pipeline): reduce render queue sort to two packed key compares (native platform).

* fix CI error caused by native/cocos/base/Utils.h

* fix(scene): LOD screen usage distance truncated to int (native platform)

* fix: prevent accessor recursion in SkinnedMeshBatchRenderer.

* fix: destroy index buffer in MeshRenderData.clear() to prevent GPU leak.
2026-10-23 15:08:39 +08:00
Cocos Robot 5b0b4522c0 [ci skip][AUTO]: Automated code generating update: 363f009a13 (#367) (#375)
Co-authored-by: cocos-robot <cocos-robot@cocos.com>
2026-10-23 11:26:07 +08:00
Tianze-Chen a803406ef1 fix(2d): allocate Graphics GPU buffers on demand (#373)
Every Graphics sub-model pre-allocated a 65536-vertex / 131072-index buffer, which is about 2.25 MiB with the 32-byte graphics vertex, while a rect or ellipse mask only needs a few hundred bytes. The cost accumulates with every mask that draws its own geometry.

Allocate the buffers from the chunk data when the sub-model is created, grow them by powers of two when the geometry outgrows them, and never shrink, so a dynamic graphic no longer re-creates its GPU buffer every frame.

Keep the ceiling at the uint16 addressable limit of 65536 vertices. The assembler does not split a single fill()/stroke() batch, so a batch of exactly 65536 vertices has to fit; capping the buffer at 65535 would upload 32 bytes past its end.

UIModelProxy used to resize the buffers to the exact data size on every upload, which re-created them whenever the geometry changed, and on Metal/Vulkan the old buffer stays alive until the GPU is done with it. It now follows the same grow-only policy and passes the valid size to update() explicitly.

Refs: cocos/cocos4#371

Co-authored-by: Engineer <engineer@cocos.com>
2026-10-23 11:23:29 +08:00
ChiaNing f570c1f02d feat(screen): configure Web DPR through startup settings (#367)
* feat(pal): declare startup maximum DPR configuration

Add an optional maximum DPR to screen initialization and readonly access to
the original DPR and explicitly configured cap. An omitted or null cap retains
the platform's existing policy.

This is the engine type contract for the staged PAL implementation. Public
Screen configuration methods and Native render-target integration remain
separate work; this commit does not change runtime rendering.

Validated against the PAL engine/four-platform contract check and full npm test
(65 source tests, 4 build tests, release/debug module validation).

* feat(screen): expose startup maximum DPR configuration

Allow applications to set, reset and read a pending maximum DPR before Screen
initialization while preserving platform defaults when unconfigured. Lock the
configuration at initialization and reject unsupported PAL implementations or
options that PAL silently ignores.

Add startup validation and compatibility tests. Only implementation and tests
are included; local documentation and generated validation artifacts remain
outside this commit.

Companion PAL commit: 2959778b7acf83dd84e3aab5957d60d80e20c461.
Native render-target integration, device acceptance, runtime changes and editor
configuration remain separate work.

Validation recorded on 2026-09-29: tsc --noEmit; 20 Screen and 6 View tests;
public declaration generation; real WebGL demo with simulated host DPR,
first-draw, input, reset, late-call rejection and resize checks. Screen source
SHA-256 still matches that verified build.

* fix(screen): restrict startup DPR configuration to Web

* fix(screen): ignore DPR cap calls on non-Web platforms

* fix(screen): preserve optional DPR types in native builds

* refactor(screen): configure Web DPR through startup settings

* refactor(screen): delegate DPR policy and validation to PAL

* style(screen): wrap fullscreen method signatures

* perf(screen): simplify startup DPR null checks

* version update
2026-10-22 19:15:17 +08:00
Cocos Robot d0a696cfe6 [ci skip][AUTO]: Automated code generating update: 996f2fe20a (#369) (#370)
Co-authored-by: cocos-robot <cocos-robot@cocos.com>
2026-10-19 14:31:30 +08:00
hyde zhou 1b3ad36e4b bump version to 4.0.0-beta.0 (#369) 2026-10-19 14:15:15 +08:00
llsansun ff0f46ff81 engine upgrade (#368) 2026-10-12 17:42:54 +08:00
yangchao 0616a948ef fix(audio): iterator invalidation、exit crash issue。 (#360)
* fix(audio): iterator invalidation when call stopall in finish callback

* fix(audio): prevent callback crashes and cache teardown hangs on Apple platforms

---------

Co-authored-by: yangchao <1162486779@qq.com>
2026-09-24 11:25:09 +08:00
yangchao ee89a99a9b fix(v8): fix iterator invalidation when removing handled promises (#357)
* fix(v8): fix iterator invalidation when removing handled promises

* fix(native): prevent iterator invalidation in callbacks and scheduler
2026-09-23 16:28:56 +08:00
llsansun f620989ce7 The final set skeleton call destroys and rebuilds the GPU bone reso… (#359)
* The final `set skeleton` call destroys and rebuilds the GPU bone resources that were bound in the previous two steps. However, the descriptor set is not rebound. As a result, the draw call for this subModel cannot access the bone matrices, so the entire character fails to render (this is not vertex deformation; the character does not appear at all). The fix should replace the reference in `descriptor.buffer` with the new buffer, mark it dirty, and lazily rebuild the descriptor before the next draw.

* opt
2026-09-23 16:18:03 +08:00
jk20012001 661de759ef fix(shader): HDR output for all floating point render targets (#351) 2026-09-22 11:50:47 +08:00
Tianze-Chen 0ab8246486 feat(ui): add component-level event API for Button (#356)
Add `on`/`off`/`targetOff` shorthands on Button that forward to the
owner node's event registry, so `button.on(Button.EventType.CLICK, ...)`
is now the documented way to listen for clicks in code (closes #104).

The CLICK event also carries the original EventTouch as the second
callback argument (non-breaking; XR-triggered clicks pass undefined).
Fix the outdated class doc example which referenced the non-existent
`Node.EventType.CLICK`, and correct the swapped `@param` docs on
ButtonEventType.

Co-authored-by: Engineer <engineer@cocos.com>
Co-authored-by: Claude Code <noreply@anthropic.com>
2026-09-22 10:21:20 +08:00
zxx43 67642997f7 modify emit rate (#352)
* modify emit rate

* fix eslint

* fix eslint

* fix eslint

* fix
2026-09-21 17:07:35 +08:00
MagicX 3be9ebc5b7 fix: prevent accessor recursion in SkinnedMeshBatchRenderer. (#354)
* Changed the GeometryRenderer and DebugRenderer from using intrusive calls to registering callbacks (custom pipeline).

* Changed the GeometryRenderer and DebugRenderer from using intrusive calls to registering callbacks. (old pipeline)

* CI error: Function parameter names cannot be omitted.

* Move the devil string to macro

* fix(mesh): hoose index format by max index value in createMesh

* perf(pipeline): reduce render queue sort to two packed key compares (native platform).

* fix CI error caused by native/cocos/base/Utils.h

* fix(scene): LOD screen usage distance truncated to int (native platform)

* fix: prevent accessor recursion in SkinnedMeshBatchRenderer.
2026-09-21 10:27:35 +08:00
160 changed files with 10481 additions and 711 deletions
+1 -1
View File
@@ -17,7 +17,7 @@ jobs:
name: "Linux-Ubuntu"
if:
(! contains(github.event.pull_request.body, '[X] does not change any runtime related code or build configuration'))
runs-on: ubuntu-latest
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v4
- name: Download external libraries
@@ -255,7 +255,7 @@ jobs:
name: "Openharmony"
if:
(! contains(github.event.pull_request.body, '[X] does not change any runtime related code or build configuration'))
runs-on: ubuntu-latest
runs-on: ubuntu-24.04
strategy:
fail-fast: false
matrix:
+1 -1
View File
@@ -20,7 +20,7 @@ jobs:
# Set the type of machine to run on
if:
(! contains(github.event.pull_request.body, '[X] does not change any runtime related code or build configuration'))
runs-on: ubuntu-latest
runs-on: ubuntu-24.04
steps:
# Checks out a copy of your repository on the ubuntu-latest machine
+1
View File
@@ -26,6 +26,7 @@ declare namespace jsb {
export function getDeviceOrientation(): number;
export function getNetworkType(): number; // TODO: enum type
export function getSafeAreaEdge(): NativeSafeAreaEdge;
export function setKeepScreenOn(enabled: boolean): void;
export function setAccelerometerEnabled(isEnabled: boolean);
export function setAccelerometerInterval(intervalInSeconds: number);
+83
View File
@@ -37,6 +37,38 @@ declare module 'pal/minigame' {
getSharedCanvas(): any;
getOpenDataContext(): any;
// worker
/**
* Create a worker thread from a packaged script path.
*
* IMPORTANT — this is optional and genuinely absent on some platforms:
* - Present: WeChat (`wx.createWorker`), ByteDance (`tt.createWorker`), Alipay
* (`my.createWorker`), Baidu (`swan.createWorker`, base library 1.6.1+), and the
* quick-game family (`qg.createWorker` on Xiaomi / Huawei 1117+ / OPPO / vivo).
* Each `pal/minigame/*.js` adapter starts with `cloneObject(minigame, <platformGlobal>)`,
* and `cloneObject` copies functions with `.bind(origin)` — so `createWorker` arrives on
* `minigame` for free, already bound to the right global. No per-platform adapter code
* is needed, and `pal/` itself must not be edited (it is regenerated from the
* `@cocos/engine-pal` package on postinstall).
* - Absent: Taobao mini-game has NO worker API at all (its API surface has no Worker
* category), and no `Worker` / `Blob` / `URL.createObjectURL` either — there is no way to
* get a real thread there. Callers must degrade to synchronous execution.
*
* Returns `undefined` (rather than throwing) when creation fails on Huawei quick game, so
* the result MUST be null-checked.
*
* Every platform caps concurrency at ONE worker except WeChat V2 (standard worker).
* Script paths must be relative (no leading "/") and end with ".js", and the file must be
* packaged under the workers directory declared in game.json / manifest.json / app.json.
*/
createWorker?: (scriptPath: string, options?: MinigameWorkerOptions) => MinigameWorker | undefined;
/**
* Platform environment info. On WeChat this carries `isSupportStandardWorker`, which gates
* the V2 standard worker (grey release; NOT supported in the WeChat devtools). Absent on
* platforms whose global has no `env`.
*/
env?: MinigameEnv;
// file system
getFileSystemManager(): FileSystemManager;
loadSubpackage? (option: LoadSubpackageOption): LoadSubpackageTask;
@@ -133,6 +165,57 @@ declare module 'pal/minigame' {
getAudioContext?: () => AudioContext;
}
/**
* Options accepted by `minigame.createWorker`. Only WeChat defines any; other platforms ignore
* the second argument. Kept loose on purpose — the platform surface differs and grows.
*/
export interface MinigameWorkerOptions {
/**
* WeChat only, base library 2.13.0+. Uses the "experimental" worker implementation, which
* speeds up JS execution several times over on iOS. Requires pairing with
* `onProcessKilled`, because the system may reclaim the worker process at any time.
* This legacy option does not select the V2 standard Worker.
*/
useExperimentalWorker?: boolean;
[key: string]: any;
}
/**
* Platform environment info exposed as `minigame.env`.
*/
export interface MinigameEnv {
/**
* WeChat only. `true` when the runtime supports the V2 standard worker: multiple concurrent
* workers, `SharedArrayBuffer`, transfer lists in `postMessage`, `OffscreenCanvas`. Requires
* WeChat client >= 8.0.74 (Android) and base library >= 3.17.0, is in grey release, and is
* NOT supported in the WeChat devtools — so it must be checked at runtime, never assumed.
*/
isSupportStandardWorker?: boolean;
[key: string]: any;
}
/**
* The worker handle returned by `minigame.createWorker`. The API shape is remarkably consistent
* across WeChat / ByteDance / Alipay / Baidu / quick-game: all use `postMessage` + `onMessage`,
* and all expose the worker-side global as `worker` (NOT `self`).
*
* Differences that the engine's backend layer must absorb:
* - `onError` is missing on some platforms (Huawei quick game documents only
* create/postMessage/onMessage/terminate) — guard before calling.
* - `onProcessKilled` is WeChat-only (iOS experimental worker reclamation).
* - The transfer list (second `postMessage` argument) is honored ONLY by WeChat V2. Huawei quick
* game documents data transfer as structured clone with no transferable objects; passing a
* transfer list elsewhere may throw, so omit it unless the platform supports it.
*/
export interface MinigameWorker {
postMessage(message: any, transfer?: any[]): void;
onMessage(listener: (res: any) => void): void;
onError?: (listener: (err: any) => void) => void;
terminate(): void;
/** WeChat only: fired when the system reclaims the worker process. */
onProcessKilled?: (listener: (err: any) => void) => void;
}
export type AccelerometerIntervalMode = 'game' | 'ui' | 'normal';
export interface AccelerometerStartParameter {
+12
View File
@@ -22,6 +22,12 @@ declare module 'pal/screen-adapter' {
* Determine whether use headless renderer, which means do not support some screen operations.
*/
isHeadlessMode: boolean;
/**
* Optional startup DPR cap, currently consumed by Web.
* Supporting adapters validate that it is finite and >= 1; other adapters ignore it.
* Omission/null preserves the adapter's default policy (Web caps DPR at 2).
*/
maxDevicePixelRatio?: number | null;
}
class ScreenAdapter {
@@ -58,6 +64,12 @@ declare module 'pal/screen-adapter' {
* Query the current fullscreen state.
*/
public get isFullScreen (): boolean;
/**
* Optional capability: the applied startup cap, or null for the adapter's default.
* Adapters exposing this property consume and validate maxDevicePixelRatio.
* Absent on adapters that ignore this setting.
*/
public readonly maxDevicePixelRatio?: number | null;
/**
* The ratio of pixel sizes:
* the size of one CSS pixel to the size of one physical pixel.
+61
View File
@@ -0,0 +1,61 @@
/**
* Engine-side contract of the `pal/worker` module.
*
* Self-contained on purpose: type checking, IDE services and declaration builds must not depend on
* whether the installed PAL package ships a worker module. When `pal/worker` is absent (an older
* PAL, or the single-thread compatibility module which is JS only), TypeScript resolves the import to
* this ambient declaration. `tests/scripts/pal-worker-types.test.cjs` checks that a real PAL
* `worker/type.d.ts` stays structurally identical to these interfaces.
*/
declare module 'pal/worker' {
export interface IWorker {
postMessage (message: any, transfer?: Transferable[]): void;
onMessage (listener: (res: any) => void): void;
onError (listener: (err: any) => void): void;
terminate (): void;
}
export interface IWorkerDiagnosis {
ready: boolean;
version: 0 | 1 | 2;
reason: string;
}
export interface IWorkerBackend {
readonly concurrencyLimit: number;
readonly supportsTransfer: boolean;
readonly supportsSharedArrayBuffer: boolean;
readonly supportsFunctionWorker: boolean;
readonly capabilityReason: string;
createScriptWorker (path: string): IWorker;
diagnose (path: string): IWorkerDiagnosis;
}
export interface IPlatformWorkerBackend extends IWorkerBackend {
readonly supportsStandardWorker: boolean;
readonly scriptFailureHint: string;
resolveScriptWorker (path: string): IWorkerResolution;
readonly hardwareConcurrency: number;
readonly scriptFallback: IPlatformWorkerBackend | null;
createFunctionWorker (fn: (...args: any[]) => any): IWorker | null;
}
export interface IWorkerResolution {
backend: IPlatformWorkerBackend | null;
diagnosis: IWorkerDiagnosis;
warnOnFailure: boolean;
}
export interface IWorkerCapabilities {
supportsStandardWorker: boolean;
available: boolean;
parallel: boolean;
concurrencyLimit: number;
supportsTransfer: boolean;
supportsSharedArrayBuffer: boolean;
supportsFunctionWorker: boolean;
reason: string;
}
export function createWorkerBackend (): IPlatformWorkerBackend;
}
+112
View File
@@ -3205,6 +3205,38 @@ request fullscreen is not supported on this platform.
exit fullscreen is not supported on this platform.
### 9010
UIMesh.setMeshData: unsupported vertexStride %d, expected %d (V3F_T2F_C4B) or %d (V3F_T2F_C4B_C4B); data rejected.
### 9011
UIMesh.setMeshData: negative counts (vertexCount %d, indexCount %d); data rejected.
### 9012
UIMesh.setMeshData: vertexData holds %d bytes, but %d vertices x %d bytes are declared; data rejected.
### 9013
UIMesh.setMeshData: indexData is %d bytes at offset %d, but %d Uint16 indices need %d bytes (2-byte aligned view); data rejected.
### 9014
UIMesh.setMeshData: indices[%d] = %d is out of range for %d vertices; data rejected.
### 9015
UIMesh.setMeshData: segment %d range [%d, %d) is out of bounds for indexCount %d; data rejected.
### 9016
UIMesh.setMeshData: %d vertices / %d indices exceed the accessor cap (%d / %d); split the mesh. Data rejected.
### 9017
UIMesh: render data allocation failed for %d vertices / %d indices (accessor cap: %d / %d).
### 9100
texture size exceeds current device limits %d/%d
@@ -3226,6 +3258,18 @@ Cannot access game frame or container.
Setting window size is not supported.
### 9204
maxDevicePixelRatio, when specified, must be a finite number >= 1.
### 9205
PAL did not apply the configured maximum DPR. Check that the engine and PAL versions match.
### 9206
maxDevicePixelRatio cannot change after ScreenAdapter.init().
### 9300
The current buffer beyond the limit in ui static component, please reduce the amount
@@ -3984,3 +4028,71 @@ Spine version not supported.
### 16420
End time must bigger than start time.
### 16500
WorkerPool script path must be a non-empty string
### 16501
WorkerPool requires a self-contained task function or a worker script path
### 16502
WorkerPool has been terminated
### 16503
WorkerPool has no available execution backend
### 16504
No worker backend for "%s" (%s). Provide options.fallback to run single-threaded, or fix packaging (docs/worker/README.md).
### 16505
WorkerPool degraded to single-threaded for "%s": worker backend failed (%s). %s
### 16506
WorkerPool is rejecting tasks (no options.fallback) for "%s": worker backend failed (%s). %s
### 16507
WorkerPool could not use a worker for "%s" and is running single-threaded via options.fallback. Reason: %s. %s
### 16508
WorkerPool could not use a worker for "%s" and is REJECTING tasks (no options.fallback). Reason: %s. %s
### 16509
Worker error
### 16510
Worker is unavailable and no synchronous fallback exists
### 16511
Worker task timed out after %sms — the worker never replied (deadlock, infinite loop, or non-protocol script). Worker discarded; see docs/worker/README.md
### 16512
Worker has been disposed
### 16513
Worker script sent a malformed reply — it must implement the engine protocol: receive { id, args }, post back { id, ok, value } or { id, ok: false, error } (docs/worker/cc-worker-template.js)
### 16514
Worker task failed
### 16515
createWorker(path) requires a non-empty worker script path
### 16516
Function workers are unavailable; use WorkerPool for an automatic sync fallback, or createWorker(path) (mode 2).
+15
View File
@@ -300,6 +300,16 @@
"overrideConstants": {
"CULL_MESHOPT": false
}
},
"worker": {
"modules": ["worker"]
},
"worker-pool": {
"modules": ["worker", "worker-pool"],
"dependentModules": ["worker"]
},
"webassembly": {
"modules": ["webassembly"]
}
},
"moduleOverrides": [{
@@ -383,6 +393,7 @@
"isVirtualModule": true,
"overrides": {
"pal/minigame": "pal/minigame/non-minigame.js",
"pal/worker": "pal/worker/web/index.js",
"pal/audio": "pal/audio/web/player.js",
"pal/system-info": "pal/system-info/web/system-info.js",
"pal/screen-adapter": "pal/screen-adapter/web/screen-adapter.js",
@@ -397,6 +408,7 @@
"isVirtualModule": true,
"overrides": {
"pal/minigame": "pal/minigame/non-minigame.js",
"pal/worker": "pal/worker/native/index.js",
"pal/audio": "pal/audio/native/player.js",
"pal/system-info": "pal/system-info/native/system-info.js",
"pal/screen-adapter": "pal/screen-adapter/native/screen-adapter.js",
@@ -411,6 +423,7 @@
"isVirtualModule": true,
"overrides": {
"pal/minigame": "pal/minigame/{{context.platform.toLowerCase()}}.js",
"pal/worker": "pal/worker/minigame/index.js",
"pal/audio": "pal/audio/minigame/player.js",
"pal/system-info": "pal/system-info/minigame/system-info.js",
"pal/screen-adapter": "pal/screen-adapter/minigame/screen-adapter.js",
@@ -425,6 +438,7 @@
"isVirtualModule": true,
"overrides": {
"pal/minigame": "pal/minigame/runtime.js",
"pal/worker": "pal/worker/minigame/index.js",
"pal/audio": "pal/audio/minigame/player.js",
"pal/system-info": "pal/system-info/minigame/system-info.js",
"pal/screen-adapter": "pal/screen-adapter/minigame/screen-adapter.js",
@@ -439,6 +453,7 @@
"isVirtualModule": true,
"overrides": {
"pal/minigame": "pal/minigame/non-minigame.js",
"pal/worker": "pal/worker/nodejs/index.js",
"pal/audio": "pal/audio/nodejs/player.js",
"pal/system-info": "pal/system-info/nodejs/system-info.js",
"pal/screen-adapter": "pal/screen-adapter/nodejs/screen-adapter.js",
+32
View File
@@ -0,0 +1,32 @@
/*
Copyright (c) 2017-2023 Xiamen Yaji Software Co., Ltd.
http://www.cocos.com
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/
// Vertex/index capacity limits of the graphics geometry.
// Uint16 can address 65536 vertices (indices 0-65535), and a single fill()/stroke() batch is not
// split, so the buffers have to cover this count.
export const MAX_VERTEX_COUNT = 65536;
// Fill and stroke both emit at most 3 indices per vertex, see GraphicsAssembler.
export const INDICES_PER_VERTEX = 3;
export const MAX_INDEX_COUNT = MAX_VERTEX_COUNT * INDICES_PER_VERTEX;
@@ -28,12 +28,10 @@ import { MeshRenderData } from '../../../renderer/render-data';
import { IBatcher } from '../../../renderer/i-batcher';
import { Graphics } from '../../../components/graphics';
import { LineCap, LineJoin, PointFlags } from '../types';
import { MAX_VERTEX_COUNT, INDICES_PER_VERTEX } from '../constants';
import { earcut as Earcut } from './earcut';
import { Impl, Point } from './impl';
const MAX_VERTEX = 65535;
const MAX_INDICES = MAX_VERTEX * 2;
const PI = Math.PI;
const min = Math.min;
const max = Math.max;
@@ -95,7 +93,7 @@ export class GraphicsAssembler implements IAssembler {
let meshBuffer = renderData;
const maxVertexCount = meshBuffer ? meshBuffer.vertexStart + vertexCount : 0;
if (maxVertexCount > MAX_VERTEX || maxVertexCount * 3 > MAX_INDICES) {
if (maxVertexCount > MAX_VERTEX_COUNT) {
++_impl.dataOffset;
if (_impl.dataOffset < renderDataList.length) {
@@ -109,7 +107,7 @@ export class GraphicsAssembler implements IAssembler {
}
if (meshBuffer && meshBuffer.vertexCount < maxVertexCount) {
meshBuffer.request(vertexCount, vertexCount * 3);
meshBuffer.request(vertexCount, vertexCount * INDICES_PER_VERTEX);
}
return renderData;
+5 -7
View File
@@ -32,6 +32,7 @@ import { safeMeasureText, BASELINE_RATIO, MIDDLE_RATIO, getBaselineOffset, getSy
import { director, DirectorEvent } from '../../../game/director';
import { ccwindow } from '../../../core/global-exports';
import { TextureBase } from '../../../asset/assets/texture-base';
import { buildFontDesc, CssFontFamily, DEFAULT_FONT_FAMILY } from '../../utils/font-family';
export interface ISharedLabelData {
canvas: HTMLCanvasElement;
@@ -102,7 +103,7 @@ interface ILabelInfo {
fontSize: number;
lineHeight: number;
hash: string;
fontFamily: string;
fontFamily: CssFontFamily;
fontDesc: string;
hAlign: number;
vAlign: number;
@@ -194,10 +195,7 @@ class LetterTexture {
// Add a white background to avoid black edges.
context.fillStyle = _backgroundStyle;
context.fillRect(0, 0, width, height);
context.font = labelInfo.fontDesc.replace(
/(\d+)(\.\d+)?(px|em|rem|pt)/g,
(w, m: string, n: string, u: string) => (+m * fontScale + (+n || 0) * fontScale).toString() + u,
);
context.font = buildFontDesc(labelInfo.fontSize * fontScale, labelInfo.fontFamily);
const fontSize = labelInfo.fontSize * fontScale;
const startX = width / 2;
@@ -425,7 +423,7 @@ export interface IShareLabelInfo {
hAlign: number;
vAlign: number;
hash: string;
fontFamily: string;
fontFamily: CssFontFamily;
fontDesc: string;
color: Color;
isOutlined: boolean;
@@ -441,7 +439,7 @@ export const shareLabelInfo: IShareLabelInfo = {
hAlign: 0,
vAlign: 0,
hash: '',
fontFamily: '',
fontFamily: DEFAULT_FONT_FAMILY,
fontDesc: 'Arial',
color: Color.WHITE.clone(),
isOutlined: false,
+4 -18
View File
@@ -26,6 +26,7 @@ import type { Label } from '../../components';
import { IAssembler } from '../../renderer/base';
import { BmfontUtils } from './bmfontUtils';
import { shareLabelInfo, LetterAtlas, computeHash, LetterRenderTexture } from './font-utils';
import { buildFontDesc, CssFontFamily, getCanvasFontFamily } from '../../utils/font-family';
const _atlasWidth = 1024;
const _atlasHeight = 1024;
@@ -59,17 +60,8 @@ export class LetterFont extends BmfontUtils {
}
}
protected _getFontFamily (comp: Label): string {
let fontFamily = 'Arial';
if (!comp.useSystemFont) {
if (comp.font) {
fontFamily = comp.font._nativeAsset || 'Arial';
}
} else {
fontFamily = comp.fontFamily || 'Arial';
}
return fontFamily;
protected _getFontFamily (comp: Label): CssFontFamily {
return getCanvasFontFamily(comp);
}
protected _updateLabelInfo (comp: Label): void {
@@ -79,12 +71,6 @@ export class LetterFont extends BmfontUtils {
}
protected _getFontDesc (): string {
let fontDesc = `${shareLabelInfo.fontSize.toString()}px `;
fontDesc += shareLabelInfo.fontFamily;
if (_isBold) {
fontDesc = `bold ${fontDesc}`;
}
return fontDesc;
return buildFontDesc(shareLabelInfo.fontSize, shareLabelInfo.fontFamily, _isBold);
}
}
+3 -12
View File
@@ -45,6 +45,7 @@ import {
safeMeasureText,
} from '../../utils/text-utils';
import type { Batcher2D } from '../../renderer/batcher-2d';
import { buildFontDesc, CssFontFamily } from '../../utils/font-family';
const Alignment = [
'left', // macro.TextAlignment.LEFT
@@ -260,18 +261,8 @@ export class TextProcessing {
}
// can cache
private _getFontDesc (fontSize: number, fontFamily: string, isBold: boolean, isItalic: boolean): string {
let fontDesc = `${fontSize.toString()}px `;
fontDesc += fontFamily;
if (isBold) {
fontDesc = `bold ${fontDesc}`;
}
if (isItalic) {
fontDesc = `italic ${fontDesc}`;
}
return fontDesc;
private _getFontDesc (fontSize: number, fontFamily: CssFontFamily, isBold: boolean, isItalic: boolean): string {
return buildFontDesc(fontSize, fontFamily, isBold, isItalic);
}
// can cache
+2 -1
View File
@@ -25,6 +25,7 @@
import { Color } from '../../../core';
import { IConfig } from '../../assets/bitmap-font';
import { SpriteFrame } from '../../assets/sprite-frame';
import { CssFontFamily, DEFAULT_FONT_FAMILY } from '../../utils/font-family';
export class TextStyle {
// ---------------ttf extra part-----------------
@@ -59,7 +60,7 @@ export class TextStyle {
public bmfontScale = 1.0;// both
// font info // todo merge to font
public fontFamily = 'Arial'; // both
public fontFamily: CssFontFamily = DEFAULT_FONT_FAMILY; // Serialized CSS family, both TTF and CHAR.
public fontDesc = ''; // both
// -----------------------bitMap extra part-------------------------
+3 -12
View File
@@ -31,6 +31,7 @@ import type { TextStyle } from './text-style';
import type { TextLayout } from './text-layout';
import { view } from '../../../ui/view';
import { approx } from '../../../core';
import { CssFontFamily, getCanvasFontFamily } from '../../utils/font-family';
const Overflow = Label.Overflow;
@@ -192,18 +193,8 @@ export class TTFUtils {
// no needs to update uv data
}
_updateFontFamily (comp: Label): string {
let _fontFamily = '';
if (!comp.useSystemFont) {
if (comp.font) {
_fontFamily = comp.font._nativeAsset || 'Arial';
} else {
_fontFamily = 'Arial';
}
} else {
_fontFamily = comp.fontFamily || 'Arial';
}
return _fontFamily;
_updateFontFamily (comp: Label): CssFontFamily {
return getCanvasFontFamily(comp);
}
_calDynamicAtlas (comp: Label, outputLayoutData: TextOutputLayoutData): void {
+89 -36
View File
@@ -32,6 +32,7 @@ import { Color, warnID, cclegacy } from '../../core';
import { scene } from '../../render-scene';
import type { IBatcher } from '../renderer/i-batcher';
import { LineCap, LineJoin } from '../assembler/graphics/types';
import { MAX_VERTEX_COUNT, MAX_INDEX_COUNT } from '../assembler/graphics/constants';
import { Impl } from '../assembler/graphics/webgl/impl';
import { Material, RenderingSubMesh } from '../../asset/assets';
import { Format, PrimitiveMode, Attribute, Device, BufferUsageBit, BufferInfo, MemoryUsageBit, deviceManager } from '../../gfx';
@@ -39,21 +40,33 @@ import { vfmtPosColor, getAttributeStride, getComponentPerVertex } from '../rend
import { NativeUIModelProxy } from '../renderer/native-2d';
import { RenderEntity, RenderEntityType } from '../renderer/render-entity';
import type { GraphicsAssembler } from '../assembler/graphics/webgl/graphics-assembler';
import type { MeshRenderData } from '../renderer/render-data';
import type { InputAssembler } from '../../gfx';
const attributes = vfmtPosColor.concat([
new Attribute('a_dist', Format.R32F),
]);
const componentPerVertex = getComponentPerVertex(attributes);
const alphaOffset = 6; // position.xyz, color.rgba, distance
const stride = getAttributeStride(attributes);
// Grow only, by powers of two, so a changing geometry does not re-create the GPU buffer every frame.
function growCapacity (needed: number, current: number, max: number): number {
let cap = Math.max(current, 1);
while (cap < needed) {
cap *= 2;
}
return Math.min(cap, max);
}
/**
* @en
* Graphics component.
* Graphics component. Fill and stroke alpha are multiplied by the node's cascaded UI opacity at draw time.
*
* @zh
* 自定义图形类。
* 自定义图形组件。绘制时,填充和描边的 alpha 会乘以节点的累计 UI 透明度。
*/
@ccclass('cc.Graphics')
@help('i18n:cc.Graphics')
@@ -224,6 +237,8 @@ export class Graphics extends UIRenderer {
protected _isNeedUploadData = true;
private _graphicsUseSubMeshes: RenderingSubMesh[] = [];
private _uploadedOpacity = 1;
private _opacityScratch: Float32Array | null = null;
//nativeObj
protected declare _graphicsNativeProxy: NativeUIModelProxy;
@@ -301,6 +316,7 @@ export class Graphics extends UIRenderer {
this.impl = null;
}
this._opacityScratch = null;
super.onDestroy();
}
@@ -555,6 +571,7 @@ export class Graphics extends UIRenderer {
}
this.impl.clear();
this._opacityScratch = null;
this._isDrawing = false;
if (JSB) {
this._graphicsNativeProxy.clear();// need native
@@ -635,7 +652,7 @@ export class Graphics extends UIRenderer {
/**
* @deprecated since v3.7.0, this is an engine private interface that will be removed in the future.
*/
public activeSubModel (idx: number): void {
public activeSubModel (idx: number, vertexCount = 1, indexCount = 1): void {
if (!this.model) {
warnID(4500, this.node.name);
return;
@@ -646,13 +663,13 @@ export class Graphics extends UIRenderer {
const vertexBuffer = gfxDevice.createBuffer(new BufferInfo(
BufferUsageBit.VERTEX | BufferUsageBit.TRANSFER_DST,
MemoryUsageBit.DEVICE,
65536 * stride, // Uint16 can address 65536 vertices (indices 0–65535)
growCapacity(vertexCount, 0, MAX_VERTEX_COUNT) * stride,
stride,
));
const indexBuffer = gfxDevice.createBuffer(new BufferInfo(
BufferUsageBit.INDEX | BufferUsageBit.TRANSFER_DST,
MemoryUsageBit.DEVICE,
65536 * Uint16Array.BYTES_PER_ELEMENT * 2, // Uint16 can address 65536 vertices (indices 0–65535)
growCapacity(indexCount, 0, MAX_INDEX_COUNT) * Uint16Array.BYTES_PER_ELEMENT,
Uint16Array.BYTES_PER_ELEMENT,
));
@@ -664,50 +681,86 @@ export class Graphics extends UIRenderer {
}
}
protected _uploadData (): void {
const impl = this.impl;
if (!impl) {
return;
}
const renderDataList = impl && impl.getRenderDataList();
if (renderDataList.length <= 0 || !this.model) {
protected _uploadData (opacity = this.node._uiProps.opacity): void {
if (!this.impl || !this.model) {
return;
}
const renderDataList = this.impl.getRenderDataList();
const subModelList = this.model.subModels;
for (let i = 0; i < renderDataList.length; i++) {
const renderData = renderDataList[i];
const ia = subModelList[i].inputAssembler;
if (renderData.lastFilledVertex === renderData.vertexStart) {
continue;
const indexCount = renderData.indexStart;
const vertexCount = indexCount ? renderData.vertexStart : 0;
const newSubModel = i >= subModelList.length;
if (newSubModel) {
this.activeSubModel(i, vertexCount, indexCount);
}
const ia = subModelList[i].inputAssembler;
const verticesChanged = newSubModel || renderData.lastFilledVertex !== vertexCount;
const indicesChanged = newSubModel || renderData.lastFilledIndex !== indexCount;
if (verticesChanged || indicesChanged) {
this._ensureCapacity(renderData, ia);
}
if (vertexCount && (verticesChanged || opacity !== this._uploadedOpacity)) {
ia.vertexBuffers[0].update(this._getUploadVertices(renderData, vertexCount, opacity));
}
if (verticesChanged) {
ia.vertexCount = vertexCount;
renderData.lastFilledVertex = vertexCount;
}
if (indicesChanged) {
if (indexCount) ia.indexBuffer!.update(renderData.iData.subarray(0, indexCount));
ia.indexCount = indexCount;
renderData.lastFilledIndex = indexCount;
}
const vb = new Float32Array(renderData.vData.buffer, 0, renderData.vertexStart * componentPerVertex);
ia.vertexBuffers[0].update(vb);
ia.vertexCount = renderData.vertexStart;
const ib = new Uint16Array(renderData.iData.buffer, 0, renderData.indexStart);
ia.indexBuffer!.update(ib);
ia.indexCount = renderData.indexStart;
renderData.lastFilledVertex = renderData.vertexStart;
renderData.lastFilledIndex = renderData.indexStart;
}
this._uploadedOpacity = opacity;
this._isNeedUploadData = false;
}
private _getUploadVertices (data: MeshRenderData, vertexCount: number, opacity: number): Float32Array {
const raw = new Float32Array(data.vData.buffer, data.vData.byteOffset, vertexCount * componentPerVertex);
if (opacity === 1) return raw;
// Keep the retained paint colors intact so each fade starts from its original alpha.
if (!this._opacityScratch || this._opacityScratch.length < raw.length) {
this._opacityScratch = new Float32Array(growCapacity(vertexCount, 0, MAX_VERTEX_COUNT) * componentPerVertex);
}
const output = this._opacityScratch.subarray(0, raw.length);
output.set(raw);
for (let i = alphaOffset; i < output.length; i += componentPerVertex) {
output[i] = raw[i] * opacity;
}
return output;
}
/**
* Grow only, never shrink: the capacity is reused after clear().
*/
private _ensureCapacity (renderData: MeshRenderData, ia: InputAssembler): void {
const vb = ia.vertexBuffers[0];
const vbStride = vb.stride;
if (renderData.vertexStart * vbStride > vb.size) {
const count = growCapacity(renderData.vertexStart, vb.size / vbStride, MAX_VERTEX_COUNT);
vb.resize(count * vbStride);
}
const ib = ia.indexBuffer;
if (!ib) {
return;
}
if (renderData.indexStart * Uint16Array.BYTES_PER_ELEMENT > ib.size) {
const count = growCapacity(renderData.indexStart, ib.size / Uint16Array.BYTES_PER_ELEMENT, MAX_INDEX_COUNT);
ib.resize(count * Uint16Array.BYTES_PER_ELEMENT);
}
}
protected _render (render: IBatcher): void {
if (this._isNeedUploadData) {
if (this.impl) {
const renderDataList = this.impl.getRenderDataList();
const len = this.model!.subModels.length;
if (renderDataList.length > len) {
for (let i = len; i < renderDataList.length; i++) {
this.activeSubModel(i);
}
}
}
this._uploadData();
const opacity = this.node._uiProps.opacity;
if (this._isNeedUploadData || this._uploadedOpacity !== opacity) {
this._uploadData(opacity);
}
render.commitModel(this, this.model, this.getMaterialInstance(0));
+1
View File
@@ -25,6 +25,7 @@
export * from './label';
export { Sprite } from './sprite';
export { UIMeshRenderer } from './ui-mesh-renderer';
export * from './ui-mesh';
export { LabelOutline } from './label-outline';
export { UIStaticBatch } from './ui-static-batch';
export { LabelShadow } from './label-shadow';
+636
View File
@@ -0,0 +1,636 @@
/*
Copyright (c) 2026
Generic 2D mesh data consumer: the plugin feeds pre-baked vertex/index/segment
data through setMeshData; this component owns buffer allocation, batching and
submission through the 2D batcher, so extensions can render custom meshes
without touching engine internals.
Vertices are ALWAYS node-local; UIMesh owns the node transform:
* not batched -- on the GPU, via USE_LOCAL + the per-draw cc-local UBO the
batcher already maintains for middleware draws;
* batched -- the FULL world matrix baked into the chunk copy on the CPU
(a merged batch carries no per-draw matrix), matching the GPU path, z /
X-Y rotation included.
USE_LOCAL / setUseLocal are derived internally; there is no world-baked
input mode.
Data is FillColorType.VERTEX, so the batcher applies no cascaded opacity:
UIMesh folds it into the copied vertices itself, accumulated as Batcher2D.walk
does for COLOR data (own color alpha x, per ancestor, UIOpacity localOpacity x
that ancestor's color alpha). `premultipliedAlpha` declares the data format:
alpha-byte-only vs RGBA + dark RGB fading.
The batcher resets the shared index tail after every upload (vertex bytes
survive), so indices are re-submitted EVERY frame (appendIndexBuffer) and only
the vertex refresh is _vertexDirty-gated. A dirty-gated submission would leave
a static mesh's draw range aliasing whichever sibling appends after the reset
(two UIMeshes in one buffer, one paused: it would draw the other's triangles).
*/
import { JSB } from 'internal:constants';
import { ccclass, editable, serializable } from 'cc.decorator';
import { errorID } from '../../core';
import { Mat4 } from '../../core/math';
import { UIRenderer } from '../framework/ui-renderer';
import { RenderData } from '../renderer/render-data';
import { RenderDrawInfo, RenderDrawInfoType } from '../renderer/render-draw-info';
import { StaticVBAccessor } from '../renderer/static-vb-accessor';
import type { Batcher2D } from '../renderer/batcher-2d';
import { vfmtPosUvColor4B, vfmtPosUvTwoColor4B, getAttributeStride } from '../renderer/vertex-format';
import { RenderEntity, RenderEntityType } from '../renderer/render-entity';
import { director, DirectorEvent } from '../../game';
import { Texture2D } from '../../asset/assets';
import { builtinResMgr } from '../../asset/asset-manager';
import { BlendFactor } from '../../gfx';
import type { MeshBuffer } from '../renderer/mesh-buffer';
import type { MaterialInstance } from '../../render-scene';
import type { Material } from '../../asset/assets/material';
import type { Node } from '../../scene-graph';
/**
* @en A segment of the mesh: a range of indices drawn with one texture+material.
* @zh 网格的一个片段:一段索引,用同一纹理+材质绘制。
*/
export interface UIMeshSegment {
indexOffset: number;
indexCount: number;
texture: Texture2D | null;
material: MaterialInstance | null;
}
/**
* @en Pre-baked mesh data for one frame.
* @zh 一帧的预烘焙网格数据。
* vertexStride: 24 (single-color V3F_T2F_C4B) or 28 (two-color V3F_T2F_C4B_C4B).
*/
export interface UIMeshData {
vertexCount: number;
vertexStride: number;
vertexData: Uint8Array;
indexCount: number;
indexData: Uint8Array;
segments: UIMeshSegment[];
}
// Shared static vertex-buffer accessors, keyed by the current Batcher2D: it
// destroys every accessor registered with it, so a rebuilt root must never
// reuse a cached (destroyed) accessor, and each new one must be registered
// with the current batcher or its buffers would never be uploaded or reset.
let _accessorBatcher: Batcher2D | null = null;
let _sharedAccessor: StaticVBAccessor | null = null;
let _sharedTintAccessor: StaticVBAccessor | null = null;
// Registration keys in the batcher's accessor map (base-36 namespaced, the
// same convention as the built-in middleware assemblers — spine/dragon-bones).
const UIMESH_ACCESSOR_KEY = Number.parseInt('UIMESH', 36);
const UIMESH_TINT_ACCESSOR_KEY = Number.parseInt('UIMESHTINT', 36);
// The two consumed vertex formats (24 / 28 bytes); strides derived from the
// definitions so the byte math always matches the chunk's format.
const MESH_STRIDE_BYTES = getAttributeStride(vfmtPosUvColor4B);
const MESH_STRIDE_TINT_BYTES = getAttributeStride(vfmtPosUvTwoColor4B);
/**
* @en A generic 2D mesh renderer that consumes pre-baked vertex/index data.
* The data provider (e.g. a spine plugin) fills setMeshData every frame; this
* component handles buffer allocation, batching and submission.
* @zh 通用 2D 网格渲染器,消费预烘焙的顶点/索引数据。数据提供方(如 spine 插件)
* 每帧调用 setMeshData,本组件负责缓冲分配、合批与提交。
*/
@ccclass('cc.UIMesh')
export class UIMesh extends UIRenderer {
@serializable
protected _enableBatch = false;
/**
* @en Whether the incoming color data is premultiplied-alpha. Declares how
* cascaded opacity is folded into the vertices (alpha byte only vs
* RGBA + dark RGB) and the blend factors of the builtin material.
* @zh 输入颜色数据是否为预乘 alpha 格式。决定级联不透明度折算方式
* (仅 alpha 字节 vs RGBA + dark RGB)及内置材质混合因子。
*/
@serializable
protected _premultipliedAlpha = false;
protected _meshData: UIMeshData | null = null;
protected _useTint = false;
private _drawInfoList: RenderDrawInfo[] = [];
// Poll cache (see _onBeforeDraw): inputs captured by the last
// updateVertexBuffer run; drift means the baked transform / folded opacity
// no longer match. The full matrix is tracked — the bake applies all of it.
private _pollOpacity = 1;
private _pollWorldMatrix = new Mat4();
// Vertex-staleness latch, consumed by _onBeforeDraw to pick a full refresh
// vs an index-only resubmit. Starts dirty so the first frame prepares.
private _vertexDirty = true;
constructor () {
super();
this._useVertexOpacity = true;
}
/**
* @en Feeds the pre-baked mesh data for the current frame.
* @zh 喂入当前帧的预烘焙网格数据。
*/
public setMeshData (data: UIMeshData): void {
// Reject bad input at the call site; a rejected frame keeps the last
// accepted mesh.
if (!this._validateMeshData(data)) return;
const useTint = data.vertexStride === MESH_STRIDE_TINT_BYTES;
if (useTint !== this._useTint) {
this.destroyRenderData();
this._useTint = useTint;
this._flushAssembler();
// The builtin fallback material follows the stride (TWO_COLORED).
this.updateMaterial();
}
this._meshData = data;
this._vertexDirty = true;
}
private _validateMeshData (data: UIMeshData): boolean {
const vc = data.vertexCount;
const ic = data.indexCount;
if (data.vertexStride !== MESH_STRIDE_BYTES && data.vertexStride !== MESH_STRIDE_TINT_BYTES) {
errorID(9010, data.vertexStride, MESH_STRIDE_BYTES, MESH_STRIDE_TINT_BYTES);
return false;
}
if (vc < 0 || ic < 0) {
errorID(9011, vc, ic);
return false;
}
// Capacity limits come from the accessor that will serve the data.
const accessor = this.ensureAccessor(data.vertexStride === MESH_STRIDE_TINT_BYTES);
if (vc > accessor.maxVertexCount || ic > accessor.maxIndexCount) {
errorID(9016, vc, ic, accessor.maxVertexCount, accessor.maxIndexCount);
return false;
}
if (!data.vertexData || data.vertexData.byteLength < vc * data.vertexStride) {
errorID(9012, data.vertexData ? data.vertexData.byteLength : 0, vc, data.vertexStride);
return false;
}
if (!data.indexData || data.indexData.byteOffset % 2 !== 0 || data.indexData.byteLength < ic * 2) {
errorID(
9013,
data.indexData ? data.indexData.byteLength : 0,
data.indexData ? data.indexData.byteOffset : 0,
ic,
ic * 2,
);
return false;
}
// Indices are mesh-local; anything >= vertexCount would sample vertices
// of other chunks in the shared buffer (silent geometry corruption).
const indices = new Uint16Array(data.indexData.buffer, data.indexData.byteOffset, ic);
for (let i = 0; i < ic; ++i) {
if (indices[i] >= vc) {
errorID(9014, i, indices[i], vc);
return false;
}
}
for (let i = 0; i < data.segments.length; ++i) {
const seg = data.segments[i];
if (seg.indexOffset < 0 || seg.indexCount < 0 || seg.indexOffset + seg.indexCount > ic) {
errorID(9015, i, seg.indexOffset, seg.indexOffset + seg.indexCount, ic);
return false;
}
}
return true;
}
/**
* @en Whether to enable sprite batching.
* @zh 是否启用合批。
*/
@editable
get enableBatch (): boolean { return this._enableBatch; }
set enableBatch (value: boolean) {
this._enableBatch = value;
this._syncTransformMode();
this.updateMaterial();
}
/**
* @en Whether the input color data is premultiplied-alpha.
* @zh 输入颜色数据是否为预乘 alpha 格式。
*/
@editable
get premultipliedAlpha (): boolean { return this._premultipliedAlpha; }
set premultipliedAlpha (value: boolean) {
this._premultipliedAlpha = value;
this.updateMaterial();
this._vertexDirty = true;
this.onPremultipliedAlphaChanged();
}
/**
* Notifies subclasses the declared format changed. The property is owned
* here (single source of truth); producers override this to forward it to
* their baker instead of redeclaring the field.
*/
protected onPremultipliedAlphaChanged (): void {}
public onLoad (): void {
super.onLoad();
// Deserialization has applied _enableBatch by now; re-derive the
// legacy switch state.
this._syncTransformMode();
}
/**
* useLocal == "vertices are still node-local at submit time". Batched data
* is world-baked by updateVertexBuffer before submit, and native
* middleware draws only merge when !useLocal — hence !enableBatch.
*/
private _syncTransformMode (): void {
this._renderEntity.setUseLocal(!this._enableBatch);
this._vertexDirty = true;
}
protected _updateColor (): void {
super._updateColor();
// The opacity fold in updateVertexBuffer reads this._color, so a
// change must re-prepare. Visibility (color.a 0 <-> !0) is recomputed
// fresh by _onBeforeDraw.
this._vertexDirty = true;
}
protected _onMaterialModified (idx: number, material: Material | null): void {
super._onMaterialModified(idx, material);
// Draw infos cache the material reference; a swap must rebuild them.
// The base mark only re-syncs visibility (no updateRenderer override
// anymore), and the passDirty self-heal path needs an assembler.
this._vertexDirty = true;
}
public onEnable (): void {
super.onEnable();
// BEFORE_DRAW fires between the update and render phases, outside the
// director.pause() gate — the render loop still redraws (and resets
// shared buffers) while paused, so submission must keep running.
if (JSB) director.on(DirectorEvent.BEFORE_DRAW, this._onBeforeDraw, this);
}
public onDisable (): void {
if (JSB) director.off(DirectorEvent.BEFORE_DRAW, this._onBeforeDraw, this);
super.onDisable();
}
/**
* JSB per-frame driver (director BEFORE_DRAW); web is driven by fillBuffers
* instead. Three jobs:
* * poll — transforms / UIOpacity never mark a middleware renderer, so
* compare the live values against the last updateVertexBuffer capture;
* * visibility — recomputed fresh (the base class' synchronous
* _updateColor recompute is assembler-gated, dead here); an invisible
* mesh submits nothing and its draw infos are cleared;
* * data — full refresh when the latch is set or the mesh just became
* visible again, else the frame-scoped appendIndexBuffer only.
*/
private _onBeforeDraw (): void {
if (!JSB || !this._renderData || !this._meshData) return;
if (this._enableBatch && !this.node.worldMatrix.strictEquals(this._pollWorldMatrix)) {
this._vertexDirty = true;
}
if (this._computeCascadedOpacity() !== this._pollOpacity) {
this._vertexDirty = true;
}
const wasRenderable = this._renderFlag;
const canRender = this._canRender();
this._renderFlag = canRender;
this._renderEntity.enabled = canRender;
if (!canRender) {
if (wasRenderable) this._renderEntity.clearDynamicRenderDrawInfos();
return;
}
if (this._vertexDirty || !wasRenderable) {
this._prepareNativeDrawInfos();
this._vertexDirty = false;
} else {
this.appendIndexBuffer();
}
}
protected _flushAssembler (): void {
if (this._renderData === null) {
const accessor = this.ensureAccessor(this._useTint);
this._renderData = RenderData.add(this._useTint ? vfmtPosUvTwoColor4B : vfmtPosUvColor4B, accessor);
}
}
protected _render (batcher: any): void {
const prepared = this._prepareBuffers();
if (!prepared || !this._meshData) return;
const { meshBuffer, startIndex } = prepared;
const data = this._meshData;
// Segments without their own material fall back to the component
// material (the builtin spine effect).
for (const seg of data.segments) {
const mat = seg.material || this.getRenderMaterial(0);
if (seg.texture && mat) {
batcher.commitMiddleware(
this,
meshBuffer,
startIndex + seg.indexOffset,
seg.indexCount,
seg.texture,
mat,
this._enableBatch,
);
}
}
}
private _prepareBuffers (): { meshBuffer: MeshBuffer, startIndex: number } | null {
// Full refresh: the dirty-gated vertex half + the frame-scoped index
// half. Shared by the web walk (_render) and _prepareNativeDrawInfos.
if (!this.updateVertexBuffer()) return null;
return this.appendIndexBuffer();
}
/**
* Vertex half of a refresh: grow the chunk, copy this frame's bytes, bake
* the world matrix when batching, fold cascaded opacity, capture the poll
* inputs. The expensive half — callers gate it (native: dirty only; web:
* every frame). Returns whether the chunk holds this frame's vertices.
*/
protected updateVertexBuffer (): boolean {
if (!this._renderData || !this._meshData) return false;
const data = this._meshData;
const rd = this._renderData;
const vc = data.vertexCount;
const ic = data.indexCount;
if (vc < 1 || ic < 1) return false;
const vLength = vc * data.vertexStride;
// ~10% head room, clamped to the accessor's per-chunk caps — an
// unclamped reserve would permanently fail data that fits (30000 ->
// 33000 requested > 32767). Per-frame counts live on the render data;
// the reserve lives on the chunk.
if (!rd.chunk || rd.chunk.vb.byteLength < vLength || rd.chunk.indexCount < ic) {
rd.resize(
Math.min(Math.ceil(vc * 1.1), rd.accessor.maxVertexCount),
Math.min(Math.ceil(ic * 1.1), rd.accessor.maxIndexCount),
);
if (!rd.chunk) {
errorID(9017, vc, ic, rd.accessor.maxVertexCount, rd.accessor.maxIndexCount);
return false;
}
rd.updateSize(vc, ic);
} else if (rd.vertexCount !== vc || rd.indexCount !== ic) {
rd.updateSize(vc, ic);
}
if (!rd.chunk) return false;
// Copy into the chunk's view of the shared vData.
const vbuf = rd.chunk.vb;
const vU8 = new Uint8Array(vbuf.buffer, vbuf.byteOffset, vLength);
vU8.set(data.vertexData.subarray(0, vLength));
// Batched: a merged batch carries no per-draw matrix, so bake the
// world transform into the chunk copy (the incoming vertexData may be
// a worker-shared view — never touch it).
if (this._enableBatch) {
this._bakeWorldTransform(vbuf, vLength, data.vertexStride);
}
// Cascaded opacity: VERTEX-type data gets no engine-side fade, UIMesh
// applies it while copying (see the opacity contract in the header).
const opacity = this._computeCascadedOpacity();
if (opacity < 0.9999) {
this._applyOpacity(vU8, vc, data.vertexStride, opacity);
}
// Capture the poll inputs (compared in _onBeforeDraw).
this._pollOpacity = opacity;
if (this._enableBatch) {
this._pollWorldMatrix.set(this.node.worldMatrix);
}
return true;
}
/**
* Index half: offset by the chunk's vertexOffset, append into the shared
* index buffer, refresh the draw-info offsets. Must run EVERY frame for
* every participating mesh — the batcher resets the index tail after each
* upload while draw infos keep absolute offsets, so a mesh that skipped
* would alias whichever sibling appends first (see the header contract).
* Runs exactly once per frame (native pump / web fillBuffers);
* commitMiddleware reads meshBuffer.iData.
*/
protected appendIndexBuffer (): { meshBuffer: MeshBuffer, startIndex: number } | null {
const data = this._meshData;
const rd = this._renderData;
if (!rd || !rd.chunk || !data || data.vertexCount < 1 || data.indexCount < 1) {
return null;
}
const meshBuffer = rd.getMeshBuffer()!;
// The native batcher resets indexOffset through shared memory after
// uploading — sync the JS-side cache before appending.
if (JSB) meshBuffer.indexOffset = meshBuffer.sharedBuffer[2];
const startIndex = meshBuffer.indexOffset;
const ic = data.indexCount;
const chunkOffset = rd.chunk.vertexOffset;
const offsetIndices = new Uint16Array(ic);
new Uint8Array(offsetIndices.buffer).set(data.indexData.subarray(0, ic * 2));
for (let i = 0; i < ic; i++) offsetIndices[i] += chunkOffset;
rd.chunk.vertexAccessor.appendIndices(rd.chunk.bufferId, offsetIndices);
rd.chunk.vertexAccessor.getMeshBuffer(rd.chunk.bufferId).setDirty();
// Static frames never re-run _prepareNativeDrawInfos — keep the cached
// draw infos' offsets in step (segment mapping mirrors it).
this._refreshDrawInfoOffsets(startIndex);
return { meshBuffer, startIndex };
}
private _refreshDrawInfoOffsets (startIndex: number): void {
const data = this._meshData;
if (!data || this._drawInfoList.length === 0) return;
let drawIndex = 0;
for (const seg of data.segments) {
const mat = seg.material || this.getRenderMaterial(0);
if (!seg.texture || !mat) continue;
const drawInfo = this._drawInfoList[drawIndex++];
if (drawInfo) drawInfo.setIndexOffset(startIndex + seg.indexOffset);
}
}
/**
* Bakes the FULL world matrix into the chunk copy's positions — exactly
* what the USE_LOCAL GPU path applies (pos = cc_matWorld * pos), z and
* X/Y-rotation included, so batched and unbatched renders agree. Identity
* is skipped.
*/
private _bakeWorldTransform (vbuf: Float32Array, byteLength: number, stride: number): void {
const m = this.node.worldMatrix;
const m00 = m.m00; const m01 = m.m01; const m02 = m.m02;
const m04 = m.m04; const m05 = m.m05; const m06 = m.m06;
const m08 = m.m08; const m09 = m.m09; const m10 = m.m10;
const m12 = m.m12; const m13 = m.m13; const m14 = m.m14;
if (m00 === 1 && m01 === 0 && m02 === 0
&& m04 === 0 && m05 === 1 && m06 === 0
&& m08 === 0 && m09 === 0 && m10 === 1
&& m12 === 0 && m13 === 0 && m14 === 0) return;
const floats = new Float32Array(vbuf.buffer, vbuf.byteOffset, byteLength >> 2);
const strideF = stride >> 2;
const vertexCount = byteLength / stride;
for (let i = 0; i < vertexCount; i++) {
const o = i * strideF;
const x = floats[o];
const y = floats[o + 1];
const z = floats[o + 2];
floats[o] = m00 * x + m04 * y + m08 * z + m12;
floats[o + 1] = m01 * x + m05 * y + m09 * z + m13;
floats[o + 2] = m02 * x + m06 * y + m10 * z + m14;
}
}
/**
* Cascaded opacity as Batcher2D.walk accumulates it for COLOR data: own
* color alpha x, per ancestor, localOpacity x that ancestor's color alpha.
*/
private _computeCascadedOpacity (): number {
let opacity = this._color.a / 255;
for (let node: Node | null = this.node; node; node = node.parent) {
opacity *= node._uiProps.localOpacity;
if (node !== this.node) {
const ancestor = node._uiProps.uiComp as UIRenderer | null;
if (ancestor && ancestor.color) opacity *= ancestor.color.a / 255;
}
}
return opacity;
}
/**
* Folds opacity into the copied vertices. Light color sits at bytes
* 20..23 (pos*3f + uv*2f), dark at 24..27 for two-color. Straight data
* fades via the alpha byte only; PMA data scales light RGBA + dark RGB
* (dark alpha is the sentinel, not a fade channel).
*/
private _applyOpacity (vU8: Uint8Array, vc: number, stride: number, opacity: number): void {
const pma = this._premultipliedAlpha;
const darkRGB = (pma && stride === MESH_STRIDE_TINT_BYTES) ? 3 : 0;
for (let i = 0; i < vc; i++) {
const o = i * stride + 20;
if (pma) {
vU8[o] = (vU8[o] * opacity + 0.5) | 0;
vU8[o + 1] = (vU8[o + 1] * opacity + 0.5) | 0;
vU8[o + 2] = (vU8[o + 2] * opacity + 0.5) | 0;
}
vU8[o + 3] = (vU8[o + 3] * opacity + 0.5) | 0;
for (let j = 0; j < darkRGB; j++) {
vU8[o + 4 + j] = (vU8[o + 4 + j] * opacity + 0.5) | 0;
}
}
}
private _prepareNativeDrawInfos (): void {
this._renderEntity.clearDynamicRenderDrawInfos();
// Vertex refresh + this frame's index submission; a null return means
// there is nothing drawable this frame.
const prepared = this._prepareBuffers();
const data = this._meshData;
const rd = this._renderData;
if (!prepared || !data || !rd?.chunk) return;
const { startIndex } = prepared;
let drawIndex = 0;
for (const seg of data.segments) {
const mat = seg.material || this.getRenderMaterial(0);
if (!seg.texture || !mat) continue;
let drawInfo = this._drawInfoList[drawIndex];
if (!drawInfo) {
drawInfo = new RenderDrawInfo();
drawInfo.setDrawInfoType(RenderDrawInfoType.MIDDLEWARE);
this._drawInfoList[drawIndex] = drawInfo;
}
drawInfo.setAccAndBuffer(rd.accessor.id, rd.chunk.bufferId);
drawInfo.setIndexOffset(startIndex + seg.indexOffset);
drawInfo.setIBCount(seg.indexCount);
drawInfo.setTexture(seg.texture.getGFXTexture());
drawInfo.setSampler(seg.texture.getGFXSampler());
drawInfo.setMaterial(mat);
this._renderEntity.setDynamicRenderDrawInfo(drawInfo, drawIndex);
drawIndex++;
}
}
/**
* The spine effect (default-spine-material): ui-sprite-material has no
* USE_LOCAL variant — node-local input through it would render stuck at
* the origin.
*/
protected _updateBuiltinMaterial (): Material {
return builtinResMgr.get<Material>('default-spine-material');
}
/**
* Keeps the builtin material instance in step with the declared vertex
* space / data format: USE_LOCAL for the GPU take-over mode, TWO_COLORED
* for two-color data, and blend factors matching the alpha format.
*/
public updateMaterial (): void {
// Align the legacy blend-factor fields first so _updateBlendFunc
// (inside super) never fights the explicit patching below.
this._srcBlendFactor = this._premultipliedAlpha ? BlendFactor.ONE : BlendFactor.SRC_ALPHA;
this._dstBlendFactor = BlendFactor.ONE_MINUS_SRC_ALPHA;
super.updateMaterial();
if (this._customMaterial) return; // custom materials are the user's contract
const inst = this.getMaterialInstance(0);
if (!inst) return;
inst.recompileShaders({
USE_LOCAL: !this._enableBatch,
TWO_COLORED: this._useTint,
});
// Straight data: src_alpha / 1-src_alpha (the effect default);
// premultiplied data: ONE / 1-src_alpha, color and alpha channels.
const src = this._premultipliedAlpha ? BlendFactor.ONE : BlendFactor.SRC_ALPHA;
const pass = inst.passes[0];
const target = pass.blendState.targets[0];
target.blend = true;
target.blendSrc = src;
target.blendSrcAlpha = src;
target.blendDst = BlendFactor.ONE_MINUS_SRC_ALPHA;
target.blendDstAlpha = BlendFactor.ONE_MINUS_SRC_ALPHA;
pass.blendState.setTarget(0, target);
pass._updatePassHash();
}
protected createRenderEntity (): RenderEntity {
const entity = new RenderEntity(RenderEntityType.DYNAMIC);
// useLocal is re-derived in _syncTransformMode once deserialization
// has run.
entity.setUseLocal(!this._enableBatch);
return entity;
}
private ensureAccessor (useTint: boolean): StaticVBAccessor {
const batcher = director.root!.batcher2D;
// The previous batcher destroyed its accessors — invalidate the cache.
if (_accessorBatcher !== batcher) {
_accessorBatcher = batcher;
_sharedAccessor = null;
_sharedTintAccessor = null;
}
let accessor = useTint ? _sharedTintAccessor : _sharedAccessor;
if (!accessor) {
const device = director.root!.device;
// Copy the format: the accessor empties its attributes array on
// destroy, and the vfmt* constants are shared module-level state.
const attributes = (useTint ? vfmtPosUvTwoColor4B : vfmtPosUvColor4B).slice();
// 32767: the spine middleware assembler's per-chunk cap
// (cocos/spine/assembler/simple.ts), half the Uint16 index space.
accessor = new StaticVBAccessor(device, attributes, 32767);
batcher.registerBufferAccessor(useTint ? UIMESH_TINT_ACCESSOR_KEY : UIMESH_ACCESSOR_KEY, accessor);
if (useTint) {
_sharedTintAccessor = accessor;
} else {
_sharedAccessor = accessor;
}
}
return accessor;
}
}
+2 -2
View File
@@ -29,7 +29,7 @@ import { EDITOR_NOT_IN_PREVIEW } from 'internal:constants';
import { Camera, CameraEvent } from '../../misc/camera-component';
import { Widget } from '../../ui/widget';
import { Vec3, screen, Enum, cclegacy, visibleRect } from '../../core';
import { view } from '../../ui/view';
import { toUISpace, view } from '../../ui/view';
import { RenderRoot2D } from './render-root-2d';
const _worldPos = new Vec3();
@@ -226,7 +226,7 @@ export class Canvas extends RenderRoot2D {
this._cameraComponent.orthoHeight = visibleRect.height / 2;
} else {
const size = screen.windowSize;
this._cameraComponent.orthoHeight = size.height / view.getScaleY() / 2;
this._cameraComponent.orthoHeight = toUISpace(size.height, view.getRatioY()) / 2;
}
this.node.getWorldPosition(_worldPos);
+41 -6
View File
@@ -395,24 +395,59 @@ export class MeshBuffer {
}
const byteCount = this.byteOffset;
const indexCount = this.indexOffset;
const indexBytes = indexCount * 2;
let allUploaded = true;
for (let i = 0; i < submitCount; ++i) {
const iaRef = this._iaPool[i];
const verticesData = new Float32Array(this.vData.buffer, 0, byteCount >> 2);
let verticesData = new Float32Array(this.vData.buffer, 0, byteCount >> 2);
const indicesData = new Uint16Array(this.iData.buffer, 0, indexCount);
let requiredVertexBytes = byteCount;
const vertexBuffer = iaRef.vertexBuffers[0];
if (byteCount > vertexBuffer.size) {
vertexBuffer.resize(byteCount);
if (byteCount > vertexBuffer.size && indexCount > 0) {
let maxVertex = 0;
for (let j = 0; j < indexCount; ++j) {
if (indicesData[j] > maxVertex) {
maxVertex = indicesData[j];
}
}
const actualByteCount = (maxVertex + 1) * this._vertexFormatBytes;
if (actualByteCount < byteCount) {
requiredVertexBytes = actualByteCount;
if (actualByteCount > vertexBuffer.size) {
vertexBuffer.resize(actualByteCount);
}
verticesData = new Float32Array(this.vData.buffer, 0, actualByteCount >> 2);
}
}
}
vertexBuffer.update(verticesData);
if (indexCount * 2 > iaRef.indexBuffer.size) {
iaRef.indexBuffer.resize(indexCount * 2);
const indexBuffer = iaRef.indexBuffer;
if (indexBytes > indexBuffer.size) {
indexBuffer.resize(indexBytes);
}
iaRef.indexBuffer.update(indicesData);
if (vertexBuffer.size < requiredVertexBytes || indexBuffer.size < indexBytes) {
allUploaded = false;
if (iOS14) {
iaRef.ia.indexCount = 0;
} else {
for (let k = 0; k < this._nextFreeIAHandle; ++k) {
this._iaPool[k].ia.indexCount = 0;
}
}
continue;
}
vertexBuffer.update(verticesData);
indexBuffer.update(indicesData);
}
if (allUploaded) {
this.dirty = false;
}
this.dirty = false;
}
private createNewIA (device: Device): IIARef {
+4
View File
@@ -735,6 +735,10 @@ export class MeshRenderData extends BaseRenderData {
this._vertexBuffers[0].destroy();
this._vertexBuffers = [];
}
if (this._indexBuffer) {
this._indexBuffer.destroy();
this._indexBuffer = null!;
}
this._iaInfo = null!;
this.vData = new Float32Array(256 * this.stride);
this.iData = new Uint16Array(256 * 6);
+6
View File
@@ -85,6 +85,12 @@ export class StaticVBAccessor extends BufferAccessor {
private _id = 0;
get id (): number { return this._id; }
/** Per-chunk capacity; allocateChunk refuses requests above these. */
get maxVertexCount (): number { return this._vCount; }
/** Per-chunk index capacity; allocateChunk refuses requests above these. */
get maxIndexCount (): number { return this._iCount; }
public constructor (device: Device, attributes: Attribute[], vCount?: number, iCount?: number) {
super(device, attributes);
this._vCount = vCount || Math.floor(macro.BATCHER2D_MEM_INCREMENT * 1024 / this._vertexFormatBytes);
+71
View File
@@ -0,0 +1,71 @@
/*
Copyright (c) 2026 Xiamen Yaji Software Co., Ltd.
https://www.cocos.com/
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/
/** A CSS family expression, distinct from an asset's raw font name. */
export type CssFontFamily = string & { readonly __cssFontFamily: unique symbol };
export const DEFAULT_FONT_FAMILY = 'Arial' as CssFontFamily;
/** Serialize one raw family name as a CSS string, preserving literal quotes and commas. */
export function quoteFontFamily (name: string): CssFontFamily {
let result = '"';
for (const character of name) {
const code = character.codePointAt(0)!;
if (code === 0 || (code >= 0xD800 && code <= 0xDFFF)) {
result += '\uFFFD';
} else if (code <= 0x1F || code === 0x7F) {
result += `\\${code.toString(16)} `;
} else if (character === '"' || character === '\\') {
result += `\\${character}`;
} else {
result += character;
}
}
return `${result}"` as CssFontFamily;
}
/** A simple generated alias is already a CSS identifier and cannot be a reserved family keyword. */
export function serializeFontFamily (name: string): CssFontFamily {
// Some Canvas implementations only recognize the bare alias registered by the font loader.
return /^[A-Za-z_][A-Za-z0-9_-]*_LABEL$/.test(name) ? name as CssFontFamily : quoteFontFamily(name);
}
interface FontFamilySource {
readonly useSystemFont: boolean;
readonly fontFamily: string;
readonly font: { readonly _nativeAsset: unknown } | null;
}
/** Resolve at the component boundary, before measurement, drawing or CSS assignment. */
export function getCanvasFontFamily (source: FontFamilySource): CssFontFamily {
const system = source.useSystemFont;
const value = system ? source.fontFamily : source.font?._nativeAsset;
const name = typeof value === 'string' && value ? value : DEFAULT_FONT_FAMILY;
return system ? name as CssFontFamily : serializeFontFamily(name);
}
/** Family is already serialized: changing size or style must never quote it again. */
export function buildFontDesc (size: number, family: CssFontFamily, bold = false, italic = false): string {
return `${italic ? 'italic ' : ''}${bold ? 'bold ' : ''}${size}px ${family}`;
}
+19 -21
View File
@@ -23,7 +23,7 @@
*/
import { warnID } from '../../core';
import { safeMeasureText } from './text-utils';
import { buildFontDesc, serializeFontFamily } from './font-family';
import downloader from '../../asset/asset-manager/downloader';
import factory from '../../asset/asset-manager/factory';
import { TTFFont } from '../assets/ttf-font';
@@ -31,10 +31,13 @@ import { ccwindow } from '../../core/global-exports';
const ccdocument = ccwindow.document;
type FontCallback = (err: Error | null, family?: string) => void;
interface IFontLoadHandle {
fontFamilyName: string;
fontDesc: string;
refWidth: number;
onComplete: ((err: Error | null, data?: any | null) => void);
onComplete: FontCallback;
startTime: number;
}
@@ -90,9 +93,9 @@ function checkFontLoaded (): void {
}
const oldWidth = fontLoadHandle.refWidth;
const fontDesc = `40px ${fontFamily}`;
_canvasContext!.font = fontDesc;
const newWidth = safeMeasureText(_canvasContext!, _testString, fontDesc);
_canvasContext!.font = fontLoadHandle.fontDesc;
// Font availability changes while loading; do not cache fallback-font metrics.
const newWidth = _canvasContext!.measureText(_testString).width;
// loaded successfully
if (oldWidth !== newWidth) {
_loadingFonts.splice(i, 1);
@@ -109,7 +112,7 @@ function checkFontLoaded (): void {
}
// refer to https://github.com/typekit/webfontloader/blob/master/src/core/nativefontwatchrunner.js
function nativeCheckFontLoaded (start: number, font: string, callback: ((err: Error | null, data?: any | null) => void)): void {
function nativeCheckFontLoaded (start: number, font: string, fontDesc: string, callback: FontCallback): void {
const loader = new Promise<void>((resolve, reject) => {
const check = (): void => {
const now = Date.now();
@@ -117,7 +120,7 @@ function nativeCheckFontLoaded (start: number, font: string, callback: ((err: Er
if (now - start >= _timeout) {
reject();
} else {
(ccdocument as any).fonts.load(`40px ${font}`).then((fonts) => {
(ccdocument as any).fonts.load(fontDesc).then((fonts) => {
if (fonts.length >= 1) {
resolve();
} else {
@@ -150,7 +153,7 @@ function nativeCheckFontLoaded (start: number, font: string, callback: ((err: Er
});
}
export function loadFont (url: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)): void {
export function loadFont (url: string, options: Record<string, any>, onComplete: FontCallback): void {
const fontFamilyName = getFontFamily(url);
// Already loaded fonts
if (_fontFaces[fontFamilyName]) {
@@ -166,17 +169,13 @@ export function loadFont (url: string, options: Record<string, any>, onComplete:
}
// Default width reference to test whether new font is loaded correctly
const fontDesc = `40px ${fontFamilyName}`;
const familyCss = serializeFontFamily(fontFamilyName);
const fontDesc = buildFontDesc(40, familyCss);
// Setup font face style
const fontStyle = ccdocument.createElement('style');
fontStyle.type = 'text/css';
let fontStr = '';
if (Number.isNaN(fontFamilyName)) {
fontStr += `@font-face { font-family:${fontFamilyName}; src:`;
} else {
fontStr += `@font-face { font-family:"${fontFamilyName}"; src:`;
}
let fontStr = `@font-face { font-family:${familyCss}; src:`;
fontStr += `url("${url}");`;
fontStyle.textContent = `${fontStr}}`;
ccdocument.body.appendChild(fontStyle);
@@ -184,7 +183,7 @@ export function loadFont (url: string, options: Record<string, any>, onComplete:
// Preload font with div
const preloadDiv = ccdocument.createElement('div');
const divStyle = preloadDiv.style;
divStyle.fontFamily = fontFamilyName;
divStyle.fontFamily = familyCss;
preloadDiv.innerHTML = '.';
divStyle.position = 'absolute';
divStyle.left = '-100px';
@@ -192,12 +191,14 @@ export function loadFont (url: string, options: Record<string, any>, onComplete:
ccdocument.body.appendChild(preloadDiv);
if (useNativeCheck()) {
nativeCheckFontLoaded(Date.now(), fontFamilyName, onComplete);
nativeCheckFontLoaded(Date.now(), fontFamilyName, fontDesc, onComplete);
} else {
const refWidth = safeMeasureText(_canvasContext!, _testString, fontDesc);
_canvasContext!.font = fontDesc;
const refWidth = _canvasContext!.measureText(_testString).width;
// Save loading font
const fontLoadHandle = {
fontFamilyName,
fontDesc,
refWidth,
onComplete,
startTime: Date.now(),
@@ -221,9 +222,6 @@ export function getFontFamily (fontHandle: string): string {
} else {
fontFamilyName = `${fontHandle.substring(slashPos + 1, ttfIndex)}_LABEL`;
}
if (fontFamilyName.indexOf(' ') !== -1) {
fontFamilyName = `"${fontFamilyName}"`;
}
return fontFamilyName;
}
+7
View File
@@ -106,6 +106,13 @@ export class BakedSkinningModel extends MorphModel {
UBOSkinningTexture.SIZE,
));
}
// The animation buffer belongs to the skinning root. Refresh its binding without
// rebuilding the instanced attribute block, which would erase custom attribute values.
for (let i = 0; i < this._subModels.length; i++) {
this._updateLocalDescriptors(i, this._subModels[i].descriptorSet);
}
this.updateInstancedJointTextureInfo();
}
// Override
+10
View File
@@ -142,6 +142,7 @@ export class SkinningModel extends MorphModel {
}
this._bufferIndices = null; this._joints.length = 0;
if (!skeleton || !skinningRoot || !mesh) { return; }
const prevRealTimeTextureMode = this._realTimeTextureMode;
this._realTimeTextureMode = false;
if (UBOSkinning.JOINT_UNIFORM_CAPACITY < skeleton.joints.length) { this._realTimeTextureMode = true; }
this.transform = skinningRoot;
@@ -161,6 +162,15 @@ export class SkinningModel extends MorphModel {
if (!jointMaps) { indices.push(index); buffers.push(0); } else { getRelevantBuffers(indices, buffers, jointMaps, index); }
this._joints.push({ indices, buffers, bound, target, bindpose, transform });
}
// Rebind recreated joint resources without resetting user-provided instanced attributes.
const subModelCount = Math.min(this._subModels.length, this._bufferIndices.length);
if (subModelCount && prevRealTimeTextureMode !== this._realTimeTextureMode) {
this.onMacroPatchesStateChanged();
}
for (let i = 0; i < subModelCount; i++) {
this._updateLocalDescriptors(i, this._subModels[i].descriptorSet);
}
}
/**
@@ -177,21 +177,21 @@ export class SkinnedMeshBatchRenderer extends SkinnedMeshRenderer {
@override
@visible(false)
get mesh (): Mesh | null {
return super.mesh;
return Reflect.get(SkinnedMeshRenderer.prototype, 'mesh', this);
}
set mesh (val) {
super.mesh = val;
Reflect.set(SkinnedMeshRenderer.prototype, 'mesh', val, this);
}
@override
@visible(false)
get skeleton (): Skeleton | null {
return super.skeleton;
return Reflect.get(SkinnedMeshRenderer.prototype, 'skeleton', this);
}
set skeleton (val) {
super.skeleton = val;
Reflect.set(SkinnedMeshRenderer.prototype, 'skeleton', val, this);
}
public onLoad (): void {
+26 -5
View File
@@ -53,6 +53,19 @@ const _windowInfo: IRenderWindowInfo = {
renderPassInfo: passInfo,
};
// The legacy limit used only when the GPU capability is unavailable,
// e.g. in editor or during asset deserialization.
const FALLBACK_MAX_RENDER_TEXTURE_SIZE = 2048;
/**
* @en Gets the maximum render texture size supported by the current GPU, or null if it is unknown.
* @zh 获取当前 GPU 支持的最大渲染贴图尺寸,未知时返回 null。
*/
function getMaxRenderTextureSize (): number | null {
const maxTextureSize = deviceManager.gfxDevice?.capabilities.maxTextureSize;
return maxTextureSize && maxTextureSize > 0 ? maxTextureSize : null;
}
/**
* @en Render texture is a render target for [[Camera]] or [[Canvas]] component,
* the render pipeline will use its `RenderWindow` as the target of the rendering process.
@@ -111,12 +124,17 @@ export class RenderTexture extends TextureBase {
/**
* @en Resize the render texture.
* @zh 修改渲染贴图的尺寸。
* @param width @en The pixel width to resize to, the range is from 1 to 2048. @zh 需要调整到的像素宽度,范围为 1-2048。
* @param height @en The pixel height to resize to, the range is from 1 to 2048. @zh 需要调整到的像素高度,范围为 1-2048。
* @param width @en The pixel width to resize to, the range is from 1 to the GPU max texture size.
* @zh 需要调整到的像素宽度,范围为 1 到当前 GPU 支持的最大贴图尺寸。
* @param height @en The pixel height to resize to, the range is from 1 to the GPU max texture size.
* @zh 需要调整到的像素高度,范围为 1 到当前 GPU 支持的最大贴图尺寸。
* Note: if the GPU limit is unavailable, the legacy 2048 limit is used as a fallback.
* @zh 注意:如果无法获取 GPU 上限,则回退到旧的 2048 限制。
*/
public resize (width: number, height: number): void {
this._width = Math.floor(clamp(width, 1, 2048));
this._height = Math.floor(clamp(height, 1, 2048));
const maxSize = getMaxRenderTextureSize() ?? FALLBACK_MAX_RENDER_TEXTURE_SIZE;
this._width = Math.floor(clamp(width, 1, maxSize));
this._height = Math.floor(clamp(height, 1, maxSize));
if (this._window) {
this._window.resize(this._width, this._height);
}
@@ -214,7 +232,10 @@ export class RenderTexture extends TextureBase {
* @deprecated Since v3.7, this is an internal engine interface and you should not call this interface under any circumstances.
*/
public validate (): boolean {
return this.width >= 1 && this.width <= 2048 && this.height >= 1 && this.height <= 2048;
const maxSize = getMaxRenderTextureSize();
const validLowerBound = this.width >= 1 && this.height >= 1;
// If the GPU limit is unknown, only validate the lower bound instead of rejecting a possibly valid asset.
return validLowerBound && (maxSize === null || (this.width <= maxSize && this.height <= maxSize));
}
/**
+1 -1
View File
@@ -45,5 +45,5 @@ export {
DebugMode,
} from './debug';
export { screen } from './screen';
export { screen, MaxDPR } from './screen';
export type { Screen } from './screen';
+65 -6
View File
@@ -25,12 +25,36 @@
THE SOFTWARE.
*/
import { screenAdapter } from 'pal/screen-adapter';
import { screenAdapter, IScreenOptions } from 'pal/screen-adapter';
import { systemInfo } from 'pal/system-info';
import { OS } from '../../../pal/system-info/enum-type';
import { legacyCC } from '../global-exports';
import { Size } from '../math';
import { settings, SettingsCategory } from '../settings';
import { error, warn, warnID } from './debug';
import { PalScreenEvent } from '../../../pal/screen-adapter/enum-type';
import { error, getError, warn, warnID } from './debug';
import type { PalScreenEvent } from '../../../pal/screen-adapter/enum-type';
/**
* @en Presets for the Web startup setting `screen.maxDevicePixelRatio`.
* Store the preset's numeric value or any finite number >= 1 in the startup settings.
* An omitted or null setting keeps the default cap of 2. Effective DPR never exceeds the browser DPR.
* Configure before Screen initialization; changing settings afterward does not resize the running game.
* Non-Web platforms ignore this setting. Higher caps increase pixel-related rendering costs.
* @zh Web 启动配置 `screen.maxDevicePixelRatio` 的预设档位。
* 在启动配置中保存预设的数值或任意有限且 >=1 的数字。
* 未配置或为 null 时保留默认上限 2,实际 DPR 不超过浏览器 DPR。
* 需在 Screen 初始化前配置,之后修改 settings 不会调整运行中游戏的分辨率。
* 非 Web 平台忽略该配置;提高上限会增加像素相关的渲染开销。
*/
export enum MaxDPR {
/** @en Cap DPR at 1 to reduce rendering cost. @zh 上限为 1,优先降低渲染开销。 */
Performance = 1,
/** @en Cap DPR at 2, matching the existing default. @zh 上限为 2,与现有默认策略一致。 */
Balanced = 2,
/** @en Cap DPR at 4 for higher-density rendering. @zh 上限为 4,允许更高密度渲染。 */
Quality = 4,
}
/**
* @en The screen API provides an easy way to do some screen managing stuff.
* @zh screen 单例对象提供简单的方法来做屏幕管理相关的工作。
@@ -40,10 +64,18 @@ export class Screen {
* @internal
*/
public init (): void {
// PAL decides whether to consume the setting and validates its value.
const maximum = settings.querySettings<number>(SettingsCategory.SCREEN, 'maxDevicePixelRatio');
const exactFitScreen = settings.querySettings(SettingsCategory.SCREEN, 'exactFitScreen') ?? true;
const orientation = settings.querySettings(SettingsCategory.SCREEN, 'orientation') ?? 'auto';
const isHeadlessMode = settings.querySettings(SettingsCategory.RENDERING, 'renderMode') === 3;
screenAdapter.init({ exactFitScreen, configOrientation: orientation, isHeadlessMode }, (): void => {
const options: IScreenOptions & { maxDevicePixelRatio?: number | null } = {
exactFitScreen, configOrientation: orientation, isHeadlessMode,
};
if (maximum != null) {
options.maxDevicePixelRatio = maximum;
}
screenAdapter.init(options, (): void => {
const director = legacyCC.director;
if (!director.root?.pipeline) {
warnID(1220);
@@ -51,6 +83,13 @@ export class Screen {
}
director.root.pipeline.shadingScale = screenAdapter.resolutionScale;
});
// Only adapters exposing this capability are expected to apply the setting.
// The property check also narrows concrete adapter types in Native TS builds.
if (maximum != null
&& 'maxDevicePixelRatio' in screenAdapter
&& screenAdapter.maxDevicePixelRatio !== maximum) {
throw new Error(getError(9205));
}
}
/**
@@ -64,6 +103,18 @@ export class Screen {
return screenAdapter.devicePixelRatio;
}
/**
* @en Controls whether the screen stays on while the app is in the foreground.
* Supported on native Android and iOS. Has no effect on other platforms.
* @zh 控制应用在前台时是否保持屏幕常亮。仅在 Android 和 iOS 原生平台生效。
* @param enabled @en Pass true to keep the screen on or false to restore normal screen timeout. @zh 传入 true 开启常亮,传入 false 恢复系统的自动熄屏行为。
*/
public setKeepScreenOn (enabled: boolean): void {
if (systemInfo.isNative && (systemInfo.os === OS.ANDROID || systemInfo.os === OS.IOS)) {
jsb.device.setKeepScreenOn(enabled);
}
}
/**
* @en Get and set the size of current window in physical pixels.
* NOTE:
@@ -137,7 +188,11 @@ export class Screen {
* @return {Promise|undefined}
* @deprecated since v3.3, please use `screen.requestFullScreen(): Promise<void>` instead.
*/
public requestFullScreen (element: HTMLElement, onFullScreenChange?: (this: Document, ev: any) => any, onFullScreenError?: (this: Document, ev: any) => any): Promise<any> | undefined;
public requestFullScreen (
element: HTMLElement,
onFullScreenChange?: (this: Document, ev: any) => any,
onFullScreenError?: (this: Document, ev: any) => any,
): Promise<any> | undefined;
/**
* @en Request to enter full screen mode.
* Many browsers forbid to enter full screen mode without an user intended interaction.
@@ -150,7 +205,11 @@ export class Screen {
* @return {Promise}
*/
public requestFullScreen (): Promise<void>;
public requestFullScreen (element?: HTMLElement, onFullScreenChange?: (this: Document, ev?: any) => any, onFullScreenError?: (this: Document, ev?: any) => any): Promise<any> {
public requestFullScreen (
element?: HTMLElement,
onFullScreenChange?: (this: Document, ev?: any) => any,
onFullScreenError?: (this: Document, ev?: any) => any,
): Promise<any> {
if (arguments.length > 0) {
warnID(1400, 'screen.requestFullScreen(element, onFullScreenChange?, onFullScreenError?)', 'screen.requestFullScreen(): Promise');
}
+4 -1
View File
@@ -47,6 +47,9 @@ export class EmptyBuffer extends Buffer {
}
}
public destroy (): void {}
public resize (size: number): void {}
public resize (size: number): void {
this._size = size;
this._count = this._size / this._stride;
}
public update (buffer: Readonly<BufferSource>, size?: number): void {}
}
+14 -6
View File
@@ -33,7 +33,7 @@ import {
} from './webgl-commands';
import { IWebGLGPUBuffer, IWebGLGPUBufferView, WebGLIndirectDrawInfos } from './webgl-gpu-objects';
import { WebGLDeviceManager } from './webgl-define';
import { warnID } from '../../core/platform/debug';
import { warn, warnID } from '../../core/platform/debug';
/** @mangle */
export class WebGLBuffer extends Buffer {
@@ -48,6 +48,7 @@ export class WebGLBuffer extends Buffer {
private _gpuBuffer: IWebGLGPUBuffer | null = null;
private _gpuBufferView: IWebGLGPUBufferView | null = null;
private _uniformBuffer: Uint8Array | null = null;
private _lastFailedSize = 0;
constructor () {
super();
@@ -125,9 +126,6 @@ export class WebGLBuffer extends Buffer {
const oldSize = this._size;
if (oldSize === size) { return; }
this._size = size;
this._count = this._size / this._stride;
if (this._uniformBuffer) {
this._uniformBuffer = new Uint8Array(size);
}
@@ -140,8 +138,18 @@ export class WebGLBuffer extends Buffer {
this._gpuBuffer.size = size;
if (size > 0) {
WebGLCmdFuncResizeBuffer(WebGLDeviceManager.instance, this._gpuBuffer);
WebGLDeviceManager.instance.memoryStatus.bufferSize -= oldSize;
WebGLDeviceManager.instance.memoryStatus.bufferSize += size;
}
this._size = this._gpuBuffer.size;
this._count = this._size / this._stride;
WebGLDeviceManager.instance.memoryStatus.bufferSize -= oldSize;
WebGLDeviceManager.instance.memoryStatus.bufferSize += this._size;
if (this._size !== size) {
if (this._lastFailedSize !== size) {
this._lastFailedSize = size;
warn(`WebGLBuffer[${this.objectID}] (usage: ${this._usage}) resize failed to reach requested size: requested ${size} bytes, actual ${this._size} bytes.`);
}
} else {
this._lastFailedSize = 0;
}
}
}
+5
View File
@@ -574,6 +574,8 @@ export function WebGLCmdFuncResizeBuffer (device: WebGLDevice, gpuBuffer: IWebGL
} else {
gl.bufferData(WebGLConstants.ARRAY_BUFFER, gpuBuffer.size, glUsage);
}
gpuBuffer.size = gl.getBufferParameter(WebGLConstants.ARRAY_BUFFER, WebGLConstants.BUFFER_SIZE) as number;
gl.bindBuffer(WebGLConstants.ARRAY_BUFFER, null);
stateCache.glArrayBuffer = null;
} else if (gpuBuffer.usage & BufferUsageBit.INDEX) {
@@ -594,6 +596,8 @@ export function WebGLCmdFuncResizeBuffer (device: WebGLDevice, gpuBuffer: IWebGL
} else {
gl.bufferData(WebGLConstants.ELEMENT_ARRAY_BUFFER, gpuBuffer.size, glUsage);
}
gpuBuffer.size = gl.getBufferParameter(WebGLConstants.ELEMENT_ARRAY_BUFFER, WebGLConstants.BUFFER_SIZE) as number;
gl.bindBuffer(WebGLConstants.ELEMENT_ARRAY_BUFFER, null);
stateCache.glElementArrayBuffer = null;
} else if (gpuBuffer.usage & BufferUsageBit.UNIFORM) {
@@ -630,6 +634,7 @@ export function WebGLCmdFuncUpdateBuffer (
gpuBuffer.indirects.setDrawInfo(offset + i, drawInfos[i]);
}
} else {
if (size > gpuBuffer.size) { return; }
const buff = buffer as ArrayBuffer;
const { gl, stateCache } = device;
+14 -6
View File
@@ -22,7 +22,7 @@
THE SOFTWARE.
*/
import { warnID } from '../../core/platform/debug';
import { warn, warnID } from '../../core/platform/debug';
import { Buffer } from '../base/buffer';
import { BufferUsageBit, BufferSource, BufferInfo, BufferViewInfo } from '../base/define';
import {
@@ -45,6 +45,7 @@ export class WebGL2Buffer extends Buffer {
}
private _gpuBuffer: IWebGL2GPUBuffer | null = null;
private _lastFailedSize = 0;
public initialize (info: Readonly<BufferInfo> | Readonly<BufferViewInfo>): void {
if ('buffer' in info) { // buffer view
@@ -114,15 +115,22 @@ export class WebGL2Buffer extends Buffer {
const oldSize = this._size;
if (oldSize === size) { return; }
this._size = size;
this._count = this._size / this._stride;
if (this._gpuBuffer) {
this._gpuBuffer.size = size;
if (size > 0) {
WebGL2CmdFuncResizeBuffer(WebGL2DeviceManager.instance, this._gpuBuffer);
WebGL2DeviceManager.instance.memoryStatus.bufferSize -= oldSize;
WebGL2DeviceManager.instance.memoryStatus.bufferSize += size;
}
this._size = this._gpuBuffer.size;
this._count = this._size / this._stride;
WebGL2DeviceManager.instance.memoryStatus.bufferSize -= oldSize;
WebGL2DeviceManager.instance.memoryStatus.bufferSize += this._size;
if (this._size !== size) {
if (this._lastFailedSize !== size) {
this._lastFailedSize = size;
warn(`WebGL2Buffer[${this.objectID}] (usage: ${this._usage}) resize failed to reach requested size: requested ${size} bytes, actual ${this._size} bytes.`);
}
} else {
this._lastFailedSize = 0;
}
}
}
+7
View File
@@ -770,6 +770,8 @@ export function WebGL2CmdFuncResizeBuffer (device: WebGL2Device, gpuBuffer: IWeb
} else {
gl.bufferData(WebGLConstants.ARRAY_BUFFER, gpuBuffer.size, glUsage);
}
gpuBuffer.size = gl.getBufferParameter(WebGLConstants.ARRAY_BUFFER, WebGLConstants.BUFFER_SIZE) as number;
gl.bindBuffer(WebGLConstants.ARRAY_BUFFER, null);
cache.glArrayBuffer = null;
} else if (gpuBuffer.usage & BufferUsageBit.INDEX) {
@@ -790,6 +792,8 @@ export function WebGL2CmdFuncResizeBuffer (device: WebGL2Device, gpuBuffer: IWeb
} else {
gl.bufferData(WebGLConstants.ELEMENT_ARRAY_BUFFER, gpuBuffer.size, glUsage);
}
gpuBuffer.size = gl.getBufferParameter(WebGLConstants.ELEMENT_ARRAY_BUFFER, WebGLConstants.BUFFER_SIZE) as number;
gl.bindBuffer(WebGLConstants.ELEMENT_ARRAY_BUFFER, null);
cache.glElementArrayBuffer = null;
} else if (gpuBuffer.usage & BufferUsageBit.UNIFORM) {
@@ -798,6 +802,8 @@ export function WebGL2CmdFuncResizeBuffer (device: WebGL2Device, gpuBuffer: IWeb
}
gl.bufferData(WebGLConstants.UNIFORM_BUFFER, gpuBuffer.size, glUsage);
gpuBuffer.size = gl.getBufferParameter(WebGLConstants.UNIFORM_BUFFER, WebGLConstants.BUFFER_SIZE) as number;
gl.bindBuffer(WebGLConstants.UNIFORM_BUFFER, null);
cache.glUniformBuffer = null;
} else if ((gpuBuffer.usage & BufferUsageBit.INDIRECT)
@@ -824,6 +830,7 @@ export function WebGL2CmdFuncUpdateBuffer (
gpuBuffer.indirects.setDrawInfo(offset + i, drawInfos[i]);
}
} else {
if (size > gpuBuffer.size) { return; }
const buff = buffer as ArrayBuffer;
const { gl } = device;
const cache = device.getStateCache();
+13 -5
View File
@@ -24,7 +24,7 @@
THE SOFTWARE.
*/
import { EDITOR_NOT_IN_PREVIEW, HTML5, NATIVE } from 'internal:constants';
import { EDITOR_NOT_IN_PREVIEW, HTML5, NATIVE, WECHAT } from 'internal:constants';
import { AccelerometerInputSource, GamepadInputDevice, HMDInputDevice, HandheldInputDevice,
HandleInputDevice, KeyboardInputSource, MouseInputSource, TouchInputSource } from 'pal/input';
import { touchManager } from '../../pal/input/touch-manager';
@@ -380,9 +380,15 @@ export class Input {
}
if (sys.hasFeature(sys.Feature.EVENT_MOUSE)) {
// Game View still needs mouse-to-touch simulation even when INPUT_TOUCH is true.
// WeChat PC already maps left mouse clicks to touch events.
// https://developers.weixin.qq.com/minigame/dev/guide/open-ability/pc-game.html
const shouldSimulateTouch = !(WECHAT && sys.hasFeature(sys.Feature.INPUT_TOUCH));
mouseInput.on(InputEventType.MOUSE_DOWN, (event): void => {
self._needSimulateTouchMoveEvent = true;
self._simulateEventTouch(event);
if (shouldSimulateTouch) {
self._needSimulateTouchMoveEvent = true;
self._simulateEventTouch(event);
}
self._dispatchEventMouse(event);
});
mouseInput.on(InputEventType.MOUSE_MOVE, (event): void => {
@@ -392,8 +398,10 @@ export class Input {
self._dispatchEventMouse(event);
});
mouseInput.on(InputEventType.MOUSE_UP, (event): void => {
self._needSimulateTouchMoveEvent = false;
self._simulateEventTouch(event);
if (shouldSimulateTouch) {
self._needSimulateTouchMoveEvent = false;
self._simulateEventTouch(event);
}
self._dispatchEventMouse(event);
});
mouseInput.on(InputEventType.MOUSE_WHEEL, (event): void => {
+6
View File
@@ -24,6 +24,12 @@
import './intersect';
// NOTE: the worker subsystem (`./worker`, `./worker-pool`) is deliberately
// NOT re-exported here. `cocos/misc` is part of the always-on `base` feature, so anything exported
// from this file ships in every build's main bundle. The worker subsystem is exposed through the
// optional `worker` and `worker-pool` features instead (see their entries in `exports/` and
// cc.config.json). Projects enabling only `worker` do not include the pool scheduler.
export { Camera } from './camera-component';
export { ModelRenderer } from './model-renderer';
export { Renderer } from './renderer';
+982
View File
@@ -0,0 +1,982 @@
/*
Copyright (c) 2018-2023 Xiamen Yaji Software Co., Ltd.
http://www.cocos.com
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/
import type { IPlatformWorkerBackend } from 'pal/worker';
import {
WorkerTask, IWorker, getOptimalWorkerCount,
getWorkerBackend, resetWorkerBackendCache,
} from './worker';
import { getError, warnID } from '../core/platform/debug';
/** Execution state, independent of the host platform. */
export type WorkerExecutionMode = 'worker' | 'sync' | 'none';
/**
* @en
* Infrastructure failures (a worker that never replies / times out, errors out, fails to spawn, or
* speaks a malformed protocol) tolerated before a script-mode pool gives up on the real worker and
* degrades to single-threaded execution via `options.fallback`. Kept at 1: each of these signals
* means the worker backend is not functioning for this script, so retrying on a real worker would
* only fail again — and on the seven single-worker mini-game platforms a retry would also re-occupy
* the one worker slot. A task-level computation error (the worker replies `{ ok: false }`) is NOT an
* infrastructure failure and never counts toward this.
* @zh
* 脚本模式的池在放弃真 Worker、降级为 `options.fallback` 单线程执行之前,所能容忍的**基础设施失败**
* 次数(Worker 永不回复 / 超时、报错、创建失败、或回发非法协议)。取 1:上述任一信号都意味着该脚本的
* Worker 后端不可用,再用真 Worker 重试只会再次失败——而且在 7 个单 Worker 小游戏平台上重试还会重新
* 占掉那唯一的槽位。任务级计算错误(Worker 回发 `{ ok: false }`)**不算**基础设施失败,不计入此数。
*/
const DEGRADE_AFTER_FAILURES = 1;
/**
* @en Options for [[WorkerPool]].
* @zh [[WorkerPool]] 的选项。
*/
export interface WorkerPoolOptions {
/**
* @en
* Maximum number of concurrent workers. Extra tasks are queued and dispatched when a worker frees up.
* Default is `1`.
* @zh
* 并发 Worker 的最大数量。多余的任务会排队,等某个 Worker 空闲后再派发。默认 `1`。
*/
maxWorkers?: number;
/**
* @en
* Idle release time in milliseconds. An idle worker is terminated after being idle for this long,
* to avoid keeping threads (and their memory) alive forever. Set to `0` to never release idle workers.
* Default is `1000` (1 second).
* @zh
* 空闲释放时间(毫秒)。Worker 空闲超过该时长后会被终止,避免线程(及其内存)长期驻留。
* 设为 `0` 表示永不释放空闲 Worker。默认 `1000`(1 秒)。
*/
idleReleaseAfter?: number;
/**
* @en
* Synchronous fallback task (**script mode only**). It must compute the same result as the worker
* script's `runTask(args)` from the same `args`. When NO worker backend is available at all —
* the platform worker environment is not fully set up ([[checkWorkerScript]] not ready), or the
* platform has no worker API (Taobao mini-game, native) and there is no global `Worker` either —
* tasks run single-threaded on the main thread with this function instead of rejecting. If omitted
* in that situation, `run()` rejects with a descriptive error.
* Runtime failures retry non-transferred arguments only. Transferred tasks reject because
* ownership has moved; subsequent tasks use this fallback. Fallback computation must be retry-safe.
* @zh
* 同步降级任务函数(**仅脚本模式**)。它必须与 worker 脚本里的 `runTask(args)` 用相同的 `args`
* 算出相同的结果。当所有 Worker 后端都不可用时——平台 Worker 环境未设置完整
* ([[checkWorkerScript]] 不 ready),或平台根本没有 Worker API(淘宝小游戏、原生)且也没有全局
* `Worker`——任务将用它在主线程**单线程**执行,而不是直接 reject。若此时未提供该函数,
* `run()` 会以带说明的错误 reject。
* 运行时失败仅重试未移交所有权的参数;已 transfer 的任务拒绝,后续任务仍使用 fallback。
* fallback 应为可安全重试的计算逻辑。
*/
fallback?: WorkerTask;
/**
* @en
* Per-task timeout in milliseconds. When exceeded, the task rejects with a timeout error and the
* worker running it is terminated so the pool spawns a fresh one.
*
* Default is `0` (no timeout). A timeout is the ONLY safety net against a worker that never
* replies — a worker script that fails to post back, or a worker silently reclaimed by the
* platform. Some platforms make this materially more likely: not every mini-game platform exposes
* `onError` (Huawei quick game documents only create/postMessage/onMessage/terminate), so an
* internal failure there produces no error event at all.
*
* Recommended for script mode in production: pick a bound well above your worst-case task duration.
* @zh
* 单个任务的超时时间(毫秒)。超时后任务以超时错误 reject,运行它的 Worker 会被终止,
* 池随后重建一个。
*
* 默认 `0`(不超时)。超时是对"Worker 永不回复"的**唯一**兜底——比如 Worker 脚本忘记回发结果,
* 或 Worker 被平台静默回收。部分平台让这种情况更容易发生:并非每个小游戏平台都暴露 `onError`
* (华为快游戏只文档化了 create/postMessage/onMessage/terminate),那里的内部失败根本不会产生错误事件。
*
* 生产环境的脚本模式建议设置超时:取一个明显高于最坏情况任务耗时的上界。
*/
timeout?: number;
}
/**
* @en
* A pool of workers bound to a single self-contained task function (function mode) or to a
* pre-packaged worker script (script mode — the only way to get a real worker on any mini-game
* platform, because they forbid rebuilding a function from source).
*
* It is designed for *high-frequency* workloads (e.g. per-frame physics / crowd simulation / data processing):
* instead of spawning and tearing down a worker for every call — which costs a Blob URL round-trip and
* thread startup — the pool keeps a bounded set of workers alive and reuses them, releasing idle workers
* after [[WorkerPoolOptions.idleReleaseAfter]].
*
* IMPORTANT — a pool is not always a source of parallelism. On seven of the nine mini-game platforms
* (ByteDance, Alipay, Baidu, Huawei, OPPO, vivo, Xiaomi) and on WeChat V1, the platform allows exactly
* ONE worker, so the pool is capped to one worker no matter what `maxWorkers` says. There it is an
* **asynchronous offload queue**: it keeps a long task off the main thread, but it cannot run two tasks
* at once. Gate features that need true parallelism on
* [[getWorkerCapabilities]]`()`.parallel, not on whether a worker exists.
*
* In function mode, on platforms that cannot build a worker from a serialized string (every mini-game
* platform, and native) each task simply runs synchronously on the main thread, so the pool is a
* transparent no-op wrapper. To get a real worker on a mini-game platform, use script mode:
* `new WorkerPool('workers/my-task/index.js')` — the pool then creates its worker from a pre-packaged
* script via `minigame.createWorker` (see the constructor and the bundled template).
*
* For *CPU-bound* workloads on a genuinely parallel platform, pass [[getOptimalWorkerCount]] as
* `maxWorkers` to parallelize across the available cores (leaving one core for the main thread). Note
* that `maxWorkers` only matters when you submit several independent tasks concurrently — a single
* queued task always uses exactly one worker.
*
* @zh
* 绑定到单个自包含任务函数(函数模式)或预打包 Worker 脚本(脚本模式——这是在任何小游戏平台上获得
* 真 Worker 的**唯一**方式,因为它们禁止用源码重建函数)的 Worker 池。
*
* 它面向*高频*负载(如逐帧的物理模拟、人群模拟、数据处理):与其每次调用都创建再销毁一个 Worker——
* 那会付出 Blob URL 往返和线程启动的成本——池会保活一个有上限的 Worker 集合并复用,
* 空闲超过 [[WorkerPoolOptions.idleReleaseAfter]] 的 Worker 会被释放。
*
* **重要——池并不总是并行来源。** 9 个小游戏平台中有 7 个(抖音、支付宝、百度、华为、OPPO、vivo、小米)
* 以及微信 V1,平台只允许**恰好 1 个** Worker,因此无论 `maxWorkers` 传什么,池都会被封顶到 1 个。
* 在这些平台上它是一个**异步卸载队列**:能把长任务从主线程挪走,但无法同时跑两个任务。
* 需要真并行的特性,请以 [[getWorkerCapabilities]]`()`.parallel 为准,而不是以"有没有 Worker"为准。
*
* 在函数模式下,凡是无法从序列化字符串构建 Worker 的平台(全部小游戏平台、原生),每个任务直接在主线程
* 同步执行,因此池是一个透明的空包装。小游戏平台上若要真 Worker,请用脚本模式:
* `new WorkerPool('workers/my-task/index.js')`——池会通过 `minigame.createWorker`
* 从预打包脚本创建 Worker(参见构造函数与随附模板)。
*
* 对于*真正可并行*平台上的 *CPU 密集型*负载,可将 [[getOptimalWorkerCount]] 作为 `maxWorkers` 传入,
* 跨可用核心并行(给主线程留一个核心)。注意:只有当你*同时*提交多个独立任务时 `maxWorkers` 才起作用——
* 单个排队任务始终只用一个 Worker。
*
* @example
* Function mode (Web real-parallel; mini-game / native transparent sync fallback):
* ```ts
* const pool = new WorkerPool((n: number) => {
* let acc = 0;
* for (let i = 0; i < n; i++) acc += Math.sqrt(i);
* return acc;
* }, { maxWorkers: getOptimalWorkerCount(), idleReleaseAfter: 1000 });
*
* const result = await pool.run([1_000_000]);
* // ...
* pool.terminate();
* ```
*
* Script mode (a real worker on Web AND every mini-game platform that has one):
* ```ts
* // Backend chain resolved at construction: platform worker (only when fully set up — see
* // checkWorkerScript) → global Worker → single-threaded via options.fallback → run() rejects.
* // Pool size is auto-capped by the platform: 1 worker on the seven single-worker platforms and
* // WeChat V1; up to maxWorkers on WeChat V2 and Web.
* // On WeChat V2 pass an explicit maxWorkers to scale beyond 1 (core count is not detectable there).
* const pool = new WorkerPool('workers/heavy-compute/index.js', {
* maxWorkers: 4,
* // Optional: same computation as the worker script's runTask(args), used single-threaded
* // when no worker backend is available at all. Without it, run() would reject there.
* fallback: (n: number) => { let acc = 0; for (let i = 0; i < n; i++) acc += Math.sqrt(i); return acc; },
* });
* const result = await pool.run([1_000_000]);
* pool.terminate();
* ```
*/
export class WorkerPool {
private readonly _fn: WorkerTask | null;
private readonly _script: string | null;
private readonly _fallback: WorkerTask | null;
private readonly _idleReleaseAfter: number;
private readonly _timeout: number;
private readonly _explicitMax: number;
private _maxWorkers: number;
/** Execution state only; platform selection and identity belong to PAL. */
private _executionMode: WorkerExecutionMode;
private _activeBackend: IPlatformWorkerBackend | null = null;
/** Changes only on recheck; runtime degradation stays in the same recovery generation. */
private _backendGeneration = 0;
private _scriptFailureHint = '';
private _backendReason: string;
private _workers: PooledWorker[] = [];
private _queue: PoolTask[] = [];
private _released = false;
private _draining = false;
private _taskId = 0;
/**
* @en Consecutive infrastructure failures on the real worker backend. Reset by [[WorkerPool.recheck]].
* Reaching [[DEGRADE_AFTER_FAILURES]] triggers degradation to single-threaded sync execution.
* @zh 真 Worker 后端上累计的基础设施失败次数。[[WorkerPool.recheck]] 会重置;达到
* [[DEGRADE_AFTER_FAILURES]] 即触发降级为单线程同步执行。
*/
private _infraFailures = 0;
/** @en Whether this pool has degraded to single-threaded sync execution. @zh 本池是否已降级为单线程同步执行。 */
private _degraded = false;
/** @en Guards against spamming the degradation warning (warn at most once per pool). @zh 防止重复刷降级警告(每池至多警告一次)。 */
private _degradeWarned = false;
/**
* @en Guards the CONSTRUCTION-time degradation warning (at most once per pool, even across
* [[WorkerPool.recheck]] re-resolutions). @zh 防止重复刷**构造期**降级警告(每池至多一次,即便
* [[WorkerPool.recheck]] 反复重解析)。
*/
private _constructionWarned = false;
/**
* @en
* Create a pool from a self-contained function or a packaged script path.
* PAL selects a usable script backend and its concurrency limit. When no backend is
* available, script tasks use options.fallback; without it, run() rejects with PAL's reason.
* Function tasks use a worker when PAL supports them, otherwise they execute inline.
* Scripts receive `{ id, args }` and reply with `{ id, ok, value }` or `{ id, ok: false, error }`.
* @zh
* 使用独立函数或已打包的脚本路径创建任务池。脚本后端的选择和并发上限由 PAL 提供。
* 没有可用后端时,脚本任务执行 options.fallback;未提供则携带 PAL 的诊断原因拒绝任务。
* 函数任务在 PAL 支持时使用 Worker,否则在主线程执行。
* 脚本接收 `{ id, args }`,回复 `{ id, ok, value }` 或 `{ id, ok: false, error }`。
*/
constructor (fnOrScript: WorkerTask | string, options?: WorkerPoolOptions) {
const isScriptMode = typeof fnOrScript === 'string';
if (isScriptMode) {
if (!fnOrScript) {
throw new TypeError(getError(16500));
}
this._script = fnOrScript;
this._fn = null;
} else {
if (typeof fnOrScript !== 'function') {
throw new TypeError(getError(16501));
}
this._fn = fnOrScript;
this._script = null;
}
const rawFallback = options ? options.fallback : undefined;
this._fallback = typeof rawFallback === 'function' ? rawFallback : null;
const rawMax = options ? options.maxWorkers : undefined;
// An explicit, valid pool size (>= 1). 0 means "not specified" so we can apply a default below.
this._explicitMax = (typeof rawMax === 'number' && Number.isFinite(rawMax) && rawMax >= 1)
? Math.floor(rawMax)
: 0;
const rawTimeout = options ? options.timeout : undefined;
this._timeout = (typeof rawTimeout === 'number' && Number.isFinite(rawTimeout) && rawTimeout > 0)
? rawTimeout
: 0;
// Use `??` so an explicit `0` (meaning "never release idle workers") is preserved.
this._idleReleaseAfter = (options && options.idleReleaseAfter !== undefined)
? options.idleReleaseAfter
: 1000;
this._executionMode = 'none';
this._backendReason = '';
this._maxWorkers = 0;
this._resolveBackend();
}
/**
* @en
* (Re-)resolve which execution backend this pool uses, and cap the pool size accordingly.
*
* Split out of the constructor so [[WorkerPool.recheck]] can run it again later. Resolution is
* driven purely by runtime capability, never by a compile-time platform constant — branching on
* `WECHAT` is what left seven mini-game platforms with a working `createWorker` falling through to
* synchronous execution.
* @zh
* (重新)解析本池使用哪个执行后端,并据此封顶池大小。
*
* 从构造函数中拆出,以便 [[WorkerPool.recheck]] 之后能再次调用。解析完全由**运行时能力**驱动,
* 绝不依赖编译期平台常量——正是对 `WECHAT` 的分支判断,让 7 个拥有可用 `createWorker` 的
* 小游戏平台掉进了同步执行。
*/
private _resolveBackend (): void {
const platform = getWorkerBackend();
const explicitMax = this._explicitMax;
const desired = explicitMax > 0 ? explicitMax : getOptimalWorkerCount();
this._activeBackend = null;
this._scriptFailureHint = platform.scriptFailureHint;
this._backendReason = '';
if (this._script) {
const resolved = platform.resolveScriptWorker(this._script);
if (resolved.backend) {
this._executionMode = 'worker';
this._activeBackend = resolved.backend;
this._scriptFailureHint = resolved.backend.scriptFailureHint;
this._maxWorkers = Math.min(desired, resolved.backend.concurrencyLimit);
} else if (this._fallback) {
this._executionMode = 'sync';
this._maxWorkers = 1;
this._warnConstructionDegrade(resolved.warnOnFailure, resolved.diagnosis.reason);
} else {
this._executionMode = 'none';
this._maxWorkers = 0;
this._backendReason = getError(16504, this._script, resolved.diagnosis.reason);
this._warnConstructionDegrade(resolved.warnOnFailure, resolved.diagnosis.reason);
}
} else if (platform.supportsFunctionWorker) {
this._executionMode = 'worker';
this._activeBackend = platform;
this._maxWorkers = Math.min(explicitMax > 0 ? explicitMax : 1, platform.concurrencyLimit);
} else {
this._executionMode = 'sync';
this._maxWorkers = 1;
}
}
/**
* @en
* Re-probe the platform and re-resolve the execution backend.
*
* The backend is normally decided once, at construction. That is wrong whenever capability appears
* LATER, which really happens:
* - the worker script lives in a WeChat subpackage that finishes downloading after the pool was
* created — `diagnose()` failed at construction because the file did not exist yet;
* - the base library hot-updates, or `wx.env.isSupportStandardWorker` flips as the V2 grey release
* rolls out to the device.
*
* Without this, a pool that probed too early stays locked to `'sync'`/`'none'` for its entire
* lifetime even though a real worker is now available.
*
* Idle executors are retired; busy executors finish their current task and are then retired.
* Queued tasks use the newly selected backend, or reject if it is unavailable without a fallback.
* Transferred tasks cannot be replayed after failure because ownership has already moved.
*
* @returns the execution state: `'worker'`, `'sync'` or `'none'`.
* @zh
* 重新探测平台并重新解析执行后端。
*
* 后端通常只在构造时决定一次。但只要能力是**之后**才出现的,这就错了,而这确实会发生:
* - worker 脚本位于微信分包中,该分包在池创建之后才下载完成——构造时 `diagnose()` 因文件尚不存在而失败;
* - 基础库热更新,或随着 V2 灰度推送到该设备,`wx.env.isSupportStandardWorker` 发生翻转。
*
* 没有这个入口,探测过早的池会在整个生命周期里被锁死在 `'sync'`/`'none'` 上,
* 即便真 Worker 现在已经可用。
*
* 空闲执行器立即释放,忙碌执行器完成当前任务后释放。排队任务交给新后端;
* 若新后端不可用且没有 fallback,则拒绝排队任务。已移交所有权的任务失败后不能重放。
*
* @returns 当前执行状态:`'worker'`、`'sync'` 或 `'none'`。
*/
public recheck (): WorkerExecutionMode {
if (this._released) {
return this.backend;
}
// Give the real worker backend another chance: a subpackage may have finished downloading or
// the base library may have hot-updated since we degraded. Reset the failure budget so the
// fresh probe starts clean. (_degradeWarned stays sticky to avoid log spam across rechecks.)
this._infraFailures = 0;
this._degraded = false;
// Drop the cached platform probe so the next read reflects the current environment.
resetWorkerBackendCache();
this._resolveBackend();
this._backendGeneration++;
// New tasks must use the newly resolved backend. Busy workers finish their current
// task, but are never reused after this capability check.
this._retireWorkers();
this._drain();
return this.backend;
}
private _retireWorkers (): void {
for (let i = this._workers.length - 1; i >= 0; i--) {
const worker = this._workers[i];
worker.retired = true;
if (!worker.busy) {
this._workers.splice(i, 1);
worker.dispose();
}
}
}
/**
* @en Current execution state: worker, synchronous fallback, or unavailable.
* @zh 当前执行状态:Worker、主线程同步回退,或不可用。
*/
public get backend (): WorkerExecutionMode {
return this._executionMode;
}
/**
* @en
* The resolved parallel worker count this pool will actually run tasks on
* (already clamped by the platform concurrency limit and the hardware estimate).
* Callers doing manual chunking should size their chunk count to this value so that chunks map
* 1:1 onto real parallel workers, instead of queueing serially on a single worker (e.g. WeChat V1,
* where `concurrencyLimit` is 1) and multiplying the per-frame round-trip latency.
* @zh
* 池实际会用于并行执行任务的 worker 数(已计入平台并发上限与硬件核数估计)。
* 手动分块的调用方应按此值确定分块数,使分块与真实并行 worker 一一对应;否则在单 worker 平台
* (如微信 V1,`concurrencyLimit` 为 1)上多块会串行排队,成倍放大每帧往返延迟。
*/
public get concurrency (): number {
return this._maxWorkers;
}
/**
* @en
* Queue a task and resolve with its return value when it completes.
* If a worker is free (or the pool is under `maxWorkers`), the task starts immediately;
* otherwise it waits in the queue.
* @zh
* 排队一个任务,完成时用其返回值 resolve。
* 如果有空闲 Worker(或池中 Worker 数未达到 `maxWorkers`),任务立即开始;否则在队列中等待。
* @param args Arguments passed to the task function. 传给任务函数的参数。
* @param transfer Transferable objects to transfer to the worker. 零拷贝转移到 Worker 的对象。
*/
public run<TResult = unknown> (args?: unknown[], transfer?: Transferable[]): Promise<TResult> {
return new Promise<TResult>((resolve, reject) => {
if (this._released) {
reject(new Error(getError(16502)));
return;
}
if (this._executionMode === 'none') {
// Script mode, but no worker backend is available (WeChat worker not fully set up,
// no global Worker) and no options.fallback was provided — we cannot proceed.
reject(new Error(this._backendReason || getError(16503)));
return;
}
this._queue.push({
args: args || [],
transfer: transfer || [],
resolve: (value: unknown): void => resolve(value as TResult),
reject,
});
this._drain();
});
}
/**
* @en
* Terminate all workers immediately and reject all pending tasks.
* @zh
* 立即终止所有 Worker,并拒绝所有排队中的任务。
*/
public terminate (): void {
if (this._released) {
return;
}
this._released = true;
const error = new Error(getError(16502));
for (const task of this._queue) {
task.reject(error);
}
this._queue.length = 0;
for (const w of this._workers) {
w.dispose();
}
this._workers.length = 0;
}
private _drain (): void {
if (this._released || this._draining) return;
this._draining = true;
try {
if (this._executionMode === 'none') {
const pending = this._queue.splice(0);
for (const task of pending) task.reject(new Error(this._backendReason));
return;
}
while (this._queue.length > 0) {
let worker = this._findIdleWorker();
if (!worker && this._workers.length < this._maxWorkers) {
try {
worker = this._spawnWorker();
} catch (err) {
// Script-mode worker creation can throw synchronously (e.g. the path is not
// packaged into the `workers` directory, or a subpackage has not been downloaded).
// Treat it as an infrastructure failure: degrade so we stop respawning a broken
// backend, and re-run this task via the fallback when one exists (otherwise reject
// it). Keep draining either way so the remaining tasks are not left hanging.
const failed = this._queue.shift();
this._onInfraFailure(failed || null, err as Error);
continue;
}
if (worker) {
this._workers.push(worker);
}
}
if (!worker) {
// No free worker and already at maxWorkers: wait for a completion callback.
return;
}
const task = this._queue.shift();
if (task) {
this._dispatch(worker, task);
}
}
} finally {
this._draining = false;
}
}
private _findIdleWorker (): PooledWorker | null {
for (const w of this._workers) {
if (!w.busy && !w.retired) {
return w;
}
}
return null;
}
private _spawnWorker (): PooledWorker {
const generation = this._backendGeneration;
let worker: IWorker | null = null;
let fn = this._fn;
if (this._script) {
if (this._executionMode === 'worker') {
// Use the exact backend PAL selected, so creation matches its concurrency and capabilities.
worker = this._activeBackend!.createScriptWorker(this._script);
} else {
// 'sync' backend (no worker at all): run the user-provided fallback inline.
// ('none' never reaches here — run() rejects before queuing.)
fn = this._fallback;
}
} else if (this._executionMode === 'worker') {
worker = this._activeBackend!.createFunctionWorker(this._fn!);
if (!worker) {
// Capability disappeared before creation. Do not silently report a worker pool
// while scheduling multiple inline executors.
this._executionMode = 'sync';
this._maxWorkers = 1;
this._retireWorkers();
}
}
// A null `worker` leaves PooledWorker in inline mode → it runs `fn` synchronously.
const pooled = new PooledWorker(worker, fn, this._idleReleaseAfter, this._onWorkerIdle.bind(this), this._timeout);
// Route infrastructure failures (timeout / onError / malformed reply) on a REAL worker back to
// the pool so it can count them and degrade to single-threaded execution instead of hanging.
// An inline executor never triggers it, so the callback simply stays unused there.
pooled.onInfraFailure = (t: PoolTask, err: Error): void => {
// Only faults from before recheck belong to an obsolete backend. Workers retired
// by degradation still recover non-transferred tasks in the current generation.
if (generation !== this._backendGeneration) t.reject(err);
else this._onInfraFailure(t, err);
};
return pooled;
}
private _dispatch (worker: PooledWorker, task: PoolTask): void {
worker.busy = true;
worker.cancelIdleTimer();
const id = ++this._taskId;
worker.onComplete = (): void => {
worker.busy = false;
if (worker.retired) this._onWorkerIdle(worker);
else this._drain();
};
// Once ownership has been transferred, the original arguments cannot be replayed safely.
task.transferred = !worker.isInline && !!this._activeBackend?.supportsTransfer && task.transfer.length > 0;
worker.execute(id, task);
}
private _onWorkerIdle (worker: PooledWorker): void {
if (this._released) {
return;
}
if (worker.busy) {
return;
}
const idx = this._workers.indexOf(worker);
if (idx < 0) {
return;
}
this._workers.splice(idx, 1);
worker.dispose();
// A worker was freed up (idle-release or failure): re-drain so queued tasks don't stall.
this._drain();
}
/**
* @internal
* Handle an INFRASTRUCTURE failure on a real worker: it timed out, errored, failed to spawn, or
* spoke a malformed protocol. These all mean the worker backend is not functioning for this
* script — unlike a task-level `{ ok: false }` reply (a genuine computation error), which is
* rejected directly and never reaches here.
*
* Script mode: count the failure and, once [[DEGRADE_AFTER_FAILURES]] is reached, degrade the
* WHOLE pool so no further task hangs on the broken backend. With `options.fallback` we switch to
* the `'sync'` backend (one inline executor on the main thread) and re-run the failed task through
* it, so the caller still gets a result instead of a rejection — the graceful "warn + run
* single-threaded" path the engine promises. Without a fallback there is no single-thread path to
* degrade to, so we keep the existing evict-and-respawn recovery and reject the task, but warn
* loudly so the developer learns the worker is broken and how to fix it.
*
* Function mode is deliberately EXCLUDED from degradation: its inline path is the SAME `_fn` that
* may have just deadlocked inside the worker, so running it on the main thread could move the hang
* onto the render thread. There we keep the existing recovery — reject the task, evict, respawn.
*
* @param task The in-flight task that failed, or `null` when the failure carries no task.
* @param error The infrastructure error.
*/
private _onInfraFailure (task: PoolTask | null, error: Error): void {
if (!this._script) {
// Function mode: no safe single-thread path (see above). Reject and let _settle evict +
// respawn a fresh worker, exactly as before the circuit breaker existed.
if (task) {
task.reject(error);
}
return;
}
this._infraFailures++;
if (!this._degraded && this._infraFailures >= DEGRADE_AFTER_FAILURES) {
this._degraded = true;
if (this._fallback) {
// Graceful degradation: every future task runs on the main thread via the fallback.
this._executionMode = 'sync';
this._backendReason = '';
this._maxWorkers = 1;
// Drop idle real workers so the next dispatch goes to an inline executor, not a
// leftover worker on the backend we just gave up on.
this._retireWorkers();
}
this._warnDegrade(error);
}
if (!task) {
return;
}
if (this._executionMode === 'sync' && this._fallback && !task.transferred) {
// Re-run the failed task on the main thread. Front of the queue preserves ordering; the
// eviction-driven re-drain (runtime failure) or the _drain loop (spawn failure) dispatches
// it through an inline executor running the fallback.
this._queue.unshift(task);
} else {
task.reject(error);
}
}
/**
* @internal
* Emit the one-time RUNTIME-degradation warning. `_degradeWarned` is sticky for the pool's
* lifetime so repeated failures — or a `recheck()` that re-degrades — never spam the log.
*/
private _warnDegrade (error: Error): void {
if (this._degradeWarned) {
return;
}
this._degradeWarned = true;
const script = this._script || '(function)';
warnID(this._fallback ? 16505 : 16506, script, error.message, this._scriptFailureHint);
}
/** PAL decides whether unavailable script execution deserves a one-time warning. */
private _warnConstructionDegrade (warnOnFailure: boolean, reason: string): void {
if (!warnOnFailure || this._constructionWarned) {
return;
}
this._constructionWarned = true;
warnID(this._fallback ? 16507 : 16508, this._script || '(function)', reason, this._scriptFailureHint);
}
}
/**
* @internal
*/
interface PoolTask {
args: unknown[];
transfer: Transferable[];
transferred?: boolean;
resolve: (value: unknown) => void;
reject: (reason?: unknown) => void;
}
/**
* @internal
* A single pooled worker, either backed by a real Web Worker or an inline synchronous executor.
*/
class PooledWorker {
public busy = false;
public retired = false;
public onComplete: (() => void) | null = null;
/**
* @internal
* Set by the pool: called when an INFRASTRUCTURE failure occurs while a task is in flight — the
* worker timed out, errored, or spoke a malformed protocol. The pool counts these and (in script
* mode) degrades to single-threaded execution so nothing hangs. Deliberately distinct from a
* task-level `{ ok: false }` reply (a genuine computation error), which is rejected directly and
* never routed here. Only real workers ever trigger it; an inline executor cannot suffer an
* infrastructure failure (a throwing `fallback`/`_fn` is a task-level error).
*/
public onInfraFailure: ((task: PoolTask, error: Error) => void) | null = null;
/**
* @en
* Whether this pooled worker runs tasks INLINE on the calling thread instead of owning a real
* worker. True for the `'sync'` backend and for function mode on platforms that cannot rebuild a
* function from source. Such an executor is a placeholder, not parallelism — [[WorkerPool.recheck]]
* retires the idle ones once a real backend appears.
* @zh
* 本池化 worker 是否在调用线程上**内联**执行任务,而非持有真正的 worker。
* `'sync'` 后端、以及无法从源码重建函数的平台上的函数模式均如此。这类执行器只是占位而非并行——
* 一旦真后端出现,[[WorkerPool.recheck]] 会把其中空闲的退役。
*/
public get isInline (): boolean {
return this._worker === null;
}
private readonly _worker: IWorker | null;
private readonly _fn: WorkerTask | null;
private readonly _idleReleaseAfter: number;
private readonly _timeout: number;
private readonly _onIdle: (worker: PooledWorker) => void;
private _current: PoolTask | null = null;
private _currentId = -1;
private _idleTimer: ReturnType<typeof setTimeout> | null = null;
private _timeoutTimer: ReturnType<typeof setTimeout> | null = null;
private _disposed = false;
private _failed = false;
constructor (
worker: IWorker | null,
fn: WorkerTask | null,
idleReleaseAfter: number,
onIdle: (worker: PooledWorker) => void,
timeout = 0,
) {
this._worker = worker;
this._fn = fn;
this._idleReleaseAfter = idleReleaseAfter;
this._onIdle = onIdle;
this._timeout = timeout > 0 ? timeout : 0;
if (worker) {
// IWorker.onMessage hands back the reply payload directly (the adapter unwraps `e.data`
// on Web, and WeChat's `onMessage` already passes `res`), so no MessageEvent here.
worker.onMessage((reply: IWorkerReply): void => {
this._onMessage(reply);
});
worker.onError((e: any): void => {
this._failed = true;
if (this._current) {
// Busy: fail the in-flight task; _settle's `_failed` branch then evicts us.
this._settle(null, new Error(e && e.message ? String(e.message) : getError(16509)));
} else {
// Idle: there is no task to settle, but this worker is no longer trustworthy.
// It MUST be evicted here — otherwise it stays in the pool with `busy === false`,
// the next task gets dispatched onto it, and `postMessage` goes into a black hole
// (the task hangs forever, and script mode has no timeout to recover it).
// Real triggers: an uncaught async error inside the worker (e.g. a `setInterval`
// callback throwing), or WeChat killing the worker process (`onProcessKilled`).
this._evict();
}
});
}
}
public execute (id: number, task: PoolTask): void {
this._current = task;
this._currentId = id;
if (!this._worker) {
if (!this._fn) {
// Script mode without a live worker should never reach here (run()/_drain guard it),
// but stay defensive: there is no function to run synchronously, so fail the task.
this._settle(null, new Error(getError(16510)));
return;
}
// Inline synchronous fallback (non-Worker platforms, function mode only). This blocks the
// main thread, which is the unavoidable behavior when no worker is available.
try {
const value = this._fn(...task.args);
this._settle(value, null);
} catch (err) {
this._settle(null, err as Error);
}
return;
}
// Arm before sending: adapters may synchronously report an error (or a test reply).
this.armTimeout();
try {
this._worker.postMessage({ id, args: task.args }, task.transfer);
} catch (err) {
this._failed = true;
this._settle(null, err instanceof Error ? err : new Error(String(err)));
}
// Watchdog. Only meaningful for a REAL worker: the inline synchronous path above blocks the
// main thread for the whole duration, so a timer could never fire during it anyway.
// Without this, a worker that accepts the message and never replies — a script that deadlocks,
// an infinite loop, a platform that silently drops the message — leaves the task pending
// forever AND leaves that worker parked in the pool with `busy === true`, permanently
// shrinking the pool's effective size by one on every occurrence.
}
/**
* @internal
* Start the per-task watchdog. On expiry the task is failed and this worker is EVICTED (not
* merely marked free): an unresponsive worker is indistinguishable from a dead one, so letting
* the pool reuse it would just hang the next task too. Eviction routes through `_onIdle`, which
* splices us out, disposes us and re-drains the queue onto a freshly spawned worker.
*/
private armTimeout (): void {
if (this._timeout <= 0) {
return;
}
this.cancelTimeoutTimer();
const id = this._currentId;
this._timeoutTimer = setTimeout(() => {
this._timeoutTimer = null;
// Ignore a timer that outlived its task (shouldn't happen — _settle cancels it — but a
// stale timer firing against a NEW task would fail an innocent one).
if (!this._current || this._currentId !== id) {
return;
}
this._failed = true;
this._settle(null, new Error(getError(16511, this._timeout)));
}, this._timeout);
}
private cancelTimeoutTimer (): void {
if (this._timeoutTimer !== null) {
clearTimeout(this._timeoutTimer);
this._timeoutTimer = null;
}
}
public cancelIdleTimer (): void {
if (this._idleTimer !== null) {
clearTimeout(this._idleTimer);
this._idleTimer = null;
}
}
public dispose (): void {
if (this._disposed) {
return;
}
this._disposed = true;
this.cancelIdleTimer();
this.cancelTimeoutTimer();
if (this._worker) {
this._worker.terminate();
}
if (this._current) {
this._current.reject(new Error(getError(16512)));
this._current = null;
this._currentId = -1;
}
this.onComplete = null;
}
private _onMessage (reply: IWorkerReply): void {
if (!this._current) {
return;
}
// Boundary check: the worker script must speak the engine protocol. A malformed reply means
// the packaged file is wrong (not based on the template) — fail loudly with a clear error
// instead of letting the task hang forever waiting for a well-formed reply.
if (!reply || typeof reply !== 'object'
|| typeof reply.id !== 'number'
|| typeof reply.ok !== 'boolean') {
this._failed = true;
this._settle(null, new Error(getError(16513)));
return;
}
// Guard against a stale/late reply from a previous task on the same worker.
if (reply.id !== this._currentId) {
return;
}
if (reply.ok) {
this._settle(reply.value, null);
} else {
this._settle(null, new Error(reply.error || getError(16514)));
}
}
private _settle (value: unknown, error: Error | null): void {
const task = this._current;
if (!task) {
return;
}
this._current = null;
this._currentId = -1;
this.cancelTimeoutTimer();
if (error) {
if (this._failed && this.onInfraFailure) {
// Infrastructure failure (timeout / onError / malformed reply): the worker backend
// itself is not functioning. Hand the task to the pool, which counts the failure,
// degrades script-mode pools to single-threaded execution once the threshold is hit,
// and either re-runs this task via the fallback or rejects it.
this.onInfraFailure(task, error);
} else {
// Task-level failure (the worker replied { ok: false }, or an inline fallback/_fn
// threw): a genuine computation error, not a broken backend. Reject directly and keep
// trusting the worker.
task.reject(error);
}
} else {
task.resolve(value);
}
// A worker that reported an uncaught error is not trustworthy for reuse: dispose it so the
// pool spawns a fresh one instead of replaying the same failure on every task.
if (this._failed) {
this._evict();
return;
}
// Mark idle (kicking off the idle-release timer) and notify the pool to drain the queue.
if (this._idleReleaseAfter > 0 && !this._disposed) {
this.cancelIdleTimer();
this._idleTimer = setTimeout(() => {
this._idleTimer = null;
this._onIdle(this);
}, this._idleReleaseAfter);
}
if (this.onComplete) {
const cb = this.onComplete;
this.onComplete = null;
cb();
}
}
/**
* @internal
* Retire this worker for good: drop any completion callback, clear the busy flag, and hand
* ourselves to the pool's idle hook (which splices us out of `_workers`, calls `dispose()` and
* re-drains the queue so queued tasks get a freshly spawned worker).
*
* Used by BOTH failure paths, which is the whole point of extracting it: `_settle`'s `_failed`
* branch (worker died while a task was in flight) and the idle `onError` branch (worker died
* while idle). The idle path can never reach the `_settle` branch, because `_settle` returns
* early when `_current` is null — routing it here is what stops a dead worker from silently
* swallowing the next task.
*/
private _evict (): void {
this.onComplete = null;
this.busy = false;
this._onIdle(this);
}
}
/**
* @internal
*/
interface IWorkerReply {
id: number;
ok: boolean;
value?: unknown;
error?: string;
}
+413
View File
@@ -0,0 +1,413 @@
/*
Copyright (c) 2018-2023 Xiamen Yaji Software Co., Ltd.
http://www.cocos.com
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/
import { createWorkerBackend } from 'pal/worker';
import type { IWorker, IPlatformWorkerBackend, IWorkerCapabilities } from 'pal/worker';
import { getError } from '../core/platform/debug';
export type { IWorker };
let backend: IPlatformWorkerBackend | undefined;
/** @internal Shared by capability queries and WorkerPool. */
export function getWorkerBackend (): IPlatformWorkerBackend {
return backend || (backend = createWorkerBackend());
}
/** @internal Re-probe PAL when a pool explicitly rechecks its capabilities. */
export function resetWorkerBackendCache (): void {
backend = undefined;
}
/**
* @en Current Worker capabilities reported by PAL.
* @zh PAL 提供的当前 Worker 能力。
*/
export function getWorkerCapabilities (): IWorkerCapabilities {
const current = getWorkerBackend();
return {
supportsStandardWorker: current.supportsStandardWorker,
available: current.concurrencyLimit > 0,
parallel: current.concurrencyLimit > 1,
concurrencyLimit: current.concurrencyLimit,
supportsTransfer: current.supportsTransfer,
supportsSharedArrayBuffer: current.supportsSharedArrayBuffer,
supportsFunctionWorker: current.supportsFunctionWorker,
reason: current.capabilityReason,
};
}
/**
* @en
* The task function executed inside a Web Worker.
*
* **Important**: the function must be *self-contained*: it is serialized via `Function.prototype.toString()`
* and reconstructed in a fresh global scope inside the worker, so it cannot capture variables from the
* enclosing closure, nor reference any engine / scene objects (`Node`, `Component`, `Vec3`, ...).
* Only plain data (numbers, strings, arrays, plain objects) and transferable buffers (`ArrayBuffer`,
* typed arrays backed by their own buffer) may cross the worker boundary.
*
* @zh
* 在 Web Worker 内执行的任务函数。
*
* **注意**:函数必须*自包含*——引擎通过 `Function.prototype.toString()` 序列化函数并在 Worker 的全新全局作用域中重建,
* 因此它不能捕获外部闭包变量,也不能引用任何引擎 / 场景对象(`Node`、`Component`、`Vec3` 等)。
* 只有普通数据(数字、字符串、数组、普通对象)和可转移缓冲区(`ArrayBuffer`、自带缓冲区的类型化数组)可以跨 Worker 边界传递。
*
* @remarks
* @en
* The default argument type is `any[]` rather than `unknown[]`, deliberately. Arguments reach the task
* through a DYNAMIC array channel — `pool.run([1_000_000])` is `unknown[]`, spread internally as
* `fn(...args)` — so the type system can never relate what you pass to `run()` to what your task
* declares. An `unknown[]` parameter therefore buys zero safety while breaking the natural spelling:
* under `strictFunctionTypes` a concrete `(limit: number) => number` is NOT assignable to
* `(...args: unknown[]) => unknown`, so `new WorkerPool(fn, { fallback: countPrimes })` would not
* compile. `any[]` restores bivariance and lets the obvious code type-check. Pass explicit type
* arguments when you want the stricter shape: `WorkerTask<[number, number], number>`.
* @zh
* 默认参数类型刻意取 `any[]` 而非 `unknown[]`。参数是通过**动态数组通道**抵达任务函数的——
* `pool.run([1_000_000])` 是 `unknown[]`,内部以 `fn(...args)` 展开——因此类型系统永远无法把你传给
* `run()` 的东西与任务函数的声明关联起来。于是 `unknown[]` 参数**换不到任何安全性**,却破坏了最自然的写法:
* 在 `strictFunctionTypes` 下,具体的 `(limit: number) => number` **不能**赋值给
* `(...args: unknown[]) => unknown`,导致 `new WorkerPool(fn, { fallback: countPrimes })` 无法编译。
* `any[]` 恢复双变,让显而易见的代码通过类型检查。需要更严格的形状时请显式传类型参数:
* `WorkerTask<[number, number], number>`。
*/
// `any[]` here is a deliberate, documented trade-off — see the remarks above. Do not "fix" it back to
// `unknown[]`: that reintroduces a compile error on every concrete task function.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
export type WorkerTask<TArgs extends any[] = any[], TResult = unknown> = (...args: TArgs) => TResult;
/**
* @en
* Detect whether the current environment supports spawning a Web Worker from a serialized function
* (i.e. `Worker` constructor + `Blob` + `URL.createObjectURL` are all available).
*
* This is the capability required by **mode 1** (pure-function workers used by [[WorkerPool]]).
* Native platforms run JavaScript inside an embedded engine (V8 / JavaScriptCore)
* without the browser host API, and mini-game platforms forbid runtime code evaluation and have no
* `Blob` (they use `createWorker` with a packaged script path instead), so both report `false` here
* and mode 1 falls back to running synchronously on the main thread. Use [[createWorker]]`(path)`
* (mode 2) for a real worker on a mini-game platform.
*
* NOTE: this answers "can I build a worker from a FUNCTION". It says nothing about whether the
* platform has workers at all — for that use [[getWorkerConcurrencyLimit]], which is nonzero on all
* nine mini-game platforms except Taobao. Conflating the two is what made a WeChat V2 build report
* an optimal worker count of 1.
* @zh
* 检测当前环境是否支持从序列化函数创建 Web Worker
* (即 `Worker` 构造器 + `Blob` + `URL.createObjectURL` 三者齐全)。
*
* 这是**模式一**([[WorkerPool]] 使用的纯函数 Worker)所需的能力。
* 原生平台在嵌入式 JS 引擎(V8 / JavaScriptCore)中运行、没有浏览器宿主 API;小游戏平台禁止运行时代码求值
* 且没有 `Blob`(它们用 `createWorker` + 打包脚本路径),因此两者这里都返回 `false`,
* 模式一自动降级为主线程同步执行。小游戏平台上若要真正的 Worker,请用 [[createWorker]]`(path)`(模式二)。
*
* 注意:本函数回答的是"能否从**函数**构建 Worker",与平台到底有没有 Worker 无关——后者请用
* [[getWorkerConcurrencyLimit]],除淘宝外它在全部 9 个小游戏平台上都非零。
* 把两者混为一谈,正是微信 V2 构建把最优 Worker 数报成 1 的原因。
*/
export function isWorkerSupported (): boolean {
return getWorkerBackend().supportsFunctionWorker;
}
/**
* @en
* Suggest a sensible worker count for CPU-bound (compute-heavy) tasks.
*
* The platform's concurrency cap is applied FIRST, because on seven of the nine mini-game platforms
* the limit is exactly one worker — a platform restriction, not a hardware one. Only where the
* platform allows many (Web, WeChat V2 standard worker) does the hardware estimate apply:
* `hardwareConcurrency - 1`, deliberately leaving one logical core for the main thread (rendering +
* game logic). This is a *starting point*, not a universal answer: I/O-bound tasks can benefit from
* more workers, and tiny per-frame tasks are often better off with `1`.
*
* Where `navigator.hardwareConcurrency` is unavailable — as is typically the case on mini-game
* platforms, which expose device info through their own APIs rather than `navigator` — this
* conservatively returns `1`. Size such a pool explicitly instead
* (`new WorkerPool(path, { maxWorkers: 4 })`).
*
* Returns `1` when the platform has no worker at all (native platforms, Taobao), matching the single
* inline executor the pool falls back to.
*
* @zh
* 为 CPU 密集型(重计算)任务推荐一个合理的 Worker 数量。
*
* **平台并发上限优先**,因为 9 个小游戏平台中有 7 个上限恰好是 1 个 Worker——这是平台限制而非硬件限制。
* 只有平台允许多 Worker 时(Web、微信 V2 标准 Worker)才采用硬件估算:`hardwareConcurrency - 1`,
* 刻意给主线程(渲染 + 游戏逻辑)留一个逻辑核。这是一个*起点*,不是普适答案:I/O 型任务可以开更多 Worker,
* 而每帧的小任务往往用 `1` 个更合适。
*
* 当 `navigator.hardwareConcurrency` 不可用时——**包括全部小游戏平台**(它们都不暴露 `navigator`)——
* 保守返回 `1`。这类平台请显式指定池大小(`new WorkerPool(path, { maxWorkers: 4 })`)。
*
* 平台完全不支持 Worker 时(原生平台、淘宝)返回 `1`,与池降级使用的单个内联执行器一致。
*
* @example
* ```ts
* const pool = new WorkerPool(myPureFn, {
* maxWorkers: getOptimalWorkerCount(),
* });
* ```
*/
export function getOptimalWorkerCount (): number {
const limit = getWorkerBackend().concurrencyLimit;
// No worker at all: the pool can only ever run one inline executor.
if (limit === 0) {
return 1;
}
// A hard platform cap (the seven single-worker mini-game platforms) wins over any hardware estimate.
// NOTE: the previous implementation reached this answer only by accident — it short-circuited on
// `isWorkerSupported()`, which tests FUNCTION-mode capability (Worker + Blob + URL). A WeChat V2
// runtime has real multi-worker support but no Blob, so it was misreported as capped at 1.
if (limit !== Infinity) {
return limit;
}
const hc = getWorkerBackend().hardwareConcurrency;
return Math.max(1, Math.floor(hc) - 1);
}
/**
* @en
* Whether the mini-game runtime supports the **standard (WeChat V2) worker**: multiple concurrent
* workers, `SharedArrayBuffer`, transfer lists in `postMessage`, `OffscreenCanvas`, etc.
*
* This is a WeChat-only capability today (detected via `minigame.env.isSupportStandardWorker`), but it
* is expressed as a backend capability rather than a platform check, so the answer stays correct if
* another platform later ships a standard worker.
*
* V2 is in grey release, so this MUST be checked at runtime before relying on any V2-only capability.
* It safely returns `false` (i.e. fall back to the single-worker generation) when:
* - the platform is not a mini-game platform at all (Web / native);
* - the platform has no `env.isSupportStandardWorker` (every non-WeChat mini-game platform);
* - `minigame.env` is undefined (old base library);
* - running in the WeChat devtools (V2 is not supported there yet).
*
* Without V2 the hard constraints are: at most **1** concurrent worker, data is structured-cloned
* (no transfer), and no platform API / rendering inside the worker.
* @zh
* 小游戏运行时是否支持**标准(微信 V2)Worker**:多并发 Worker、`SharedArrayBuffer`、
* `postMessage` 的 transfer 列表、`OffscreenCanvas` 等。
*
* 目前这是微信独有的能力(通过 `minigame.env.isSupportStandardWorker` 检测),但它被表达为后端能力
* 而非平台判断,因此将来若其他平台也推出标准 Worker,这里的答案依然正确。
*
* V2 仍在灰度,因此依赖任何 V2 能力前**必须**运行时检测。以下情况安全返回 `false`(即回退到单 Worker 代际):
* - 根本不是小游戏平台(Web / 原生);
* - 平台没有 `env.isSupportStandardWorker`(所有非微信小游戏平台);
* - `minigame.env` 为 undefined(旧基础库);
* - 微信开发者工具中运行(V2 暂不支持)。
*
* 无 V2 时的硬约束:最多 **1** 个并发 Worker、数据走结构化克隆(无 transfer)、Worker 内无平台 API / 渲染。
*/
export function isSupportStandardWorker (): boolean {
return getWorkerBackend().supportsStandardWorker;
}
/**
* @en Result of [[checkWorkerScript]]: whether the platform worker environment is fully set up for a script path.
* @zh [[checkWorkerScript]] 的结果:平台 Worker 环境对某脚本路径是否设置完整。
*/
export interface IWorkerScriptStatus {
/**
* @en Whether a worker can be used for this path. Only when `true` should you go the worker route.
* @zh 该路径能否使用 Worker。仅当为 `true` 时才应走 Worker 路线。
*/
ready: boolean;
/**
* @en Worker version: `2` = standard (WeChat V2) worker, `1` = single-worker generation, `0` = unavailable.
* @zh Worker 版本:`2` = 标准(微信 V2)Worker,`1` = 单 Worker 代际,`0` = 不可用。
*/
version: 0 | 1 | 2;
/**
* @en Human-readable reason when not ready (empty string when ready). Suitable for error messages.
* @zh 不可用时的原因说明(可用时为空字符串),可直接用于报错信息。
*/
reason: string;
}
/**
* @en
* Check whether the platform's worker environment is **fully set up** for the given script path.
*
* "Fully set up" means ALL of the following hold:
* 1. the platform exposes a worker API at all (`minigame.createWorker`, or a global `Worker`);
* 2. the path is valid: a non-empty **relative** path ending with `.js` (mini-game platforms reject
* absolute paths and non-JS files);
* 3. on mini-game platforms, the file **actually exists** in the code package (verified via
* `minigame.getFileSystemManager().accessSync`) and is **not empty** (best-effort `statSync`).
* A missing file usually means it was not placed in the workers directory declared in
* `game.json` (WeChat) / `manifest.json` (quick game) / `app.json`, or its subpackage has not
* been downloaded yet.
*
* When `ready` is `true`, `version` tells you which worker generation you got (`2` = WeChat standard
* multi-worker, `1` = single-worker generation). When `ready` is `false`, `reason` explains why, and
* callers should fall back to a standard Web `Worker` (if any), then to synchronous execution.
* @zh
* 检查平台的 Worker 环境对给定脚本路径是否**设置完整**。
*
* "设置完整"指以下条件全部成立:
* 1. 平台确实暴露了 Worker API(`minigame.createWorker`,或全局 `Worker`);
* 2. 路径合法:非空、**相对路径**、以 `.js` 结尾(小游戏平台会拒绝绝对路径与非 JS 文件);
* 3. 在小游戏平台上,文件**确实存在**于代码包中(通过 `minigame.getFileSystemManager().accessSync`
* 校验)且**非空**(尽力而为的 `statSync`)。文件缺失通常意味着它没被放进 `game.json`(微信)/
* `manifest.json`(快游戏)/ `app.json` 声明的 workers 目录,或所在分包尚未下载。
*
* `ready` 为 `true` 时,`version` 表明拿到的 Worker 代际(`2` = 微信标准多 Worker,`1` = 单 Worker 代际)。
* `ready` 为 `false` 时,`reason` 说明原因,调用方应降级到标准 Web `Worker`(若有),再不行就同步执行。
*/
export function checkWorkerScript (path: string): IWorkerScriptStatus {
return getWorkerBackend().diagnose(path);
}
/**
* @en
* The maximum number of worker instances that can run **concurrently** on the current platform.
*
* - Web (global `Worker`): effectively unlimited → `Infinity`.
* - WeChat **V2** standard worker (`env.isSupportStandardWorker`): multiple workers → `Infinity`.
* - WeChat V1, ByteDance, Alipay, Baidu, and the quick-game family (Huawei / OPPO / vivo / Xiaomi):
* only ONE worker at a time → `1`.
* - Taobao mini-game and native platforms (no worker API at all) → `0`.
*
* A cap of `1` means the platform has a worker but no parallelism: [[WorkerPool]] there is an
* **asynchronous offload queue** — it frees the main thread from a long task, but it cannot run two
* tasks at once. [[WorkerPool]] in **script mode** (`new WorkerPool(path)`) already caps its pool size
* per platform automatically (via [[checkWorkerScript]]), so it never tries to create more workers
* than the platform allows — creating a second worker on a single-worker platform fails.
*
* Do NOT pass this result directly as `maxWorkers`: where it returns `Infinity` the pool treats that
* as "not specified". Pass a concrete number instead:
* ```ts
* const pool = new WorkerPool('workers/my-task/index.js', { maxWorkers: 4 });
* ```
* @zh
* 当前平台上能够**并发**运行的 worker 实例数量上限。
*
* - Web(全局 `Worker`):实际上无限制 → `Infinity`。
* - 微信 **V2** 标准 Worker(`env.isSupportStandardWorker`):支持多 Worker → `Infinity`。
* - 微信 V1、抖音、支付宝、百度,以及快游戏家族(华为 / OPPO / vivo / 小米):同一时刻仅 1 个 → `1`。
* - 淘宝小游戏与原生平台(完全没有 Worker API)→ `0`。
*
* 上限为 `1` 意味着平台有 Worker 但**没有并行能力**:此时 [[WorkerPool]] 是一个**异步卸载队列**——
* 它能把长任务从主线程挪走,但无法同时跑两个任务。[[WorkerPool]] **脚本模式**(`new WorkerPool(path)`)
* 已通过 [[checkWorkerScript]] 自动按平台封顶池大小,不会创建超过平台允许的 Worker 数——
* 在单 Worker 平台上创建第二个会失败。
*
* 不要把本函数的返回值直接传给 `maxWorkers`:返回 `Infinity` 时池会将其视为"未指定"。请传具体数值:
* ```ts
* const pool = new WorkerPool('workers/my-task/index.js', { maxWorkers: 4 });
* ```
*/
export function getWorkerConcurrencyLimit (): number {
return getWorkerBackend().concurrencyLimit;
}
/**
* @en
* Create a worker from a packaged script path (**mode 2**), aligned with `minigame.createWorker`.
* - Mini-game platforms (all nine): `minigame.createWorker(path)` — the script must live in the
* packaged workers directory declared in `game.json` (WeChat) / `manifest.json` (quick game) /
* `app.json`; if it is in a subpackage, download that subpackage first.
* - Web: `new Worker(path)` (the script must be same-origin).
*
* Unlike mode 1, this works on mini-game platforms because the worker code is a real packaged file
* rather than a runtime-serialized string (which those platforms forbid). The returned [[IWorker]]
* exposes the WeChat-aligned messaging API, and the caller defines its own message protocol
* (no envelope is imposed).
*
* Platform order matters and is decided by the backend, not by a platform constant: on a mini-game
* build the mini-game worker is tried first, and only if it is not fully set up (script missing,
* subpackage not yet downloaded, base library too old) does it fall through to a global `Worker`
* (which some devtools environments provide), then to a precise error.
* @zh
* 从打包好的脚本路径创建 Worker(**模式二**),对齐 `minigame.createWorker`。
* - 小游戏平台(全部 9 个):`minigame.createWorker(path)`——脚本须位于 `game.json`(微信)/
* `manifest.json`(快游戏)/ `app.json` 声明的 workers 目录内;若在分包中,需先下载该分包。
* - Web:`new Worker(path)`(脚本需同源)。
*
* 与模式一不同,这在小游戏平台上可用,因为 Worker 代码是真实打包文件而非运行时序列化字符串
* (那些平台禁止后者)。返回的 [[IWorker]] 暴露对齐微信的消息 API,协议由调用方自定义(不强加信封)。
*
* 平台顺序很重要,且由后端而非平台常量决定:小游戏构建下优先尝试小游戏 Worker,只有当它未完全就绪时
* (脚本缺失、分包未下载、基础库过旧)才降级到全局 `Worker`(部分开发者工具环境提供),再不行就精确报错。
* @internal
*/
function createWorkerFromPath (path: string): IWorker {
if (typeof path !== 'string' || !path) {
throw new TypeError(getError(16515));
}
return getWorkerBackend().createScriptWorker(path);
}
/**
* @en
* Create a worker. The signature is aligned with the mini-game `createWorker`:
*
* - `createWorker(path: string)` → **mode 2**: a worker loaded from a packaged script. Web uses
* `new Worker(path)`; every mini-game platform that has a worker uses
* `minigame.createWorker(path)` (WeChat / ByteDance / Alipay / Baidu / Huawei / OPPO / vivo /
* Xiaomi). Works on all of them.
* - `createWorker(fn: WorkerTask)` → **mode 1**: a worker built from a self-contained function
* (**Web only**). On mini-game platforms and native this throws, because they forbid rebuilding a
* function from source — use [[WorkerPool]] instead, which automatically falls back to
* synchronous execution there.
*
* Both return an [[IWorker]] (`postMessage` / `onMessage` / `onError` / `terminate`). Check
* [[getWorkerCapabilities]] first if you need to know whether the platform has a worker at all
* (Taobao mini-game and native do not).
* @zh
* 创建一个 Worker,签名对齐小游戏的 `createWorker`:
*
* - `createWorker(path: string)` → **模式二**:从打包脚本加载 Worker。Web 用 `new Worker(path)`;
* 每个有 Worker 的小游戏平台用 `minigame.createWorker(path)`(微信 / 抖音 / 支付宝 / 百度 / 华为 /
* OPPO / vivo / 小米),两端都可用。
* - `createWorker(fn: WorkerTask)` → **模式一**:从自包含函数构建 Worker(**仅 Web**)。
* 小游戏平台与原生下会抛错,因为它们禁止用源码重建函数——请改用 [[WorkerPool]],
* 它在这些平台会自动降级为同步执行。
*
* 两者都返回 [[IWorker]](`postMessage` / `onMessage` / `onError` / `terminate`)。若需要先知道平台
* 到底有没有 Worker(淘宝小游戏与原生没有),请先查 [[getWorkerCapabilities]]。
*
* @example
* ```ts
* // Mode 2: your own packaged worker script (Web + all worker-capable mini-game platforms).
* const worker = cc.createWorker('workers/my-worker/index.js');
* worker.onMessage((res) => { console.log(res); });
* worker.postMessage({ cmd: 'compute', data });
* worker.terminate();
* ```
*/
export function createWorker (path: string): IWorker;
export function createWorker (fn: WorkerTask): IWorker;
export function createWorker (pathOrFn: string | WorkerTask): IWorker {
if (typeof pathOrFn === 'function') {
const w = getWorkerBackend().createFunctionWorker(pathOrFn);
if (!w) {
throw new Error(getError(16516));
}
return w;
}
return createWorkerFromPath(pathOrFn);
}
+17 -14
View File
@@ -110,7 +110,7 @@ export default class ShapeModule {
*/
@displayOrder(6)
@tooltip('i18n:shapeModule.arc')
@visible(function (this: ShapeModule) {
@visible(function selectArc (this: ShapeModule) {
const subset: Array<keyof typeof ParticleShapeType> = ['Cone', 'Circle'];
const enumName = getShapeTypeEnumName(this.shapeType);
return subset.includes(enumName);
@@ -131,7 +131,7 @@ export default class ShapeModule {
*/
@displayOrder(5)
@tooltip('i18n:shapeModule.angle')
@visible(function (this: ShapeModule) {
@visible(function selectAngle (this: ShapeModule) {
const subset: Array<keyof typeof ParticleShapeType> = ['Cone'];
const enumName = getShapeTypeEnumName(this.shapeType);
return subset.includes(enumName);
@@ -208,7 +208,7 @@ export default class ShapeModule {
@serializable
@displayOrder(2)
@tooltip('i18n:shapeModule.emitFrom')
@visible(function (this: ShapeModule) {
@visible(function selectEmitFrom (this: ShapeModule) {
const subset: Array<keyof typeof ParticleShapeType> = ['Box', 'Cone', 'Sphere', 'Hemisphere'];
const enumName = getShapeTypeEnumName(this.shapeType);
return subset.includes(enumName);
@@ -216,8 +216,8 @@ export default class ShapeModule {
public emitFrom = ParticleEmitLocation.Volume;
/**
* @en Align particle with particle direction.
* @zh 根据粒子的初始方向决定粒子的移动方向。
* @en Align the particle's negative Z axis with its initial emission direction, then apply start rotation.
* @zh 将粒子的负 Z 轴对齐到初始发射方向,再叠加初始旋转。
*/
@serializable
@displayOrder(16)
@@ -258,7 +258,7 @@ export default class ShapeModule {
@serializable
@displayOrder(3)
@tooltip('i18n:shapeModule.radius')
@visible(function (this: ShapeModule) {
@visible(function selectRadius (this: ShapeModule) {
const subset: Array<keyof typeof ParticleShapeType> = ['Circle', 'Cone', 'Sphere', 'Hemisphere'];
const enumName = getShapeTypeEnumName(this.shapeType);
return subset.includes(enumName);
@@ -278,7 +278,7 @@ export default class ShapeModule {
@serializable
@displayOrder(4)
@tooltip('i18n:shapeModule.radiusThickness')
@visible(function (this: ShapeModule) {
@visible(function selectRadiusThickness (this: ShapeModule) {
const subset: Array<keyof typeof ParticleShapeType> = ['Circle', 'Cone', 'Sphere', 'Hemisphere'];
const enumName = getShapeTypeEnumName(this.shapeType);
return subset.includes(enumName);
@@ -293,7 +293,7 @@ export default class ShapeModule {
@serializable
@displayOrder(7)
@tooltip('i18n:shapeModule.arcMode')
@visible(function (this: ShapeModule) {
@visible(function selectArcMode (this: ShapeModule) {
const subset: Array<keyof typeof ParticleShapeType> = ['Cone', 'Circle'];
const enumName = getShapeTypeEnumName(this.shapeType);
return subset.includes(enumName);
@@ -304,11 +304,12 @@ export default class ShapeModule {
* @en Control arc spread for Cone and circle shape.
* @zh 控制可能产生粒子的弧周围的离散间隔。
*/
@visible(function noArc (this: ShapeModule) { return this.arcMode !== ParticleArcMode.Random; }) // Bug fix: Hide this input when arcMode is random
// Bug fix: Hide this input when arcMode is random
@visible(function noArc (this: ShapeModule) { return this.arcMode !== ParticleArcMode.Random; })
@serializable
@displayOrder(9)
@tooltip('i18n:shapeModule.arcSpread')
@visible(function (this: ShapeModule) {
@visible(function selectArcSpread (this: ShapeModule) {
const subset: Array<keyof typeof ParticleShapeType> = ['Cone', 'Circle'];
const enumName = getShapeTypeEnumName(this.shapeType);
return subset.includes(enumName);
@@ -319,13 +320,14 @@ export default class ShapeModule {
* @en Emit speed around arc (available for Cone and Circle).
* @zh 粒子沿圆周发射的速度。
*/
// Bug fix: Hide this input when arcMode is random
@type(CurveRange)
@visible(function noArc (this: ShapeModule) { return this.arcMode !== ParticleArcMode.Random; }) // Bug fix: Hide this input when arcMode is random
@visible(function noArc (this: ShapeModule) { return this.arcMode !== ParticleArcMode.Random; })
@range([0, 1])
@serializable
@displayOrder(10)
@tooltip('i18n:shapeModule.arcSpeed')
@visible(function (this: ShapeModule) {
@visible(function selectArcSpeed (this: ShapeModule) {
const subset: Array<keyof typeof ParticleShapeType> = ['Cone', 'Circle'];
const enumName = getShapeTypeEnumName(this.shapeType);
return subset.includes(enumName);
@@ -340,7 +342,7 @@ export default class ShapeModule {
@serializable
@displayOrder(11)
@tooltip('i18n:shapeModule.length')
@visible(function (this: ShapeModule) {
@visible(function selectCone (this: ShapeModule) {
const subset: Array<keyof typeof ParticleShapeType> = ['Cone'];
const enumName = getShapeTypeEnumName(this.shapeType);
return subset.includes(enumName);
@@ -354,7 +356,7 @@ export default class ShapeModule {
@serializable
@displayOrder(12)
@tooltip('i18n:shapeModule.boxThickness')
@visible(function (this: ShapeModule) {
@visible(function selectBox (this: ShapeModule) {
const subset: Array<keyof typeof ParticleShapeType> = ['Box'];
const enumName = getShapeTypeEnumName(this.shapeType);
return subset.includes(enumName);
@@ -445,6 +447,7 @@ export default class ShapeModule {
if (this.arcMode === ParticleArcMode.Random) {
return randomRange(0, this._arc);
}
/* eslint-disable-next-line max-len */
let angle = this.totalAngle + 2 * Math.PI * this.arcSpeed.evaluate(this.particleSystem!.time, 1)! * (this.particleSystem!.time - this.lastTime);
this.totalAngle = angle;
if (this.arcSpread !== 0) {
+31 -7
View File
@@ -42,7 +42,7 @@ import VelocityOvertimeModule from './animator/velocity-overtime';
import Burst from './burst';
import ShapeModule from './emitter/shape-module';
import { ParticleCullingMode, ParticleSpace } from './enum';
import { particleEmitZAxis } from './particle-general-function';
import { isCurveTwoValues, particleEmitZAxis } from './particle-general-function';
import ParticleSystemRenderer from './renderer/particle-system-renderer-data';
import TrailModule from './renderer/trail';
import { ParticleSystemRendererBase } from './renderer/particle-system-renderer-base';
@@ -55,6 +55,9 @@ import { director, DirectorEvent } from '../game/director';
const _world_mat = new Mat4();
const _world_rol = new Quat();
const _emitDirection = new Vec3();
const _alignRotation = new Quat();
const _startRotation = new Quat();
const superMaterials = Object.getOwnPropertyDescriptor(Renderer.prototype, 'sharedMaterials')!;
@@ -141,7 +144,7 @@ export class ParticleSystem extends ModelRenderer {
@range([0, Number.POSITIVE_INFINITY])
@displayOrder(10)
@tooltip('i18n:particle_system.startSizeY')
@visible(function (this: ParticleSystem): boolean { return this.startSize3D; })
@visible(function (this: ParticleSystem): boolean { return this.startSize3D; }) // eslint-disable-line func-names, comma-dangle
public startSizeY = new CurveRange();
/**
@@ -153,7 +156,7 @@ export class ParticleSystem extends ModelRenderer {
@range([0, Number.POSITIVE_INFINITY])
@displayOrder(10)
@tooltip('i18n:particle_system.startSizeZ')
@visible(function (this: ParticleSystem): boolean { return this.startSize3D; })
@visible(function (this: ParticleSystem): boolean { return this.startSize3D; }) // eslint-disable-line func-names, comma-dangle
public startSizeZ = new CurveRange();
/**
@@ -184,7 +187,7 @@ export class ParticleSystem extends ModelRenderer {
@radian
@displayOrder(12)
@tooltip('i18n:particle_system.startRotationX')
@visible(function (this: ParticleSystem): boolean { return this.startRotation3D; })
@visible(function (this: ParticleSystem): boolean { return this.startRotation3D; }) // eslint-disable-line func-names, comma-dangle
public startRotationX = new CurveRange();
/**
@@ -196,7 +199,7 @@ export class ParticleSystem extends ModelRenderer {
@radian
@displayOrder(12)
@tooltip('i18n:particle_system.startRotationY')
@visible(function (this: ParticleSystem): boolean { return this.startRotation3D; })
@visible(function (this: ParticleSystem): boolean { return this.startRotation3D; }) // eslint-disable-line func-names, comma-dangle
public startRotationY = new CurveRange();
/**
@@ -1376,6 +1379,14 @@ export class ParticleSystem extends ModelRenderer {
self._textureAnimationModule.init(particle);
}
const alignToDirection = self._shapeModule?.enable && self._shapeModule.alignToDirection;
if (alignToDirection) {
Vec3.copy(_emitDirection, particle.velocity);
if (self._simulationSpace === ParticleSpace.World) {
Vec3.transformQuat(_emitDirection, _emitDirection, _world_rol);
}
}
const curveStartSpeed = self.startSpeed.evaluate(loopDelta, rand)!;
Vec3.multiplyScalar(particle.velocity, particle.velocity, curveStartSpeed);
@@ -1392,6 +1403,17 @@ export class ParticleSystem extends ModelRenderer {
} else {
particle.startEuler.set(0, 0, self.startRotationZ.evaluate(loopDelta, rand));
}
if (alignToDirection && _emitDirection.lengthSqr() > 0) {
// Align before applying start rotation, in simulation space. Use the
// shape direction so zero start speed still has a defined orientation.
Vec3.normalize(_emitDirection, _emitDirection);
Quat.rotationTo(_alignRotation, particleEmitZAxis, _emitDirection);
const r2d = 180 / Math.PI;
Quat.fromEuler(_startRotation, particle.startEuler.x * r2d, particle.startEuler.y * r2d, particle.startEuler.z * r2d);
Quat.multiply(_startRotation, _alignRotation, _startRotation);
Quat.toEuler(particle.startEuler, _startRotation);
particle.startEuler.multiplyScalar(1 / r2d);
}
particle.rotation.set(particle.startEuler);
// apply startSize.
@@ -1455,16 +1477,18 @@ export class ParticleSystem extends ModelRenderer {
if (!self._isEmitting) return;
const randTime = isCurveTwoValues(self.rateOverTime) ? pseudoRandom(randomRangeInt(0, bits.INT_MAX)) : 1;
// emit by rateOverTime
self._emitRateTimeCounter += self.rateOverTime.evaluate(self._time / self.duration, 1)! * dt;
self._emitRateTimeCounter += self.rateOverTime.evaluate(self._time / self.duration, randTime)! * dt;
if (self._emitRateTimeCounter > 1) {
const emitNum = Math.floor(self._emitRateTimeCounter);
self._emitRateTimeCounter -= emitNum;
self.emit(emitNum, dt);
}
const randDist = isCurveTwoValues(self.rateOverDistance) ? pseudoRandom(randomRangeInt(0, bits.INT_MAX)) : 1;
// emit by rateOverDistance
const rateOverDistance = self.rateOverDistance.evaluate(self._time / self.duration, 1)!;
const rateOverDistance = self.rateOverDistance.evaluate(self._time / self.duration, randDist)!;
if (rateOverDistance > 0) {
Vec3.copy(self._oldWPos, self._curWPos);
self.node.getWorldPosition(self._curWPos);
@@ -69,6 +69,7 @@ const CC_USE_EMBEDDED_ALPHA = 'CC_USE_EMBEDDED_ALPHA';
const CC_RENDER_MODE = 'CC_RENDER_MODE';
const ROTATION_OVER_TIME_MODULE_ENABLE = 'ROTATION_OVER_TIME_MODULE_ENABLE';
const USE_NORMAL_MAP = 'USE_NORMAL_MAP';
const INSTANCE_PARTICLE = 'CC_INSTANCE_PARTICLE';
const RENDER_MODE_BILLBOARD = 0;
const RENDER_MODE_STRETCHED_BILLBOARD = 1;
@@ -336,7 +337,16 @@ export default class ParticleSystemRendererCPU extends ParticleSystemRendererBas
return;
}
if (this._alignSpace === ParticleAlignmentSpace.Local) {
const ps = this._particleSystem;
if (mode === ParticleRenderMode.Mesh && ps?._shapeModule?.enable && ps._shapeModule.alignToDirection) {
// Aligned particle rotations are already in simulation space. The mesh
// shader only needs the remaining simulation-to-world rotation.
if (ps.simulationSpace === ParticleSpace.Local) {
ps.node.getWorldRotation(_node_rot);
} else {
_node_rot.set(0, 0, 0, 1);
}
} else if (this._alignSpace === ParticleAlignmentSpace.Local) {
this._particleSystem?.node.getRotation(_node_rot);
} else if (this._alignSpace === ParticleAlignmentSpace.World) {
this._particleSystem?.node.getWorldRotation(_node_rot);
@@ -393,9 +403,11 @@ export default class ParticleSystemRendererCPU extends ParticleSystemRendererBas
}
ps.node.getWorldMatrix(_tempWorldTrans);
const mat: Material | null = ps.getMaterialInstance(0) || this._defaultMat;
const pass = mat!.passes[0];
this.doUpdateScale(pass);
this.doUpdateRotation(pass);
const pass = mat?.passes[0];
if (pass) {
this.doUpdateScale(pass);
this.doUpdateRotation(pass);
}
this._updateList.forEach((value: IParticleModule, key: string): void => {
// TODO(cjh): Bug here? _updateList is a Map, the old code uses `this._updateList['some_key'] = some_value;`
@@ -686,7 +698,8 @@ export default class ParticleSystemRendererCPU extends ParticleSystemRendererBas
this._renderInfo!.mainTexture = shareMaterial.getProperty('mainTexture', 0) as Texture2D;
}
if (ps.sharedMaterial == null && this._defaultMat == null) {
// Renderer can destroy the cached instance when replacing a preview material.
if (ps.sharedMaterial == null && (!this._defaultMat || !this._defaultMat.passes.length)) {
_matInsInfo.parent = builtinResMgr.get<Material>('default-particle-material');
_matInsInfo.owner = this._particleSystem;
_matInsInfo.subModelIdx = 0;
@@ -699,6 +712,11 @@ export default class ParticleSystemRendererCPU extends ParticleSystemRendererBas
}
}
const mat: Material = ps.getMaterialInstance(0) || this._defaultMat!;
// A custom material may still have an invalid or unavailable effect.
if (!mat || !mat.passes.length) {
warn('Particle material has no render passes. Check its effect import and selected technique.');
return;
}
if (ps.simulationSpace === ParticleSpace.World) {
this._defines[CC_USE_WORLD_SPACE] = true;
} else {
@@ -745,6 +763,10 @@ export default class ParticleSystemRendererCPU extends ParticleSystemRendererBas
const roationModule = this._particleSystem._rotationOvertimeModule;
enable = roationModule ? roationModule.enable : false;
this._defines[ROTATION_OVER_TIME_MODULE_ENABLE] = enable;
// Explicitly clear the override when the material omits the disabled macro.
const materialDefines = (shareMaterial || mat.parent || mat).passes[0]?.defines;
this._defines[USE_NORMAL_MAP] = !!materialDefines?.[USE_NORMAL_MAP];
this._defines[INSTANCE_PARTICLE] = this._useInstance;
const matIns: MaterialInstance | null = ps.getMaterialInstance(0);
@@ -772,7 +794,7 @@ export default class ParticleSystemRendererCPU extends ParticleSystemRendererBas
this._trailDefines[CC_USE_WORLD_SPACE] = false;
}
let mat: Material | null = ps.getMaterialInstance(1);
if (mat === null && this._defaultTrailMat === null) {
if (mat === null && (!this._defaultTrailMat || !this._defaultTrailMat.passes.length)) {
_matInsInfo.parent = builtinResMgr.get<Material>('default-trail-material');
_matInsInfo.owner = this._particleSystem;
_matInsInfo.subModelIdx = 1;
@@ -61,6 +61,7 @@ const RENDER_MODE_MESH = 4;
const COLOR_OVER_TIME_MODULE_ENABLE = 'COLOR_OVER_TIME_MODULE_ENABLE';
const ROTATION_OVER_TIME_MODULE_ENABLE = 'ROTATION_OVER_TIME_MODULE_ENABLE';
const USE_NORMAL_MAP = 'USE_NORMAL_MAP';
const SIZE_OVER_TIME_MODULE_ENABLE = 'SIZE_OVER_TIME_MODULE_ENABLE';
const VELOCITY_OVER_TIME_MODULE_ENABLE = 'VELOCITY_OVER_TIME_MODULE_ENABLE';
const FORCE_OVER_TIME_MODULE_ENABLE = 'FORCE_OVER_TIME_MODULE_ENABLE';
@@ -229,7 +230,7 @@ export default class ParticleSystemRendererGPU extends ParticleSystemRendererBas
this.initShaderUniform(mat);
mat.recompileShaders(this._defines);
if (this._model) {
this._model.setSubModelMaterial(0, mat);
this._model.updateMaterial(mat);
}
}
@@ -265,7 +266,16 @@ export default class ParticleSystemRendererGPU extends ParticleSystemRendererBas
return;
}
if (this._alignSpace === ParticleAlignmentSpace.Local) {
const ps = this._particleSystem;
if (mode === ParticleRenderMode.Mesh && ps?._shapeModule?.enable && ps._shapeModule.alignToDirection) {
// Aligned particle rotations are already in simulation space. The mesh
// shader only needs the remaining simulation-to-world rotation.
if (ps.simulationSpace === ParticleSpace.Local) {
ps.node.getWorldRotation(_node_rot);
} else {
_node_rot.set(0, 0, 0, 1);
}
} else if (this._alignSpace === ParticleAlignmentSpace.Local) {
this._particleSystem?.node.getRotation(_node_rot);
} else if (this._alignSpace === ParticleAlignmentSpace.World) {
this._particleSystem?.node.getWorldRotation(_node_rot);
@@ -363,6 +373,9 @@ export default class ParticleSystemRendererGPU extends ParticleSystemRendererBas
}
const pass = mat.passes[0];
if (!pass) {
return;
}
_tempVec4.x = this._particleSystem.time;
_tempVec4.y = dt;
pass.setUniform(this._uTimeHandle, _tempVec4);
@@ -375,6 +388,13 @@ export default class ParticleSystemRendererGPU extends ParticleSystemRendererBas
public initShaderUniform (mat: Material): void {
const pass = mat.passes[0];
if (!pass) {
return;
}
// Explicitly clear the override when the material omits the disabled macro.
const materialDefines = (this._particleSystem?.sharedMaterial || mat.parent || mat).passes[0]?.defines;
this._defines[USE_NORMAL_MAP] = !!materialDefines?.[USE_NORMAL_MAP];
this._uTimeHandle = pass.getHandle('u_timeDelta');
this._uRotHandle = pass.getHandle('u_worldRot');
@@ -597,7 +617,8 @@ export default class ParticleSystemRendererGPU extends ParticleSystemRendererBas
this._renderInfo!.mainTexture = shareMaterial.getProperty('mainTexture', 0) as Texture2D;
}
if (ps.sharedMaterial == null && this._defaultMat == null) {
// Recreate the fallback if its passes have been destroyed.
if (ps.sharedMaterial == null && (!this._defaultMat || !this._defaultMat.passes.length)) {
_matInsInfo.parent = builtinResMgr.get<Material>('default-particle-gpu-material');
_matInsInfo.owner = ps;
_matInsInfo.subModelIdx = 0;
@@ -610,6 +631,11 @@ export default class ParticleSystemRendererGPU extends ParticleSystemRendererBas
}
}
const mat: Material | null = ps.getMaterialInstance(0) || this._defaultMat!;
// A custom material may still have an invalid or unavailable effect.
if (!mat || !mat.passes.length) {
warn('Particle material has no render passes. Check its effect import and selected technique.');
return;
}
ps.node.getWorldMatrix(_tempWorldTrans);
+72 -22
View File
@@ -102,7 +102,7 @@ class TrailSegment {
}
if (this.start === -1) {
this.start = 0;
this.end = 1;
this.end = 1 % this.trailElements.length;
return this.trailElements[0];
}
if (this.start === this.end) {
@@ -128,20 +128,25 @@ class TrailSegment {
p: Particle,
dt: number,
): void {
const end = this.start >= this.end ? this.end + this.trailElements.length : this.end;
for (let i = this.start; i < end; i++) {
if (this.start === -1) return;
const count = this.count();
const start = this.start;
let removed = 0;
for (let i = start; i < start + count; i++) {
if (f(target, this.trailElements[i % this.trailElements.length], p, dt)) {
this.start++;
this.start %= this.trailElements.length;
removed++;
}
}
if (this.start === end) {
if (removed === count) {
this.start = -1;
this.end = -1;
}
}
public count (): number {
if (this.start === -1) return 0;
if (this.start < this.end) {
return this.end - this.start;
} else {
@@ -182,7 +187,11 @@ export default class TrailModule {
}
if (val && !this._enable) {
this._enable = val;
if (this._particleSystem!.processor) this._particleSystem!.processor.updateTrailMaterial();
if (this._particleSystem?.processor) this._particleSystem.processor.updateTrailMaterial();
}
if (!this._particleSystem) {
this._enable = val;
return;
}
if (val && !this._trailModel) {
this._createModel();
@@ -397,7 +406,7 @@ export default class TrailModule {
}
public onDisable (): void {
this._particleTrail.clear();
this.clear();
this._detachFromScene();
}
@@ -423,6 +432,7 @@ export default class TrailModule {
}
public destroy (): void {
this.clear();
this.destroySubMeshData();
if (this._trailModel) {
director.root!.destroyModel(this._trailModel);
@@ -441,17 +451,14 @@ export default class TrailModule {
}
public clear (): void {
if (this.enable) {
const trailIter = this._particleTrail.values();
let trail = trailIter.next();
while (!trail.done) {
trail.value.clear();
trail = trailIter.next();
}
this._particleTrail.clear();
this.updateRenderData();
if (this._trailModel) this._trailModel.enabled = false;
for (const trail of this._particleTrail.values()) {
trail.clear();
this._trailSegments?.free(trail);
}
this._particleTrail.clear();
this.vbOffset = 0;
this.ibOffset = 0;
if (this._trailModel) this._trailModel.enabled = false;
}
public updateMaterial (): void {
@@ -505,7 +512,7 @@ export default class TrailModule {
}
if (lastSeg) {
trail.iterateElement(this, this._updateTrailElement, p, scaledDt);
if (Vec3.squaredDistance(lastSeg.position, _temp_vec3) < this._minSquaredDistance) {
if (trail.count() > 0 && Vec3.squaredDistance(lastSeg.position, _temp_vec3) < this._minSquaredDistance) {
return;
}
}
@@ -516,6 +523,8 @@ export default class TrailModule {
Vec3.copy(lastSeg.position, _temp_vec3);
lastSeg.lifetime = 0;
lastSeg.direction = 0;
lastSeg.velocity.set(0, 0, 0);
if (this.widthFromParticle) {
lastSeg.width = p.size.x * this.widthRatio.evaluate(0, 1)!;
} else {
@@ -526,6 +535,7 @@ export default class TrailModule {
if (trailNum === 2) {
const lastSecondTrail = trail.getElement(trail.end - 2)!;
Vec3.subtract(lastSecondTrail.velocity, lastSeg.position, lastSecondTrail.position);
Vec3.normalize(lastSecondTrail.velocity, lastSecondTrail.velocity);
} else if (trailNum > 2) {
const lastSecondTrail = trail.getElement(trail.end - 2)!;
const lastThirdTrail = trail.getElement(trail.end - 3)!;
@@ -557,14 +567,28 @@ export default class TrailModule {
public updateRenderData (): void {
this.vbOffset = 0;
this.ibOffset = 0;
for (const p of this._particleTrail.keys()) {
const trailSeg = this._particleTrail.get(p)!;
let vertexCount = 0;
for (const trail of this._particleTrail.values()) {
if (trail.count() > 0) vertexCount += (trail.count() + 1) * 2;
}
// Initialization preallocates the estimated capacity; grow only if that estimate is exceeded.
if (vertexCount > this._iaVertCount) {
if (!this._ensureBufferCapacity(Math.min(vertexCount, 65536))) {
// Do not upload or draw with a partially resized pair of GPU buffers.
this.updateIA(0);
if (this._trailModel) this._trailModel.enabled = false;
return;
}
}
for (const [p, trailSeg] of this._particleTrail) {
if (trailSeg.start === -1) {
continue;
}
const indexOffset = this.vbOffset * 4 / this._vertSize;
const end = trailSeg.start >= trailSeg.end ? trailSeg.end + trailSeg.trailElements.length : trailSeg.end;
const trailNum = end - trailSeg.start;
// Uint16 indices cannot address vertices beyond this limit.
if (indexOffset + (trailNum + 1) * 2 > 65536) continue;
// const lastSegRatio = vec3.distance(trailSeg.getTailElement()!.position, p.position) / this._minParticleDistance;
const textCoordSeg = 1 / (trailNum /* - 1 + lastSegRatio */);
const startSegEle = trailSeg.trailElements[trailSeg.start];
@@ -656,11 +680,13 @@ export default class TrailModule {
const subModels = this._trailModel && this._trailModel.subModels;
if (subModels && subModels.length > 0) {
const subModel = subModels[0];
subModel.inputAssembler.vertexBuffers[0].update(this._vbF32!);
subModel.inputAssembler.indexBuffer!.update(this._iBuffer!);
if (count > 0) {
subModel.inputAssembler.vertexBuffers[0].update(this._vbF32!, this.vbOffset * 4);
subModel.inputAssembler.indexBuffer!.update(this._iBuffer!, count * Uint16Array.BYTES_PER_ELEMENT);
}
subModel.inputAssembler.firstIndex = 0;
subModel.inputAssembler.indexCount = count;
subModel.inputAssembler.vertexCount = this._iaVertCount;
subModel.inputAssembler.vertexCount = this.vbOffset * 4 / this._vertSize;
}
}
@@ -676,8 +702,31 @@ export default class TrailModule {
this._trailModel = (cclegacy.director.root as Root).createModel(scene.Model);
}
private _ensureBufferCapacity (vertexCount: number): boolean {
if (vertexCount <= this._iaVertCount) return true;
if (!this._subMeshData) return false;
const capacity = Math.min(65536, Math.max(vertexCount, this._iaVertCount * 2));
const vertexBytes = capacity * this._vertSize;
const indexBytes = capacity * 3 * Uint16Array.BYTES_PER_ELEMENT;
const vertexBuffer = this._subMeshData.vertexBuffers[0];
const indexBuffer = this._subMeshData.indexBuffer!;
if (vertexBuffer.size < vertexBytes) vertexBuffer.resize(vertexBytes);
if (indexBuffer.size < indexBytes) indexBuffer.resize(indexBytes);
if (vertexBuffer.size < vertexBytes || indexBuffer.size < indexBytes) return false;
// Commit CPU storage and capacity only after both GPU allocations succeed.
const buffer = new ArrayBuffer(vertexBytes);
this._vbF32 = new Float32Array(buffer);
this._vbUint32 = new Uint32Array(buffer);
this._iBuffer = new Uint16Array(capacity * 3);
this._iaVertCount = capacity;
this._iaIndexCount = this._iBuffer.length;
return true;
}
private rebuild (): void {
const self = this;
// Preserve the full estimate from onInit instead of relying on runtime buffer growth.
const device: Device = director.root!.device;
const vertexBuffer = device.createBuffer(new BufferInfo(
BufferUsageBit.VERTEX | BufferUsageBit.TRANSFER_DST,
@@ -715,6 +764,7 @@ export default class TrailModule {
private _updateTrailElement (module: TrailModule, trailEle: ITrailElement, p: Particle, dt: number): boolean {
trailEle.lifetime += dt;
if (module._trailLifetime <= 0 || trailEle.lifetime > module._trailLifetime) return true;
if (module.colorFromParticle) {
trailEle.color.set(p.color);
trailEle.color.multiply(module.colorOvertime.evaluate(1.0 - p.remainingLifetime / p.startLifetime, 1));
+130 -141
View File
@@ -26,7 +26,6 @@
import { BufferInfo, Buffer, BufferUsageBit, ClearFlagBit, Color, DescriptorSet, LoadOp,
Format, Rect, Sampler, StoreOp, Texture, Viewport, MemoryUsageBit,
UniformBlock,
Device,
} from '../../gfx';
import { ReflectionProbe } from '../../render-scene/scene/reflection-probe';
import { Camera, SkyBoxFlagValue } from '../../render-scene/scene/camera';
@@ -446,58 +445,109 @@ export function getDescBindingFromName (bindingName: string): number {
return -1;
}
const uploadedUniforms = new WeakMap<Buffer, Float32Array>();
function isUniformChanged (cached: Float32Array, values: number[]): boolean {
return cached.length !== values.length || values.some((v, i) => !Object.is(Math.fround(v), cached[i]));
}
class DescBuffManager {
private buffers: Buffer[] = [];
private currBuffIdx: number = 0;
private device: Device;
public currUniform: Float32Array;
private _root;
private currUniform: Float32Array;
private lastUploadedBuffer: Buffer | null = null;
constructor (bufferSize: number, numBuffers: number = 2) {
const root = this._root = cclegacy.director.root;
const device = root.device;
this.device = device;
const root = cclegacy.director.root;
const device = (root.pipeline as WebPipeline)?.device || root.device;
const { buffers } = this;
const bufferInfo = new BufferInfo(
BufferUsageBit.UNIFORM | BufferUsageBit.TRANSFER_DST,
MemoryUsageBit.HOST | MemoryUsageBit.DEVICE,
bufferSize,
bufferSize,
);
this.currUniform = new Float32Array(bufferSize / 4);
for (let i = 0; i < numBuffers; i++) {
const bufferInfo: BufferInfo = new BufferInfo(
BufferUsageBit.UNIFORM | BufferUsageBit.TRANSFER_DST,
MemoryUsageBit.HOST | MemoryUsageBit.DEVICE,
bufferSize,
bufferSize,
);
this.buffers.push(this.device.createBuffer(bufferInfo));
buffers.push(device.createBuffer(bufferInfo));
}
}
getCurrentBuffer (): Buffer {
const { director } = cclegacy;
this.currBuffIdx = director.getTotalFrames() % this.buffers.length;
return this.buffers[this.currBuffIdx];
updateBuffer (binding: number, descriptorSet: DescriptorSet, values: number[]): void {
const { buffers, currUniform } = this;
let lastBuf = this.lastUploadedBuffer;
if (!lastBuf || isUniformChanged(currUniform, values)) {
if (lastBuf) {
uploadedUniforms.delete(lastBuf);
}
lastBuf = buffers[this.currBuffIdx];
this.currBuffIdx = (this.currBuffIdx + 1) % buffers.length;
currUniform.set(values);
lastBuf.update(currUniform);
uploadedUniforms.set(lastBuf, currUniform);
this.lastUploadedBuffer = lastBuf;
}
descriptorSet.bindBuffer(binding, lastBuf);
}
updateData (vals: number[]): void {
this.currUniform.set(vals);
}
updateBuffer (bindId: number, setData: DescriptorSetData): void {
const descriptorSet = setData.descriptorSet!;
const buffer = this.getCurrentBuffer();
buffer.update(this.currUniform);
bindGlobalDesc(descriptorSet, bindId, buffer);
destroy (): void {
const { buffers } = this;
for (const buffer of buffers) {
uploadedUniforms.delete(buffer);
buffer.destroy();
}
buffers.length = 0;
this.lastUploadedBuffer = null;
}
}
const buffsMap: Map<string, DescBuffManager> = new Map();
const currBindBuffs: Map<string, number> = new Map();
interface ConstantBlockInfo {
offset: number;
buffer: number[];
blockId: number;
}
const layouts: Map<string, DescriptorSetData> = new Map();
export function getDescriptorSetDataFromLayout (layoutName: string): DescriptorSetData | undefined {
interface LayoutUBOCache {
descriptorSetData: DescriptorSetData;
uniformBlockMap: Map<number, number[]>;
constantBlockMap: Map<number, ConstantBlockInfo>;
}
const pipelineCaches = new WeakMap<WebPipeline, { buffsMap: Map<string, DescBuffManager>; layouts: Map<string, LayoutUBOCache> }>();
const pendingBlocks: Map<number, number[]> = new Map();
function getUBOCache (webPip: WebPipeline): { buffsMap: Map<string, DescBuffManager>; layouts: Map<string, LayoutUBOCache> } {
let cache = pipelineCaches.get(webPip);
if (!cache) {
cache = { buffsMap: new Map(), layouts: new Map() };
pipelineCaches.set(webPip, cache);
}
return cache;
}
export function destroyUBOCache (webPip: WebPipeline): void {
const cache = pipelineCaches.get(webPip);
if (!cache) { return; }
for (const manager of cache.buffsMap.values()) {
manager.destroy();
}
pipelineCaches.delete(webPip);
}
function getLayoutUBOCache (layoutName: string): LayoutUBOCache | undefined {
const webPip = cclegacy.director.root.pipeline as WebPipeline;
const { layouts } = getUBOCache(webPip);
const descLayout = layouts.get(layoutName);
if (descLayout) {
return descLayout;
}
const webPip = cclegacy.director.root.pipeline as WebPipeline;
const stageId = webPip.layoutGraph.locateChild(webPip.layoutGraph.N, layoutName);
const layout = webPip.layoutGraph.getLayout(stageId);
const layoutData = layout.getSet(UpdateFrequency.PER_PASS);
layouts.set(layoutName, layoutData!);
return layoutData;
const lg = webPip.layoutGraph;
const stageId = lg.locateChild(lg.N, layoutName);
const layoutData = lg.getLayout(stageId).getSet(UpdateFrequency.PER_PASS);
if (!layoutData) { return undefined; }
const cache: LayoutUBOCache = { descriptorSetData: layoutData, uniformBlockMap: new Map(), constantBlockMap: new Map() };
layouts.set(layoutName, cache);
return cache;
}
export function getDescriptorSetDataFromLayout (layoutName: string): DescriptorSetData | undefined {
return getLayoutUBOCache(layoutName)?.descriptorSetData;
}
export function getDescriptorSetDataFromLayoutId (id: number): DescriptorSetData | undefined {
@@ -507,147 +557,74 @@ export function getDescriptorSetDataFromLayoutId (id: number): DescriptorSetData
return layoutData;
}
export function updateGlobalDescBinding (data: RenderData, sceneId: number, idxRD: number, layoutName = 'default'): void {
updatePerPassUBO(layoutName, sceneId, idxRD, data);
}
function getUniformBlock (block: string, layoutName: string): UniformBlock | undefined {
const webPip = cclegacy.director.root.pipeline as WebPipeline;
const lg = webPip.layoutGraph;
const nodeId = lg.locateChild(0xFFFFFFFF, layoutName);
const ppl = lg.getLayout(nodeId);
const layout = ppl.getSet(UpdateFrequency.PER_PASS)!.descriptorSetLayoutData;
const nameID: number = lg.attributeIndex.get(block)!;
return layout.uniformBlocks.get(nameID);
}
function getUniformOffset (uniform: string, block: string, layout: string): number {
const uniformBlock = getUniformBlock(block, layout);
if (!uniformBlock) return -1;
function getUniformOffset (uniform: string, uniformBlock: UniformBlock): number {
let offset = 0;
for (const currUniform of uniformBlock.members) {
const currCount = getUBOTypeCount(currUniform.type);
if (currUniform.name === uniform) {
return offset;
}
offset += currCount * currUniform.count;
offset += getUBOTypeCount(currUniform.type) * currUniform.count;
}
return -1;
}
const uniformBlockMap: Map<string, number[]> = new Map();
class ConstantBlockInfo {
offset: number = -1;
buffer: number[] = [];
blockId: number = -1;
}
const constantBlockMap: Map<number, ConstantBlockInfo> = new Map();
function copyToConstantBuffer (target: number[], val: number[], offset: number): boolean {
let isImparity = false;
if (offset < 0 || offset > target.length) {
return isImparity;
}
const length = Math.min(val.length, target.length - offset);
for (let i = 0; i < length; i++) {
if (target[offset + i] !== val[i]) {
target[offset + i] = val[i];
isImparity = true;
}
}
return isImparity;
}
function addConstantBuffer (block: string, layout: string): number[] | null {
let buffers = uniformBlockMap.get(block);
function addConstantBuffer (blockId: number, currBlock: UniformBlock, uniformBlockMap: Map<number, number[]>): number[] {
let buffers = uniformBlockMap.get(blockId);
if (buffers) {
return buffers;
}
buffers = [];
const webPip = cclegacy.director.root.pipeline as WebPipeline;
const lg = webPip.layoutGraph;
let currCount = 0;
const currBlock = getUniformBlock(block, layout);
if (!currBlock) return null;
for (const uniform of currBlock.members) {
currCount += getUBOTypeCount(uniform.type) * uniform.count;
}
buffers.length = currCount;
buffers.fill(0);
uniformBlockMap.set(block, buffers);
buffers = new Array<number>(currCount).fill(0);
uniformBlockMap.set(blockId, buffers);
return buffers;
}
function updateGlobalDescBuffer (descKey: string, vals: number[]): void {
let currDescBuff = buffsMap.get(descKey);
if (!currDescBuff) {
buffsMap.set(descKey, new DescBuffManager(vals.length * 4, 2));
currDescBuff = buffsMap.get(descKey);
function updateConstantBlock ({ buffer, blockId, offset }: ConstantBlockInfo, data: number[]): void {
const length = Math.min(data.length, buffer.length - offset);
for (let i = 0; i < length; ++i) {
buffer[offset + i] = data[i];
}
currDescBuff!.updateData(vals);
pendingBlocks.set(blockId, buffer);
}
function updateConstantBlock (
constantBuff: ConstantBlockInfo,
data: number[],
descriptorSetData: DescriptorSetData,
sceneId: number,
idxRD: number,
): void {
const blockId = constantBuff.blockId;
const buffer = constantBuff.buffer;
const isImparity = copyToConstantBuffer(buffer, data, constantBuff.offset);
const bindId = getDescBinding(blockId, descriptorSetData);
const desc = descriptorSetData.descriptorSet!;
if (isImparity || !desc.getBuffer(bindId) && bindId !== -1) {
const descKey = `${blockId}${bindId}${idxRD}${sceneId}`;
currBindBuffs.set(descKey, bindId);
updateGlobalDescBuffer(descKey, buffer);
}
}
function updateDefaultConstantBlock (blockId: number, sceneId: number, idxRD: number, vals: number[], setData: DescriptorSetData): void {
const bindId = getDescBinding(blockId, setData);
if (bindId === -1) { return; }
const descKey = `${blockId}${bindId}${idxRD}${sceneId}`;
currBindBuffs.set(descKey, bindId);
updateGlobalDescBuffer(descKey, vals);
}
export function updatePerPassUBO (layout: string, sceneId: number, idxRD: number, user: RenderData): void {
export function updateGlobalDescBinding (user: RenderData, sceneId: number, layout = 'default'): void {
const { constants, samplers, textures, buffers } = user;
const webPip = cclegacy.director.root.pipeline as WebPipeline;
const { buffsMap } = getUBOCache(webPip);
const lg = webPip.layoutGraph;
const descriptorSetData = getDescriptorSetDataFromLayout(layout)!;
currBindBuffs.clear();
const { descriptorSetData, uniformBlockMap, constantBlockMap } = getLayoutUBOCache(layout)!;
const descriptorSet = descriptorSetData.descriptorSet!;
const uniformBlocks = descriptorSetData.descriptorSetLayoutData.uniformBlocks;
pendingBlocks.clear();
for (const [key, data] of constants) {
let constantBlock = constantBlockMap.get(key);
if (!constantBlock) {
const currMemKey = Array.from(lg.constantIndex).find(([_, v]) => v === key)![0];
for (const [block, blockId] of lg.attributeIndex) {
const constantBuff = addConstantBuffer(block, layout);
if (!constantBuff) continue;
const offset = getUniformOffset(currMemKey, block, layout);
for (const [blockId, uniformBlock] of uniformBlocks) {
const constantBuff = addConstantBuffer(blockId, uniformBlock, uniformBlockMap);
const offset = getUniformOffset(currMemKey, uniformBlock);
// not found
if (offset === -1) {
// Although the current uniformMem does not belong to the current uniform block,
// it does not mean that it should not be bound to the corresponding descriptor.
updateDefaultConstantBlock(blockId, sceneId, idxRD, constantBuff, descriptorSetData);
const binding = getDescBinding(blockId, descriptorSetData);
if (binding !== -1 && !descriptorSet.getBuffer(binding)) {
pendingBlocks.set(blockId, constantBuff);
}
continue;
}
constantBlockMap.set(key, new ConstantBlockInfo());
constantBlock = constantBlockMap.get(key)!;
constantBlock.buffer = constantBuff;
constantBlock.blockId = blockId;
constantBlock.offset = offset;
updateConstantBlock(constantBlock, data, descriptorSetData, sceneId, idxRD);
constantBlock = { buffer: constantBuff, blockId, offset };
constantBlockMap.set(key, constantBlock);
updateConstantBlock(constantBlock, data);
}
} else {
updateConstantBlock(constantBlock, data, descriptorSetData, sceneId, idxRD);
updateConstantBlock(constantBlock, data);
}
}
const descriptorSet = descriptorSetData.descriptorSet!;
for (const [key, value] of textures) {
const bindId = getDescBinding(key, descriptorSetData);
if (bindId === -1) { continue; }
@@ -666,15 +643,27 @@ export function updatePerPassUBO (layout: string, sceneId: number, idxRD: number
bindGlobalDesc(descriptorSet, bindId, value);
}
}
for (const [key, value] of currBindBuffs) {
const buffManager = buffsMap.get(key)!;
buffManager.updateBuffer(value, descriptorSetData);
for (const [blockId, values] of pendingBlocks) {
const binding = getDescBinding(blockId, descriptorSetData);
if (binding === -1) { continue; }
const boundBuffer = descriptorSet.getBuffer(binding);
const boundValues = boundBuffer ? uploadedUniforms.get(boundBuffer) : undefined;
if (boundValues && !isUniformChanged(boundValues, values)) {
continue;
}
const key = `${layout}:${blockId}:${sceneId}`;
let manager = buffsMap.get(key);
if (!manager) {
manager = new DescBuffManager(values.length * 4);
buffsMap.set(key, manager);
}
manager.updateBuffer(binding, descriptorSet, values);
}
for (const [key, value] of buffers) {
const bindId = getDescBinding(key, descriptorSetData);
if (bindId === -1) { continue; }
const buffer = descriptorSet.getBuffer(bindId);
if (!buffer) {
if (buffer !== value) {
bindGlobalDesc(descriptorSet, bindId, value);
}
}
+14 -26
View File
@@ -103,7 +103,6 @@ import {
RasterPass,
RasterSubpass,
RaytracePass,
RenderData,
RenderGraph,
RenderGraphValue,
RenderGraphVisitor,
@@ -773,7 +772,6 @@ class DeviceRenderPass implements RecordingInterface {
protected _layoutName: string;
protected _viewport: Viewport | null = null;
private _layout: RenderPassLayoutInfo | null = null;
private _idxOfRenderData: number = 0;
private _traversalResolves (callback: (resolvePair: ResolvePair) => void): void {
const subpassGraph = this._rasterPass.subpassGraph;
@@ -899,7 +897,6 @@ class DeviceRenderPass implements RecordingInterface {
);
}
get passMergeInfo (): RenderPassMergeInfo { return rpMergeInfos.get(this._rasterPass)!; }
get indexOfRD (): number { return this._idxOfRenderData; }
get rasterID (): number { return this._rasterID; }
get layoutName (): string { return this._layoutName; }
get passID (): number { return this._passID; }
@@ -911,9 +908,6 @@ class DeviceRenderPass implements RecordingInterface {
get clearStencil (): number { return this._clearStencil; }
get deviceQueues (): Map<number, DeviceRenderQueue> { return this._deviceQueues; }
get viewport (): Viewport | null { return this._viewport; }
addIdxOfRD (): void {
this._idxOfRenderData++;
}
visitResource (resName: string): void {
const resourceGraph = context.resourceGraph;
const vertId = resourceGraph.vertex(resName);
@@ -1038,7 +1032,6 @@ class DeviceRenderPass implements RecordingInterface {
this._layoutName = context.renderGraph.getLayout(id);
this._passID = cclegacy.rendering.getPassID(this._layoutName);
this._deviceQueues.clear();
this._idxOfRenderData = 0;
let framebuffer: Framebuffer | null = null;
const colTextures: Texture[] = [];
const currFramebuffer = this._framebuffer;
@@ -1172,8 +1165,9 @@ class DeviceComputePass implements RecordingInterface {
for (const queue of this._deviceQueues) {
queue.record();
}
const renderData = context.renderGraph.getData(this._computeInfo.id);
updateGlobalDescBinding(renderData, -1, 0, context.renderGraph.getLayout(this._computeInfo.id));
const rg = context.renderGraph;
const passId = this._computeInfo.id;
updateGlobalDescBinding(rg.getData(passId), -1, rg.getLayout(passId));
}
resetResource (id: number, pass: ComputePass): void {
@@ -1309,32 +1303,26 @@ class DeviceRenderScene implements RecordingInterface {
recordCommand(context.commandBuffer, this._renderPass, pass, blitDesc.stageDesc!, shader, screenIa);
}
protected _updateGlobal (data: RenderData, sceneId: number): void {
const devicePass = this._currentQueue.devicePass;
devicePass.addIdxOfRD();
updateGlobalDescBinding(data, sceneId, devicePass.indexOfRD, context.renderGraph.getLayout(devicePass.rasterID));
}
protected _updateRenderData (): void {
if (this._currentQueue.isUpdateUBO) return;
const devicePass = this._currentQueue.devicePass;
const queue = this._currentQueue;
if (queue.isUpdateUBO) return;
const devicePass = queue.devicePass;
const rg = context.renderGraph;
const rasterId = devicePass.rasterID;
const passRenderData = context.renderGraph.getData(rasterId);
const layout = rg.getLayout(rasterId);
const sceneId = this.sceneID;
// global
this._updateGlobal(context.renderGraph.globalRenderData, sceneId);
updateGlobalDescBinding(rg.globalRenderData, sceneId, layout);
// pass
this._updateGlobal(passRenderData, sceneId);
updateGlobalDescBinding(rg.getData(rasterId), sceneId, layout);
// queue
const queueId = this._currentQueue.queueId;
const queueRenderData = context.renderGraph.getData(queueId)!;
this._updateGlobal(queueRenderData, sceneId);
updateGlobalDescBinding(rg.getData(queue.queueId)!, sceneId, layout);
// scene
const sceneRenderData = context.renderGraph.getData(sceneId)!;
if (sceneRenderData) this._updateGlobal(sceneRenderData, sceneId);
const sceneRenderData = rg.getData(sceneId);
if (sceneRenderData) updateGlobalDescBinding(sceneRenderData, sceneId, layout);
devicePass.processRenderLayout();
context.passDescriptorSet?.update();
this._currentQueue.isUpdateUBO = true;
queue.isUpdateUBO = true;
}
private _applyViewport (): void {
+1
View File
@@ -58,6 +58,7 @@ export enum ResourceResidency {
PERSISTENT,
EXTERNAL,
BACKBUFFER,
CUSTOM,
}
export enum QueueHint {
+3 -2
View File
@@ -45,7 +45,7 @@ import { GeometryRenderer } from '../geometry-renderer';
import { Material } from '../../asset/assets';
import { decideProfilerCamera } from '../pipeline-funcs';
import { DebugViewCompositeType } from '../debug-view';
import { buildReflectionProbePass, genHashValue, resetPassMGState } from './define';
import { buildReflectionProbePass, destroyUBOCache, genHashValue, resetPassMGState } from './define';
import { createGfxDescriptorSetsAndPipelines } from './layout-graph-utils';
import { Root } from '../../root';
import { Scene } from '../../scene-graph';
@@ -1360,6 +1360,7 @@ export class WebPipeline extends WebSetter implements BasicPipeline {
return true;
}
public destroy (): boolean {
destroyUBOCache(this);
this._pipelineSceneData?.destroy();
return true;
}
@@ -1624,7 +1625,7 @@ export class WebPipeline extends WebSetter implements BasicPipeline {
addShadingRateTexture (name: string, width: number, height: number, residency = ResourceResidency.MANAGED): number {
const resID = this._resourceGraph.find(name);
if (resID !== 0xFFFFFFFF) {
this.addShadingRateTexture(name, width, height);
this.updateShadingRateTexture(name, width, height);
return resID;
}
const desc = new ResourceDesc();
+20 -5
View File
@@ -141,12 +141,27 @@ export class InstancedBuffer {
private _appendInstance (instance: IInstancedItem, data: Uint8Array, shader: Shader, descriptorSet: DescriptorSet): void {
if (instance.count >= instance.capacity) { // resize buffers
instance.capacity = Math.min(instance.capacity << 1, MAX_CAPACITY);
const requiredCapacity = instance.count + 1;
const targetCapacity = Math.min(Math.max(instance.capacity << 1, requiredCapacity), MAX_CAPACITY);
const targetSize = instance.stride * targetCapacity;
instance.vb.resize(targetSize);
if (instance.vb.size < targetSize) {
const requiredSize = instance.stride * requiredCapacity;
if (instance.vb.size < requiredSize) {
instance.vb.resize(requiredSize);
}
}
instance.capacity = Math.floor(instance.vb.size / instance.stride);
if (instance.count >= instance.capacity) {
instance.count = instance.capacity;
return;
}
const newSize = instance.stride * instance.capacity;
const oldData = instance.data;
instance.data = new Uint8Array(newSize);
instance.data.set(oldData);
instance.vb.resize(newSize);
if (newSize > instance.data.byteLength) {
const oldData = instance.data;
instance.data = new Uint8Array(newSize);
instance.data.set(oldData.subarray(0, instance.count * instance.stride));
}
}
instance.shader = shader;
instance.descriptorSet = descriptorSet;
+9 -1
View File
@@ -28,7 +28,7 @@ import { NodeEventType } from './node-event';
import { CCObjectFlags } from '../core/data/object';
import { NodeUIProperties } from './node-ui-properties';
import { MobilityMode, NodeSpace, TransformBit } from './node-enum';
import { IVec2Like, Mat4, Quat, Vec3 } from '../core/math';
import { EPSILON, IVec2Like, Mat4, Quat, toDegree, Vec3 } from '../core/math';
import { Layers } from './layers';
import { editorExtrasTag, SerializationContext, SerializationOutput, serializeTag } from '../core/data';
import { _tempFloatArray, fillMat4WithTempFloatArray } from './utils.jsb';
@@ -692,6 +692,14 @@ nodeProto.setPosition = function setPosition(val: Readonly<Vec3> | number, y?: n
this._setPosition();
};
nodeProto.getAngle2D = function getAngle2D(): number {
const { x, y, z, w } = this._lrot;
if (Math.abs(x) < EPSILON && Math.abs(y) < EPSILON) {
return toDegree(Math.atan2(2 * w * z, 1 - 2 * z * z));
}
return this.eulerAngles.z;
};
nodeProto.getRotation = function getRotation(out?: Quat): Quat {
const lrot = this._lrot;
if (out) {
+31 -4
View File
@@ -29,7 +29,7 @@ import { NodeUIProperties } from './node-ui-properties';
import { cclegacy } from '../core/global-exports';
import { nodePolyfill } from './node-dev';
import { ISchedulable } from '../core/scheduler';
import { approx, EPSILON, Mat3, mat4, Mat4, quat, Quat, v3, Vec3 } from '../core/math';
import { approx, EPSILON, Mat3, mat4, Mat4, quat, Quat, toDegree, v3, Vec3 } from '../core/math';
import { MobilityMode, NodeSpace, TransformBit } from './node-enum';
import { CustomSerializable, editorExtrasTag, SerializationContext, SerializationOutput, serializeTag } from '../core/data';
import { errorID, warnID, error, log, getError } from '../core/platform/debug';
@@ -59,6 +59,7 @@ const ACTIVE_ON = 1 << 1;
const idGenerator = new js.IDGenerator('Node');
/* eslint-disable-next-line max-len */
function getConstructor<T> (typeOrClassName: string | Constructor<T> | AbstractedConstructor<T>): Constructor<T> | AbstractedConstructor<T> | null | undefined {
if (!typeOrClassName) {
errorID(3804);
@@ -316,6 +317,7 @@ export class Node extends CCObject implements ISchedulable, CustomSerializable {
return null;
}
/* eslint-disable-next-line max-len */
protected static _findComponents<T extends Component> (node: Node, constructor: Constructor<T> | AbstractedConstructor<T>, components: Component[]): void {
const cls = constructor;
const comps = node._components;
@@ -1847,6 +1849,22 @@ export class Node extends CCObject implements ISchedulable, CustomSerializable {
}
}
/**
* @en Gets the signed local Z rotation in degrees for 2D nodes, in [-180, 180].
* Full turns are not preserved. For non-planar rotations, returns the Euler Z component.
* @zh 获取二维节点的本地 Z 轴有符号旋转角度,范围为 [-180, 180],不保留累计圈数。
* 非平面旋转返回欧拉角的 Z 分量。
*/
public getAngle2D (): number {
// YZX Euler decomposition folds Z into [-90, 90]. For a 2D rotation,
// extract the signed angle directly, without changing the 3D Euler cache.
const { x, y, z, w } = this._lrot;
if (Math.abs(x) < EPSILON && Math.abs(y) < EPSILON) {
return toDegree(Math.atan2(2 * w * z, 1 - 2 * z * z));
}
return this.eulerAngles.z;
}
/**
* @en Rotation in world coordinate system, represented by a quaternion
* @zh 世界坐标系下的旋转,用四元数表示
@@ -2801,9 +2819,18 @@ export class Node extends CCObject implements ISchedulable, CustomSerializable {
Mat3.multiplyMat4(m3_1, m3_1, m4_2);
const localScale = self._lscale;
localScale.x = Vec3.set(v3_a, m3_1.m00, m3_1.m01, m3_1.m02).length();
localScale.y = Vec3.set(v3_a, m3_1.m03, m3_1.m04, m3_1.m05).length();
localScale.z = Vec3.set(v3_a, m3_1.m06, m3_1.m07, m3_1.m08).length();
// Restore the requested signs. For negative X, the parent may already supply a reflection.
const parentScale = parent._scale;
const parentSign = (parentScale.x < 0 ? -1 : 1) * (parentScale.y < 0 ? -1 : 1) * (parentScale.z < 0 ? -1 : 1);
const localScaleX = Vec3.set(v3_a, m3_1.m00, m3_1.m01, m3_1.m02).length() * (worldScale.x < 0 ? -parentSign : 1);
const localScaleY = Vec3.set(v3_a, m3_1.m03, m3_1.m04, m3_1.m05).length() * (worldScale.y < 0 ? -1 : 1);
const localScaleZ = Vec3.set(v3_a, m3_1.m06, m3_1.m07, m3_1.m08).length() * (worldScale.z < 0 ? -1 : 1);
if ((localScale.x < 0) !== (localScaleX < 0)
|| (localScale.y < 0) !== (localScaleY < 0)
|| (localScale.z < 0) !== (localScaleZ < 0)) {
rotationFlag = TransformBit.ROTATION;
}
Vec3.set(localScale, localScaleX, localScaleY, localScaleZ);
if (localScale.x === 0 || localScale.y === 0 || localScale.z === 0) {
rotationFlag = TransformBit.ROTATION;
}
+54 -7
View File
@@ -93,8 +93,8 @@ enum State {
export enum ButtonEventType {
/**
* @event click
* @param {Event.EventCustom} event
* @param {Button} button - The Button component.
* @param {EventTouch} event - The original touch event, undefined if the click is triggered by XR.
*/
CLICK = 'click',
}
@@ -156,16 +156,16 @@ export enum ButtonEventType {
*
* @example
* ```ts
* import { log, Node } from 'cc';
* import { log } from 'cc';
* // Add an event to the button.
* button.node.on(Node.EventType.TOUCH_START, (event) => {
* log("This is a callback after the trigger event");
* });
* // You could also add a click event
* // Note: In this way, you can't get the touch event info, so use it wisely.
* button.node.on(Node.EventType.CLICK, (button) => {
* //The event is a custom event, you could get the Button component via first argument
* })
* // The callback receives the Button component and the original touch event (if available).
* button.on(Button.EventType.CLICK, (button, event) => {
* log('button clicked');
* });
* ```
*/
@ccclass('cc.Button')
@@ -586,6 +586,53 @@ export class Button extends Component {
super();
}
/**
* @en
* Register a Button event listener on the component. Button events are dispatched by the owner
* node, and this method is a shorthand which forwards the registration to the node, so
* `button.on(...)` and `button.node.on(...)` share the same listener registry.
* @zh
* 在组件上注册 Button 事件监听。Button 的事件由所属节点派发,此方法是 `this.node.on(type, ...)`
* 的便捷封装,`button.on(...)` 与 `button.node.on(...)` 共用同一份监听器。
* @param type @en Event type, e.g. [[ButtonEventType.CLICK]]. @zh 事件类型,如 [[ButtonEventType.CLICK]]。
* @param callback @en The callback, receives the Button component and the original event. @zh 回调函数,参数为 Button 组件与原始事件。
* @param target @en The target to be bound with. @zh 绑定的目标对象。
* @example
* ```ts
* button.on(Button.EventType.CLICK, (button, event) => {
* // clicked
* }, this);
* ```
*/
public on (type: ButtonEventType, callback: (button: Button, event?: EventTouch) => void, target?: unknown): void {
this.node.on(type, callback, target);
}
/**
* @en
* Remove a Button event listener registered via [[on]] or `button.node.on`. To remove a listener,
* the `type`, `callback` and `target` must match the registration.
* @zh
* 移除通过 [[on]] 或 `button.node.on` 注册的 Button 事件监听。`type`、`callback`、`target`
* 需与注册时一致才能正确移除。
*/
public off (type: ButtonEventType, callback?: (button: Button, event?: EventTouch) => void, target?: unknown): void {
this.node.off(type, callback, target);
}
/**
* @en
* Remove all Button event listeners registered with the given target.
* Note: this forwards to `node.targetOff`, so listeners registered by other components
* or by the engine internals on the same node with the same target are removed as well.
* @zh
* 移除指定 target 上注册的所有 Button 事件监听。注意:此方法会转发到 `node.targetOff`,
* 同一节点上其他组件或引擎内部以相同 target 注册的监听也会被一并移除。
*/
public targetOff (target: unknown): void {
this.node.targetOff(target);
}
public __preload (): void {
if (!this.target) {
this.target = this.node;
@@ -892,7 +939,7 @@ export class Button extends Component {
if (this._pressed) {
ComponentEventHandler.emitEvents(this.clickEvents, event);
this.node.emit(ButtonEventType.CLICK, this);
this.node.emit(ButtonEventType.CLICK, this, event);
}
this._pressed = false;
this._updateState();
+9 -5
View File
@@ -41,6 +41,7 @@ import { InputFlag, InputMode, KeyboardReturnType } from './types';
import { EditBoxImplBase } from './edit-box-impl-base';
import { BrowserType, OS } from '../../../pal/system-info/enum-type';
import { ccwindow } from '../../core/global-exports';
import { getCanvasFontFamily } from '../../2d/utils/font-family';
const ccdocument = ccwindow.document;
@@ -519,7 +520,7 @@ export class EditBoxImpl extends EditBoxImplBase {
let font = textLabel.font;
if (font && !(font instanceof BitmapFont)) {
font = font._fontFamily;
font = getCanvasFontFamily(textLabel as Label);
} else {
font = textLabel.fontFamily;
}
@@ -570,7 +571,7 @@ export class EditBoxImpl extends EditBoxImplBase {
let font = placeholderLabel.font;
if (font && !(font instanceof BitmapFont)) {
font = placeholderLabel.font._fontFamily;
font = getCanvasFontFamily(placeholderLabel as Label);
} else {
font = placeholderLabel.fontFamily;
}
@@ -610,9 +611,12 @@ export class EditBoxImpl extends EditBoxImplBase {
break;
}
styleEl!.innerHTML = `#${this._domId}::-webkit-input-placeholder{text-transform: initial;-family: ${font};font-size: ${fontSize}px;color: ${fontColor};line-height: ${lineHeight}px;text-align: ${horizontalAlign};}`
+ `#${this._domId}::-moz-placeholder{text-transform: initial;-family: ${font};font-size: ${fontSize}px;color: ${fontColor};line-height: ${lineHeight}px;text-align: ${horizontalAlign};}`
+ `#${this._domId}::-ms-input-placeholder{text-transform: initial;-family: ${font};font-size: ${fontSize}px;color: ${fontColor};line-height: ${lineHeight}px;text-align: ${horizontalAlign};}`;
styleEl!.innerHTML = `#${this._domId}::-webkit-input-placeholder{text-transform: initial;-family: ${font};`
+ `font-size: ${fontSize}px;color: ${fontColor};line-height: ${lineHeight}px;text-align: ${horizontalAlign};}`
+ `#${this._domId}::-moz-placeholder{text-transform: initial;-family: ${font};`
+ `font-size: ${fontSize}px;color: ${fontColor};line-height: ${lineHeight}px;text-align: ${horizontalAlign};}`
+ `#${this._domId}::-ms-input-placeholder{text-transform: initial;-family: ${font};`
+ `font-size: ${fontSize}px;color: ${fontColor};line-height: ${lineHeight}px;text-align: ${horizontalAlign};}`;
// EDGE_BUG_FIX: hide clear button, because clearing input box in Edge does not emit input event
// issue refference: https://github.com/angular/angular/issues/26307
if (sys.browserType === BrowserType.EDGE) {
+107 -45
View File
@@ -56,6 +56,28 @@ import type { Game } from '../game';
const localWinSize = size();
/**
* A pair of equal lengths measured in the two coordinate spaces:
* `pixels` device pixels cover the same distance as `units` UI units, so `scale = pixels / units`.
* Converting between the spaces with those two lengths directly avoids the extra rounding of
* `pixels / scale`, which is off by one ULP in the common case
* (e.g. `1532 / (1532 / 1920) === 1919.9999999999998`).
*/
export interface ScaleRatio {
/** A length in device pixels (the container). */
readonly pixels: number;
/** The same length in UI units (the design resolution). */
readonly units: number;
}
export function toUISpace (value: number, ratio: ScaleRatio): number {
return (value * ratio.units) / ratio.pixels;
}
export function toPixelSpace (value: number, ratio: ScaleRatio): number {
return (value * ratio.pixels) / ratio.units;
}
const orientationMap = {
[macro.ORIENTATION_AUTO]: Orientation.AUTO,
[macro.ORIENTATION_LANDSCAPE]: Orientation.LANDSCAPE,
@@ -69,8 +91,8 @@ export class View extends Eventify(System) {
*/
public _designResolutionSize: Size = size(0, 0); // resolution size, it is the size appropriate for the app resources.
private _scaleX: number = 1;
private _scaleY: number = 1;
private _ratioX: ScaleRatio = { pixels: 1, units: 1 };
private _ratioY: ScaleRatio = { pixels: 1, units: 1 };
private _viewportRect: Rect = rect(); // Viewport is the container's rect related to content's coordinates in pixel
private _visibleRect: Rect = rect(); // The visible rect in content's coordinate in point
private _autoFullScreen: boolean = false; // Auto full screen disabled by default
@@ -352,8 +374,8 @@ export class View extends Eventify(System) {
*/
public getVisibleSizeInPixel (): Size {
return new Size(
this._visibleRect.width * this._scaleX,
this._visibleRect.height * this._scaleY,
toPixelSpace(this._visibleRect.width, this._ratioX),
toPixelSpace(this._visibleRect.height, this._ratioY),
);
}
@@ -371,8 +393,8 @@ export class View extends Eventify(System) {
*/
public getVisibleOriginInPixel (): Vec2 {
return new Vec2(
this._visibleRect.x * this._scaleX,
this._visibleRect.y * this._scaleY,
toPixelSpace(this._visibleRect.x, this._ratioX),
toPixelSpace(this._visibleRect.y, this._ratioY),
);
}
@@ -451,9 +473,9 @@ export class View extends Eventify(System) {
const result = policy.apply(this, this._designResolutionSize);
if (result.scale && result.scale.length === 2) {
this._scaleX = result.scale[0];
this._scaleY = result.scale[1];
if (result.ratioX && result.ratioY) {
this._ratioX = result.ratioX;
this._ratioY = result.ratioY;
}
if (result.viewport) {
@@ -468,8 +490,8 @@ export class View extends Eventify(System) {
vb.x = 0;
vb.y = 0;
vb.width = rv.width / this._scaleX;
vb.height = rv.height / this._scaleY;
vb.width = toUISpace(rv.width, this._ratioX);
vb.height = toUISpace(rv.height, this._ratioY);
}
policy.postApply(this);
@@ -534,7 +556,7 @@ export class View extends Eventify(System) {
* @zh 返回横轴的缩放比,这个缩放比是将画布像素分辨率放到设计分辨率的比例。
*/
public getScaleX (): number {
return this._scaleX;
return this._ratioX.pixels / this._ratioX.units;
}
/**
@@ -542,7 +564,31 @@ export class View extends Eventify(System) {
* @zh 返回纵轴的缩放比,这个缩放比是将画布像素分辨率缩放到设计分辨率的比例。
*/
public getScaleY (): number {
return this._scaleY;
return this._ratioY.pixels / this._ratioY.units;
}
/**
* @en Returns the exact ratio behind `getScaleX()`, use it with `toUISpace()` / `toPixelSpace()`
* to convert lengths without the rounding error of `pixels / getScaleX()`.
* @zh 返回 `getScaleX()` 背后的精确比例,配合 `toUISpace()` / `toPixelSpace()` 换算长度,
* 以避免 `像素 / getScaleX()` 带来的舍入误差。
* @engineInternal
* @mangle
*/
public getRatioX (): ScaleRatio {
return this._ratioX;
}
/**
* @en Returns the exact ratio behind `getScaleY()`, use it with `toUISpace()` / `toPixelSpace()`
* to convert lengths without the rounding error of `pixels / getScaleY()`.
* @zh 返回 `getScaleY()` 背后的精确比例,配合 `toUISpace()` / `toPixelSpace()` 换算长度,
* 以避免 `像素 / getScaleY()` 带来的舍入误差。
* @engineInternal
* @mangle
*/
public getRatioY (): ScaleRatio {
return this._ratioY;
}
/**
@@ -579,14 +625,15 @@ export class View extends Eventify(System) {
}
/**
* Convert location in Cocos screen coordinate to location in UI space
* @en Converts a length from device pixels to UI units, preferring the exact scale ratio.
* @zh 将像素长度换算为 UI 单位长度,优先使用精确比例。
* @engineInternal
* @mangle
*/
public _convertToUISpace (point: Vec2): void {
const viewport = this._viewportRect;
point.x = (point.x - viewport.x) / this._scaleX;
point.y = (point.y - viewport.y) / this._scaleY;
point.x = toUISpace(point.x - viewport.x, this._ratioX);
point.y = toUISpace(point.y - viewport.y, this._ratioY);
}
private _updateAdaptResult (width: number, height: number, windowId?: number): void {
@@ -617,8 +664,9 @@ export class View extends Eventify(System) {
*/
interface AdaptResult {
scale: number[];
viewport?: null | Rect;
ratioX: ScaleRatio;
ratioY: ScaleRatio;
}
/**
@@ -699,8 +747,9 @@ class ContentStrategy {
public name = 'ContentStrategy';
private _result: AdaptResult = {
scale: [1, 1],
viewport: null,
ratioX: { pixels: 1, units: 1 },
ratioY: { pixels: 1, units: 1 },
};
protected _strategy = ResolutionPolicy.UNKNOWN;
@@ -722,13 +771,13 @@ class ContentStrategy {
/**
* @en Function to apply this strategy
* The return value is {scale: [scaleX, scaleY], viewport: {new Rect}},
* The return value is {ratioX, ratioY, viewport: {new Rect}},
* The target view can then apply these value to itself, it's preferred not to modify directly its private variables
* @zh 调用策略方法
* @return The result scale and viewport rect
* @return The exact ratios and the viewport rect
*/
public apply (_view: View, designedResolution: Size): AdaptResult {
return { scale: [1, 1] };
return this._result;
}
/**
@@ -743,7 +792,14 @@ class ContentStrategy {
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
public _buildResult (containerW: number, containerH: number, contentW: number, contentH: number, scaleX: number, scaleY: number): AdaptResult {
public _buildResult (
containerW: number,
containerH: number,
contentW: number,
contentH: number,
ratioX: ScaleRatio,
ratioY: ScaleRatio,
): AdaptResult {
// Makes content fit better the canvas
if (Math.abs(containerW - contentW) < 2) {
contentW = containerW;
@@ -760,8 +816,9 @@ class ContentStrategy {
);
const result = this._result;
result.scale = [scaleX, scaleY];
result.viewport = viewport;
result.ratioX = ratioX;
result.ratioY = ratioY;
return result;
}
}
@@ -819,10 +876,15 @@ class ExactFit extends ContentStrategy {
const windowSize = screen.windowSize;
const containerW = windowSize.width;
const containerH = windowSize.height;
const scaleX = containerW / designedResolution.width;
const scaleY = containerH / designedResolution.height;
return this._buildResult(containerW, containerH, containerW, containerH, scaleX, scaleY);
return this._buildResult(
containerW,
containerH,
containerW,
containerH,
{ pixels: containerW, units: designedResolution.width },
{ pixels: containerH, units: designedResolution.height },
);
}
}
@@ -842,21 +904,21 @@ class ShowAll extends ContentStrategy {
const designH = designedResolution.height;
const scaleX = containerW / designW;
const scaleY = containerH / designH;
let scale = 0;
let contentW: number;
let contentH: number;
let ratio: ScaleRatio;
if (scaleX < scaleY) {
scale = scaleX;
ratio = { pixels: containerW, units: designW };
contentW = containerW;
contentH = designH * scale;
contentH = toPixelSpace(designH, ratio);
} else {
scale = scaleY;
contentW = designW * scale;
ratio = { pixels: containerH, units: designH };
contentW = toPixelSpace(designW, ratio);
contentH = containerH;
}
return this._buildResult(containerW, containerH, contentW, contentH, scale, scale);
return this._buildResult(containerW, containerH, contentW, contentH, ratio, ratio);
}
}
@@ -868,7 +930,7 @@ class NoBorder extends ContentStrategy {
this._strategy = ResolutionPolicy.NO_BORDER;
}
public apply (_view, designedResolution): AdaptResult {
public apply (_view: View, designedResolution: Size): AdaptResult {
const windowSize = screen.windowSize;
const containerW = windowSize.width;
const containerH = windowSize.height;
@@ -876,21 +938,21 @@ class NoBorder extends ContentStrategy {
const designH = designedResolution.height;
const scaleX = containerW / designW;
const scaleY = containerH / designH;
let scale: number;
let contentW: number;
let contentH: number;
let ratio: ScaleRatio;
if (scaleX < scaleY) {
scale = scaleY;
contentW = designW * scale;
ratio = { pixels: containerH, units: designH };
contentW = toPixelSpace(designW, ratio);
contentH = containerH;
} else {
scale = scaleX;
ratio = { pixels: containerW, units: designW };
contentW = containerW;
contentH = designH * scale;
contentH = toPixelSpace(designH, ratio);
}
return this._buildResult(containerW, containerH, contentW, contentH, scale, scale);
return this._buildResult(containerW, containerH, contentW, contentH, ratio, ratio);
}
}
@@ -907,11 +969,11 @@ class FixedHeight extends ContentStrategy {
const containerW = windowSize.width;
const containerH = windowSize.height;
const designH = designedResolution.height;
const scale = containerH / designH;
const contentW = containerW;
const contentH = containerH;
const ratio: ScaleRatio = { pixels: containerH, units: designH };
return this._buildResult(containerW, containerH, contentW, contentH, scale, scale);
return this._buildResult(containerW, containerH, contentW, contentH, ratio, ratio);
}
}
@@ -928,11 +990,11 @@ class FixedWidth extends ContentStrategy {
const containerW = windowSize.width;
const containerH = windowSize.height;
const designW = designedResolution.width;
const scale = containerW / designW;
const contentW = containerW;
const contentH = containerH;
const ratio: ScaleRatio = { pixels: containerW, units: designW };
return this._buildResult(containerW, containerH, contentW, contentH, scale, scale);
return this._buildResult(containerW, containerH, contentW, contentH, ratio, ratio);
}
}
@@ -1026,12 +1088,12 @@ export class ResolutionPolicy {
/**
* @en Function to apply this resolution policy
* The return value is {scale: [scaleX, scaleY], viewport: {new Rect}},
* The return value is {ratioX, ratioY, viewport: {new Rect}},
* The target view can then apply these value to itself, it's preferred not to modify directly its private variables
* @zh 调用策略方法
* @param _view - The target view
* @param designedResolution - The user defined design resolution
* @return An object contains the scale X/Y values and the viewport rect
* @return An object contains the exact ratios and the viewport rect
*/
public apply (_view: View, designedResolution: Size): AdaptResult {
this._containerStrategy.apply(_view, designedResolution);
+229
View File
@@ -0,0 +1,229 @@
# Worker 使用与维护
Worker 分为两个可选引擎功能:`worker` 提供 `createWorker`、`getWorkerCapabilities`、
`checkWorkerScript` 等基础 API;额外启用 `worker-pool` 才提供 `WorkerPool`。
它们不会自动把渲染、物理、音频或业务逻辑移到其他线程。
## 安装与构建
正式依赖是 `@cocos/engine-pal`,当前锁文件解析为 `1.0.5`,包含 Worker 平台实现。在 cocos4 根目录执行:
```sh
npm ci
npm run build
```
`npm run build` 先生成压缩 JS,再生成声明。日志中的 `Performance` 只统计模块分析和摇树,
后续压缩、source map 与写文件仍可能耗时数分钟,不能据此判断构建完成。
`build:min` 每 15 秒输出累计耗时,正常完成后输出完成提示,失败时退出码为 1。
是否成功仍以整个命令正常退出为准;进度提示不代表完成百分比。
`npm ci` 的 `postinstall` 会运行 `scripts/spread-pal.cjs`,将安装包的 `dist/` 复制到引擎 `pal/`。
`pal/.pal-source.json` 记录复制来源和版本。`pal/` 是生成目录,不提交,不直接修改。
仅拉取引擎代码、没有更新依赖,不等于已经安装新版 PAL。可检查:
```sh
node -p "require('./node_modules/@cocos/engine-pal/package.json').version"
```
本地修改 PAL 源码时,在 `cocos-pal` 构建后,从 cocos4 根目录同步:
```sh
node scripts/spread-pal.cjs --source ../cocos-pal/dist
npm run build
```
显式本地来源不会被构建检查自动换成 npm 包;恢复正式包时执行不带 `--source` 的
`node scripts/spread-pal.cjs`。
## 启用功能与选择模式
在 Creator 的引擎功能裁剪配置中展开 **Worker** 分组,按需要勾选子项(两项默认均关闭):
| 功能 | ccbuild 的 features | 从 cc 可用的能力 |
| --- | --- | --- |
| 基础 Worker 功能 | `['worker']` | 创建 Worker、收发消息、查询能力,由开发者管理生命周期 |
| Worker Pool | `['worker-pool']` | 基础 Worker API,以及任务池、队列、超时和安全同步降级 |
分组标题的勾选框是全选/清空:只选基础 Worker 时显示半选;全选会同时启用 Worker Pool。
勾选 Worker Pool 会关联开启基础 Worker;取消基础 Worker 时也会取消 Worker Pool。
功能 ID 与项目已有配置保持兼容,无需迁移 `cache` 或 `includeModules`。
`worker-pool` 依赖 `worker`,Creator 会关联该依赖;直接调用 ccbuild 时,选择 `worker-pool`
也会包含两者的导出入口。`exports/worker.ts` 与 `exports/worker-pool.ts` 分别提供公开 API,
`cocos/misc/index.ts` 不导出它们。只启用 `worker` 的构建不包含线程池调度器;两项均不启用时,
也会裁掉基础 Worker API 及其 PAL Worker 依赖。完整引擎预构建仍会生成所有模块,项目构建时才按配置裁剪。
**迁移已有项目:** 之前只启用 `worker` 且使用了 `WorkerPool` 的项目,需要额外启用 `worker-pool`,
并重新构建。仅手动管理 Worker 的项目保留 `worker` 即可。`cc` 导入名称及运行时协议不变。
- **脚本模式**:`new WorkerPool('workers/task.js', options)`,适用于 Web 和提供 Worker 的小游戏环境。
- **函数模式**:`new WorkerPool(fn, options)`,Web 在具备 Worker、Blob、对象 URL 能力时创建真实 Worker;
不支持时在主线程执行原函数。函数必须自包含,不能捕获外部变量。
- **自定义消息服务**:`createWorker(path)` 返回 `postMessage/onMessage/onError/terminate` 接口。
它不提供任务池协议或自动同步 fallback。长期音频、网络等消息服务应自行管理消息和生命周期。
仅启用 `worker` 时可以这样自行管理:
```ts
import { createWorker, getWorkerCapabilities } from 'cc';
if (getWorkerCapabilities().available) {
const worker = createWorker('workers/service.js');
worker.onMessage(result => console.log(result));
worker.onError(error => { console.error(error); worker.terminate(); });
worker.postMessage({ command: 'compute', value: 21 });
// 在服务结束或组件销毁时调用 worker.terminate()。
} else {
// 由业务自行处理无 Worker 的情况。
}
```
原生和 Node.js 的 PAL Worker 入口报告不支持 JS Worker,不因宿主偶然存在全局 `Worker` 而创建它。
池可在主线程执行函数或显式 fallback;原生子系统自身的线程策略由原生实现决定。
## 脚本模式最小示例
复制 [`cc-worker-template.js`](./cc-worker-template.js) 到项目构建输出的 `workers/task.js`,
在其 `runTask(args)` 中实现计算逻辑。模板兼容 Web `self` 和小游戏 `worker` 消息入口。
```ts
import { WorkerPool } from 'cc';
const pool = new WorkerPool('workers/task.js', {
maxWorkers: 4,
timeout: 5000,
fallback: (n: number) => n * 2, // 必须与脚本计算等价,并允许安全重试
});
try {
const result = await pool.run<number>([21]);
console.log(result, pool.backend, pool.concurrency);
} finally {
pool.terminate();
}
```
对应脚本中的任务函数为:
```js
function runTask(args) {
return args[0] * 2;
}
```
脚本接收 `{ id, args }`,回复 `{ id, ok: true, value }` 或 `{ id, ok: false, error }`。
自定义脚本必须保留该协议。主线程场景对象、DOM、闭包变量无法直接在 Worker 内使用。
引擎不会自动复制项目 Worker 脚本或修改小游戏打包配置。必须保证:
1. Web 的脚本路径能在最终部署地址访问,且满足同源和安全策略要求。
2. 小游戏脚本位于平台声明的 Worker 目录内。微信在构建产物 `game.json` 中配置
`"workers": "workers"`;分包脚本需先下载分包。
3. 微信 Worker 的 `require` 依赖也在 Worker 目录内;该目录只放 JS 文件。
完整示例见 [`examples/worker-demo.ts`](./examples/worker-demo.ts) 和
[`examples/prime-worker.js`](./examples/prime-worker.js)。需启用 Worker Pool 功能并打包脚本。
示例耗时包含启动、消息传递和计算成本,加速比不是通过标准。
## 能力检测与微信 V1/V2
```ts
import { getWorkerCapabilities, checkWorkerScript } from 'cc';
console.log(getWorkerCapabilities());
console.log(checkWorkerScript('workers/task.js'));
```
`available` 表示平台报告存在 Worker 能力;`parallel` 表示并发上限大于 1。
它们不保证特定脚本可以运行。实际池状态应看 `pool.backend`(`worker / sync / none`),
实际池大小看 `pool.concurrency`。Web 的脚本加载和执行错误可能在创建后才异步报告。
PAL 1.0.5 对非标准小游戏 Worker 的并发上限保守设为 1,对标准 Worker 和 Web 不设固定平台上限;
实际创建数量仍受 `maxWorkers`、设备与运行时限制,创建可能失败。
微信 V1/V2 都使用 `wx.createWorker(path)`。PAL 以
`wx.env.isSupportStandardWorker === true` 判断标准 Worker 能力,未提供或为 false 时按单 Worker、
无 transfer 处理,不根据系统类型或版本号强行开启。`useExperimentalWorker` 不是 V2 开关。
基础库、客户端、灰度和开发者工具的当前支持范围,应查阅微信官方文档并在目标环境验证;
版本达标也不能代替能力检测。
标准 Worker 支持的 OffscreenCanvas、音频和网络能力不等于引擎会自动使用它们。
Canvas 需由主线程通过 `transferControlToOffscreen()` 转移;Worker 内平台 API 使用 `worker.xxx`。
SharedArrayBuffer 在消息中共享,不放入 transfer 列表;跨 realm 检测可用
`buffer?.constructor?.name === 'SharedArrayBuffer'`,避免依赖 `instanceof`。
## 失败恢复、transfer 与 recheck
脚本后端由 PAL 选择:优先平台 Worker;适用时再尝试全局 Web Worker;都不可用时使用显式
`options.fallback`。没有 fallback 则任务拒绝。函数模式不支持 Worker 时直接执行原函数。
- `timeout` 默认 0,表示关闭。生产脚本建议按最坏任务耗时设置超时,以处理永不回复的 Worker。
- 脚本创建失败、忙时错误、超时、畸形回复和发送异常属于基础设施失败。有 fallback 时,池降级为同步执行。
- 未移交所有权的失败任务可用 fallback 重算;已经 transfer 的任务拒绝,后续任务使用同步 fallback。
业务必须保证 fallback 可安全重试。
- 同一次降级中,其他忙碌 Worker 完成后退役;它们随后失败时,未 transfer 的任务仍可恢复。
`retired` 只表示不再复用,不能单独作为禁止 fallback 的依据。
- `recheck()` 刷新能力并选择新后端,推进后端代次;检查前的旧 Worker 失败只拒绝其原任务,
不会再次熔断新后端。排队任务交给新后端,或在无后端且无 fallback 时拒绝。
- Worker 正常返回 `{ ok: false }` 属于任务计算错误,直接拒绝,不触发基础设施降级。
- 函数模式的运行时故障不自动在主线程重放原函数,避免将可能死锁的函数移到主线程。
`run(args, transfer)` 可能移交缓冲区所有权。需要恢复数据时应保留副本或能够重新生成参数。
脚本模板不自动 transfer 返回值;Web 函数模式 bootstrap 会递归收集可转移返回值,
处理循环引用、深层对象、自有属性和去重,SharedArrayBuffer 不参与 transfer。
正式构建使用错误编号,完整说明保留在 `EngineErrorMap.md` 的 16500—16516 条目;
调试构建保留详细消息。诊断参数、任务拒绝和降级行为在正式构建中仍然有效。
## 平台抽象与旧 PAL 兼容
`cocos/misc/worker-pool.ts` 只负责调度、队列、超时和恢复;`worker.ts` 管理能力快照及后端缓存。
平台 API、脚本检查、消息适配和函数 bootstrap 位于 `cocos-pal/src/worker`。
`cc.config.json` 将 `pal/worker` 映射到 web、minigame、native、nodejs 入口。
`@types/pal/worker.d.ts` 提供引擎侧独立类型契约,`tests/scripts/pal-worker-types.test.cjs`
校验其与已安装 PAL 的声明一致。它不依赖生成的兼容声明文件。
安装与各仓库构建入口调用统一的 `scripts/ensure-pal.cjs`:
1. npm 来源的 `pal/` 与已安装包版本不同:重新复制整个 PAL。
2. Worker 缺失或为引擎兼容实现,来源已有真实实现:恢复真实 Worker。
3. 来源完全没有 Worker:生成 JS 单线程兼容实现,支持未更新依赖的旧环境构建。
4. 已有真实 Worker 实现:不做局部覆盖;不完整的真实模块需要重新执行 spread 修复。
兼容实现共享文件为 `pal/worker/compat.js`,不生成根 `index.js`,避免绕过平台映射或留下解析缓存。
来源为 `--source` 的目录只从该来源恢复;不会混入 npm 的 Worker。整个 `pal/` 缺失时仍需先安装依赖。
这些检查不能代替安装新版本依赖;仅拉取引擎后继续使用旧 npm 包,仍可能使用同步兼容。
编辑器绕过仓库构建脚本时,应先完成安装和 spread。
新增 PAL 检查可在 `scripts/ensure-pal.cjs` 增加独立函数并注册到 `checks`。
检查必须幂等,修改返回 true,无需修改返回 false,无法继续构建时抛出错误。
## 测试与验收
在 cocos4 根目录执行:
```sh
npm run test:pal
npm test -- --runInBand
node scripts/test-worker-release.cjs
```
- `test:pal`:同步来源、旧 PAL 兼容、升级/降级、构建入口及类型契约。
- `tests/misc/worker-*.test.ts`:实际 PAL 产物上的平台能力、Web/微信路径、队列、生命周期、超时、
代次隔离、并发降级、transfer 和函数 bootstrap。平台 API 为可控替身;旧 PAL 专项使用兼容模块。
- `test-worker-release.cjs`:实际编译仅 Worker、Worker Pool 及未启用两项功能的 HTML5 产物,
检查导出、手动消息通信及 source map 模块清单,验证裁剪边界;同时保留正式错误编号、
调度、消息协议、transfer 失败恢复及 recheck 检查。它要求安装带 Worker 的 PAL。
合入前还应在 cocos-test-projects 的 `assets/cases/scene/worker-test/worker.scene` 验收:
1. Web:对比主线程与 Worker 模式,确认结果一致、场景持续更新,池状态确为 `worker`;
禁用 Worker API 后确认 fallback。反复切换模式和销毁场景,不应留下任务或线程。
2. 微信:检查最终 `game.json` 和脚本文件,分别验证非标准单 Worker 环境和有标准能力标志的环境;
验证脚本缺失、未下载分包、创建失败、超时与 transfer 后失败。
3. 原生:确认不启动 JS Worker,函数或显式 fallback 在主线程运行。
4. 裁剪:在相同构建参数下对比开启/关闭 Worker,分别记录原始和压缩包体;不能用旧包或不同配置比较。
自动测试和 ccbuild 成功不代表浏览器、开发者工具或真机已通过。验收记录应包含引擎提交、PAL 版本、
平台/客户端环境、构建参数、池状态与结果;不得把 `sync` fallback 当成真实 Worker 成功。
+100
View File
@@ -0,0 +1,100 @@
/**
* Cocos universal worker entry template (Web + WeChat mini-game).
*
* This is a READY-MADE worker file you copy into your own project. It implements the exact message
* protocol expected by the engine's `cc.WorkerPool` (script mode) and `cc.createWorker(path)`, and it
* runs on BOTH Web (`self.onmessage`) and WeChat (`worker.onMessage`) with no further changes.
*
* WHY A PHYSICAL FILE IS REQUIRED ON WECHAT
* -----------------------------------------
* WeChat mini-games have no global `Worker` constructor and FORBID dynamically executing JS code
* (`eval` / `new Function` are banned). So the engine cannot ship a function's source string and
* rebuild it inside a WeChat worker. The only way to get real parallelism on WeChat is to write the
* task into a physical JS file like this one, package it, and declare it in `game.json`.
*
* HOW TO USE
* ----------
* Enable the `worker-pool` engine feature (which depends on `worker`) for the pool example below.
* `createWorker(path)` alone only requires `worker`; the caller manages its message protocol.
* 1. Copy this file into your project's worker directory, e.g. `workers/heavy-compute/index.js`.
* 2. Implement your pure computation in `runTask(args)` below. It MUST be self-contained: it runs in
* a separate thread and CANNOT access `cc`, the scene, the DOM, or any closure variable from the
* main thread. Only `args` (structured-cloned) is available as input, and the return value must be
* structured-cloneable (or a Transferable such as ArrayBuffer / TypedArray).
* 3. Package & configure:
* - WeChat: declare the worker root in the built `game.json` -> { "workers": "workers" }, and make
* sure this file lives inside that directory. WeChat V1 allows only ONE worker at a time; V2
* (standard worker, gray release / Android) allows multiple. The engine pool auto-caps to the
* platform limit, so you do not need to branch on this yourself.
* - Web: make sure this file is served at the same path you pass to the pool.
* 4. Drive it from the main thread:
* // Pool size defaults to a CPU-based count and is auto-capped per platform (WeChat V1 => 1).
* // On WeChat V2 pass an explicit maxWorkers to scale beyond 1 (core count is not detectable there).
* const pool = new cc.WorkerPool('workers/heavy-compute/index.js', { maxWorkers: 4 });
* const result = await pool.run([1000000]); // args array -> runTask(args)
* pool.terminate();
*
* MESSAGE PROTOCOL (must match the engine; do not change the plumbing below)
* --------------------------------------------------------------------------
* main -> worker : { id: number, args: any[] }
* worker -> main : { id: number, ok: true, value: any }
* | { id: number, ok: false, error: string }
*/
// ==== YOUR TASK: put your pure, self-contained computation here ==================
function runTask (args) {
// `args` is exactly the array you passed to `pool.run([...])`.
// Example below: a heavy numeric loop. Replace it with your own logic.
var n = (args && args[0]) || 0;
var acc = 0;
for (var i = 0; i < n; i++) {
acc += Math.sqrt(i);
}
return acc;
// ---- Multi-task variant (optional) -------------------------------------------
// If one worker file should handle several kinds of work, dispatch on an argument:
// switch (args && args[0]) {
// case 'normals': return computeNormals(args[1]);
// case 'lod': return computeLod(args[1]);
// default: throw new Error('unknown task: ' + (args && args[0]));
// }
// Remember: every helper you call (computeNormals, ...) must also be defined in THIS file
// (or required from another file inside the same worker directory).
}
// =================================================================================
// ---- Message plumbing (works on Web and WeChat; normally no need to edit) --------
function handleMessage (msg) {
var id = msg && msg.id;
try {
var value = runTask(msg && msg.args);
reply({ id: id, ok: true, value: value });
} catch (e) {
reply({ id: id, ok: false, error: String((e && e.message) || e) });
}
}
function reply (msg) {
// WeChat mini-game: the global `worker` object.
if (typeof worker !== 'undefined' && worker && typeof worker.postMessage === 'function') {
worker.postMessage(msg);
return;
}
// Web Worker: the global `self`.
if (typeof self !== 'undefined' && typeof self.postMessage === 'function') {
self.postMessage(msg);
}
}
// Register the message handler for the current platform (mutually exclusive).
if (typeof worker !== 'undefined' && worker && typeof worker.onMessage === 'function') {
// WeChat mini-game worker.
worker.onMessage(handleMessage);
} else if (typeof self !== 'undefined') {
// Web Worker.
self.onmessage = function (e) {
handleMessage(e && e.data);
};
}
+114
View File
@@ -0,0 +1,114 @@
/**
* WorkerPool 脚本模式示例:同时提交 4 个计算任务,并与主线程结果比较。
*
* 1. 在引擎功能配置中启用 worker-pool(会依赖 worker)。
* 2. 将 prime-worker.js 打包为 workers/prime-worker.js;微信还需配置 game.json 的 workers 目录。
* 3. 将此组件挂到场景节点,检查结果一致性、实际 pool.backend 和 pool.concurrency。
*
* Web 和标准小游戏 Worker 可按能力并发,其他小游戏 Worker 可能只有一个槽位。
* 没有可用 Worker 或发生安全可恢复的故障时,显式 fallback 在主线程执行。
* 计时包含 Worker 启动、消息传递和计算,设备、任务大小和预热都会影响结果;
* 不能用单次加速比判断平台支持性,也不能把 sync fallback 当成 Worker 成功。
*/
import {
_decorator, Component, WorkerPool, checkWorkerScript, getWorkerCapabilities,
} from 'cc';
const { ccclass } = _decorator;
const WORKER_PATH = 'workers/prime-worker.js';
const LIMIT = 200_000; // 计算小于该值的素数个数;单任务约 100~300ms,可按机器性能调整
const TASKS = 4;
// worker 收下消息却永不回复时的兜底(死锁 / 无限循环 / 平台静默丢消息)。
// 触发后 Worker 被驱逐,本示例通过 fallback 重算并降级。0 = 关闭。
const TIMEOUT = 10_000;
// 与 prime-worker.js 中 runTask(args) 完全一致的算法:
// 1) 作为串行基线计时;2) 作为无 worker 后端时的单线程降级(options.fallback)。
// 两处必须保持同步——demo 会对比二者结果来证明 worker 链路计算正确。
function countPrimes (limit: number): number {
let count = 0;
for (let n = 2; n < limit; n++) {
let isPrime = true;
for (let d = 2; d * d <= n; d++) {
if (n % d === 0) { isPrime = false; break; }
}
if (isPrime) { count++; }
}
return count;
}
@ccclass('WorkerDemo')
export class WorkerDemo extends Component {
public start (): void {
this.benchmark().catch((e) => {
console.error('[WorkerDemo] benchmark failed:', e);
});
}
private async benchmark (): Promise<void> {
// 0a) 平台能力快照——业务决定"要不要开这个特性"的正确依据。
// 注意 parallel 与 available 的区别:7 个小游戏平台 available 为真但 parallel 为假。
const caps = getWorkerCapabilities();
console.log(`[WorkerDemo] capabilities: available=${caps.available} `
+ `parallel=${caps.parallel} concurrencyLimit=${caps.concurrencyLimit} `
+ `transfer=${caps.supportsTransfer} sab=${caps.supportsSharedArrayBuffer}`);
console.log(`[WorkerDemo] capability reason: ${caps.reason}`);
// 0b) 脚本路径预检:文件是否真的在代码包里、路径是否合法。
// 引擎内部也做同样的检查来决定后端:平台 worker → Web Worker → fallback 单线程 → 报错。
const status = checkWorkerScript(WORKER_PATH);
console.log(`[WorkerDemo] checkWorkerScript: ready=${status.ready} `
+ `version=${status.version} reason="${status.reason}"`);
// 1) 串行基线:主线程连续算 TASKS 次。
const t0 = Date.now();
let expected = 0;
for (let i = 0; i < TASKS; i++) {
expected = countPrimes(LIMIT);
}
const serialMs = Date.now() - t0;
// 2) WorkerPool 并行:后端由引擎自动解析,池大小自动按平台 concurrencyLimit 封顶
// (7 个单 worker 平台 + 微信 V1 → 1;微信 V2 / Web → maxWorkers)。
const pool = new WorkerPool(WORKER_PATH, {
maxWorkers: TASKS,
timeout: TIMEOUT,
fallback: countPrimes, // 无任何 worker 后端时单线程兜底,保证 demo 总能跑通
});
console.log(`[WorkerDemo] resolved backend: ${pool.backend}`);
const t1 = Date.now();
let results: number[];
try {
results = await Promise.all(
Array.from({ length: TASKS }, () => pool.run<number>([LIMIT])),
);
} finally {
pool.terminate();
}
const poolMs = Date.now() - t1;
// 3) 验证:所有任务结果必须与串行基线一致。
const allMatch = results.every((r) => r === expected);
console.log(`[WorkerDemo] primes below ${LIMIT} = ${expected}, results match: ${allMatch}`);
const speedup = serialMs / Math.max(1, poolMs);
console.log(`[WorkerDemo] serial: ${serialMs}ms | pool(${TASKS} tasks): ${poolMs}ms `
+ `| speedup: ${speedup.toFixed(2)}x`);
// 启动和通信成本也在计时内。以结果和实际后端验收,不用加速比推断是否正确。
if (pool.backend === 'sync') {
console.warn('[WorkerDemo] 池已走 fallback 单线程执行,请检查平台能力、脚本打包和运行时降级日志。');
} else if (pool.concurrency <= 1) {
console.log('[WorkerDemo] 当前池只使用 1 个 Worker,任务可异步卸载,但不会并行执行。');
} else {
console.log('[WorkerDemo] 当前池支持多个 Worker;实际收益需在目标设备上重复测量。');
}
if (!allMatch) {
throw new Error('[WorkerDemo] worker 脚本与 fallback 结果不一致,'
+ '请检查 prime-worker.js 与 countPrimes 算法是否同步!');
}
}
}
@@ -1,3 +1,4 @@
#pragma define-meta USE_NORMAL_MAP default(false)
#pragma define-meta CC_RENDER_MODE range([0, 4])
#pragma define RENDER_MODE_BILLBOARD 0
#pragma define RENDER_MODE_STRETCHED_BILLBOARD 1
@@ -19,6 +20,13 @@ uniform Constants {
out mediump vec2 uv;
out mediump vec4 color;
#if USE_NORMAL_MAP
out highp vec3 particlePositionWS;
#if CC_RENDER_MODE == RENDER_MODE_MESH
out highp vec3 particleNormalWS;
#endif
#endif
void computeVertPos (inout vec4 pos, vec2 vertOffset, vec4 q, vec3 s
#if CC_RENDER_MODE == RENDER_MODE_BILLBOARD || CC_RENDER_MODE == RENDER_MODE_VERTICAL_BILLBOARD
, mat4 viewInv
@@ -0,0 +1,56 @@
#pragma define-meta USE_NORMAL_MAP default(false)
// Both stages must declare the range: Mesh uses 4, beyond the inferred [0, 3].
#pragma define-meta CC_RENDER_MODE range([0, 4])
#pragma extension([GL_OES_standard_derivatives, __VERSION__ < 300])
#include <builtin/uniforms/cc-global>
#if USE_NORMAL_MAP
in highp vec3 particlePositionWS;
#if CC_RENDER_MODE == 4
in highp vec3 particleNormalWS;
#endif
uniform sampler2D normalMap;
uniform ParticleNormalConstants {
vec4 particleNormalParams;
};
vec4 ApplyParticleNormalLighting (vec4 col, vec2 texCoord) {
// Derive the tangent frame from the animated UVs and final world position.
// This also handles billboard rotation and meshes without tangent attributes.
highp vec3 dpdx = dFdx(particlePositionWS);
highp vec3 dpdy = dFdy(particlePositionWS);
highp vec2 duvdx = dFdx(texCoord);
highp vec2 duvdy = dFdy(texCoord);
#if CC_RENDER_MODE == 4
highp vec3 n = normalize(particleNormalWS);
n *= gl_FrontFacing ? 1.0 : -1.0;
#else
highp vec3 n = normalize(cross(dpdx, dpdy));
// Keep the two-sided billboard's surface normal facing the viewer.
n *= dot(n, cc_cameraPos.xyz - particlePositionWS) < 0.0 ? -1.0 : 1.0;
#endif
highp vec3 perpendicularY = cross(dpdy, n);
highp vec3 perpendicularX = cross(n, dpdx);
highp vec3 tangent = perpendicularY * duvdx.x + perpendicularX * duvdy.x;
highp vec3 bitangent = perpendicularY * duvdx.y + perpendicularX * duvdy.y;
highp float frameLength = max(dot(tangent, tangent), dot(bitangent, bitangent));
highp float inverseLength = inversesqrt(max(frameLength, 1e-20));
vec3 mappedNormal = texture(normalMap, texCoord).xyz * 2.0 - 1.0;
mappedNormal.xy *= particleNormalParams.x;
highp vec3 perturbedNormal = (tangent * mappedNormal.x + bitangent * mappedNormal.y) * inverseLength + n * mappedNormal.z;
n = dot(perturbedNormal, perturbedNormal) > 1e-12 ? normalize(perturbedNormal) : n;
vec3 lighting = mix(cc_ambientGround.rgb, cc_ambientSky.rgb, n.y * 0.5 + 0.5) * cc_ambientSky.w;
#if !CC_DISABLE_DIRECTIONAL_LIGHT
lighting += cc_mainLitColor.rgb * cc_mainLitColor.w * max(dot(n, -cc_mainLitDir.xyz), 0.0);
#endif
col.rgb *= lighting;
return col;
}
#else
vec4 ApplyParticleNormalLighting (vec4 col, vec2 texCoord) {
return col;
}
#endif
@@ -0,0 +1,9 @@
{
"ver": "1.0.7",
"importer": "effect-header",
"imported": true,
"uuid": "46b14ea9-3215-41c5-97d6-65254854762e",
"files": [],
"subMetas": {},
"userData": {}
}
@@ -365,6 +365,14 @@ vec4 gpvs_main () {
color *= a_color1;
#endif
#if USE_NORMAL_MAP
particlePositionWS = pos.xyz;
#if CC_RENDER_MODE == RENDER_MODE_MESH
// Inverse-transpose of particle rotation and scale, including mirrored scale.
highp vec3 safeScale = mix(vec3(-1.0), vec3(1.0), step(vec3(0.0), compScale)) * max(abs(compScale), vec3(0.000001));
particleNormalWS = mat3(xformNoScale) * (a_normal / safeScale);
#endif
#endif
pos = cc_matViewProj * pos;
float frameIndex = 0.;
@@ -108,6 +108,14 @@ vec4 lpvs_main () {
uv = computeUV(a_texCoord4.w, a_texCoord.xy, frameTile_velLenScale.xy) * mainTiling_Offset.xy + mainTiling_Offset.zw;
#endif
#if USE_NORMAL_MAP
particlePositionWS = pos.xyz;
#if CC_RENDER_MODE == RENDER_MODE_MESH
// Inverse-transpose of particle rotation and scale, including mirrored scale.
highp vec3 safeScale = mix(vec3(-1.0), vec3(1.0), step(vec3(0.0), compScale)) * max(abs(compScale), vec3(0.000001));
particleNormalWS = mat3(xformNoScale) * (a_normal / safeScale);
#endif
#endif
pos = cc_matViewProj * pos;
return pos;
@@ -145,7 +145,7 @@ void main() {
color = packRGBE(color.rgb); // for reflection-map
#else
color = CCSurfacesDebugDisplayInvalidNumber(color);
#if !CC_USE_FLOAT_OUTPUT || CC_IS_TRANSPARENCY_PASS
#if !CC_USE_FLOAT_OUTPUT
color.rgb = HDRToLDR(color.rgb);
color.rgb = LinearToSRGB(color.rgb);
#endif
@@ -26,6 +26,8 @@ CCEffect %{
r1: &r1 { cullMode: none }
p1: &p1
mainTexture: { value: grey }
normalMap: { value: normal, editor: { parent: USE_NORMAL_MAP } }
normalStrength: { value: 1.0, target: particleNormalParams.x, editor: { parent: USE_NORMAL_MAP, slide: true, range: [0, 5], step: 0.01 } }
mainTiling_Offset: { value: [1, 1, 0, 0] }
p2: &p2
<<: *p1
@@ -119,6 +121,8 @@ CCProgram tinted-fs %{
in vec2 uv;
in vec4 color;
#include <builtin/internal/particle-normal>
uniform sampler2D mainTexture;
uniform FragConstants {
@@ -127,14 +131,14 @@ CCProgram tinted-fs %{
vec4 add () {
vec4 col = 2.0 * color * tintColor * CCSampleWithAlphaSeparated(mainTexture, uv);
return CCFragOutput(col);
return CCFragOutput(ApplyParticleNormalLighting(col, uv));
}
vec4 multiply () {
vec4 col;
vec4 texColor = CCSampleWithAlphaSeparated(mainTexture, uv);
col.rgb = tintColor.rgb * texColor.rgb * color.rgb * vec3(2.0);
return CCFragOutput(col);
return CCFragOutput(ApplyParticleNormalLighting(col, uv));
}
}%
@@ -146,16 +150,18 @@ CCProgram no-tint-fs %{
in vec2 uv;
in vec4 color;
#include <builtin/internal/particle-normal>
uniform sampler2D mainTexture;
vec4 addSmooth () {
vec4 col = color * CCSampleWithAlphaSeparated(mainTexture, uv);
col.rgb *= col.a;
return CCFragOutput(col);
return CCFragOutput(ApplyParticleNormalLighting(col, uv));
}
vec4 premultiplied () {
vec4 col = color * CCSampleWithAlphaSeparated(mainTexture, uv) * color.a;
return CCFragOutput(col);
return CCFragOutput(ApplyParticleNormalLighting(col, uv));
}
}%
@@ -26,6 +26,8 @@ CCEffect %{
r1: &r1 { cullMode: none }
p1: &p1
mainTexture: { value: grey }
normalMap: { value: normal, editor: { parent: USE_NORMAL_MAP } }
normalStrength: { value: 1.0, target: particleNormalParams.x, editor: { parent: USE_NORMAL_MAP, slide: true, range: [0, 5], step: 0.01 } }
mainTiling_Offset: { value: [1, 1, 0, 0] }
p2: &p2
<<: *p1
@@ -119,6 +121,8 @@ CCProgram tinted-fs %{
in vec2 uv;
in vec4 color;
#include <builtin/internal/particle-normal>
uniform sampler2D mainTexture;
uniform FragConstants {
vec4 tintColor;
@@ -126,14 +130,14 @@ CCProgram tinted-fs %{
vec4 add () {
vec4 col = 2.0 * color * tintColor * CCSampleWithAlphaSeparated(mainTexture, uv);
return CCFragOutput(col);
return CCFragOutput(ApplyParticleNormalLighting(col, uv));
}
vec4 multiply () {
vec4 col;
vec4 texColor = CCSampleWithAlphaSeparated(mainTexture, uv);
col.rgb = tintColor.rgb * texColor.rgb * color.rgb * vec3(2.0);
return CCFragOutput(col);
return CCFragOutput(ApplyParticleNormalLighting(col, uv));
}
}%
@@ -145,16 +149,18 @@ CCProgram no-tint-fs %{
in vec2 uv;
in vec4 color;
#include <builtin/internal/particle-normal>
uniform sampler2D mainTexture;
vec4 addSmooth () {
vec4 col = color * CCSampleWithAlphaSeparated(mainTexture, uv);
col.rgb *= col.a;
return CCFragOutput(col);
return CCFragOutput(ApplyParticleNormalLighting(col, uv));
}
vec4 premultiplied () {
vec4 col = color * CCSampleWithAlphaSeparated(mainTexture, uv) * color.a;
return CCFragOutput(col);
return CCFragOutput(ApplyParticleNormalLighting(col, uv));
}
}%
+28 -1
View File
@@ -346,6 +346,21 @@
"enginePlugin": false,
"category": "network"
},
"worker": {
"default": false,
"label": "i18n:ENGINE.features.worker.label",
"description": "i18n:ENGINE.features.worker.description",
"enginePlugin": true,
"category": "worker"
},
"worker-pool": {
"default": false,
"label": "i18n:ENGINE.features.worker_pool.label",
"description": "i18n:ENGINE.features.worker_pool.description",
"enginePlugin": true,
"category": "worker",
"dependencies": ["worker"]
},
"terrain": {
"default": true,
"label": "i18n:ENGINE.features.terrain.label",
@@ -397,7 +412,7 @@
"spine-3.8": {
"enginePlugin": true,
"cmakeConfig": "USE_SPINE_3_8",
"default": true,
"default": false,
"isNativeModule": true,
"label": "i18n:ENGINE.features.spine_38.label",
"description": "i18n:ENGINE.features.spine_38.description",
@@ -489,6 +504,13 @@
"description": "i18n:ENGINE.features.xr.description",
"enginePlugin": false,
"envCondition": "$NATIVE || $HTML5"
},
"webassembly": {
"default": true,
"required": true,
"label": "WebAssembly",
"description": "Export the engine's cross-platform WebAssembly loading interface as cc.wasm, so that extensions and game scripts can load their own .wasm files. 以 cc.wasm 导出引擎的跨平台 WebAssembly 加载接口,供扩展与游戏脚本加载自己的 .wasm 文件。",
"enginePlugin": true
}
},
"categories": {
@@ -498,6 +520,11 @@
"checkable": true,
"required": true
},
"worker": {
"label": "i18n:ENGINE.features.categories.worker.label",
"description": "i18n:ENGINE.features.categories.worker.description",
"checkable": true
},
"2d": {
"label": "i18n:ENGINE.features.categories.2d.label",
"description": "i18n:ENGINE.features.categories.2d.description",
+12
View File
@@ -896,6 +896,10 @@ module.exports = link(mixin({
},
features: {
categories: {
worker: {
label: 'Worker',
description: 'Worker features. The group checkbox selects or clears all items; Worker Pool depends on Basic Worker.',
},
'2d': {
label: '2D',
description: '2D',
@@ -1133,6 +1137,14 @@ module.exports = link(mixin({
label: "WebSocket Server",
description: "Enable WebSocket Server for native. Note: WebSocket must also be enabled.",
},
worker: {
label: "Basic Worker",
description: "Enable cross-platform Worker creation, messaging and capability queries. Manage workers yourself; enable Worker Pool separately for task scheduling and synchronous fallback.",
},
worker_pool: {
label: "Worker Pool",
description: "Enable WorkerPool task scheduling, queuing, timeouts and safe synchronous fallback. Depends on Worker.",
},
flags: {
spine: {
loadManual: {
+12
View File
@@ -874,6 +874,10 @@ module.exports = link(mixin({
},
features: {
categories: {
worker: {
label: 'Worker',
description: 'Worker 功能分组。分组勾选框用于全选或清空;Worker Pool 依赖基础 Worker 功能。',
},
'2d': {
label: '2D',
description: '2D',
@@ -1111,6 +1115,14 @@ module.exports = link(mixin({
label: "WebSocket Server",
description: "对原生启用 WebSocket Server。注意: 必须同时启用 WebSocket。",
},
worker: {
label: "基础 Worker 功能",
description: "启用跨平台 Worker 创建、消息通信和能力查询,由开发者自行管理 Worker。需要任务调度与同步降级时,额外启用 Worker Pool。",
},
worker_pool: {
label: "Worker Pool",
description: "启用 WorkerPool 任务调度、队列、超时和安全同步降级。依赖 Worker 功能。",
},
flags: {
spine: {
loadManual: {
@@ -42,7 +42,7 @@ function formatValue(value) {
}
const imageExt = ['.png', '.jpg', '.jpeg', '.webp', '.gif'];
const pageAttr = ['name', 'size', 'format', 'filter', 'repeat', 'pma'];
const pageAttr = ['name', 'size', 'format', 'filter', 'repeat', 'scale', 'pma'];
class ParseAtlasFile {
constructor() { }
+52
View File
@@ -0,0 +1,52 @@
/*
Copyright (c) 2026 Xiamen Yaji Software Co., Ltd.
https://www.cocos.com/
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/
import { instantiateWasm, fetchBuffer, fetchUrl, ensureWasmModuleReady } from 'pal/wasm';
/**
* @en
* The engine's packaged cross-platform WebAssembly interface (pal/wasm).
*
* Re-exported under the public `cc.wasm` namespace so extension/game code can
* load its own `.wasm` files through the same platform-adaptive path the engine
* uses internally for box2d / physx / spine / webgpu:
*
* - web: fetch the `.wasm` bytes, then `WebAssembly.instantiate`;
* - mini-game: resolve the path into `cocos-js/` and delegate to the platform's
* `CCWebAssembly.instantiate` (which accepts a file path, never
* raw bytes — this is why embedded-base64 wasm fails there);
* - native: read the file from `src/cocos-js/` via `fileUtils`.
*
* The `wasmUrl` argument is a bare file name (e.g. `'foo.wasm'`) whose file is
* expected to land in the build output's `cocos-js/` directory.
* @zh
* 引擎封装好的跨平台 WebAssembly 接口(pal/wasm),通过 `cc.wasm` 命名空间公开,
* 供扩展/游戏代码用与引擎内部一致的路径加载自己的 `.wasm`。
*/
export const wasm = {
instantiateWasm,
fetchBuffer,
fetchUrl,
ensureWasmModuleReady,
};
+28
View File
@@ -0,0 +1,28 @@
/*
Copyright (c) 2026 Xiamen Yaji Software Co., Ltd.
https://www.cocos.com/
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated engine source code (the "Software"), a limited,
worldwide, royalty-free, non-assignable, revocable and non-exclusive license
to use Cocos Creator solely to develop games on your target platforms. You shall
not use Cocos Creator software for developing other software or tools that's
used for developing games. You are not granted to publish, distribute,
sublicense, and/or sell copies of Cocos Creator.
The software or tools in this License Agreement are licensed, not sold.
Xiamen Yaji Software Co., Ltd. reserves all rights not expressly granted to you.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/
/** Entry of the optional `worker-pool` feature, which depends on `worker`. */
export { WorkerPool } from '../cocos/misc/worker-pool';
export type { WorkerPoolOptions, WorkerExecutionMode } from '../cocos/misc/worker-pool';
+55
View File
@@ -0,0 +1,55 @@
/*
Copyright (c) 2020 Xiamen Yaji Software Co., Ltd.
https://www.cocos.com/
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated engine source code (the "Software"), a limited,
worldwide, royalty-free, non-assignable, revocable and non-exclusive license
to use Cocos Creator solely to develop games on your target platforms. You shall
not use Cocos Creator software for developing other software or tools that's
used for developing games. You are not granted to publish, distribute,
sublicense, and/or sell copies of Cocos Creator.
The software or tools in this License Agreement are licensed, not sold.
Xiamen Yaji Software Co., Ltd. reserves all rights not expressly granted to you.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/
/**
* Entry of the optional `worker` feature.
*
* The worker API lives in `cocos/misc/worker.ts` but is intentionally NOT re-exported from
* `cocos/misc/index.ts`: that file belongs to the always-on `base` feature, so anything exported
* there ships in every build's main bundle. Routing the subsystem through this dedicated entry lets
* builds omit the Worker API and its PAL dependencies when the feature is disabled.
* Pool scheduling is separately enabled by the `worker-pool` feature.
*
* Only the public surface is re-exported here. Platform implementations live in `pal/worker`.
* Internal backend selection and cache management stay off the `cc` namespace.
*/
export {
createWorker,
isWorkerSupported,
isSupportStandardWorker,
checkWorkerScript,
getWorkerConcurrencyLimit,
getOptimalWorkerCount,
getWorkerCapabilities,
} from '../cocos/misc/worker';
export type { WorkerTask, IWorkerScriptStatus } from '../cocos/misc/worker';
export type {
IWorker,
IWorkerBackend,
IWorkerDiagnosis,
IWorkerCapabilities,
} from 'pal/worker';
+1
View File
@@ -12,6 +12,7 @@ module.exports = {
moduleNameMapper: {
...pathsToModuleNameMapper(compilerOptions.paths, { prefix: `${__dirname}/` }),
'external:(.*)': '<rootDir>/native/external/$1',
'^pal/worker$': '<rootDir>/tests/mocks/pal-worker.js',
},
transformIgnorePatterns: [
// ignore everything in the node_modules EXCEPT for:
+2
View File
@@ -660,6 +660,8 @@ elseif(OPENHARMONY)
endif()
cocos_source_files(
cocos/platform/interfaces/modules/canvas/CanvasFont.cpp
cocos/platform/interfaces/modules/canvas/CanvasFont.h
cocos/platform/interfaces/modules/canvas/CanvasRenderingContext2D.cpp
cocos/platform/interfaces/modules/canvas/CanvasRenderingContext2D.h
cocos/platform/interfaces/modules/canvas/ICanvasRenderingContext2D.h
+122 -22
View File
@@ -27,6 +27,87 @@
#include "core/assets/RenderingSubMesh.h"
namespace cc {
namespace {
// GPU buffers are allocated on demand, in vertex/index counts, keep in sync with
// cocos/2d/assembler/graphics/constants.ts. Grow only: doResize re-creates the GPU buffer.
constexpr uint32_t MAX_VERTEX_COUNT = 65536;
constexpr uint32_t INDICES_PER_VERTEX = 3;
constexpr uint32_t MAX_INDEX_COUNT = MAX_VERTEX_COUNT * INDICES_PER_VERTEX;
// Graphics vertex layout: position.xyz, color.rgba, distance.
constexpr uint32_t FLOATS_PER_VERTEX = 8;
constexpr uint32_t VERTEX_STRIDE = FLOATS_PER_VERTEX * sizeof(float);
constexpr uint32_t ALPHA_OFFSET = 6;
inline uint32_t growCapacity(uint32_t needed, uint32_t current, uint32_t maxCap) {
uint32_t cap = current > 1U ? current : 1U;
while (cap < needed && cap < maxCap) {
cap *= 2;
}
return cap < maxCap ? cap : maxCap;
}
class GraphicsModel final : public scene::Model {
public:
void resizeGeometry(size_t size) {
_geometry.resize(size);
_lastOpacity = -1.F;
}
void setVertices(size_t index, const float* source, uint32_t count) {
auto& chunk = _geometry[index];
chunk.paintAlpha.clear();
if (count) {
// JS can replace its arrays after updateRenderer and before the native UI walk.
chunk.vertices.assign(source, source + count * FLOATS_PER_VERTEX);
} else {
chunk.vertices.clear();
}
}
void updateUBOs(uint32_t stamp) override {
const auto* node = getNode();
if (node && node->_getFinalOpacity() != _lastOpacity) {
// The UI walk resolves this node's opacity immediately before submitting the model.
const float opacity = node->_getFinalOpacity();
for (size_t i = 0; i < _geometry.size(); ++i) {
auto& chunk = _geometry[i];
if (chunk.vertices.empty()) continue;
if (opacity != 1.F && chunk.paintAlpha.empty()) {
chunk.paintAlpha.resize(chunk.vertices.size() / FLOATS_PER_VERTEX);
for (size_t v = 0; v < chunk.paintAlpha.size(); ++v) {
chunk.paintAlpha[v] = chunk.vertices[v * FLOATS_PER_VERTEX + ALPHA_OFFSET];
}
}
for (size_t v = 0; v < chunk.paintAlpha.size(); ++v) {
chunk.vertices[v * FLOATS_PER_VERTEX + ALPHA_OFFSET] = chunk.paintAlpha[v] * opacity;
}
auto* vb = getSubModels()[i]->getInputAssembler()->getVertexBuffers().front();
vb->update(chunk.vertices.data(), static_cast<uint32_t>(chunk.vertices.size() * sizeof(float)));
}
_lastOpacity = opacity;
}
scene::Model::updateUBOs(stamp);
}
void destroy() override {
_geometry.clear();
scene::Model::destroy();
}
private:
struct Chunk {
ccstd::vector<float> vertices;
ccstd::vector<float> paintAlpha;
};
ccstd::vector<Chunk> _geometry;
float _lastOpacity{-1.F};
};
} // namespace
UIModelProxy::UIModelProxy() {
_device = Root::getInstance()->getDevice();
}
@@ -36,7 +117,7 @@ UIModelProxy::~UIModelProxy() {
}
void UIModelProxy::initModel(Node* node) {
_model = Root::getInstance()->createModel<scene::Model>();
_model = Root::getInstance()->createModel<GraphicsModel>();
_model->setNode(node);
_model->setTransform(node);
_node = node;
@@ -55,16 +136,20 @@ void UIModelProxy::activeSubModels() {
return;
}
// Allocate exactly for the data of this chunk, rounded up to a power of two.
const uint32_t vertexCapacity = growCapacity(drawInfo->getVertexOffset(), 0, MAX_VERTEX_COUNT);
const uint32_t indexCapacity = growCapacity(drawInfo->getIndexOffset(), 0, MAX_INDEX_COUNT);
auto* vertexBuffer = _device->createBuffer({
gfx::BufferUsageBit::VERTEX | gfx::BufferUsageBit::TRANSFER_DST,
gfx::MemoryUsageBit::DEVICE,
65536 * _stride, // Uint16 can address 65536 vertices (indices 0–65535)
_stride,
vertexCapacity * VERTEX_STRIDE,
VERTEX_STRIDE,
});
auto* indexBuffer = _device->createBuffer({
gfx::BufferUsageBit::INDEX | gfx::BufferUsageBit::TRANSFER_DST,
gfx::MemoryUsageBit::DEVICE,
65536 * sizeof(uint16_t) * 2, // Uint16 can address 65536 vertices (indices 0–65535)
static_cast<uint32_t>(indexCapacity * sizeof(uint16_t)),
sizeof(uint16_t),
});
gfx::BufferList vbReference;
@@ -81,34 +166,48 @@ void UIModelProxy::activeSubModels() {
}
void UIModelProxy::uploadData() {
if (!_model) return;
auto* entity = static_cast<RenderEntity*>(_node->getUserData());
const auto& drawInfos = entity->getDynamicRenderDrawInfos();
const auto& subModelList = _model->getSubModels();
for (size_t i = 0; i < drawInfos.size(); i++) {
auto* drawInfo = drawInfos[i];
auto* model = static_cast<GraphicsModel*>(_model.get());
model->resizeGeometry(subModelList.size());
for (size_t i = 0; i < subModelList.size(); i++) {
auto* drawInfo = i < drawInfos.size() ? drawInfos[i] : nullptr;
auto* ia = subModelList.at(i)->getInputAssembler();
if (drawInfo->getVertexOffset() <= 0 || drawInfo->getIndexOffset() <= 0) continue;
gfx::BufferList vBuffers = ia->getVertexBuffers();
if (!vBuffers.empty()) {
auto size = drawInfo->getVertexOffset() * _stride;
// if (size > vBuffers[0]->getSize()) {
vBuffers[0]->resize(size);
// }
vBuffers[0]->update(drawInfo->getVDataBuffer()); // vdata
const uint32_t vertexCount = drawInfo ? drawInfo->getVertexOffset() : 0U;
const uint32_t indexCount = drawInfo ? drawInfo->getIndexOffset() : 0U;
const auto& vBuffers = ia->getVertexBuffers();
if (!vertexCount || !indexCount || vBuffers.empty() || vertexCount > MAX_VERTEX_COUNT || indexCount > MAX_INDEX_COUNT ||
!drawInfo->getVDataBuffer() || !drawInfo->getIDataBuffer()) {
model->setVertices(i, nullptr, 0);
ia->setVertexCount(0);
ia->setIndexCount(0);
continue;
}
ia->setVertexCount(drawInfo->getVertexOffset()); // count
gfx::Buffer* vBuffer = vBuffers[0];
const uint32_t neededVBytes = vertexCount * VERTEX_STRIDE;
if (neededVBytes > vBuffer->getSize()) {
const uint32_t capacity = growCapacity(vertexCount, vBuffer->getSize() / VERTEX_STRIDE, MAX_VERTEX_COUNT);
vBuffer->resize(capacity * VERTEX_STRIDE);
}
model->setVertices(i, drawInfo->getVDataBuffer(), vertexCount);
ia->setVertexCount(vertexCount); // count
gfx::Buffer* iBuffer = ia->getIndexBuffer();
auto size = drawInfo->getIndexOffset() * 2;
// if (size > iBuffer->getSize()) {
iBuffer->resize(size);
// }
iBuffer->update(drawInfo->getIDataBuffer()); // idata
ia->setIndexCount(drawInfo->getIndexOffset()); // indexCount
const auto neededIBytes = static_cast<uint32_t>(indexCount * sizeof(uint16_t));
if (neededIBytes > iBuffer->getSize()) {
const uint32_t capacity = growCapacity(indexCount, static_cast<uint32_t>(iBuffer->getSize() / sizeof(uint16_t)),
MAX_INDEX_COUNT);
iBuffer->resize(static_cast<uint32_t>(capacity * sizeof(uint16_t)));
}
iBuffer->update(drawInfo->getIDataBuffer(), neededIBytes); // idata
ia->setIndexCount(indexCount); // indexCount
// drawInfo->setModel(_model); // hack, render by model
}
if (!drawInfos.empty()) {
if (!drawInfos.empty() && drawInfos[0]) {
drawInfos[0]->setModel(_model);
}
}
@@ -132,6 +231,7 @@ void UIModelProxy::clear() {
if (_model == nullptr) {
return;
}
static_cast<GraphicsModel*>(_model.get())->resizeGeometry(0);
const auto& subModels = _model->getSubModels();
for (const auto& subModel : subModels) {
auto* ia = subModel->getInputAssembler();
-1
View File
@@ -56,7 +56,6 @@ private:
ccstd::vector<scene::Model*> _models{};
gfx::Device* _device{nullptr};
uint32_t _stride{32};
ccstd::vector<gfx::Attribute> _attributes{
gfx::Attribute{gfx::ATTR_NAME_POSITION, gfx::Format::RGB32F},
gfx::Attribute{gfx::ATTR_NAME_COLOR, gfx::Format::RGBA32F},
@@ -86,6 +86,12 @@ void BakedSkinningModel::bindSkeleton(Skeleton *skeleton, Node *skinningRoot, Me
pipeline::UBOSkinning::size,
});
}
// JSB synchronizes the new root's animation buffer before calling bindSkeleton.
for (index_t i = 0; i < _subModels.size(); ++i) {
updateLocalDescriptors(i, _subModels[i]->getDescriptorSet());
}
updateInstancedJointTextureInfo();
}
void BakedSkinningModel::updateTransform(uint32_t stamp) {
+12
View File
@@ -23,6 +23,8 @@
****************************************************************************/
#include "3d/models/SkinningModel.h"
#include <algorithm>
#include <utility>
#include "3d/assets/Mesh.h"
@@ -80,6 +82,7 @@ void SkinningModel::bindSkeleton(Skeleton *skeleton, Node *skinningRoot, Mesh *m
_joints.clear();
if (!skeleton || !skinningRoot || !mesh) return;
const bool prevRealTimeTextureMode = _realTimeTextureMode;
auto jointCount = static_cast<uint32_t>(skeleton->getJoints().size());
_realTimeTextureMode = pipeline::SkinningJointCapacity::jointUniformCapacity < jointCount;
setTransform(skinningRoot);
@@ -113,6 +116,15 @@ void SkinningModel::bindSkeleton(Skeleton *skeleton, Node *skinningRoot, Mesh *m
jointInfo.indices = std::move(indices);
_joints.emplace_back(std::move(jointInfo));
}
// Rebind recreated resources without resetting custom instanced attributes.
const auto subModelCount = std::min(_subModels.size(), _bufferIndices.size());
if (subModelCount && prevRealTimeTextureMode != _realTimeTextureMode) {
onMacroPatchesStateChanged();
}
for (index_t i = 0; i < subModelCount; ++i) {
updateLocalDescriptors(i, _subModels[i]->getDescriptorSet());
}
}
void SkinningModel::updateTransform(uint32_t stamp) {
@@ -37,6 +37,7 @@
#include <sys/types.h>
#include <mutex>
#include <thread>
#include <utility>
#include "application/ApplicationManager.h"
#include "audio/include/AudioEngine.h"
@@ -265,10 +266,11 @@ int AudioEngineImpl::play2d(const ccstd::string &filePath, bool loop, float volu
auto iter = _callbackMap.find(id);
if (iter != _callbackMap.end()) {
if (state == IAudioPlayer::State::OVER) {
iter->second(id, filePath);
}
auto callback = std::move(iter->second);
_callbackMap.erase(iter);
if (state == IAudioPlayer::State::OVER) {
callback(id, filePath);
}
}
});
+9 -4
View File
@@ -27,7 +27,9 @@
#import <OpenAL/al.h>
#include <atomic>
#include <functional>
#include <memory>
#include <mutex>
#include "base/std/container/string.h"
@@ -40,6 +42,7 @@
namespace cc {
class AudioEngineImpl;
class AudioPlayer;
class Scheduler;
class AudioCache {
public:
@@ -96,13 +99,15 @@ protected:
std::mutex _readDataTaskMutex;
State _state{State::INITIAL};
std::atomic<State> _state{State::INITIAL};
std::shared_ptr<bool> _isDestroyed;
// Assigned before the read task is submitted; workers must not look up the current application.
std::weak_ptr<Scheduler> _scheduler;
std::shared_ptr<std::atomic_bool> _isDestroyed;
ccstd::string _fileFullPath;
unsigned int _id;
bool _isLoadingFinished{false};
bool _isSkipReadDataTask{false};
std::atomic_bool _isLoadingFinished{false};
std::atomic_bool _isSkipReadDataTask{false};
friend class AudioEngineImpl;
friend class AudioPlayer;
+22 -14
View File
@@ -31,7 +31,6 @@
#import <Foundation/Foundation.h>
#import <OpenAL/alc.h>
#include <thread>
#include "application/ApplicationManager.h"
#include "base/Scheduler.h"
#include "base/memory/Memory.h"
@@ -85,7 +84,7 @@ unsigned int __idIndex = 0;
using namespace cc;
AudioCache::AudioCache()
: _isDestroyed(std::make_shared<bool>(false)), _id(++__idIndex){
: _isDestroyed(std::make_shared<std::atomic_bool>(false)), _id(++__idIndex){
ALOGVV("AudioCache() %p, id=%u", this, _id);
for (int i = 0; i < QUEUEBUFFER_NUM; ++i) {
_queBuffers[i] = nullptr;
@@ -114,7 +113,7 @@ AudioCache::~AudioCache() {
_alBufferId = INVALID_AL_BUFFER_ID;
}
} else {
ALOGW("AudioCache (%p), id=%u, buffer isn't ready, state=%d", this, _id, _state);
ALOGW("AudioCache (%p), id=%u, buffer isn't ready, state=%d", this, _id, static_cast<int>(_state.load()));
}
if (_queBufferFrames > 0) {
@@ -267,7 +266,6 @@ void AudioCache::readDataTask(unsigned int selfId) {
invokingPlayCallbacks();
invokingLoadCallbacks();
_isLoadingFinished = true;
if (_state != State::READY) {
_state = State::FAILED;
if (_alBufferId != INVALID_AL_BUFFER_ID && alIsBuffer(_alBufferId)) {
@@ -277,12 +275,13 @@ void AudioCache::readDataTask(unsigned int selfId) {
}
}
_isLoadingFinished = true;
_readDataTaskMutex.unlock();
}
void AudioCache::addPlayCallback(const std::function<void()> &callback) {
std::lock_guard<std::mutex> lk(_playCallbackMutex);
switch (_state) {
switch (_state.load()) {
case State::INITIAL:
case State::LOADING:
_playCallbacks.push_back(callback);
@@ -296,7 +295,7 @@ void AudioCache::addPlayCallback(const std::function<void()> &callback) {
break;
default:
ALOGE("Invalid state: %d", _state);
ALOGE("Invalid state: %d", static_cast<int>(_state.load()));
break;
}
}
@@ -312,7 +311,7 @@ void AudioCache::invokingPlayCallbacks() {
}
void AudioCache::addLoadCallback(const std::function<void(bool)> &callback) {
switch (_state) {
switch (_state.load()) {
case State::INITIAL:
case State::LOADING:
_loadCallbacks.push_back(callback);
@@ -326,7 +325,7 @@ void AudioCache::addLoadCallback(const std::function<void(bool)> &callback) {
break;
default:
ALOGE("Invalid state: %d", _state);
ALOGE("Invalid state: %d", static_cast<int>(_state.load()));
break;
}
}
@@ -337,18 +336,27 @@ void AudioCache::invokingLoadCallbacks() {
return;
}
auto scheduler = _scheduler.lock();
if (!scheduler) {
return;
}
auto isDestroyed = _isDestroyed;
auto scheduler = CC_CURRENT_ENGINE()->getScheduler();
scheduler->performFunctionInCocosThread([&, isDestroyed]() {
const bool isReady = _state.load() == State::READY;
scheduler->performFunctionInCocosThread([this, isDestroyed, isReady]() {
if (*isDestroyed) {
ALOGV("invokingLoadCallbacks perform in cocos thread, AudioCache (%p) was destroyed!", this);
return;
}
for (auto &&cb : _loadCallbacks) {
cb(_state == State::READY);
// A callback may uncache this file or end the audio engine. Do not access the
// cache again after invoking user code, and cancel any remaining callbacks.
auto callbacks = std::move(_loadCallbacks);
for (auto &&cb : callbacks) {
if (*isDestroyed) {
break;
}
cb(isReady);
}
_loadCallbacks.clear();
});
}
@@ -167,6 +167,13 @@ AudioEngineImpl::~AudioEngineImpl() {
sche->unschedule("AudioEngine", this);
}
// AudioEngine::end() has joined the worker pool before deleting this backend.
// Queued tasks are discarded by the pool, so their caches will never receive
// a read/skip notification from a worker. Unblock those cache destructors.
for (auto &entry : _audioCaches) {
entry.second.setSkipReadDataTask(true);
}
if (s_ALContext) {
alDeleteSources(MAX_AUDIOINSTANCES, _alSources);
@@ -286,6 +293,7 @@ AudioCache *AudioEngineImpl::preload(const ccstd::string &filePath, std::functio
auto it = _audioCaches.find(filePath);
if (it == _audioCaches.end()) {
audioCache = &_audioCaches[filePath];
audioCache->_scheduler = _scheduler;
audioCache->_fileFullPath = FileUtils::getInstance()->fullPathForFilename(filePath);
unsigned int cacheId = audioCache->_id;
auto isCacheDestroyed = audioCache->_isDestroyed;
@@ -28,6 +28,7 @@
#include <cstdlib>
#include <cstring>
#include <mutex>
#include <utility>
#include "audio/common/decoder/AudioDecoder.h"
#include "base/Log.h"
#include "base/Utils.h"
@@ -500,6 +501,7 @@ void AudioEngineImpl::setFinishCallback(int audioID, const std::function<void(in
}
void AudioEngineImpl::update(float /*dt*/) {
ccstd::vector<std::function<void()>> finishCallbacks;
ALint sourceState;
int audioID;
AudioPlayer *player;
@@ -534,7 +536,9 @@ void AudioEngineImpl::update(float /*dt*/) {
_threadMutex.unlock();
if (player->_finishCallbak) {
player->_finishCallbak(audioID, filePath); //IDEA: callback will delay 50ms
finishCallbacks.emplace_back([callback = std::move(player->_finishCallbak), audioID, filePath]() {
callback(audioID, filePath);
});
}
delete player;
_alSourceUsed[alSource] = false;
@@ -549,6 +553,12 @@ void AudioEngineImpl::update(float /*dt*/) {
sche->unschedule("AudioEngine", this);
}
}
// Callbacks may play/stop audio or destroy the engine. Finish all access to
// player state before invoking them, and keep the callbacks in local storage.
for (const auto &callback : finishCallbacks) {
callback();
}
}
void AudioEngineImpl::uncache(const ccstd::string &filePath) {
+19 -10
View File
@@ -157,6 +157,7 @@ void Scheduler::schedule(const ccSchedulerFunc &callback, void *target, float in
if (iter == _hashForTimers.end()) {
element = ccnew HashTimerEntry();
element->target = target;
element->generation = ++_nextTimerGeneration;
_hashForTimers[target] = element;
@@ -368,10 +369,23 @@ void Scheduler::runFunctionsToBePerformedInCocosThread() {
void Scheduler::update(float dt) {
_updateHashLocked = true;
// Iterate over all the custom selectors
HashTimerEntry *elt = nullptr;
for (auto iter = _hashForTimers.begin(); iter != _hashForTimers.end();) {
elt = iter->second;
// Callbacks can rehash the map or remove and recreate a target. Snapshot
// identities, not iterators or entry pointers; new entries start next frame.
struct TimerIdentity {
void *target;
uint64_t generation;
};
ccstd::vector<TimerIdentity> targets;
targets.reserve(_hashForTimers.size());
for (const auto &entry : _hashForTimers) {
targets.push_back({entry.first, entry.second->generation});
}
for (const auto &target : targets) {
auto iter = _hashForTimers.find(target.target);
if (iter == _hashForTimers.end() || iter->second->generation != target.generation) {
continue;
}
auto *elt = iter->second;
_currentTarget = elt;
_currentTargetSalvaged = false;
@@ -396,14 +410,9 @@ void Scheduler::update(float dt) {
// only delete currentTarget if no actions were scheduled during the cycle (issue #481)
if (_currentTargetSalvaged && _currentTarget->timers.empty()) {
++iter;
removeHashElement(_currentTarget);
if (iter != _hashForTimers.end()) {
++iter;
}
} else {
++iter;
}
_currentTarget = nullptr;
}
_updateHashLocked = false;
+4 -1
View File
@@ -28,6 +28,7 @@
#pragma once
#include <cstdint>
#include <functional>
#include <mutex>
@@ -278,6 +279,7 @@ private:
struct HashTimerEntry {
ccstd::vector<Timer *> timers;
void *target;
uint64_t generation;
int timerIndex;
Timer *currentTimer;
bool currentTimerSalvaged;
@@ -291,9 +293,10 @@ private:
// Used for "selectors with interval"
ccstd::unordered_map<void *, HashTimerEntry *> _hashForTimers;
uint64_t _nextTimerGeneration = 0;
struct HashTimerEntry *_currentTarget = nullptr;
bool _currentTargetSalvaged = false;
// If true unschedule will not remove anything from a hash. Elements will only be marked for deletion.
// True while timer entries are being updated.
bool _updateHashLocked = false;
// Used for "perform Function"
@@ -42,7 +42,7 @@ ValueArrayPool::ValueArrayPool() {
}
ValueArray &ValueArrayPool::get(uint32_t argc, bool &outNeedDelete) {
if (SE_UNLIKELY(_depth >= _pools.size())) {
if (SE_UNLIKELY(argc > MAX_ARGS || _depth >= _pools.size())) {
outNeedDelete = true;
auto *ret = ccnew ValueArray();
ret->resize(argc);
@@ -50,7 +50,6 @@ ValueArray &ValueArrayPool::get(uint32_t argc, bool &outNeedDelete) {
}
outNeedDelete = false;
CC_ASSERT_LE(argc, MAX_ARGS);
auto &ret = _pools[_depth][argc];
CC_ASSERT(ret.size() == argc);
return ret;
@@ -1184,10 +1184,12 @@ void ScriptEngine::removeUnhandledPromise(v8::Local<v8::Promise> promise) {
// Remove handled promises from the list
SE_ASSERT(promise->GetIsolate() == _isolate, "Wrong isolate");
auto *isolate = promise->GetIsolate();
for (auto it = _unhandledPromises.begin(); it != _unhandledPromises.end(); ++it) {
for (auto it = _unhandledPromises.begin(); it != _unhandledPromises.end();) {
v8::Local<v8::Promise> const unhandledPromise = std::get<0>(*it).Get(isolate);
if (unhandledPromise == promise) {
_unhandledPromises.erase(it--);
it = _unhandledPromises.erase(it);
} else {
++it;
}
}
}
+1 -1
View File
@@ -30,4 +30,4 @@ THE SOFTWARE.
#define COCOS_VERSION_DEFINED 1
#define COCOS_VERSION 40000
// #define COCOS_PRE_RELEASE "alpha"
// #define COCOS_PRE_RELEASE "beta"
+33 -3
View File
@@ -23,15 +23,34 @@
****************************************************************************/
#include "core/assets/RenderTexture.h"
#include "base/std/optional.h"
#include "core/Root.h"
#include "core/platform/Debug.h"
#include "core/utils/IDGenerator.h"
#include "renderer/gfx-base/GFXDef-common.h"
#include "renderer/gfx-base/GFXDevice.h"
#include "scene/RenderWindow.h"
namespace cc {
namespace {
// The legacy limit used only when the GPU capability is unavailable,
// e.g. when assets are loaded before the renderer is initialized.
constexpr uint32_t FALLBACK_MAX_RENDER_TEXTURE_SIZE = 2048;
// Returns ccstd::nullopt when the device or its max texture size is unavailable.
ccstd::optional<uint32_t> getMaxRenderTextureSize() {
auto *device = gfx::Device::getInstance();
if (device == nullptr) {
return ccstd::nullopt;
}
const uint32_t maxTextureSize = device->getCapabilities().maxTextureSize;
if (maxTextureSize == 0) {
return ccstd::nullopt;
}
return maxTextureSize;
}
gfx::RenderPassInfo getDefaultRenderPassInfo(gfx::Device *device) {
gfx::RenderPassInfo info;
info.colorAttachments.push_back({
@@ -72,8 +91,11 @@ bool RenderTexture::destroy() {
}
void RenderTexture::resize(uint32_t width, uint32_t height) {
_width = std::floor(clampf(static_cast<float>(width), 1.F, 2048.F));
_height = std::floor(clampf(static_cast<float>(height), 1.F, 2048.F));
const auto maxTextureSize = getMaxRenderTextureSize();
const auto maxSize = static_cast<float>(
maxTextureSize.has_value() ? maxTextureSize.value() : FALLBACK_MAX_RENDER_TEXTURE_SIZE);
_width = static_cast<uint32_t>(std::floor(clampf(static_cast<float>(width), 1.F, maxSize)));
_height = static_cast<uint32_t>(std::floor(clampf(static_cast<float>(height), 1.F, maxSize)));
if (_window != nullptr) {
_window->resize(_width, _height);
}
@@ -146,7 +168,15 @@ void RenderTexture::initDefault(const ccstd::optional<ccstd::string> &uuid) {
}
bool RenderTexture::validate() const {
return _width >= 1 && _width <= 2048 && _height >= 1 && _height <= 2048;
if (_width == 0 || _height == 0) {
return false;
}
const auto maxTextureSize = getMaxRenderTextureSize();
if (!maxTextureSize.has_value()) {
return true;
}
const uint32_t maxSize = maxTextureSize.value();
return _width <= maxSize && _height <= maxSize;
}
ccstd::vector<uint8_t> RenderTexture::readPixels(uint32_t x, uint32_t y, uint32_t width, uint32_t height) const {
+3 -2
View File
@@ -73,8 +73,9 @@ public:
/**
* @en Resize the render texture
* @zh 修改渲染贴图的尺寸
* @param width The pixel width, the range is from 1 to 2048
* @param height The pixel height, the range is from 1 to 2048
* The upper bound is the GPU max texture size. If the limit is unavailable, 2048 is used as a fallback.
* @param width The pixel width, the range is from 1 to the maximum texture size supported by the GPU
* @param height The pixel height, the range is from 1 to the maximum texture size supported by the GPU
*/
void resize(uint32_t width, uint32_t height);
+28
View File
@@ -432,10 +432,21 @@ ccstd::unordered_map<uint32_t, ccstd::string> debugInfos = {
{ 9007, "Since v3.6, Because mask changes the inheritance relationship, you can directly manipulate the rendering components under the same node to complete the operation." },
{ 9008, "request fullscreen is not supported on this platform." },
{ 9009, "exit fullscreen is not supported on this platform." },
{ 9010, "UIMesh.setMeshData: unsupported vertexStride %d, expected %d (V3F_T2F_C4B) or %d (V3F_T2F_C4B_C4B); data rejected." },
{ 9011, "UIMesh.setMeshData: negative counts (vertexCount %d, indexCount %d); data rejected." },
{ 9012, "UIMesh.setMeshData: vertexData holds %d bytes, but %d vertices x %d bytes are declared; data rejected." },
{ 9013, "UIMesh.setMeshData: indexData is %d bytes at offset %d, but %d Uint16 indices need %d bytes (2-byte aligned view); data rejected." },
{ 9014, "UIMesh.setMeshData: indices[%d] = %d is out of range for %d vertices; data rejected." },
{ 9015, "UIMesh.setMeshData: segment %d range [%d, %d) is out of bounds for indexCount %d; data rejected." },
{ 9016, "UIMesh.setMeshData: %d vertices / %d indices exceed the accessor cap (%d / %d); split the mesh. Data rejected." },
{ 9017, "UIMesh: render data allocation failed for %d vertices / %d indices (accessor cap: %d / %d)." },
{ 9100, "texture size exceeds current device limits %d/%d" },
{ 9101, "The length of the TypedArrayBuffer must be an integer." },
{ 9201, "Cannot access game frame or container." },
{ 9202, "Setting window size is not supported." },
{ 9204, "maxDevicePixelRatio, when specified, must be a finite number >= 1." },
{ 9205, "PAL did not apply the configured maximum DPR. Check that the engine and PAL versions match." },
{ 9206, "maxDevicePixelRatio cannot change after ScreenAdapter.init()." },
{ 9300, "The current buffer beyond the limit in ui static component, please reduce the amount" },
{ 9301, "The UI has not been initialized" },
{ 9302, "Can't getGFXSampler with out device" },
@@ -624,6 +635,23 @@ ccstd::unordered_map<uint32_t, ccstd::string> debugInfos = {
{ 16418, "Debug bones or slots is invalid in cached mode." },
{ 16419, "Spine version not supported." },
{ 16420, "End time must bigger than start time." },
{ 16500, "WorkerPool script path must be a non-empty string" },
{ 16501, "WorkerPool requires a self-contained task function or a worker script path" },
{ 16502, "WorkerPool has been terminated" },
{ 16503, "WorkerPool has no available execution backend" },
{ 16504, "No worker backend for '%s' (%s). Provide options.fallback to run single-threaded, or fix packaging (docs/worker/README.md)." },
{ 16505, "WorkerPool degraded to single-threaded for '%s': worker backend failed (%s). %s" },
{ 16506, "WorkerPool is rejecting tasks (no options.fallback) for '%s': worker backend failed (%s). %s" },
{ 16507, "WorkerPool could not use a worker for '%s' and is running single-threaded via options.fallback. Reason: %s. %s" },
{ 16508, "WorkerPool could not use a worker for '%s' and is REJECTING tasks (no options.fallback). Reason: %s. %s" },
{ 16509, "Worker error" },
{ 16510, "Worker is unavailable and no synchronous fallback exists" },
{ 16511, "Worker task timed out after %sms — the worker never replied (deadlock, infinite loop, or non-protocol script). Worker discarded; see docs/worker/README.md" },
{ 16512, "Worker has been disposed" },
{ 16513, "Worker script sent a malformed reply — it must implement the engine protocol: receive { id, args }, post back { id, ok, value } or { id, ok: false, error } (docs/worker/cc-worker-template.js)" },
{ 16514, "Worker task failed" },
{ 16515, "createWorker(path) requires a non-empty worker script path" },
{ 16516, "Function workers are unavailable; use WorkerPool for an automatic sync fallback, or createWorker(path) (mode 2)." },
};
}//namespace cc
+22 -5
View File
@@ -684,7 +684,12 @@ const Quaternion &Node::getWorldRotation() const { // NOLINT(misc-no-recursion)
void Node::setWorldScale(float x, float y, float z) {
bool forceUpdate = _parent != nullptr && (_transformFlags & static_cast<uint32_t>(TransformBit::SCALE)) != static_cast<uint32_t>(TransformBit::NONE);
if (!forceUpdate && _worldScale.approxEquals({x, y, z})) {
// World-scale decomposition can hide local mirror signs. Preserve the same-value no-op for nonnegative targets.
const bool parentedNonnegativeTarget = _parent != nullptr && x >= 0.F && y >= 0.F && z >= 0.F;
if (!forceUpdate && (_parent == nullptr || (y >= 0.F && z >= 0.F)) &&
_worldScale.approxEquals({x, y, z}) &&
(_worldScale.x < 0.F) == (x < 0.F) &&
(parentedNonnegativeTarget || ((_localScale.y < 0.F) == (y < 0.F) && (_localScale.z < 0.F) == (z < 0.F)))) {
return;
}
@@ -738,10 +743,22 @@ void Node::setWorldScale(float x, float y, float z) {
// remove rotation part of the local matrix
Mat3::multiply(localRotInv, localRS, &localRS);
// extract scaling part from local matrix
_localScale.x = Vec3{localRS.m[0], localRS.m[1], localRS.m[2]}.length();
_localScale.y = Vec3{localRS.m[3], localRS.m[4], localRS.m[5]}.length();
_localScale.z = Vec3{localRS.m[6], localRS.m[7], localRS.m[8]}.length();
// Restore the requested signs after extracting the scale magnitudes.
// A negative X request accounts for parent reflection. A nonnegative X keeps
// the original positive local X behavior.
const Vec3 &parentScale = _parent->_worldScale;
const float parentSign = (parentScale.x < 0.F ? -1.F : 1.F) *
(parentScale.y < 0.F ? -1.F : 1.F) *
(parentScale.z < 0.F ? -1.F : 1.F);
const float localScaleX = Vec3{localRS.m[0], localRS.m[1], localRS.m[2]}.length() * (_worldScale.x < 0.F ? -parentSign : 1.F);
const float localScaleY = Vec3{localRS.m[3], localRS.m[4], localRS.m[5]}.length() * (_worldScale.y < 0.F ? -1.F : 1.F);
const float localScaleZ = Vec3{localRS.m[6], localRS.m[7], localRS.m[8]}.length() * (_worldScale.z < 0.F ? -1.F : 1.F);
if ((_localScale.x < 0.F) != (localScaleX < 0.F) ||
(_localScale.y < 0.F) != (localScaleY < 0.F) ||
(_localScale.z < 0.F) != (localScaleZ < 0.F)) {
rotationFlag = TransformBit::ROTATION;
}
_localScale.set(localScaleX, localScaleY, localScaleZ);
if (_localScale.x == 0 || _localScale.y == 0 || _localScale.z == 0) {
rotationFlag = TransformBit::ROTATION;
+13
View File
@@ -24,6 +24,8 @@
#pragma once
#include <cmath>
#include "base/Ptr.h"
#include "base/std/any.h"
#include "bindings/utils/BindingUtils.h"
@@ -35,6 +37,7 @@
#include "core/scene-graph/NodeEnum.h"
#include "math/Mat3.h"
#include "math/Mat4.h"
#include "math/Math.h"
#include "math/Quaternion.h"
#include "math/Vec3.h"
#include "math/Vec4.h"
@@ -434,6 +437,16 @@ public:
return getEulerAngles().z;
}
// Signed local 2D angle in degrees, normalized to [-180, 180].
inline float getAngle2D() const {
// Keep 2D angles independent of the folded Z in YZX Euler decomposition.
const auto &q = _localRotation;
if (std::abs(q.x) < 1e-6F && std::abs(q.y) < 1e-6F) {
return std::atan2(2.F * q.w * q.z, 1.F - 2.F * q.z * q.z) * math::RAD_TO_DEG;
}
return getEulerAngles().z;
}
inline Vec3 getForward() const {
Vec3 forward{0, 0, -1};
forward.transformQuat(getWorldRotation());
@@ -0,0 +1,279 @@
/*
Copyright (c) 2026 Xiamen Yaji Software Co., Ltd.
https://www.cocos.com/
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/
#include "platform/interfaces/modules/canvas/CanvasFont.h"
#include <cmath>
#include <cstdlib>
#include <limits>
#include <regex>
#include <string_view>
namespace cc::detail {
namespace {
bool isSpace(char c) {
return c == ' ' || c == '\t' || c == '\n' || c == '\r' || c == '\f';
}
bool isNewline(char c) {
return c == '\n' || c == '\r' || c == '\f';
}
void skipSpace(std::string_view input, size_t &pos) {
while (pos < input.size() && isSpace(input[pos])) ++pos;
}
int hexValue(char c) {
if (c >= '0' && c <= '9') return c - '0';
if (c >= 'a' && c <= 'f') return c - 'a' + 10;
if (c >= 'A' && c <= 'F') return c - 'A' + 10;
return -1;
}
void appendCodePoint(std::string &output, uint32_t code) {
if (code == 0 || code > 0x10FFFF || (code >= 0xD800 && code <= 0xDFFF)) code = 0xFFFD;
if (code < 0x80) {
output += static_cast<char>(code);
} else if (code < 0x800) {
output += static_cast<char>(0xC0 | (code >> 6));
output += static_cast<char>(0x80 | (code & 0x3F));
} else if (code < 0x10000) {
output += static_cast<char>(0xE0 | (code >> 12));
output += static_cast<char>(0x80 | ((code >> 6) & 0x3F));
output += static_cast<char>(0x80 | (code & 0x3F));
} else {
output += static_cast<char>(0xF0 | (code >> 18));
output += static_cast<char>(0x80 | ((code >> 12) & 0x3F));
output += static_cast<char>(0x80 | ((code >> 6) & 0x3F));
output += static_cast<char>(0x80 | (code & 0x3F));
}
}
// https://www.w3.org/TR/css-syntax-3/#consume-an-escaped-code-point
bool readEscape(std::string_view input, size_t &pos, bool quoted, std::string &output) {
if (++pos == input.size()) return false;
if (isNewline(input[pos])) {
if (!quoted) return false;
if (input[pos++] == '\r' && pos < input.size() && input[pos] == '\n') ++pos;
return true;
}
if (hexValue(input[pos]) >= 0) {
uint32_t code = 0;
for (int digits = 0; digits < 6 && pos < input.size() && hexValue(input[pos]) >= 0; ++digits) {
code = code * 16 + static_cast<uint32_t>(hexValue(input[pos++]));
}
if (pos < input.size() && isSpace(input[pos])) {
if (input[pos++] == '\r' && pos < input.size() && input[pos] == '\n') ++pos;
}
appendCodePoint(output, code);
} else if (input[pos] == '\0') {
appendCodePoint(output, 0);
++pos;
} else {
output += input[pos++];
}
return true;
}
bool decodeQuotedFamily(std::string_view input, std::string &family) {
size_t pos = 0;
skipSpace(input, pos);
if (pos == input.size() || (input[pos] != '"' && input[pos] != '\'')) return false;
const char quote = input[pos++];
while (pos < input.size()) {
const char c = input[pos];
if (c == quote) {
++pos;
skipSpace(input, pos);
return pos == input.size() && !family.empty();
}
if (isNewline(c)) return false;
if (c == '\\') {
if (!readEscape(input, pos, true, family)) return false;
} else if (c == '\0') {
appendCodePoint(family, 0);
++pos;
} else {
family += c;
++pos;
}
}
return false;
}
} // namespace
static CanvasFont parseLegacyCanvasFont(const std::string &font) {
#if CC_PLATFORM == CC_PLATFORM_WINDOWS
std::string boldStr;
std::string fontName = "Arial";
std::string fontSizeStr = "30";
std::regex re(R"(\s*((\d+)([\.]\d+)?)px\s+([^\r\n]*))");
std::match_results<std::string::const_iterator> results;
if (std::regex_search(font.cbegin(), font.cend(), results, re)) {
fontSizeStr = results[2].str();
// support get font name from `60px American` or `60px "American abc-abc_abc"`
// support get font name contain space,example `times new roman`
// if regex rule that does not conform to the rules,such as Chinese,it defaults to Arial
std::match_results<std::string::const_iterator> fontResults;
std::regex fontRe(R"(([\w\s-]+|"[\w\s-]+"$))");
std::string tmp(results[4].str());
if (std::regex_match(tmp, fontResults, fontRe)) {
fontName = results[4].str();
}
}
auto fontSize = static_cast<float>(atof(fontSizeStr.c_str()));
bool isBold = !boldStr.empty() || font.find("bold", 0) != std::string::npos || font.find("Bold", 0) != std::string::npos;
bool isItalic = font.find("italic", 0) != std::string::npos || font.find("Italic", 0) != std::string::npos;
return {fontName, static_cast<float>(fontSize), isBold, isItalic, false, false};
#elif CC_PLATFORM == CC_PLATFORM_QNX
std::string boldStr;
std::string fontName = "Arial";
std::string fontSizeStr = "30";
// support get font name from `60px American` or `60px "American abc-abc_abc"`
std::regex re("(bold)?\\s*((\\d+)([\\.]\\d+)?)px\\s+([\\w-]+|\"[\\w -]+\"$)");
std::match_results<std::string::const_iterator> results;
if (std::regex_search(font.cbegin(), font.cend(), results, re)) {
boldStr = results[1].str();
fontSizeStr = results[2].str();
fontName = results[5].str();
}
bool isItalic = font.find("italic", 0) != std::string::npos || font.find("Italic", 0) != std::string::npos;
auto fontSize = static_cast<float>(atof(fontSizeStr.c_str()));
bool isBold = !boldStr.empty() || font.find("bold", 0) != std::string::npos || font.find("Bold", 0) != std::string::npos;
// SE_LOGD("CanvasRenderingContext2D::setfont: %s, Size: %f, isBold: %b\n", fontName.c_str(), fontSize, isBold);
return {fontName, fontSize, isBold, isItalic, false, false};
#elif CC_PLATFORM == CC_PLATFORM_LINUX
std::string fontName = "sans-serif";
std::string fontSizeStr = "30";
std::regex re(R"(\s*((\d+)([\.]\d+)?)px\s+([^\r\n]*))");
std::match_results<std::string::const_iterator> results;
if (std::regex_search(font.cbegin(), font.cend(), results, re)) {
fontSizeStr = results[2].str();
// support get font name from `60px American` or `60px "American abc-abc_abc"`
// support get font name contain space,example `times new roman`
// if regex rule that does not conform to the rules,such as Chinese,it defaults to sans-serif
std::match_results<std::string::const_iterator> fontResults;
std::regex fontRe(R"(([\w\s-]+|"[\w\s-]+"$))");
std::string tmp(results[4].str());
if (std::regex_match(tmp, fontResults, fontRe)) {
// fontName = results[4].str();
}
}
bool isBold = font.find("bold", 0) != std::string::npos || font.find("Bold", 0) != std::string::npos;
bool isItalic = font.find("italic", 0) != std::string::npos || font.find("Italic", 0) != std::string::npos;
float fontSize = static_cast<float>(atof(fontSizeStr.c_str()));
// SE_LOGD("CanvasRenderingContext2D::setfont: %s, Size: %f, isBold: %b\n", fontName.c_str(), fontSize, isBold);
return {fontName, fontSize, isBold, isItalic, false, false};
#elif CC_PLATFORM == CC_PLATFORM_ANDROID || CC_PLATFORM == CC_PLATFORM_OHOS || CC_PLATFORM == CC_PLATFORM_OPENHARMONY
std::string fontName = "sans-serif";
std::string fontSizeStr = "30";
std::regex re(R"(\s*((\d+)([\.]\d+)?)px\s+([^\r\n]*))");
std::match_results<std::string::const_iterator> results;
if (std::regex_search(font.cbegin(), font.cend(), results, re)) {
fontSizeStr = results[2].str();
// support get font name from `60px American` or `60px "American abc-abc_abc"`
// support get font name contain space,example `times new roman`
// if regex rule that does not conform to the rules,such as Chinese,it defaults to sans-serif
std::match_results<std::string::const_iterator> fontResults;
std::regex fontRe(R"(([\w\s-]+|"[\w\s-]+"$))");
std::string tmp(results[4].str());
if (std::regex_match(tmp, fontResults, fontRe)) {
fontName = results[4].str();
}
}
double fontSize = atof(fontSizeStr.c_str());
bool isBold = font.find("bold", 0) != std::string::npos || font.find("Bold", 0) != std::string::npos;
bool isItalic = font.find("italic", 0) != std::string::npos || font.find("Italic", 0) != std::string::npos;
bool isSmallCaps = font.find("small-caps", 0) != std::string::npos || font.find("Small-Caps") != std::string::npos;
bool isOblique = font.find("oblique", 0) != std::string::npos || font.find("Oblique", 0) != std::string::npos;
// font-style: italic, oblique, normal
// font-weight: normal, bold
// font-variant: normal, small-caps
return {fontName, static_cast<float>(fontSize), isBold, isItalic, isOblique, isSmallCaps};
#elif CC_PLATFORM == CC_PLATFORM_MACOS || CC_PLATFORM == CC_PLATFORM_IOS
std::string boldStr;
std::string fontName = "Arial";
std::string fontSizeStr = "30";
bool isItalic = font.find("italic", 0) != std::string::npos || font.find("Italic", 0) != std::string::npos;
// support get font name from `60px American` or `60px "American abc-abc_abc"`
std::regex re("(bold)?\\s*((\\d+)([\\.]\\d+)?)px\\s+([\\w-]+|\"[\\w -]+\"$)");
std::match_results<std::string::const_iterator> results;
if (std::regex_search(font.cbegin(), font.cend(), results, re)) {
boldStr = results[1].str();
fontSizeStr = results[2].str();
fontName = results[5].str();
}
float fontSize = atof(fontSizeStr.c_str());
bool isBold = !boldStr.empty() || font.find("bold", 0) != std::string::npos || font.find("Bold", 0) != std::string::npos;
return {fontName, static_cast<float>(fontSize), isBold, isItalic, false, false};
#endif
return {};
}
CanvasFont parseCanvasFont(const std::string &font) {
static const std::regex DESCRIPTION(R"(\s*((\d+)([\.]\d+)?)px\s+([\s\S]*))");
std::smatch match;
std::string family;
if (!std::regex_search(font, match, DESCRIPTION) || !decodeQuotedFamily(match[4].str(), family)) {
return parseLegacyCanvasFont(font);
}
// Recover the descriptor used before TS serialized the asset's registered alias.
// Use it only when the old platform parser recognizes that complete alias;
// partial matches and unsupported names keep the original fallback behavior.
const auto legacyDescription = font.substr(0, static_cast<size_t>(match.position(4))) + family;
auto compatible = parseLegacyCanvasFont(legacyDescription);
if (compatible.family == family) {
return compatible;
}
auto fallback = parseLegacyCanvasFont(font);
#if CC_PLATFORM == CC_PLATFORM_MACOS || CC_PLATFORM == CC_PLATFORM_IOS || CC_PLATFORM == CC_PLATFORM_QNX
// These platforms used to lose the size when the family was rejected.
// Recover it only for complete quoted families with an engine-supported
// style prefix. Keep the fallback family and existing style flags intact.
static const std::regex STYLE_PREFIX(R"(\s*(?:(?:normal|bold|italic|oblique|small-caps)\s+)*)", std::regex::icase);
if (std::regex_match(font.cbegin(), font.cbegin() + match.position(1), STYLE_PREFIX)) {
const auto size = static_cast<float>(atof(match[1].str().c_str()));
// Native backends may narrow sizes to int. Do not recover unsafe values.
if (std::isfinite(size) && size >= 0.F && static_cast<double>(size) <= std::numeric_limits<int>::max()) {
fallback.size = size;
}
}
#endif
return fallback;
}
} // namespace cc::detail
@@ -0,0 +1,46 @@
/*
Copyright (c) 2026 Xiamen Yaji Software Co., Ltd.
https://www.cocos.com/
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/
#pragma once
#include <string>
#include "base/Macros.h"
namespace cc::detail {
struct CanvasFont {
std::string family;
float size{0.F};
bool bold{false};
bool italic{false};
bool oblique{false};
bool smallCaps{false};
};
// Internal native Canvas parsing, including the existing per-platform fallbacks.
// Family interpretation must not depend on the font registry. Callers serialize raw
// asset aliases once as CSS strings, including any literal quotes in the alias.
CC_DLL CanvasFont parseCanvasFont(const std::string &font);
} // namespace cc::detail
@@ -25,12 +25,12 @@
#include "platform/interfaces/modules/canvas/CanvasRenderingContext2D.h"
#include <cstdint>
#include <regex>
#include "base/csscolorparser.h"
#include "cocos/bindings/jswrapper/SeApi.h"
#include "cocos/bindings/manual/jsb_platform.h"
#include "math/Math.h"
#include "platform/FileUtils.h"
#include "platform/interfaces/modules/canvas/CanvasFont.h"
#if defined(CC_SERVER_MODE)
#include "platform/empty/modules/CanvasRenderingContext2DDelegate.h"
@@ -218,133 +218,11 @@ void CanvasRenderingContext2D::rect(float x, float y, float w, float h) {
void CanvasRenderingContext2D::setFont(const ccstd::string &font) {
recreateBufferIfNeeded();
#if CC_PLATFORM == CC_PLATFORM_WINDOWS
#if CC_PLATFORM == CC_PLATFORM_WINDOWS || CC_PLATFORM == CC_PLATFORM_QNX || CC_PLATFORM == CC_PLATFORM_LINUX || CC_PLATFORM == CC_PLATFORM_ANDROID || CC_PLATFORM == CC_PLATFORM_OHOS || CC_PLATFORM == CC_PLATFORM_OPENHARMONY || CC_PLATFORM == CC_PLATFORM_MACOS || CC_PLATFORM == CC_PLATFORM_IOS
if (_font != font) {
_font = font;
ccstd::string boldStr;
ccstd::string fontName = "Arial";
ccstd::string fontSizeStr = "30";
std::regex re(R"(\s*((\d+)([\.]\d+)?)px\s+([^\r\n]*))");
std::match_results<ccstd::string::const_iterator> results;
if (std::regex_search(_font.cbegin(), _font.cend(), results, re)) {
fontSizeStr = results[2].str();
// support get font name from `60px American` or `60px "American abc-abc_abc"`
// support get font name contain space,example `times new roman`
// if regex rule that does not conform to the rules,such as Chinese,it defaults to Arial
std::match_results<ccstd::string::const_iterator> fontResults;
std::regex fontRe(R"(([\w\s-]+|"[\w\s-]+"$))");
ccstd::string tmp(results[4].str());
if (std::regex_match(tmp, fontResults, fontRe)) {
fontName = results[4].str();
}
}
auto fontSize = static_cast<float>(atof(fontSizeStr.c_str()));
bool isBold = !boldStr.empty() || font.find("bold", 0) != ccstd::string::npos || font.find("Bold", 0) != ccstd::string::npos;
bool isItalic = font.find("italic", 0) != ccstd::string::npos || font.find("Italic", 0) != ccstd::string::npos;
_delegate->updateFont(fontName, static_cast<float>(fontSize), isBold, isItalic, false, false);
}
#elif CC_PLATFORM == CC_PLATFORM_QNX
if (_font != font) {
_font = font;
ccstd::string boldStr;
ccstd::string fontName = "Arial";
ccstd::string fontSizeStr = "30";
// support get font name from `60px American` or `60px "American abc-abc_abc"`
std::regex re("(bold)?\\s*((\\d+)([\\.]\\d+)?)px\\s+([\\w-]+|\"[\\w -]+\"$)");
std::match_results<ccstd::string::const_iterator> results;
if (std::regex_search(_font.cbegin(), _font.cend(), results, re)) {
boldStr = results[1].str();
fontSizeStr = results[2].str();
fontName = results[5].str();
}
bool isItalic = font.find("italic", 0) != ccstd::string::npos || font.find("Italic", 0) != ccstd::string::npos;
auto fontSize = static_cast<float>(atof(fontSizeStr.c_str()));
bool isBold = !boldStr.empty() || font.find("bold", 0) != ccstd::string::npos || font.find("Bold", 0) != ccstd::string::npos;
//SE_LOGD("CanvasRenderingContext2D::set_font: %s, Size: %f, isBold: %b\n", fontName.c_str(), fontSize, isBold);
_delegate->updateFont(fontName, fontSize, isBold, isItalic, false, false);
}
#elif CC_PLATFORM == CC_PLATFORM_LINUX
if (_font != font) {
_font = font;
ccstd::string fontName = "sans-serif";
ccstd::string fontSizeStr = "30";
std::regex re(R"(\s*((\d+)([\.]\d+)?)px\s+([^\r\n]*))");
std::match_results<ccstd::string::const_iterator> results;
if (std::regex_search(_font.cbegin(), _font.cend(), results, re)) {
fontSizeStr = results[2].str();
// support get font name from `60px American` or `60px "American abc-abc_abc"`
// support get font name contain space,example `times new roman`
// if regex rule that does not conform to the rules,such as Chinese,it defaults to sans-serif
std::match_results<ccstd::string::const_iterator> fontResults;
std::regex fontRe(R"(([\w\s-]+|"[\w\s-]+"$))");
ccstd::string tmp(results[4].str());
if (std::regex_match(tmp, fontResults, fontRe)) {
//fontName = results[4].str();
}
}
bool isBold = font.find("bold", 0) != ccstd::string::npos || font.find("Bold", 0) != ccstd::string::npos;
bool isItalic = font.find("italic", 0) != ccstd::string::npos || font.find("Italic", 0) != ccstd::string::npos;
float fontSize = static_cast<float>(atof(fontSizeStr.c_str()));
//SE_LOGD("CanvasRenderingContext2D::set_font: %s, Size: %f, isBold: %b\n", fontName.c_str(), fontSize, isBold);
_delegate->updateFont(fontName, fontSize, isBold, isItalic, false, false);
}
#elif CC_PLATFORM == CC_PLATFORM_ANDROID || CC_PLATFORM == CC_PLATFORM_OHOS || CC_PLATFORM == CC_PLATFORM_OPENHARMONY
if (_font != font) {
_font = font;
ccstd::string fontName = "sans-serif";
ccstd::string fontSizeStr = "30";
std::regex re(R"(\s*((\d+)([\.]\d+)?)px\s+([^\r\n]*))");
std::match_results<ccstd::string::const_iterator> results;
if (std::regex_search(_font.cbegin(), _font.cend(), results, re)) {
fontSizeStr = results[2].str();
// support get font name from `60px American` or `60px "American abc-abc_abc"`
// support get font name contain space,example `times new roman`
// if regex rule that does not conform to the rules,such as Chinese,it defaults to sans-serif
std::match_results<ccstd::string::const_iterator> fontResults;
std::regex fontRe(R"(([\w\s-]+|"[\w\s-]+"$))");
ccstd::string tmp(results[4].str());
if (std::regex_match(tmp, fontResults, fontRe)) {
fontName = results[4].str();
}
}
double fontSize = atof(fontSizeStr.c_str());
bool isBold = font.find("bold", 0) != ccstd::string::npos || font.find("Bold", 0) != ccstd::string::npos;
bool isItalic = font.find("italic", 0) != ccstd::string::npos || font.find("Italic", 0) != ccstd::string::npos;
bool isSmallCaps = font.find("small-caps", 0) != ccstd::string::npos || font.find("Small-Caps") != ccstd::string::npos;
bool isOblique = font.find("oblique", 0) != ccstd::string::npos || font.find("Oblique", 0) != ccstd::string::npos;
//font-style: italic, oblique, normal
//font-weight: normal, bold
//font-variant: normal, small-caps
_delegate->updateFont(fontName, static_cast<float>(fontSize), isBold, isItalic, isOblique, isSmallCaps);
}
#elif CC_PLATFORM == CC_PLATFORM_MACOS || CC_PLATFORM == CC_PLATFORM_IOS
if (_font != font) {
_font = font;
ccstd::string boldStr;
ccstd::string fontName = "Arial";
ccstd::string fontSizeStr = "30";
bool isItalic = font.find("italic", 0) != ccstd::string::npos || font.find("Italic", 0) != ccstd::string::npos;
// support get font name from `60px American` or `60px "American abc-abc_abc"`
std::regex re("(bold)?\\s*((\\d+)([\\.]\\d+)?)px\\s+([\\w-]+|\"[\\w -]+\"$)");
std::match_results<ccstd::string::const_iterator> results;
if (std::regex_search(_font.cbegin(), _font.cend(), results, re)) {
boldStr = results[1].str();
fontSizeStr = results[2].str();
fontName = results[5].str();
}
float fontSize = atof(fontSizeStr.c_str());
bool isBold = !boldStr.empty() || font.find("bold", 0) != ccstd::string::npos || font.find("Bold", 0) != ccstd::string::npos;
_delegate->updateFont(fontName, static_cast<float>(fontSize), isBold, isItalic, false, false);
const auto parsed = detail::parseCanvasFont(font);
_delegate->updateFont(parsed.family, parsed.size, parsed.bold, parsed.italic, parsed.oblique, parsed.smallCaps);
}
#endif
}
@@ -1007,7 +1007,8 @@ public:
for (auto *set : sets) {
set->update(oldView, newView);
}
_gpuBufferViewSet.erase(iter);
// Connecting the new view may have rehashed the map.
_gpuBufferViewSet.erase(oldView);
}
}
@@ -1018,7 +1019,8 @@ public:
for (auto *set : sets) {
set->update(oldView, newView);
}
_gpuTextureViewSet.erase(iter);
// Connecting the new view may have rehashed the map.
_gpuTextureViewSet.erase(oldView);
}
}
@@ -1217,7 +1219,8 @@ public:
ia->update(oldBuffer, newBuffer);
_ias[newBuffer].insert(ia);
}
_ias.erase(iter);
// Registering the new buffer may have rehashed the map.
_ias.erase(oldBuffer);
}
}
@@ -28,13 +28,15 @@
* ========================= !DO NOT CHANGE THE FOLLOWING SECTION MANUALLY! =========================
*/
// NOLINTBEGIN(misc-include-cleaner)
#include "cocos/renderer/pipeline/custom/LayoutGraphSerialization.h"
// clang-format off
#include "cocos/renderer/pipeline/custom/ArchiveTypes.h"
#include "cocos/renderer/pipeline/custom/LayoutGraphGraphs.h"
#include "cocos/renderer/pipeline/custom/LayoutGraphSerialization.h"
#include "cocos/renderer/pipeline/custom/LayoutGraphTypes.h"
#include "cocos/renderer/pipeline/custom/RenderCommonSerialization.h"
#include "cocos/renderer/pipeline/custom/details/Range.h"
#include "cocos/renderer/pipeline/custom/details/SerializationUtils.h"
// clang-format on
namespace cc {
@@ -71,6 +71,7 @@ inline const char* getName(ResourceResidency e) noexcept {
case ResourceResidency::PERSISTENT: return "PERSISTENT";
case ResourceResidency::EXTERNAL: return "EXTERNAL";
case ResourceResidency::BACKBUFFER: return "BACKBUFFER";
case ResourceResidency::CUSTOM: return "CUSTOM";
}
return "";
}

Some files were not shown because too many files have changed in this diff Show More