* 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
* 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
* 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
`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>
* 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
* 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>
* 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.
* 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.
* 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.
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>
* 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
* 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
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>
* 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.
A very long label string (e.g. 8000+ characters) makes the text layout
canvas exceed MAX_SIZE, so the font is meant to be scaled down by the
shrink ratio. Clamping _fontScale to a minimum of 1 defeated that
downscale and the text displayed abnormally; lower the floor to 0.1 so
the font can shrink with the canvas.
Fixes#344
Co-authored-by: ctz <ctz@ctzdeMacBook-Air.local>
Co-authored-by: Claude Code <noreply@anthropic.com>
* 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
* feat(webgpu): support compute shader on webgpu
* fix(webgpu): fix webComputePassBuilder addTexture and descriptor set bind
* fix(webgpu): mark compute producer passes valid and force-prepare bound descriptor sets
* feat(profiler): add compute dispatch counter
* perf(webgpu): cache compute pipeline states
* refactor(webgpu): simplify descriptor set prepare and dedupe bind group collection
- WebGPUDescriptorSet.prepare(): build the bind group when it was never created,
so command buffers no longer need a force-prepare branch.
- WebGPUCommandBuffer: extract _collectBindGroups() shared by the draw and
compute paths; drop the defaultResource bind group fallback since prepare()
now guarantees a valid bind group.
- executor: guard PreRenderVisitor.dispatch with the COMPUTE_SHADER feature
(symmetric with PostRenderVisitor.compute) and drop the redundant pass check.
* fix(webgpu): respect storage buffer access type in bind group layout
* fix(types): narrow types to pass tsc check
* chore(webgpu): clean up redundant assertions and long line in pipeline state
---------
Co-authored-by: VanityNie <vanitynie@qq.com>
* When copying the old buffer value, if the old value is `undefined` (out‑of‑bounds access to an empty array), preserve the default value of `-1` instead of writing `undefined`.
* opt
Use regionTexExtentHeight instead of regionTexExtentWidth when calculating copied texture extents to prevent incorrect row and slice strides.
Co-authored-by: vanitynie <vanitynie@qq.com>