DragDropManager lets the player drag elements with the mouse or a finger, and drop them onto drop zones. Use it for inventories, matching puzzles and card games.
Draggables and drop zones are matched by groups: a drop zone only accepts draggables whose group it lists.
| Member | Description |
|---|---|
registerDraggable() |
Makes an element draggable |
registerDropZone() |
Makes an element accept drops |
registerScrollView() |
Sets up a scrollable element |
registerDraggable
DragDropManager.registerDraggable(el: HTMLElement, options?: { dragGroup?: string; dragReturnOnInvalidDrop?: boolean }): void
Makes an element draggable.
| Parameter | Type | Default | Description |
|---|---|---|---|
el |
HTMLElement |
The element to drag | |
options.dragGroup |
string |
"" |
The group it belongs to |
options.dragReturnOnInvalidDrop |
boolean |
true |
Jump back to where it started if it's dropped outside an accepting drop zone |
How it works
- The element moves by changing its
leftandtopstyle. - It's raised above the elements around it while it's dragged.
- It stays where it's dropped on a drop zone. Move it yourself in the zone's
onDropif you want it to snap into place.
Dragging out of scroll views
An element inside a scroll view, a Hidden-overflow container, or a Row, Column or Grid layout is lifted out when you start dragging it. It moves to the top of the scene so it isn't cut off and can be dropped anywhere, for example from an inventory list onto a character. An empty gap of the same size keeps its place in the list.
- If it's dropped on a drop zone, the gap closes and the element stays where it was dropped, now outside the list. Move it, hide it or put it back in the zone's
onDrop. - If it's dropped somewhere else and dragReturnOnInvalidDrop is on, it goes back into its old place in the list.
- If it's dropped somewhere else and dragReturnOnInvalidDrop is off, it stays where it was dropped and the gap closes.
A click without dragging leaves it where it is.
Example
onStart() {
for (const gem of [this.dom.gem_red, this.dom.gem_blue, this.dom.gem_green]) {
DragDropManager.registerDraggable(gem, { dragGroup: "gem" });
}
},
registerDropZone
DragDropManager.registerDropZone(el: HTMLElement, options?: {
acceptGroups?: string;
onDragEnter?: (details: DragDropDetails) => void;
onDragExit?: (details: DragDropDetails) => void;
onDrop?: (details: DragDropDetails) => void;
}): void
Makes an element accept dropped elements.
| Parameter | Type | Default | Description |
|---|---|---|---|
el |
HTMLElement |
The drop zone | |
options.acceptGroups |
string |
Every group | The groups it accepts, separated by commas, such as "gem, coin" |
options.onDragEnter |
(details) => void |
None | Called when an accepted element is dragged onto it |
options.onDragExit |
(details) => void |
None | Called when that element is dragged off it again without being dropped |
options.onDrop |
(details) => void |
None | Called when an accepted element is dropped on it |
Each handler receives a DragDropDetails object with:
| Field | Description |
|---|---|
el |
The element being dragged |
zoneEl |
The drop zone |
dragGroup |
The dragged element's group |
How it works
- An element is dropped on the accepting zone under the pointer when it's released. The dragged element itself is ignored, so it doesn't hide the zone underneath it.
- After
onDragEnter, a zone always gets eitheronDragExitoronDrop, never both. If the drag is interrupted, for example by the system cancelling a touch, the zone getsonDragExit. - Zones only react to groups they accept. If zones are inside each other, the innermost zone that accepts the element gets it.
- Calling it again on the same element replaces its options.
- While an accepted element is over a zone, the zone has the
mm-dragdrop-hoverclass. Style it with a.mm-dragdrop-hoverrule in your project's CSS, or useonDragEnterandonDragExitfor anything more.
Example
onStart() {
DragDropManager.registerDropZone(this.dom.chest, {
acceptGroups: "gem",
onDragEnter: ({ zoneEl }) => {
zoneEl.setState("open"); // the chest opens while a gem is held over it
},
onDragExit: ({ zoneEl }) => {
zoneEl.setState("closed");
},
onDrop: ({ el, zoneEl }) => {
el.hide(); // the gem goes into the chest
zoneEl.setState("sparkle"); // the chest node has a "sparkle" state
Store.Set("gems", Store.Get("gems", 0) + 1);
},
});
},
registerScrollView
DragDropManager.registerScrollView(el: HTMLElement, options?: {
axis?: "x" | "y" | "both";
dragToScroll?: boolean;
snap?: "" | "start" | "center";
}): void
Sets up an element that scrolls. Containers with a Scroll overflow are set up automatically, so you only need this for elements you create in code. The element needs its own scrolling CSS, such as overflow-y: auto.
| Parameter | Type | Default | Description |
|---|---|---|---|
el |
HTMLElement |
The element that scrolls | |
options.axis |
"x" | "y" | "both" |
"y" |
Which way it scrolls |
options.dragToScroll |
boolean |
true |
Let the mouse drag it to scroll |
options.snap |
"" | "start" | "center" |
"" |
After a mouse drag, settle with a child lined up at the start or in the middle. Use it with CSS scroll-snap-type so the wheel and touch snap too |
It adds scrollToItem(), scrollToStart() and scrollToEnd() to the element, as described on the Container page.
How it works
- Touch scrolls the way it normally does. Drag to scroll is for the mouse and pens.
- A drag only starts after the pointer moves a few pixels, so short clicks still press buttons.
- Dragging that starts on a draggable element, a text field or a slider doesn't scroll.
In the Scene Editor
You can set this up without code. Turn on Draggable on an image and give it a Drag Group. Then turn on Is Drop Zone on a container and fill in its fields:
- Accept Groups: the groups it accepts, separated by commas.
- On Drag Enter, On Drag Exit and On Drop: the names of methods in the scene's script to call.
Each method receives the DragDropDetails object first, followed by any arguments you write after the name. For example, onGemDrop("red") calls onGemDrop(details, "red"). The button next to each field adds the method to the script if it doesn't exist yet, as onGemDrop(drag: DragDropDetails) in a TypeScript scene.
onGemDrop(drag) {
drag.el.hide();
log(`A ${drag.dragGroup} went into the chest`);
},