Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(render): KTX2 textures under zstd supercompression decode on web and mini-games

esengine011e36104a2d
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 40efca0e3..b30ebaf5e 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -389,15 +389,17 @@ if(ES_BUILD_WEB OR ES_BUILD_WXGAME)
add_executable(basis_module
src/esengine/bindings/modules/basis/BasisModuleEntry.cpp
third_party/basis_universal/transcoder/basisu_transcoder.cpp
+ third_party/basis_universal/zstd/zstddeclib.c
)
target_include_directories(basis_module PRIVATE
${CMAKE_CURRENT_SOURCE_DIR}/third_party/basis_universal/transcoder
)
- # ETC1S works without zstd; disabling it avoids the zstd dependency. UASTC
- # assets must then be encoded without zstd supercompression.
+ # zstd too, as the native host builds it: a UASTC KTX2 made elsewhere is
+ # usually zstd-supercompressed, and without it every one fails to decode.
+ # It costs this module ~21KB brotli, paid only by a package carrying KTX2.
target_compile_definitions(basis_module PRIVATE
BASISD_SUPPORT_KTX2=1
- BASISD_SUPPORT_KTX2_ZSTD=0
+ BASISD_SUPPORT_KTX2_ZSTD=1
)
es_apply_basis_module_settings(basis_module)
set_target_properties(basis_module PROPERTIES
diff --git a/build-tools/basis/README.md b/build-tools/basis/README.md
index ae50c106e..1ee564be3 100644
--- a/build-tools/basis/README.md
+++ b/build-tools/basis/README.md
@@ -38,7 +38,7 @@ and re-vendor when bumping the `basis_universal` submodule.
## Compatibility note
-UASTC KTX2 is emitted **without zstd supercompression** because the runtime
-transcoder is built `BASISD_SUPPORT_KTX2_ZSTD=0` (`CMakeLists.txt`). Keep these in
-sync: enabling zstd here without enabling it there would make assets fail to
-transcode on-device.
+UASTC KTX2 is emitted **without zstd supercompression**. Every runtime
+transcoder reads zstd (`BASISD_SUPPORT_KTX2_ZSTD=1` in `CMakeLists.txt`, and the
+native host's), so an authored zstd KTX2 decodes; whether the cook should emit it
+is a package-size decision, not a compatibility one.
diff --git a/build-tools/basis/encoder.mjs b/build-tools/basis/encoder.mjs
index 7d27cc9a3..968c67ac7 100644
--- a/build-tools/basis/encoder.mjs
+++ b/build-tools/basis/encoder.mjs
@@ -1,16 +1,10 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * PNG/JPG/RGBA → KTX2 (Basis Universal) encoder for the build-time asset cook.
- * Wraps the vendored, prebuilt Basis encoder wasm
- * (basis_encoder.cjs + basis_encoder.wasm — built from third_party/basis_universal,
- * see README.md) behind a small Promise API. Build-time only: the *runtime*
- * transcoder is a separate side module (sdk/src/asset/basisTranscoder.ts).
- *
- * UASTC is emitted WITHOUT KTX2 zstd supercompression, because the engine's
- * runtime transcoder is built BASISD_SUPPORT_KTX2_ZSTD=0 (CMakeLists.txt); a
- * zstd-supercompressed UASTC KTX2 would fail to transcode at runtime. ETC1S needs
- * no supercompression. Both transcode at runtime to ASTC/ETC2/BC (compressed.ts).
+ * PNG/JPG/RGBA → KTX2 (Basis Universal) encoder for the build-time asset cook,
+ * over the vendored encoder wasm (see README.md). The runtime transcoder is a
+ * separate side module (sdk/src/asset/basisTranscoder.ts), and reads zstd
+ * supercompression whether or not this emits it.
*/
import { createRequire } from 'node:module';
import { fileURLToPath } from 'node:url';