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(components): Draggable sinks into the engine

esengine32ab3a74e840
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b200d77c5..b78e54d22 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,14 @@ published separately; it ships inside the editor.
### Changed
+- **`Draggable` is an engine component.** It was a script component, so it never
+ reached the inspector's reflection table, the scene file or the editor's usual
+ component list the way engine components do. Its optional bounds changed shape
+ in the move: `constraintMin`/`constraintMax` were `{x, y} | null` and are now a
+ `Vec2` paired with a `constrainMin`/`constrainMax` flag, because zero is a
+ usable limit and cannot double as "no limit". `DragState` stays a script
+ component — it is per-frame state, never authored and never persisted.
+
- **The visual editor is no longer open source.** It moved to a private repository
(`esengine/estella-editor`) and is mounted back at `desktop/` as an **optional**
submodule; the engine — runtime, SDK, asset pipeline, CLI, project templates and
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index c014e66f5..2b65106d2 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -1148,41 +1148,57 @@
},
{
"name": "Draggable",
- "source": "ts",
+ "source": "cpp",
"fields": [
{
"key": "enabled",
"type": "boolean",
- "default": "true"
+ "default": "true",
+ "doc": "Whether this entity can be dragged at all."
},
{
"key": "dragThreshold",
"type": "number",
- "default": "5"
+ "default": "5",
+ "doc": "Pointer travel before a press becomes a drag.",
+ "range": "≥ 0"
},
{
"key": "lockX",
"type": "boolean",
- "default": "false"
+ "default": "false",
+ "doc": "Pin the X axis; the drag only moves in Y."
},
{
"key": "lockY",
"type": "boolean",
- "default": "false"
+ "default": "false",
+ "doc": "Pin the Y axis; the drag only moves in X."
+ },
+ {
+ "key": "constrainMin",
+ "type": "boolean",
+ "default": "false",
+ "doc": "Apply the lower bound below."
},
{
"key": "constraintMin",
- "type": "unknown",
- "default": "—"
+ "type": "Vec2",
+ "default": "(0, 0)",
+ "doc": "Lowest world position the drag may reach."
+ },
+ {
+ "key": "constrainMax",
+ "type": "boolean",
+ "default": "false",
+ "doc": "Apply the upper bound below."
},
{
"key": "constraintMax",
- "type": "unknown",
- "default": "—"
+ "type": "Vec2",
+ "default": "(0, 0)",
+ "doc": "Highest world position the drag may reach."
}
- ],
- "animatable": [
- "dragThreshold"
]
},
{
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 12e895078..43af42ae6 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5,7 +5,7 @@ Symbols: 113 public · 66 beta · 1481 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"4f073fe384c59476"
+"1df12cb48da3bf45"
```
## ANCHOR_AXES — const @experimental
@@ -2588,13 +2588,15 @@ totalDeltaWorld: { x: number; y: number; }
## Draggable — const @experimental
```
-ComponentDef<DraggableData>
+BuiltinComponentDef<DraggableData>
```
## DraggableData — interface @experimental
```
-constraintMax: { x: number; y: number; } | null
-constraintMin: { x: number; y: number; } | null
+constrainMax: boolean
+constrainMin: boolean
+constraintMax: Vec2
+constraintMin: Vec2
dragThreshold: number
enabled: boolean
lockX: boolean
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 9ffe04168..1f6662702 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5,7 +5,7 @@ Symbols: 113 public · 71 beta · 1500 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"4f073fe384c59476"
+"1df12cb48da3bf45"
```
## ANCHOR_AXES — const @experimental
@@ -2596,13 +2596,15 @@ totalDeltaWorld: { x: number; y: number; }
## Draggable — const @experimental
```
-ComponentDef<DraggableData>
+BuiltinComponentDef<DraggableData>
```
## DraggableData — interface @experimental
```
-constraintMax: { x: number; y: number; } | null
-constraintMin: { x: number; y: number; } | null
+constrainMax: boolean
+constrainMin: boolean
+constraintMax: Vec2
+constraintMin: Vec2
dragThreshold: number
enabled: boolean
lockX: boolean
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index b308b26c2..2dcce0089 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -2583,13 +2583,15 @@ totalDeltaWorld: { x: number; y: number; }
## Draggable — const @experimental
```
-ComponentDef<DraggableData>
+BuiltinComponentDef<DraggableData>
```
## DraggableData — interface @experimental
```
-constraintMax: { x: number; y: number; } | null
-constraintMin: { x: number; y: number; } | null
+constrainMax: boolean
+constrainMin: boolean
+constraintMax: Vec2
+constraintMin: Vec2
dragThreshold: number
enabled: boolean
lockX: boolean
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 846565930..5c4845ee2 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -2583,13 +2583,15 @@ totalDeltaWorld: { x: number; y: number; }
## Draggable — const @experimental
```
-ComponentDef<DraggableData>
+BuiltinComponentDef<DraggableData>
```
## DraggableData — interface @experimental
```
-constraintMax: { x: number; y: number; } | null
-constraintMin: { x: number; y: number; } | null
+constrainMax: boolean
+constrainMin: boolean
+constraintMax: Vec2
+constraintMin: Vec2
dragThreshold: number
enabled: boolean
lockX: boolean
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 3ac6157a8..ea95b3436 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -24,6 +24,7 @@ addCharacterController3D: (entity: Entity, component: CharacterController3D) =>
addChildren: (entity: Entity, component: Children) => void
addCircleCollider: (entity: Entity, component: CircleCollider) => void
addConvexCollider3D: (entity: Entity, component: ConvexCollider3D) => void
+addDraggable: (entity: Entity, component: Draggable) => void
addDragonBonesAnimation: (entity: Entity, component: DragonBonesAnimation) => void
addFlexContainer: (entity: Entity, component: FlexContainer) => void
addInteractable: (entity: Entity, component: Interactable) => void
@@ -66,6 +67,7 @@ getCharacterController3D: (entity: Entity) => CharacterController3D
getChildren: (entity: Entity) => Children
getCircleCollider: (entity: Entity) => CircleCollider
getConvexCollider3D: (entity: Entity) => ConvexCollider3D
+getDraggable: (entity: Entity) => Draggable
getDragonBonesAnimation: (entity: Entity) => DragonBonesAnimation
getFlexContainer: (entity: Entity) => FlexContainer
getInteractable: (entity: Entity) => Interactable
@@ -104,6 +106,7 @@ hasCharacterController3D: (entity: Entity) => boolean
hasChildren: (entity: Entity) => boolean
hasCircleCollider: (entity: Entity) => boolean
hasConvexCollider3D: (entity: Entity) => boolean
+hasDraggable: (entity: Entity) => boolean
hasDragonBonesAnimation: (entity: Entity) => boolean
hasFlexContainer: (entity: Entity) => boolean
hasInteractable: (entity: Entity) => boolean
@@ -142,6 +145,7 @@ removeCharacterController3D: (entity: Entity) => void
removeChildren: (entity: Entity) => void
removeCircleCollider: (entity: Entity) => void
removeConvexCollider3D: (entity: Entity) => void
+removeDraggable: (entity: Entity) => void
removeDragonBonesAnimation: (entity: Entity) => void
removeFlexContainer: (entity: Entity) => void
removeInteractable: (entity: Entity) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 85a6b4c8b..26d113c85 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -2583,13 +2583,15 @@ totalDeltaWorld: { x: number; y: number; }
## Draggable — const @experimental
```
-ComponentDef<DraggableData>
+BuiltinComponentDef<DraggableData>
```
## DraggableData — interface @experimental
```
-constraintMax: { x: number; y: number; } | null
-constraintMin: { x: number; y: number; } | null
+constrainMax: boolean
+constrainMin: boolean
+constraintMax: Vec2
+constraintMin: Vec2
dragThreshold: number
enabled: boolean
lockX: boolean
diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
index 424009502..1f6347448 100644
--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
@@ -541,6 +541,58 @@ export function createConvexCollider3DData(): ConvexCollider3DPtrData {
};
}
+export interface DraggablePtrData {
+ enabled: boolean;
+ dragThreshold: number;
+ lockX: boolean;
+ lockY: boolean;
+ constrainMin: boolean;
+ constraintMin: Vec2;
+ constrainMax: boolean;
+ constraintMax: Vec2;
+}
+
+export function fillDraggable(
+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
+ ptr: number, out: DraggablePtrData,
+): void {
+ out.enabled = u8[ptr] !== 0;
+ out.dragThreshold = f32[(ptr + 4) >> 2];
+ out.lockX = u8[ptr + 8] !== 0;
+ out.lockY = u8[ptr + 9] !== 0;
+ out.constrainMin = u8[ptr + 10] !== 0;
+ const constraintMin_ = out.constraintMin; constraintMin_.x = f32[(ptr + 12) >> 2]; constraintMin_.y = f32[((ptr + 12) >> 2) + 1];
+ out.constrainMax = u8[ptr + 20] !== 0;
+ const constraintMax_ = out.constraintMax; constraintMax_.x = f32[(ptr + 24) >> 2]; constraintMax_.y = f32[((ptr + 24) >> 2) + 1];
+}
+
+export function writeDraggable(
+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
+ ptr: number, data: DraggablePtrData,
+): void {
+ u8[ptr] = data.enabled ? 1 : 0;
+ f32[(ptr + 4) >> 2] = data.dragThreshold;
+ u8[ptr + 8] = data.lockX ? 1 : 0;
+ u8[ptr + 9] = data.lockY ? 1 : 0;
+ u8[ptr + 10] = data.constrainMin ? 1 : 0;
+ f32[(ptr + 12) >> 2] = data.constraintMin.x; f32[((ptr + 12) >> 2) + 1] = data.constraintMin.y;
+ u8[ptr + 20] = data.constrainMax ? 1 : 0;
+ f32[(ptr + 24) >> 2] = data.constraintMax.x; f32[((ptr + 24) >> 2) + 1] = data.constraintMax.y;
+}
+
+export function createDraggableData(): DraggablePtrData {
+ return {
+ enabled: false,
+ dragThreshold: 0,
+ lockX: false,
+ lockY: false,
+ constrainMin: false,
+ constraintMin: { x: 0, y: 0 },
+ constrainMax: false,
+ constraintMax: { x: 0, y: 0 },
+ };
+}
+
export interface DragonBonesAnimationPtrData {
timeScale: number;
loop: boolean;
@@ -2102,6 +2154,7 @@ export const PTR_ACCESSORS: Record<string, PtrAccessor<any>> = {
CharacterController3D: { fill: fillCharacterController3D, write: writeCharacterController3D, create: createCharacterController3DData },
CircleCollider: { fill: fillCircleCollider, write: writeCircleCollider, create: createCircleColliderData },
ConvexCollider3D: { fill: fillConvexCollider3D, write: writeConvexCollider3D, create: createConvexCollider3DData },
+ Draggable: { fill: fillDraggable, write: writeDraggable, create: createDraggableData },
DragonBonesAnimation: { fill: fillDragonBonesAnimation, write: writeDragonBonesAnimation, create: createDragonBonesAnimationData },
FlexContainer: { fill: fillFlexContainer, write: writeFlexContainer, create: createFlexContainerData },
Interactable: { fill: fillInteractable, write: writeInteractable, create: createInteractableData },
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index a8047c9c1..9c15f95c3 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -15,7 +15,7 @@ import type { Dimension, Padding } from '../wasm/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 = '4f073fe384c59476';
+export const ABI_LAYOUT_HASH = '1df12cb48da3bf45';
/**
* One asset-valued field of a component: which field, and what kind of
@@ -320,6 +320,32 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
restitution: { min: 0, max: 1 },
},
},
+ Draggable: {
+ defaults: {
+ enabled: true,
+ dragThreshold: 5,
+ lockX: false,
+ lockY: false,
+ constrainMin: false,
+ constraintMin: { x: 0, y: 0 },
+ constrainMax: false,
+ constraintMax: { x: 0, y: 0 },
+ },
+ assetFields: [],
+ entityFields: [],
+ colorFields: [],
+ animatableFields: [],
+ fields: {
+ enabled: { tooltip: "Whether this entity can be dragged at all." },
+ dragThreshold: { min: 0, unit: "px", tooltip: "Pointer travel before a press becomes a drag." },
+ lockX: { tooltip: "Pin the X axis; the drag only moves in Y.", category: "Axis" },
+ lockY: { tooltip: "Pin the Y axis; the drag only moves in X.", category: "Axis" },
+ constrainMin: { tooltip: "Apply the lower bound below.", category: "Bounds" },
+ constraintMin: { tooltip: "Lowest world position the drag may reach.", category: "Bounds" },
+ constrainMax: { tooltip: "Apply the upper bound below.", category: "Bounds" },
+ constraintMax: { tooltip: "Highest world position the drag may reach.", category: "Bounds" },
+ },
+ },
DragonBonesAnimation: {
defaults: {
skeletonPath: '',
@@ -1165,6 +1191,17 @@ export interface ConvexCollider3DData {
enabled: boolean;
}
+export interface DraggableData {
+ enabled: boolean;
+ dragThreshold: number;
+ lockX: boolean;
+ lockY: boolean;
+ constrainMin: boolean;
+ constraintMin: Vec2;
+ constrainMax: boolean;
+ constraintMax: Vec2;
+}
+
export interface DragonBonesAnimationData {
skeletonPath: string;
atlasPath: string;
diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.ts
index 0f5ab8240..fff421cb3 100644
--- a/sdk/src/ecs/component.ts
+++ b/sdk/src/ecs/component.ts
@@ -14,7 +14,7 @@ export type { AssetFieldMeta, SkeletalFieldMeta };
// `esengine` import site is unchanged; Camera/ParticleEmitter add TS-only fields by
// extending the generated base.
import type {
- TransformData, SpriteData, ShapeRendererData, Light2DData, ShadowCaster2DData,
+ TransformData, SpriteData, ShapeRendererData, Light2DData, ShadowCaster2DData, DraggableData,
CanvasData, VelocityData, ParentData, ChildrenData, SpineAnimationData, DragonBonesAnimationData,
TilemapLayerData, BitmapTextData, TrailRendererData, ParticleForceFieldData,
CameraData as CameraDataCpp, ParticleEmitterData as ParticleEmitterDataCpp,
@@ -768,7 +768,7 @@ export type ScaleMode = (typeof ScaleMode)[keyof typeof ScaleMode];
// the generated module (the single source). Adding/removing a C++ field flows here
// automatically; tsc then enforces every consumer matches.
export type {
- TransformData, SpriteData, ShapeRendererData, Light2DData, ShadowCaster2DData,
+ TransformData, SpriteData, ShapeRendererData, Light2DData, ShadowCaster2DData, DraggableData,
CanvasData, VelocityData, ParentData, ChildrenData, SpineAnimationData, DragonBonesAnimationData,
TilemapLayerData, BitmapTextData, TrailRendererData, ParticleForceFieldData,
};
@@ -860,6 +860,16 @@ export const Sprite = defineBuiltin<SpriteData>('Sprite',
metaDefaults<SpriteData>('Sprite')
);
+/**
+ * Authored drag configuration, read by the drag system. Works on a UI node and
+ * on a plain world-space sprite alike — the hit test answers for both.
+ *
+ * @experimental
+ */
+export const Draggable = defineBuiltin<DraggableData>('Draggable',
+ metaDefaults<DraggableData>('Draggable')
+);
+
// shapeType's dropdown is generated from the C++ ShapeType enum (ES_PROPERTY enum=).
export const ShapeRenderer = defineBuiltin<ShapeRendererData>('ShapeRenderer',
metaDefaults<ShapeRendererData>('ShapeRenderer')
diff --git a/sdk/src/ui/input/drag.ts b/sdk/src/ui/input/drag.ts
index 352a0567e..ac97fb92e 100644
--- a/sdk/src/ui/input/drag.ts
+++ b/sdk/src/ui/input/drag.ts
@@ -61,11 +61,13 @@ function applyConstraints(
let x = draggable.lockX ? dragState.startWorldPos.x : newX;
let y = draggable.lockY ? dragState.startWorldPos.y : newY;
- if (draggable.constraintMin !== null) {
+ // A flag rather than a null bound: zero is a usable limit, so it cannot
+ // double as "no limit".
+ if (draggable.constrainMin) {
x = Math.max(x, draggable.constraintMin.x);
y = Math.max(y, draggable.constraintMin.y);
}
- if (draggable.constraintMax !== null) {
+ if (draggable.constrainMax) {
x = Math.min(x, draggable.constraintMax.x);
y = Math.min(y, draggable.constraintMax.y);
}
diff --git a/sdk/src/ui/input/draggable.ts b/sdk/src/ui/input/draggable.ts
index f82c1091c..76f187586 100644
--- a/sdk/src/ui/input/draggable.ts
+++ b/sdk/src/ui/input/draggable.ts
@@ -7,23 +7,11 @@
*/
import { defineComponent } from '../../ecs/component';
-export interface DraggableData {
- enabled: boolean;
- dragThreshold: number;
- lockX: boolean;
- lockY: boolean;
- constraintMin: { x: number; y: number } | null;
- constraintMax: { x: number; y: number } | null;
-}
-
-export const Draggable = defineComponent<DraggableData>('Draggable', {
- enabled: true,
- dragThreshold: 5,
- lockX: false,
- lockY: false,
- constraintMin: null,
- constraintMax: null,
-});
+// An engine component now, so it reaches the inspector, the scene file and the
+// reflection table like any other, and its defaults come from the C++ struct.
+// Defined with the rest of them; re-exported here so this stays the drag module.
+export { Draggable } from '../../ecs/component';
+export type { DraggableData } from '../../ecs/component';
export interface DragStateData {
isDragging: boolean;
@@ -35,7 +23,7 @@ export interface DragStateData {
}
// Per-frame drag state written by the drag system — never authored, never
-// persisted.
+// persisted, so it stays a script component and never crosses the wasm boundary.
export const DragState = defineComponent<DragStateData>('DragState', {
isDragging: false,
startWorldPos: { x: 0, y: 0 },
diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.ts
index 978ec47ca..eb4706211 100644
--- a/sdk/src/wasm/ptrLayouts.generated.ts
+++ b/sdk/src/wasm/ptrLayouts.generated.ts
@@ -160,6 +160,19 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
{ name: 'enabled', type: 'bool', offset: 13 },
],
},
+ Draggable: {
+ ptrFn: 'getDraggablePtr',
+ fields: [
+ { name: 'enabled', type: 'bool', offset: 0 },
+ { name: 'dragThreshold', type: 'f32', offset: 4 },
+ { name: 'lockX', type: 'bool', offset: 8 },
+ { name: 'lockY', type: 'bool', offset: 9 },
+ { name: 'constrainMin', type: 'bool', offset: 10 },
+ { name: 'constraintMin', type: 'vec2', offset: 12 },
+ { name: 'constrainMax', type: 'bool', offset: 20 },
+ { name: 'constraintMax', type: 'vec2', offset: 24 },
+ ],
+ },
DragonBonesAnimation: {
ptrFn: 'getDragonBonesAnimationPtr',
fields: [
diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.ts
index df349910d..3837de87f 100644
--- a/sdk/src/wasm/wasm.generated.ts
+++ b/sdk/src/wasm/wasm.generated.ts
@@ -336,6 +336,17 @@ export interface ConvexCollider3D {
enabled: boolean;
}
+export interface Draggable {
+ enabled: boolean;
+ dragThreshold: number;
+ lockX: boolean;
+ lockY: boolean;
+ constrainMin: boolean;
+ constraintMin: Vec2;
+ constrainMax: boolean;
+ constraintMax: Vec2;
+}
+
export interface DragonBonesAnimation {
skeletonPath: string;
atlasPath: string;
@@ -739,6 +750,10 @@ export interface Registry {
getConvexCollider3D(entity: Entity): ConvexCollider3D;
addConvexCollider3D(entity: Entity, component: ConvexCollider3D): void;
removeConvexCollider3D(entity: Entity): void;
+ hasDraggable(entity: Entity): boolean;
+ getDraggable(entity: Entity): Draggable;
+ addDraggable(entity: Entity, component: Draggable): void;
+ removeDraggable(entity: Entity): void;
hasDragonBonesAnimation(entity: Entity): boolean;
getDragonBonesAnimation(entity: Entity): DragonBonesAnimation;
addDragonBonesAnimation(entity: Entity, component: DragonBonesAnimation): void;
@@ -872,6 +887,7 @@ export interface ESEngineModule {
Children: new () => Children;
CircleCollider: new () => CircleCollider;
ConvexCollider3D: new () => ConvexCollider3D;
+ Draggable: new () => Draggable;
DragonBonesAnimation: new () => DragonBonesAnimation;
FlexContainer: new () => FlexContainer;
Interactable: new () => Interactable;
diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
index 21e96e47c..c68035153 100644
--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
@@ -156,6 +156,40 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho
"tooltip": "How the canvas adapts the design resolution to the screen.",
},
},
+ "Draggable": {
+ "constrainMax": {
+ "category": "Bounds",
+ "tooltip": "Apply the upper bound below.",
+ },
+ "constrainMin": {
+ "category": "Bounds",
+ "tooltip": "Apply the lower bound below.",
+ },
+ "constraintMax": {
+ "category": "Bounds",
+ "tooltip": "Highest world position the drag may reach.",
+ },
+ "constraintMin": {
+ "category": "Bounds",
+ "tooltip": "Lowest world position the drag may reach.",
+ },
+ "dragThreshold": {
+ "min": 0,
+ "tooltip": "Pointer travel before a press becomes a drag.",
+ "unit": "px",
+ },
+ "enabled": {
+ "tooltip": "Whether this entity can be dragged at all.",
+ },
+ "lockX": {
+ "category": "Axis",
+ "tooltip": "Pin the X axis; the drag only moves in Y.",
+ },
+ "lockY": {
+ "category": "Axis",
+ "tooltip": "Pin the Y axis; the drag only moves in X.",
+ },
+ },
"DragonBonesAnimation": {
"animation": {
"enumSource": "dragonbonesAnimations",
diff --git a/sdk/tests/ui-behavior.test.ts b/sdk/tests/ui-behavior.test.ts
index ae13c2ee1..7f6d54db6 100644
--- a/sdk/tests/ui-behavior.test.ts
+++ b/sdk/tests/ui-behavior.test.ts
@@ -25,8 +25,10 @@ describe('ui2 behavior components', () => {
expect(Focusable._name).toBe('Focusable');
});
- it('Draggable is a user component (ts-side)', () => {
- expect(Draggable._builtin).toBe(false);
+ it('Draggable is an engine component', () => {
+ // It sank into C++ so it reaches the inspector and the scene file;
+ // this asserts the module still re-exports the same name.
+ expect(Draggable._builtin).toBe(true);
expect(Draggable._name).toBe('Draggable');
});
});
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index 488e6cdce..b4f011f6f 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 11f30170ee77e18b
+ * @schema_hash 96c16f9290122248
*/
-#define ES_EDITOR_API_SCHEMA_HASH "11f30170ee77e18b"
+#define ES_EDITOR_API_SCHEMA_HASH "96c16f9290122248"
#include <emscripten/bind.h>
#include <string>
@@ -15,6 +15,7 @@
#include "../ecs/components/Camera.hpp"
#include "../ecs/components/Canvas.hpp"
#include "../ecs/components/Collider.hpp"
+#include "../ecs/components/Draggable.hpp"
#include "../ecs/components/DragonBonesAnimation.hpp"
#include "../ecs/components/FlexContainer.hpp"
#include "../ecs/components/Hierarchy.hpp"
@@ -69,6 +70,7 @@ std::vector<std::string> editor_getComponentNames() {
"Children",
"CircleCollider",
"ConvexCollider3D",
+ "Draggable",
"DragonBonesAnimation",
"FlexContainer",
"Interactable",
@@ -243,6 +245,19 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"isSensor","type":"bool","group":"ConvexCollider3D"},
{"key":"enabled","type":"bool","group":"ConvexCollider3D"}
])JSON";
+ } else if (name == "Draggable") {
+ return R"JSON([
+ {"key":"enabled","type":"bool","group":"Draggable"},
+ {"key":"dragThreshold","type":"float","group":"Draggable"},
+ {"key":"lockX","type":"bool","group":"Draggable"},
+ {"key":"lockY","type":"bool","group":"Draggable"},
+ {"key":"constrainMin","type":"bool","group":"Draggable"},
+ {"key":"constraintMin.x","type":"float","group":"Draggable"},
+ {"key":"constraintMin.y","type":"float","group":"Draggable"},
+ {"key":"constrainMax","type":"bool","group":"Draggable"},
+ {"key":"constraintMax.x","type":"float","group":"Draggable"},
+ {"key":"constraintMax.y","type":"float","group":"Draggable"}
+ ])JSON";
} else if (name == "DragonBonesAnimation") {
return R"JSON([
{"key":"skeletonPath","type":"asset","group":"DragonBonesAnimation"},
@@ -723,6 +738,9 @@ bool editor_addComponent(Registry& reg, u32 e, const std::string& name) {
} else if (name == "ConvexCollider3D") {
if (!reg.has<esengine::ecs::ConvexCollider3D>(entity)) reg.emplace<esengine::ecs::ConvexCollider3D>(entity);
return true;
+ } else if (name == "Draggable") {
+ if (!reg.has<esengine::ecs::Draggable>(entity)) reg.emplace<esengine::ecs::Draggable>(entity);
+ return true;
} else if (name == "DragonBonesAnimation") {
if (!reg.has<esengine::ecs::DragonBonesAnimation>(entity)) reg.emplace<esengine::ecs::DragonBonesAnimation>(entity);
return true;
@@ -836,6 +854,8 @@ bool editor_removeComponent(Registry& reg, u32 e, const std::string& name) {
if (reg.has<esengine::ecs::CircleCollider>(entity)) { reg.remove<esengine::ecs::CircleCollider>(entity); return true; }
} else if (name == "ConvexCollider3D") {
if (reg.has<esengine::ecs::ConvexCollider3D>(entity)) { reg.remove<esengine::ecs::ConvexCollider3D>(entity); return true; }
+ } else if (name == "Draggable") {
+ if (reg.has<esengine::ecs::Draggable>(entity)) { reg.remove<esengine::ecs::Draggable>(entity); return true; }
} else if (name == "DragonBonesAnimation") {
if (reg.has<esengine::ecs::DragonBonesAnimation>(entity)) { reg.remove<esengine::ecs::DragonBonesAnimation>(entity); return true; }
} else if (name == "FlexContainer") {
@@ -908,6 +928,7 @@ bool editor_hasComponent(Registry& reg, u32 e, const std::string& name) {
if (name == "Children") return reg.has<esengine::ecs::Children>(entity);
if (name == "CircleCollider") return reg.has<esengine::ecs::CircleCollider>(entity);
if (name == "ConvexCollider3D") return reg.has<esengine::ecs::ConvexCollider3D>(entity);
+ if (name == "Draggable") return reg.has<esengine::ecs::Draggable>(entity);
if (name == "DragonBonesAnimation") return reg.has<esengine::ecs::DragonBonesAnimation>(entity);
if (name == "FlexContainer") return reg.has<esengine::ecs::FlexContainer>(entity);
if (name == "Interactable") return reg.has<esengine::ecs::Interactable>(entity);
@@ -955,6 +976,7 @@ std::vector<std::string> editor_getComponents(Registry& reg, u32 e) {
if (reg.has<esengine::ecs::Children>(entity)) result.push_back("Children");
if (reg.has<esengine::ecs::CircleCollider>(entity)) result.push_back("CircleCollider");
if (reg.has<esengine::ecs::ConvexCollider3D>(entity)) result.push_back("ConvexCollider3D");
+ if (reg.has<esengine::ecs::Draggable>(entity)) result.push_back("Draggable");
if (reg.has<esengine::ecs::DragonBonesAnimation>(entity)) result.push_back("DragonBonesAnimation");
if (reg.has<esengine::ecs::FlexContainer>(entity)) result.push_back("FlexContainer");
if (reg.has<esengine::ecs::Interactable>(entity)) result.push_back("Interactable");
@@ -1110,6 +1132,16 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::s
else if (field == "restitution") { c.restitution = value; }
else { return false; }
return true;
+ } else if (comp == "Draggable") {
+ if (!reg.has<esengine::ecs::Draggable>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::Draggable>(entity);
+ if (field == "dragThreshold") { c.dragThreshold = value; }
+ else if (field == "constraintMin.x") { c.constraintMin.x = value; }
+ else if (field == "constraintMin.y") { c.constraintMin.y = value; }
+ else if (field == "constraintMax.x") { c.constraintMax.x = value; }
+ else if (field == "constraintMax.y") { c.constraintMax.y = value; }
+ else { return false; }
+ return true;
} else if (comp == "DragonBonesAnimation") {
if (!reg.has<esengine::ecs::DragonBonesAnimation>(entity)) return false;
auto& c = reg.get<esengine::ecs::DragonBonesAnimation>(entity);
@@ -1568,6 +1600,14 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::st
const auto& c = reg.get<esengine::ecs::ConvexCollider3D>(entity);
if (field == "friction") { return c.friction; }
else if (field == "restitution") { return c.restitution; }
+ } else if (comp == "Draggable") {
+ if (!reg.has<esengine::ecs::Draggable>(entity)) return 0.0f;
+ const auto& c = reg.get<esengine::ecs::Draggable>(entity);
+ if (field == "dragThreshold") { return c.dragThreshold; }
+ else if (field == "constraintMin.x") { return c.constraintMin.x; }
+ else if (field == "constraintMin.y") { return c.constraintMin.y; }
+ else if (field == "constraintMax.x") { return c.constraintMax.x; }
+ else if (field == "constraintMax.y") { return c.constraintMax.y; }
} else if (comp == "DragonBonesAnimation") {
if (!reg.has<esengine::ecs::DragonBonesAnimation>(entity)) return 0.0f;
const auto& c = reg.get<esengine::ecs::DragonBonesAnimation>(entity);
@@ -2342,6 +2382,16 @@ bool editor_setBool(Registry& reg, u32 e, const std::string& comp, const std::st
else if (field == "enabled") { c.enabled = value; }
else { return false; }
return true;
+ } else if (comp == "Draggable") {
+ if (!reg.has<esengine::ecs::Draggable>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::Draggable>(entity);
+ if (field == "enabled") { c.enabled = value; }
+ else if (field == "lockX") { c.lockX = value; }
+ else if (field == "lockY") { c.lockY = value; }
+ else if (field == "constrainMin") { c.constrainMin = value; }
+ else if (field == "constrainMax") { c.constrainMax = value; }
+ else { return false; }
+ return true;
} else if (comp == "DragonBonesAnimation") {
if (!reg.has<esengine::ecs::DragonBonesAnimation>(entity)) return false;
auto& c = reg.get<esengine::ecs::DragonBonesAnimation>(entity);
@@ -2558,6 +2608,14 @@ bool editor_getBool(Registry& reg, u32 e, const std::string& comp, const std::st
const auto& c = reg.get<esengine::ecs::ConvexCollider3D>(entity);
if (field == "isSensor") { return c.isSensor; }
else if (field == "enabled") { return c.enabled; }
+ } else if (comp == "Draggable") {
+ if (!reg.has<esengine::ecs::Draggable>(entity)) return false;
+ const auto& c = reg.get<esengine::ecs::Draggable>(entity);
+ if (field == "enabled") { return c.enabled; }
+ else if (field == "lockX") { return c.lockX; }
+ else if (field == "lockY") { return c.lockY; }
+ else if (field == "constrainMin") { return c.constrainMin; }
+ else if (field == "constrainMax") { return c.constrainMax; }
} else if (comp == "DragonBonesAnimation") {
if (!reg.has<esengine::ecs::DragonBonesAnimation>(entity)) return false;
const auto& c = reg.get<esengine::ecs::DragonBonesAnimation>(entity);
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 6cd61e04b..f09b2f385 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -15,6 +15,7 @@
#include "../ecs/components/Camera.hpp"
#include "../ecs/components/Canvas.hpp"
#include "../ecs/components/Collider.hpp"
+#include "../ecs/components/Draggable.hpp"
#include "../ecs/components/DragonBonesAnimation.hpp"
#include "../ecs/components/FlexContainer.hpp"
#include "../ecs/components/Hierarchy.hpp"
@@ -1401,6 +1402,16 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
.field("isSensor", &ConvexCollider3DJS::isSensor)
.field("enabled", &ConvexCollider3DJS::enabled);
+ value_object<esengine::ecs::Draggable>("Draggable")
+ .field("enabled", &esengine::ecs::Draggable::enabled)
+ .field("dragThreshold", &esengine::ecs::Draggable::dragThreshold)
+ .field("lockX", &esengine::ecs::Draggable::lockX)
+ .field("lockY", &esengine::ecs::Draggable::lockY)
+ .field("constrainMin", &esengine::ecs::Draggable::constrainMin)
+ .field("constraintMin", &esengine::ecs::Draggable::constraintMin)
+ .field("constrainMax", &esengine::ecs::Draggable::constrainMax)
+ .field("constraintMax", &esengine::ecs::Draggable::constraintMax);
+
value_object<esengine::ecs::DragonBonesAnimation>("DragonBonesAnimation")
.field("skeletonPath", &esengine::ecs::DragonBonesAnimation::skeletonPath)
.field("atlasPath", &esengine::ecs::DragonBonesAnimation::atlasPath)
@@ -1993,6 +2004,27 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {
r.remove<esengine::ecs::ConvexCollider3D>(entity);
}))
+ // Draggable
+ .function("hasDraggable", optional_override([](Registry& r, u32 e) {
+ return r.has<esengine::ecs::Draggable>(static_cast<Entity>(e));
+ }))
+ .function("getDraggable", optional_override([](Registry& r, u32 e) -> esengine::ecs::Draggable& {
+ auto entity = static_cast<Entity>(e);
+ static esengine::ecs::Draggable s_dummy{};
+ if (!r.valid(entity) || !r.has<esengine::ecs::Draggable>(entity)) return s_dummy;
+ return r.get<esengine::ecs::Draggable>(entity);
+ }), allow_raw_pointers())
+ .function("addDraggable", optional_override([](Registry& r, u32 e, const esengine::ecs::Draggable& c) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity)) return;
+ r.emplaceOrReplace<esengine::ecs::Draggable>(entity, c);
+ }))
+ .function("removeDraggable", optional_override([](Registry& r, u32 e) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity) || !r.has<esengine::ecs::Draggable>(entity)) return;
+ r.remove<esengine::ecs::Draggable>(entity);
+ }))
+
// DragonBonesAnimation
.function("hasDragonBonesAnimation", optional_override([](Registry& r, u32 e) {
return r.has<esengine::ecs::DragonBonesAnimation>(static_cast<Entity>(e));
@@ -2633,6 +2665,7 @@ emscripten::val esengineGetBuiltinComponentNames() {
arr.set(i++, val(std::string("Children")));
arr.set(i++, val(std::string("CircleCollider")));
arr.set(i++, val(std::string("ConvexCollider3D")));
+ arr.set(i++, val(std::string("Draggable")));
arr.set(i++, val(std::string("DragonBonesAnimation")));
arr.set(i++, val(std::string("FlexContainer")));
arr.set(i++, val(std::string("Interactable")));
@@ -2757,6 +2790,14 @@ static_assert(offsetof(esengine::ecs::ConvexCollider3D, friction) == 4, "ABI off
static_assert(offsetof(esengine::ecs::ConvexCollider3D, restitution) == 8, "ABI offset drift: esengine::ecs::ConvexCollider3D.restitution (EHT expected 8)");
static_assert(offsetof(esengine::ecs::ConvexCollider3D, isSensor) == 12, "ABI offset drift: esengine::ecs::ConvexCollider3D.isSensor (EHT expected 12)");
static_assert(offsetof(esengine::ecs::ConvexCollider3D, enabled) == 13, "ABI offset drift: esengine::ecs::ConvexCollider3D.enabled (EHT expected 13)");
+static_assert(offsetof(esengine::ecs::Draggable, enabled) == 0, "ABI offset drift: esengine::ecs::Draggable.enabled (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::Draggable, dragThreshold) == 4, "ABI offset drift: esengine::ecs::Draggable.dragThreshold (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::Draggable, lockX) == 8, "ABI offset drift: esengine::ecs::Draggable.lockX (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::Draggable, lockY) == 9, "ABI offset drift: esengine::ecs::Draggable.lockY (EHT expected 9)");
+static_assert(offsetof(esengine::ecs::Draggable, constrainMin) == 10, "ABI offset drift: esengine::ecs::Draggable.constrainMin (EHT expected 10)");
+static_assert(offsetof(esengine::ecs::Draggable, constraintMin) == 12, "ABI offset drift: esengine::ecs::Draggable.constraintMin (EHT expected 12)");
+static_assert(offsetof(esengine::ecs::Draggable, constrainMax) == 20, "ABI offset drift: esengine::ecs::Draggable.constrainMax (EHT expected 20)");
+static_assert(offsetof(esengine::ecs::Draggable, constraintMax) == 24, "ABI offset drift: esengine::ecs::Draggable.constraintMax (EHT expected 24)");
static_assert(offsetof(esengine::ecs::DragonBonesAnimation, timeScale) == 48, "ABI offset drift: esengine::ecs::DragonBonesAnimation.timeScale (EHT expected 48)");
static_assert(offsetof(esengine::ecs::DragonBonesAnimation, loop) == 52, "ABI offset drift: esengine::ecs::DragonBonesAnimation.loop (EHT expected 52)");
static_assert(offsetof(esengine::ecs::DragonBonesAnimation, playing) == 53, "ABI offset drift: esengine::ecs::DragonBonesAnimation.playing (EHT expected 53)");
@@ -3024,7 +3065,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "4f073fe384c59476";
+static const char* kEsAbiLayoutHash = "1df12cb48da3bf45";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/ecs/components/Draggable.hpp b/src/esengine/ecs/components/Draggable.hpp
new file mode 100644
index 000000000..da4b5651e
--- /dev/null
+++ b/src/esengine/ecs/components/Draggable.hpp
@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Draggable.hpp
+ * @brief Pointer-drag configuration.
+ * @details Authored per entity; the drag system reads it and writes DragState.
+ * Works on a UI node and on a plain world-space sprite alike — the hit
+ * test answers for both.
+ */
+#pragma once
+
+#include "../../core/Types.hpp"
+#include "../../core/Reflection.hpp"
+#include "../../math/Math.hpp"
+
+namespace esengine::ecs {
+
+// Not marked public yet: it has just become an engine component and its
+// bounds fields changed shape in doing so. It earns that once it has held.
+ES_COMPONENT()
+struct Draggable {
+ ES_PROPERTY(tooltip="Whether this entity can be dragged at all.")
+ bool enabled{true};
+
+ // Screen pixels the pointer must travel before a press becomes a drag. Below
+ // it the press is still a click, which is what makes a draggable button work.
+ ES_PROPERTY(min=0, unit=px, tooltip="Pointer travel before a press becomes a drag.")
+ f32 dragThreshold{5.0f};
+
+ ES_PROPERTY(category=Axis, tooltip="Pin the X axis; the drag only moves in Y.")
+ bool lockX{false};
+
+ ES_PROPERTY(category=Axis, tooltip="Pin the Y axis; the drag only moves in X.")
+ bool lockY{false};
+
+ // A bound and a flag rather than an optional value: zero is a perfectly good
+ // limit, so it cannot double as "no limit".
+ ES_PROPERTY(category=Bounds, tooltip="Apply the lower bound below.")
+ bool constrainMin{false};
+
+ ES_PROPERTY(category=Bounds, tooltip="Lowest world position the drag may reach.")
+ glm::vec2 constraintMin{0.0f, 0.0f};
+
+ ES_PROPERTY(category=Bounds, tooltip="Apply the upper bound below.")
+ bool constrainMax{false};
+
+ ES_PROPERTY(category=Bounds, tooltip="Highest world position the drag may reach.")
+ glm::vec2 constraintMax{0.0f, 0.0f};
+};
+
+} // namespace esengine::ecs