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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(rc6): Basis Universal KTX2 transcoder module (Batch C3, build)
esengine56c269d3ec7d
diff --git a/.gitmodules b/.gitmodulesindex e016fda66..6b023d399 100644--- a/.gitmodules+++ b/.gitmodules@@ -31,3 +31,6 @@[submodule "tools/mcp-server"]path = tools/mcp-serverurl = 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.gitdiff --git a/CMakeLists.txt b/CMakeLists.txtindex 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 moduleif(ES_ENABLE_BOX2D)add_executable(physics_modulediff --git a/build-tools/build.config.js b/build-tools/build.config.jsindex 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.jsindex 53ed418e8..12a830c0d 100644--- a/build-tools/cli.js+++ b/build-tools/cli.js@@ -25,7 +25,7 @@ programprogram.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 @@ programconst 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.cmakeindex 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.cppnew file mode 100644index 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_universalnew file mode 160000index 000000000..1aab02ba2--- /dev/null+++ b/third_party/basis_universal@@ -0,0 +1 @@+Subproject commit 1aab02ba2df16ad873229030ea191ea8c10e3fc9