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): per-sprite parallax scrolling

yhheff7bb1971a0
diff --git a/desktop/public/scenes/parallax-control.esscene b/desktop/public/scenes/parallax-control.esscene
new file mode 100644
index 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.json
new file mode 100644
index 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.esscene
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.snap
index 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.cpp
index 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::s
else 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::st
else 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.cpp
index 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: e
static_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.hpp
index 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.cpp
index 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;