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(rc6): Basis Universal KTX2 transcoder module (Batch C3, build)

esengine56c269d3ec7d
diff --git a/.gitmodules b/.gitmodules
index e016fda66..6b023d399 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -31,3 +31,6 @@
[submodule "tools/mcp-server"]
path = tools/mcp-server
url = https://github.com/esengine/estella-mcp-server.git
+[submodule "third_party/basis_universal"]
+ path = third_party/basis_universal
+ url = https://github.com/BinomialLLC/basis_universal.git
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 4a78396c6..f70f52bc9 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -16,6 +16,7 @@ option(ES_ENABLE_PARTICLES "Enable Particle system" ON)
option(ES_ENABLE_TIMELINE "Enable Timeline animation" ON)
option(ES_ENABLE_POSTPROCESS "Enable Post-processing pipeline" ON)
option(ES_ENABLE_BITMAP_TEXT "Enable Bitmap text rendering" ON)
+option(ES_ENABLE_BASIS "Build the Basis Universal KTX2 transcoder module" OFF)
option(ES_BUILD_MAIN_MODULE "Build as MAIN_MODULE for dynamic linking" OFF)
option(ES_BUILD_SIDE_MODULE "Build side modules for dynamic linking" OFF)
@@ -508,6 +509,28 @@ html,body{width:100%;height:100%;overflow:hidden;background:#1a1a1a}
)
endif()
+ # Basis Universal KTX2 transcoder module (compressed textures — RC6)
+ if(ES_ENABLE_BASIS)
+ add_executable(basis_module
+ src/esengine/bindings/BasisModuleEntry.cpp
+ third_party/basis_universal/transcoder/basisu_transcoder.cpp
+ )
+ 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.
+ target_compile_definitions(basis_module PRIVATE
+ BASISD_SUPPORT_KTX2=1
+ BASISD_SUPPORT_KTX2_ZSTD=0
+ )
+ es_apply_basis_module_settings(basis_module)
+ set_target_properties(basis_module PROPERTIES
+ OUTPUT_NAME "basis"
+ RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/sdk"
+ )
+ endif()
+
# Physics standalone WASM module
if(ES_ENABLE_BOX2D)
add_executable(physics_module
diff --git a/build-tools/build.config.js b/build-tools/build.config.js
index 347111e50..af511daf9 100644
--- a/build-tools/build.config.js
+++ b/build-tools/build.config.js
@@ -54,6 +54,15 @@ export default {
'sdk/physics.wasm': 'wasm/web/physics.wasm',
},
},
+ basis: {
+ buildDir: 'build-basis',
+ cmakeFlags: ['-DES_BUILD_WEB=ON', '-DES_BUILD_TESTS=OFF', '-DES_ENABLE_BASIS=ON'],
+ targets: ['basis_module'],
+ outputs: {
+ 'sdk/basis.js': 'wasm/web/basis.js',
+ 'sdk/basis.wasm': 'wasm/web/basis.wasm',
+ },
+ },
'web-main': {
buildDir: 'build-web-main',
cmakeFlags: ['-DES_BUILD_WEB=ON', '-DES_BUILD_TESTS=OFF', '-DES_BUILD_MAIN_MODULE=ON'],
diff --git a/build-tools/cli.js b/build-tools/cli.js
index 53ed418e8..12a830c0d 100644
--- a/build-tools/cli.js
+++ b/build-tools/cli.js
@@ -25,7 +25,7 @@ program
program
.command('build')
.description('Build ESEngine')
- .option('-t, --target <target>', 'Build target (web, wechat, playable, spine, spine38, physics, web-main, wechat-main, physics-side, sdk, all)', 'web')
+ .option('-t, --target <target>', 'Build target (web, wechat, playable, spine, spine38, physics, basis, web-main, wechat-main, physics-side, sdk, all)', 'web')
.option('-d, --debug', 'Debug build', false)
.option('-r, --release', 'Release build (default)', true)
.option('-c, --clean', 'Clean before build', false)
@@ -49,7 +49,7 @@ program
const isDebug = options.debug && !options.release;
const targets = options.target === 'all'
- ? ['web', 'wechat', 'playable', 'spine', 'spine38', 'spine41', 'physics', 'physics-playable']
+ ? ['web', 'wechat', 'playable', 'spine', 'spine38', 'spine41', 'physics', 'physics-playable', 'basis']
: [options.target];
if (options.clean) {
diff --git a/cmake/Emscripten.cmake b/cmake/Emscripten.cmake
index bdfd77e4d..e88f86db6 100644
--- a/cmake/Emscripten.cmake
+++ b/cmake/Emscripten.cmake
@@ -308,6 +308,40 @@ function(es_apply_spine_module_settings TARGET_NAME)
endif()
endfunction()
+# =============================================================================
+# Basis Universal KTX2 Transcoder Module (standalone WASM, no GL)
+# =============================================================================
+
+set(ES_EMSCRIPTEN_BASIS_MODULE_FLAGS
+ -sWASM=1
+ -sALLOW_MEMORY_GROWTH=1
+ -sNO_EXIT_RUNTIME=1
+ -sEXPORT_ES6=0
+ -sMODULARIZE=1
+ -sDYNAMIC_EXECUTION=0
+ -sFILESYSTEM=0
+ "-sEXPORT_NAME='ESBasisModule'"
+ "-sEXPORTED_FUNCTIONS=['_es_basis_init','_es_basis_open','_es_basis_get_width','_es_basis_get_height','_es_basis_transcoded_size','_es_basis_transcode','_es_basis_close','_malloc','_free']"
+ "-sEXPORTED_RUNTIME_METHODS=['cwrap','HEAPU8','HEAPU32']"
+ -O3
+ -flto
+ -Wl,--gc-sections
+ -fno-exceptions
+ -fno-rtti
+)
+
+function(es_apply_basis_module_settings TARGET_NAME)
+ if(ES_BUILD_WEB OR ES_BUILD_WXGAME)
+ target_compile_options(${TARGET_NAME} PRIVATE ${ES_EMSCRIPTEN_COMPILE_FLAGS} -flto -fno-exceptions -fno-rtti)
+
+ string(REPLACE ";" " " LINK_FLAGS_STR "${ES_EMSCRIPTEN_BASIS_MODULE_FLAGS}")
+ set_target_properties(${TARGET_NAME} PROPERTIES
+ SUFFIX ".js"
+ LINK_FLAGS "${LINK_FLAGS_STR}"
+ )
+ endif()
+endfunction()
+
# =============================================================================
# Physics Module (standalone WASM, no GL)
# =============================================================================
diff --git a/src/esengine/bindings/BasisModuleEntry.cpp b/src/esengine/bindings/BasisModuleEntry.cpp
new file mode 100644
index 000000000..3485813bc
--- /dev/null
+++ b/src/esengine/bindings/BasisModuleEntry.cpp
@@ -0,0 +1,89 @@
+/**
+ * @file BasisModuleEntry.cpp
+ * @brief Emscripten module: Basis Universal KTX2 transcoder (RC6 Batch C3)
+ * @details A standalone wasm module (built like spine/physics) exposing a small C
+ * API over basist::ktx2_transcoder. The SDK loads it on demand and uses it
+ * to turn a KTX2/Basis container into GPU-ready compressed (or RGBA8) bytes
+ * for upload. Stateless from the caller's view: open → query → transcode →
+ * close, one image at a time.
+ *
+ * The integer `target` codes form a stable contract with the TS side
+ * (sdk/src/asset/compressed.ts / BasisTranscoder impl):
+ * 0 = ETC2_RGBA8, 1 = ASTC_4x4, 2 = S3TC_DXT5 (BC3), 3 = RGBA8 (fallback).
+ */
+
+#include "basisu_transcoder.h"
+
+#include <cstdint>
+
+namespace {
+
+basist::ktx2_transcoder g_transcoder;
+bool g_open = false;
+
+basist::transcoder_texture_format mapFormat(int target) {
+ switch (target) {
+ case 0: return basist::transcoder_texture_format::cTFETC2_RGBA; // ETC2_RGBA8
+ case 1: return basist::transcoder_texture_format::cTFASTC_4x4_RGBA; // ASTC 4x4
+ case 2: return basist::transcoder_texture_format::cTFBC3_RGBA; // S3TC/DXT5
+ default: return basist::transcoder_texture_format::cTFRGBA32; // uncompressed fallback
+ }
+}
+
+bool isUncompressed(int target) { return target == 3; }
+
+// Blocks (compressed) or pixels (uncompressed) in level 0.
+uint32_t levelUnits(const basist::ktx2_image_level_info& info, int target) {
+ return isUncompressed(target) ? (info.m_orig_width * info.m_orig_height)
+ : (info.m_num_blocks_x * info.m_num_blocks_y);
+}
+
+} // namespace
+
+extern "C" {
+
+/** Initialize the transcoder lookup tables. Call once after module load. */
+void es_basis_init() {
+ basist::basisu_transcoder_init();
+}
+
+/**
+ * Open a KTX2 container. `pData` must stay valid (allocated in this module's heap)
+ * until es_basis_close(). Returns 1 on success.
+ */
+int es_basis_open(const uint8_t* pData, uint32_t dataSize) {
+ es_basis_close();
+ if (!g_transcoder.init(pData, dataSize)) return 0;
+ if (!g_transcoder.start_transcoding()) return 0;
+ g_open = true;
+ return 1;
+}
+
+uint32_t es_basis_get_width() { return g_open ? g_transcoder.get_width() : 0u; }
+uint32_t es_basis_get_height() { return g_open ? g_transcoder.get_height() : 0u; }
+
+/** Bytes required to transcode level 0 to `target`, or 0 on error. */
+uint32_t es_basis_transcoded_size(int target) {
+ if (!g_open) return 0u;
+ basist::ktx2_image_level_info info;
+ if (!g_transcoder.get_image_level_info(info, 0, 0, 0)) return 0u;
+ return levelUnits(info, target) * basist::basis_get_bytes_per_block_or_pixel(mapFormat(target));
+}
+
+/** Transcode level 0 into `pOut` (>= es_basis_transcoded_size). Returns 1 on success. */
+int es_basis_transcode(int target, uint8_t* pOut, uint32_t outSize) {
+ if (!g_open || !pOut) return 0;
+ basist::ktx2_image_level_info info;
+ if (!g_transcoder.get_image_level_info(info, 0, 0, 0)) return 0;
+ const basist::transcoder_texture_format fmt = mapFormat(target);
+ const uint32_t units = levelUnits(info, target);
+ if (outSize < units * basist::basis_get_bytes_per_block_or_pixel(fmt)) return 0;
+ return g_transcoder.transcode_image_level(0, 0, 0, pOut, units, fmt) ? 1 : 0;
+}
+
+/** Release the open container. Safe to call when none is open. */
+void es_basis_close() {
+ g_open = false;
+}
+
+} // extern "C"
diff --git a/third_party/basis_universal b/third_party/basis_universal
new file mode 160000
index 000000000..1aab02ba2
--- /dev/null
+++ b/third_party/basis_universal
@@ -0,0 +1 @@
+Subproject commit 1aab02ba2df16ad873229030ea191ea8c10e3fc9