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(render): per-sprite parallax scrolling
yhheff7bb1971a0
diff --git a/desktop/public/scenes/parallax-control.esscene b/desktop/public/scenes/parallax-control.esscenenew file mode 100644index 000000000..9eade91ca--- /dev/null+++ b/desktop/public/scenes/parallax-control.esscene@@ -0,0 +1,28 @@+{+ "version": "1.0",+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 200, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "Normal",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ { "type": "Sprite", "data": { "size": { "x": 100, "y": 100 }, "color": { "r": 0, "g": 1, "b": 0, "a": 1 }, "parallax": { "x": 1, "y": 1 } } }+ ],+ "visible": true+ }+ ]+}diff --git a/desktop/public/scenes/parallax-control.textures.json b/desktop/public/scenes/parallax-control.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/parallax-control.textures.json@@ -0,0 +1 @@+{}diff --git a/desktop/public/scenes/parallax.esscene b/desktop/public/scenes/parallax.esscenenew file mode 100644index 000000000..c212cac7d--- /dev/null+++ b/desktop/public/scenes/parallax.esscene@@ -0,0 +1,28 @@+{+ "version": "1.0",+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 200, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "Locked",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ { "type": "Sprite", "data": { "size": { "x": 100, "y": 100 }, "color": { "r": 0, "g": 1, "b": 0, "a": 1 }, "parallax": { "x": 0, "y": 0 } } }+ ],+ "visible": true+ }+ ]+}diff --git a/desktop/public/scenes/parallax.textures.json b/desktop/public/scenes/parallax.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/parallax.textures.json@@ -0,0 +1 @@+{}diff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.tsindex 30d5f8406..eccc733ff 100644--- a/sdk/src/component.generated.ts+++ b/sdk/src/component.generated.ts@@ -15,7 +15,7 @@ import type { Dimension, Padding, VisualState } from './wasm.generated';* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to* run on mismatch, because mismatched offsets read the wrong heap bytes.*/-export const ABI_LAYOUT_HASH = '70f3953079450020';+export const ABI_LAYOUT_HASH = 'b129a05be7804b7f';export interface AssetFieldMeta {field: string;@@ -436,6 +436,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {flipY: false,tileSize: { x: 0, y: 0 },tileSpacing: { x: 0, y: 0 },+ parallax: { x: 1, y: 1 },material: 0,enabled: true,},@@ -451,6 +452,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {layer: { step: 1, tooltip: "Sorting layer — controls draw order across sprites.", enumSource: "sortingLayers" },tileSize: { advanced: true },tileSpacing: { advanced: true },+ parallax: { tooltip: "Parallax scroll factor (1 = with world, <1 = slower, 0 = locked to camera).", advanced: true },material: { advanced: true },},},@@ -832,6 +834,7 @@ export interface SpriteData {flipY: boolean;tileSize: Vec2;tileSpacing: Vec2;+ parallax: Vec2;material: number;enabled: boolean;}diff --git a/sdk/src/ecs/ptrAccessors.generated.ts b/sdk/src/ecs/ptrAccessors.generated.tsindex 2806794f2..a48b4199b 100644--- a/sdk/src/ecs/ptrAccessors.generated.ts+++ b/sdk/src/ecs/ptrAccessors.generated.ts@@ -901,6 +901,7 @@ export interface SpritePtrData {flipY: boolean;tileSize: Vec2;tileSpacing: Vec2;+ parallax: Vec2;material: number;enabled: boolean;}@@ -920,8 +921,9 @@ export function fillSprite(out.flipY = u8[ptr + 57] !== 0;const tileSize_ = out.tileSize; tileSize_.x = f32[(ptr + 60) >> 2]; tileSize_.y = f32[((ptr + 60) >> 2) + 1];const tileSpacing_ = out.tileSpacing; tileSpacing_.x = f32[(ptr + 68) >> 2]; tileSpacing_.y = f32[((ptr + 68) >> 2) + 1];- out.material = u32[(ptr + 76) >> 2];- out.enabled = u8[ptr + 80] !== 0;+ const parallax_ = out.parallax; parallax_.x = f32[(ptr + 76) >> 2]; parallax_.y = f32[((ptr + 76) >> 2) + 1];+ out.material = u32[(ptr + 84) >> 2];+ out.enabled = u8[ptr + 88] !== 0;}export function writeSprite(@@ -939,8 +941,9 @@ export function writeSprite(u8[ptr + 57] = data.flipY ? 1 : 0;f32[(ptr + 60) >> 2] = data.tileSize.x; f32[((ptr + 60) >> 2) + 1] = data.tileSize.y;f32[(ptr + 68) >> 2] = data.tileSpacing.x; f32[((ptr + 68) >> 2) + 1] = data.tileSpacing.y;- u32[(ptr + 76) >> 2] = data.material;- u8[ptr + 80] = data.enabled ? 1 : 0;+ f32[(ptr + 76) >> 2] = data.parallax.x; f32[((ptr + 76) >> 2) + 1] = data.parallax.y;+ u32[(ptr + 84) >> 2] = data.material;+ u8[ptr + 88] = data.enabled ? 1 : 0;}export function createSpriteData(): SpritePtrData {@@ -956,6 +959,7 @@ export function createSpriteData(): SpritePtrData {flipY: false,tileSize: { x: 0, y: 0 },tileSpacing: { x: 0, y: 0 },+ parallax: { x: 0, y: 0 },material: 0,enabled: false,};diff --git a/sdk/src/ptrLayouts.generated.ts b/sdk/src/ptrLayouts.generated.tsindex a3f0c0d42..e2a0a28fe 100644--- a/sdk/src/ptrLayouts.generated.ts+++ b/sdk/src/ptrLayouts.generated.ts@@ -252,8 +252,9 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {{ name: 'flipY', type: 'bool', offset: 57 },{ name: 'tileSize', type: 'vec2', offset: 60 },{ name: 'tileSpacing', type: 'vec2', offset: 68 },- { name: 'material', type: 'u32', offset: 76 },- { name: 'enabled', type: 'bool', offset: 80 },+ { name: 'parallax', type: 'vec2', offset: 76 },+ { name: 'material', type: 'u32', offset: 84 },+ { name: 'enabled', type: 'bool', offset: 88 },],},TilemapLayer: {diff --git a/sdk/src/wasm.generated.ts b/sdk/src/wasm.generated.tsindex 16be29b51..d958b19f3 100644--- a/sdk/src/wasm.generated.ts+++ b/sdk/src/wasm.generated.ts@@ -369,6 +369,7 @@ export interface Sprite {flipY: boolean;tileSize: Vec2;tileSpacing: Vec2;+ parallax: Vec2;material: number;enabled: boolean;}diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snapindex 87801b078..ca4696b03 100644--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap@@ -476,6 +476,10 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho"material": {"advanced": true,},+ "parallax": {+ "advanced": true,+ "tooltip": "Parallax scroll factor (1 = with world, <1 = slower, 0 = locked to camera).",+ },"pivot": {"advanced": true,"tooltip": "Anchor point (0–1) the sprite rotates and scales about.",diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cppindex 8d8d77678..091a42f9c 100644--- a/src/esengine/bindings/EditorAPI.generated.cpp+++ b/src/esengine/bindings/EditorAPI.generated.cpp@@ -2,10 +2,10 @@* @file EditorAPI.generated.cpp* @brief Auto-generated editor API with string-dispatched component access* @details Generated by EHT - DO NOT EDIT- * @schema_hash 4ebe63d3ff723023+ * @schema_hash 700d4705e6c35c0d*/-#define ES_EDITOR_API_SCHEMA_HASH "4ebe63d3ff723023"+#define ES_EDITOR_API_SCHEMA_HASH "700d4705e6c35c0d"#include <emscripten/bind.h>#include <string>@@ -352,6 +352,8 @@ std::string editor_getComponentSchema(const std::string& name) {{"key":"tileSize.y","type":"float","group":"Sprite"},{"key":"tileSpacing.x","type":"float","group":"Sprite"},{"key":"tileSpacing.y","type":"float","group":"Sprite"},+ {"key":"parallax.x","type":"float","group":"Sprite"},+ {"key":"parallax.y","type":"float","group":"Sprite"},{"key":"material","type":"asset","group":"Sprite"},{"key":"enabled","type":"bool","group":"Sprite"}])JSON";@@ -914,6 +916,8 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::selse if (field == "tileSize.y") { c.tileSize.y = value; }else if (field == "tileSpacing.x") { c.tileSpacing.x = value; }else if (field == "tileSpacing.y") { c.tileSpacing.y = value; }+ else if (field == "parallax.x") { c.parallax.x = value; }+ else if (field == "parallax.y") { c.parallax.y = value; }else { return false; }return true;} else if (comp == "StateVisuals") {@@ -1219,6 +1223,8 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::stelse if (field == "tileSize.y") { return c.tileSize.y; }else if (field == "tileSpacing.x") { return c.tileSpacing.x; }else if (field == "tileSpacing.y") { return c.tileSpacing.y; }+ else if (field == "parallax.x") { return c.parallax.x; }+ else if (field == "parallax.y") { return c.parallax.y; }} else if (comp == "StateVisuals") {if (!reg.has<esengine::ecs::StateVisuals>(entity)) return 0.0f;const auto& c = reg.get<esengine::ecs::StateVisuals>(entity);diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cppindex 37429306f..ef81e431f 100644--- a/src/esengine/bindings/WebBindings.generated.cpp+++ b/src/esengine/bindings/WebBindings.generated.cpp@@ -569,6 +569,7 @@ struct SpriteJS {bool flipY;glm::vec2 tileSize;glm::vec2 tileSpacing;+ glm::vec2 parallax;u32 material;bool enabled;};@@ -586,6 +587,7 @@ esengine::ecs::Sprite spriteFromJS(const SpriteJS& js) {c.flipY = js.flipY;c.tileSize = js.tileSize;c.tileSpacing = js.tileSpacing;+ c.parallax = js.parallax;c.material = js.material;c.enabled = js.enabled;return c;@@ -604,6 +606,7 @@ SpriteJS spriteToJS(const esengine::ecs::Sprite& c) {js.flipY = c.flipY;js.tileSize = c.tileSize;js.tileSpacing = c.tileSpacing;+ js.parallax = c.parallax;js.material = c.material;js.enabled = c.enabled;return js;@@ -1020,6 +1023,7 @@ EMSCRIPTEN_BINDINGS(esengine_components) {.field("flipY", &SpriteJS::flipY).field("tileSize", &SpriteJS::tileSize).field("tileSpacing", &SpriteJS::tileSpacing)+ .field("parallax", &SpriteJS::parallax).field("material", &SpriteJS::material).field("enabled", &SpriteJS::enabled);@@ -1890,8 +1894,9 @@ static_assert(offsetof(esengine::ecs::Sprite, flipX) == 56, "ABI offset drift: estatic_assert(offsetof(esengine::ecs::Sprite, flipY) == 57, "ABI offset drift: esengine::ecs::Sprite.flipY (EHT expected 57)");static_assert(offsetof(esengine::ecs::Sprite, tileSize) == 60, "ABI offset drift: esengine::ecs::Sprite.tileSize (EHT expected 60)");static_assert(offsetof(esengine::ecs::Sprite, tileSpacing) == 68, "ABI offset drift: esengine::ecs::Sprite.tileSpacing (EHT expected 68)");-static_assert(offsetof(esengine::ecs::Sprite, material) == 76, "ABI offset drift: esengine::ecs::Sprite.material (EHT expected 76)");-static_assert(offsetof(esengine::ecs::Sprite, enabled) == 80, "ABI offset drift: esengine::ecs::Sprite.enabled (EHT expected 80)");+static_assert(offsetof(esengine::ecs::Sprite, parallax) == 76, "ABI offset drift: esengine::ecs::Sprite.parallax (EHT expected 76)");+static_assert(offsetof(esengine::ecs::Sprite, material) == 84, "ABI offset drift: esengine::ecs::Sprite.material (EHT expected 84)");+static_assert(offsetof(esengine::ecs::Sprite, enabled) == 88, "ABI offset drift: esengine::ecs::Sprite.enabled (EHT expected 88)");static_assert(offsetof(esengine::ecs::TilemapLayer, cellSize) == 0, "ABI offset drift: esengine::ecs::TilemapLayer.cellSize (EHT expected 0)");static_assert(offsetof(esengine::ecs::TilemapLayer, originOffset) == 8, "ABI offset drift: esengine::ecs::TilemapLayer.originOffset (EHT expected 8)");static_assert(offsetof(esengine::ecs::TilemapLayer, tileset) == 16, "ABI offset drift: esengine::ecs::TilemapLayer.tileset (EHT expected 16)");@@ -1938,7 +1943,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif// ABI Hash -- runtime handshake against the SDK bundle// =============================================================================-static const char* kEsAbiLayoutHash = "70f3953079450020";+static const char* kEsAbiLayoutHash = "b129a05be7804b7f";std::string esengineGetAbiLayoutHash() {return std::string(kEsAbiLayoutHash);diff --git a/src/esengine/ecs/components/Sprite.hpp b/src/esengine/ecs/components/Sprite.hppindex 9c07e85a9..0cd0c4935 100644--- a/src/esengine/ecs/components/Sprite.hpp+++ b/src/esengine/ecs/components/Sprite.hpp@@ -89,6 +89,13 @@ struct Sprite {ES_PROPERTY(advanced)glm::vec2 tileSpacing{0.0f, 0.0f};+ /** @brief Parallax scroll factor per axis. 1 = moves with the world (default, no+ * parallax); <1 = scrolls slower than the camera (appears farther, e.g. a+ * background); 0 = locked to the camera (e.g. a sky). The renderer offsets+ * the sprite by camera_center * (1 - factor). */+ ES_PROPERTY(advanced, tooltip="Parallax scroll factor (1 = with world, <1 = slower, 0 = locked to camera).")+ glm::vec2 parallax{1.0f, 1.0f};+/** @brief Custom material ID (0 = use default batch shader) */ES_PROPERTY(asset = material, advanced)u32 material{0};diff --git a/src/esengine/renderer/plugins/SpritePlugin.cpp b/src/esengine/renderer/plugins/SpritePlugin.cppindex 1324bb6a6..aeea05fe7 100644--- a/src/esengine/renderer/plugins/SpritePlugin.cpp+++ b/src/esengine/renderer/plugins/SpritePlugin.cpp@@ -22,6 +22,15 @@ void SpritePlugin::collect(RenderCollectContext& collect_ctx) {auto& ctx = collect_ctx.frame_context;auto spriteView = registry.view<ecs::Transform, ecs::Sprite>();+ // Camera center in world space (from the inverse view-projection), for parallax —+ // the same derivation TilemapRenderPlugin uses, so sprite and tilemap parallax+ // scroll consistently. Computed once per collect, not per sprite.+ glm::mat4 invVP = glm::inverse(ctx.view_projection);+ glm::vec4 camBL = invVP * glm::vec4(-1.0f, -1.0f, 0.0f, 1.0f);+ glm::vec4 camTR = invVP * glm::vec4( 1.0f, 1.0f, 0.0f, 1.0f);+ const f32 camCenterX = (camBL.x / camBL.w + camTR.x / camTR.w) * 0.5f;+ const f32 camCenterY = (camBL.y / camBL.w + camTR.y / camTR.w) * 0.5f;+for (auto entity : spriteView) {const auto& sprite = spriteView.get<ecs::Sprite>(entity);if (!sprite.enabled) continue;@@ -30,6 +39,10 @@ void SpritePlugin::collect(RenderCollectContext& collect_ctx) {auto& transform = spriteView.get<ecs::Transform>(entity);transform.ensureDecomposed();glm::vec3 position = transform.worldPosition;+ // Parallax: shift toward the camera by (1 - factor); factor 1 = no shift. Applied+ // before the frustum cull so a parallaxed sprite is culled at where it's drawn.+ position.x += camCenterX * (1.0f - sprite.parallax.x);+ position.y += camCenterY * (1.0f - sprite.parallax.y);const auto& rotation = transform.worldRotation;const auto& scale = transform.worldScale;