Topic: MODULE: [UI] DragDrop 1.0.0: helps to drag things around your AGS game!

[Crimson Wizard]

DOWNLOAD DragDrop 1.0.0 MODULE
DOWNLOAD DragDropCommon 1.0.0 MODULE
DOWNLOAD Demo game (needs AGS 3.2.1 or higher)

Latest source code may be found here
Git cloning address: https://ivan-mogilko@bitbucket.org/ivan-mogilko/ags-script-modules.git
Demo Game(s) cloning address: https://ivan-mogilko@bitbucket.org/ivan-mogilko/ags-script-demos.git

Module supports AGS 3.2.1 and higher.



DragDrop module implements abstract drag-and-drop functionality. It does not drag and drop any particular item on its own, but it provides means for easily scripting such actions inside your game, or write advanced d'n'd script modules for which it serves as a functional base.

Here it is accompanied by DragDropCommon module, which lets you drag and drop built-in AGS objects, such as: characters, room objects, guis and gui controls, and inventory items. DragDropCommon module requires DragDrop, and may serve a good example of its use.


DragDrop API may be confusing at first, and requires expanded explanation. For those who want a quick test of its ability, here is a quick example of using DragDropCommon in your game:

1. Add both DragDrop and DragDropCommon modules to your game. DragDrop should be higher in the module list, or your game won't compile.
2. In one of the rooms add following code to the "After Fade-in" event handler:

Code: Adventure Game Studio

1.   DragDrop.Enabled = true;
2.   DragDropCommon.ModeEnabled[eDragDropCharacter] = true;
3.   DragDropCommon.ModeEnabled[eDragDropRoomObject] = true;
4.   DragDropCommon.DragMove = eDDCmnMoveSelf;
5.  

3. Just in case, add following code to the "Leave room" event handler:

Code: Adventure Game Studio

1.   DragDropCommon.DisableAllModes();
2.   DragDrop.Enabled = false;
3.  

4. That's it! Now you can drag and drop characters and objects with your mouse in that room. Have fun .



Using DragDrop

DragDrop is an abstract functionality module, which means that it does not drag any objects by itself. Instead, it tracks mouse movement and related button state, and tells you when the important events take place. It is up to you to handle such events correspondingly: provide description of a custom draggable object, update custom object's position as it is being dragged around, etc.
A number of things in DragDrop may be automated, but almost everything may also be customized and overriden. You will need a good understanding of the concepts to make it work best for your game.


Basic terms
Draggable object - this is something that can be dragged to another position.
Hooking - is an event of "grappling up" the draggable object to move it somewhere.
Hook Key - is the key or mouse button that should be pressed down to hook an object.
Dragging - is the process of moving hooked object around while the hook key is down; NOTE: it does not have to literally move an actual object on screen, it may be a "pseudo-object", an object link, etc.
Drop - the event of putting an object onto new position; usually occurs when the hook key was released, but may also be triggered by script command.



Signal properties
Since AGS does not support custom callbacks (calling your own functions when something happened in script module), DragDrop tells you about immediate events by setting certain signal properties. These properties are easily distinguished by "Evt*" prefix.
The positive values on signal properties only set for 1 game tick (update), and are reset immediately afterwards. They literally mean that the event has just occured, and you should react to that. The next tick they will be reset until some event occurs again.
You will have to check these properties periodically, in the "repeatedly_execute" or "repeatedly_execute_always" functions of GlobalScript or your own custom script to know when the related events occur.


Drag-and-drop phases
Module distinguishes several phases (steps) in drag-n-drop action. Changing from one phase to another is followed by signalling an event (as explained in Signal properties section). The phase may be changed automatically, when certain conditions are met, or by calling particular module function. Latter lets user to customize and control DragDrop behavior.

The following table lists all phases, as well as corresponding events. "Automation" column names properties that regulate default/automatic passing of the phase, while "User command" column lists the functions that must be called to manually pass to the next phase, skipping or overriding automation.
Note that some of the commands won't work unless the module is in particular phase. For example, you cannot order module to drop an object if no object is dragged yet.

Phase	Explanation	Event	Automation	User command
Idle	At this phase module waits until the hook key is pressed down.	---	DefaultHookKey, DefaultHookMouseButton, AutoTrackHookKey properties	HookKeyDown()
Hooking object	Module expects to grapple an object under mouse cursor.	EvtWantObject	---	HookObject()
Waiting for drag	After object was hooked, module expects certain conditions to complete before dragging may start, such as minimal mouse move distance or time hook key was pressed down.	EvtObjectHooked	DragMinDistance, DragMinTime properties	HookKeyUp(), Drop(), DropAt(), Revert()
Dragging	The object is being dragged around. It takes releasing hook key or explicit command for a dragging to stop.	EvtDragStarted	AutoTrackHookKey property	HookKeyUp(), Drop(), DropAt(), Revert()
Dropping	When the hook key is released, module notifies user that the object is about to be dropped. User may rely on default action, or call a related command.	EvtWantDrop	DefaultUnhookAction property	Drop(), DropAt(), Revert()
After dropped	This is one extra tick before returning to idle mode, when the user script may still access information on dropped object and perform some final processing on its side.	EvtDropped	---	---

Practical use in detail

Whether to automate or manually control particular phases - this depends on what effect you are trying to achieve.

Letting module trigger object hook and dragging is done by assigning a hook key using either DragDrop.DefaultHookKey or DragDrop.DefaultHookMouseButton properties. DragDrop.AutoTrackHookKey property should also be set as 'true'.

If you want to use several hook keys, for example - each key determining its own custom drag'n'drop mode - then you should probably disable default hook key by setting both properties (DefaultHookKey and DefaultHookMouseButton) to zero. In your own script call DragDrop.HookKeyDown() function, providing key code or mouse button code.

You may still keep AutoTrackHookKey enabled so that the module was automatically detecting when the hook key you defined is released.

If you just do not want the module to be affected by actual key/mouse clicks at all, then you should set AutoTrackHookKey to 'false'.
Also, HookKeyDown() does not need to get a real key code. You may pass some imaginary key code. Since the module writes that key code down and lets you read it while the object is being dragged, that code could later be used in your own script as a reference.
If AutoTrackHookKey is disabled, you will have to call DragDrop.HookKeyUp() in time to tell the module that the hook key was released (whether that was a real or not real key).

In any case you must provide your own object data upon EvtWantObject signal. You do so by calling DragDrop.HookObject() function. This function basically tells the module some abstract information about the dragged object:

Code: Adventure Game Studio

1. static void  HookObject(int user_mode, int obj_x, int obj_y, int tag = 0, String stag = 0);
2.  

'User_mode' is a custom value that determines a drag'n'drop mode. Pass the value you want - since you will be the one who needs it - or just any random number, except for 0, which means "no mode" for the module.
'Obj_x' and 'obj_y' are object's coordinates that define its position. These should be the values that you may rely upon in your own script. As for the module itself, it does not care if these are sensible or related to an actual item on screen at all. However the module remembers a distance between mouse cursor and provided object coordinates, and keeps this distance same when calculating new object position after mouse drag starts. This calculated position may be read using DragDrop.ObjectX and DragDrop.ObjectY properties.
The 'tag' and 'stag' parameters are user-defined values that could be useful if you need to identify the dragged object somehow. They are readable using DragDrop.ObjectTag and DragDrop.ObjectSTag properties as long as the object is being dragged, and right after it was dropped.

Remember, that although the dragged object's position is updated properly by the module, it does not move anything itself. You should do that in your own script, using ObjectX and ObjectY values as a reference. Whether you actually move something on screen, or just check where object was supposed to move, is completely up to you.

When getting EvtWantDrop signal you have a chance to decide whether to let object drop at its current position, drop somewhere else, or completely revert back to initial position. This can be done by calling DragDrop.Drop(), DragDrop.DropAt() or DragDrop.Revert().
If you do not call anything at this time, the module will drop or revert depending on the DragDrop.DefaultUnhookAction setting.

In either case, module will update ObjectX and ObjectY values last time, and set EvtDropped signal, which means that the object is not going anywhere anymore (at least not until next drag). You may use this moment as a last chance to update your real object. For example, you may finally assign its position to ObjectX and ObjectY values.



DragDrop API

Following are properties and functions of the DragDrop class, that are exposed for use in your scripts:

Code: Adventure Game Studio

1. enum DragDropMode
2. {
3.   eDragDropNone = 0
4. };
5.  
6. // An action to do when the hook key is released
7. enum DragDropUnhookAction
8. {
9.   eDDUnhookDrop,  // drop the dragged object at current cursor position
10.   eDDUnhookRevert // revert the dragged object to its initial position
11. };
12.  
13. struct DragDrop
14. {
15.   ///////////////////////////////////////////////////////////////////////////
16.   //
17.   // Setting up
18.   // ------------------------------------------------------------------------
19.   // Functions and properties meant to configure the drag'n'drop behavior.
20.   //
21.   ///////////////////////////////////////////////////////////////////////////
22.  
23.   /// Enables or disables DragDrop work, without cancelling any settings
24.   import static attribute bool        Enabled;
25.  
26.   /// Get/set default hook key
27.   import static attribute eKeyCode    DefaultHookKey;
28.   /// Get/set default hook mouse button
29.   import static attribute MouseButton DefaultHookMouseButton;
30.   /// Get/set minimal number of pixels the mouse should move before it is considered to be dragging
31.   import static attribute int         DragMinDistance;
32.   /// Get/set minimal time (in milliseconds) the mouse should move before it is considered to be dragging
33.   import static attribute int         DragMinTime;
34.  
35.   /// Get/set if the module should automatically track hook key press and release
36.   import static attribute bool        AutoTrackHookKey;
37.   /// Get/set the default action that should be done to dragged object when the hook key is released;
38.   /// this action may be overriden by user by explicitly calling Drop() or Revert()
39.   import static attribute DragDropUnhookAction DefaultUnhookAction;
40.  
41.  
42.   ///////////////////////////////////////////////////////////////////////////
43.   //
44.   // Event signals
45.   // ------------------------------------------------------------------------
46.   // Properties meant to signal user about drag'n'drop events.
47.   //
48.   ///////////////////////////////////////////////////////////////////////////
49.  
50.   /// Gets if the hook key was pushed down and the module is looking for the actual
51.   /// draggable object under the cursor; this is when the user should supply module
52.   /// with draggable object
53.   readonly import static attribute bool EvtWantObject;
54.   /// Gets if the draggable object was just hooked; this is when the user may take
55.   /// some action right before the object will be actually dragged around
56.   readonly import static attribute bool EvtObjectHooked;
57.   /// Gets if mouse drag just started; this event takes place if the draggable object
58.   /// was found and drag conditions were met (minimal drag time and/or distance)
59.   readonly import static attribute bool EvtDragStarted;
60.   /// Gets if the mouse drag was just released; the event takes place just a tick
61.   /// before object is actually dropped on a new place, letting user to choose a drop
62.   /// coordinates or revert the drag
63.   readonly import static attribute bool EvtWantDrop;
64.   /// Gets if the object was just dropped on a new position
65.   readonly import static attribute bool EvtDropped;
66.  
67.  
68.   ///////////////////////////////////////////////////////////////////////////
69.   //
70.   // State control
71.   // ------------------------------------------------------------------------
72.   // Properties and functions meant to tell about current drag'n'drop process
73.   // and control its state.
74.   //
75.   ///////////////////////////////////////////////////////////////////////////
76.  
77.   /// Gets if the module is currently doing nothing
78.   readonly import static attribute bool         IsIdle;
79.   /// Gets if the module has an object hooked (during pre-dragging, dragging or dropping states)
80.   readonly import static attribute bool         HasObjectHooked;
81.   /// Gets if the mouse is currently being dragged (drag button held down and mouse moved)
82.   readonly import static attribute bool         IsDragging;
83.   /// Gets the current hook key
84.   readonly import static attribute int          CurrentKey;
85.   /// Gets the current drag mouse button
86.   readonly import static attribute MouseButton  CurrentMouseButton;
87.   /// Gets the current drag mode (this hints the type of object being dragged)
88.   readonly import static attribute int          CurrentMode;
89.   /// Gets the user-defined dragged object integer tag
90.   readonly import static attribute int          ObjectTag;
91.   /// Gets the user-defined dragged object String tag
92.   readonly import static attribute String       ObjectSTag;
93.   /// Gets X coordinate of cursor position at which the hook key was pushed down
94.   readonly import static attribute int          DragStartX;
95.   /// Gets Y coordinate of cursor position at which the hook key was pushed down
96.   readonly import static attribute int          DragStartY;
97.   /// Gets X coordinate of initial object's position
98.   readonly import static attribute int          ObjectStartX;
99.   /// Gets Y coordinate of initial object's position
100.   readonly import static attribute int          ObjectStartY;
101.   /// Gets X coordinate of the dragged object's position
102.   readonly import static attribute int          ObjectX;
103.   /// Gets Y coordinate of the dragged object's position
104.   readonly import static attribute int          ObjectY;
105.  
106.   /// Notify hook key push down; this does not have to be real keycode
107.   import static void  HookKeyDown(int user_key = 0, MouseButton mbtn = 0);
108.   /// Assign a draggable object for the module when it expects to find one under the mouse cursor
109.   import static void  HookObject(int user_mode, int obj_x, int obj_y, int tag = 0, String stag = 0);
110.   /// Notify hook key release
111.   import static void  HookKeyUp();
112.  
113.   /// Drop the object now
114.   import static void  Drop();
115.   /// Drop the object now and position it at the given coordinates
116.   import static void  DropAt(int x, int y);
117.   /// Reset drag; if an AGS object was dragged, return it to original position
118.   import static void  Revert();
119. };
120.  

Examples of use

The possibly simpliest example of using DragDrop is this:

Code: Adventure Game Studio

1. function game_start()
2. {
3.   DragDrop.Enabled = true;
4. }
5.  
6. #define MY_DRAGDROP_MODE 1
7.  
8. function repeatedly_execute()
9. {
10.   if (DragDrop.EvtWantObject)
11.   {
12.     DragDrop.HookObject(MY_DRAGDROP_MODE, mouse.x, mouse.y);
13.   }
14.   else if (DragDrop.EvtDropped)
15.   {
16.     // cannot use blocking functions in repeatedly_execute, so use SayBackground
17.     player.SayBackground(String.Format("An object was moved from (%d,%d) to (%d,%d)", DragDrop.ObjectStartX, DragDrop.ObjectStartY, DragDrop.ObjectX, DragDrop.ObjectY));
18.   }
19. }
20.  

Real working examples may be larger, and I recommend to refer to the Demo game for better code:
https://bitbucket.org/ivan-mogilko/ags-script-modules/downloads/DragDropDemo_1.0.0.zip

Also, the DragDropCommon module itself may be a good example, because it uses DragDrop features to move actual AGS objects around.



Using DragDropCommon

DragDropCommon module uses DragDrop interface in same way as a regular user will, to drag the built-in AGS object types, such as Characters, Room objects, GUIs and GUI controls, and Inventory Items. It is pretty simple to setup and use. As with base DragDrop module there is default behavior and ways to override one.


DragDropCommon API

Following are properties and functions of the DragDropCommon class, that are exposed for use in your scripts:

Code: Adventure Game Studio

1.  
2. enum DragDropCommonMode
3. {
4.   eDragDropCharacter = 1,
5.   eDragDropGUI,
6.   eDragDropGUIControl,
7.   eDragDropRoomObject,
8.   eDragDropInvItem,
9.   NUM_DRAGDROPCOMMON_MODES
10. };
11.  
12. // DragDropCommonMove enumeration determines the way hooked object is being dragged around
13. enum DragDropCommonMove
14. {
15.   // drag actual object itself (position updates real-time)
16.   eDDCmnMoveSelf,
17.   // drag overlay with object's image, while object stays in place until drag ends;
18.   // this currently works only for characters and room objects!
19.   eDDCmnMoveGhostOverlay,
20.   // drag GUI with object's image; this is currently only way to drag inventory items
21.   eDDCmnMoveGhostGUI
22. };
23.  
24. struct DragDropCommon
25. {
26.   ///////////////////////////////////////////////////////////////////////////
27.   //
28.   // Setting up
29.   // ------------------------------------------------------------------------
30.   // Functions and properties meant to configure the drag'n'drop behavior.
31.   //
32.   ///////////////////////////////////////////////////////////////////////////
33.  
34.   /// Get/set whether particular drag'n'drop mode is enabled
35.   import static attribute bool  ModeEnabled[];
36.   /// Disable drag'n'drop for all the modes
37.   import static void            DisableAllModes();
38.  
39.   /// Get/set whether click on AGS object should be tested using pixel-perfect detection
40.   /// (alternatively only hit inside bounding rectangle is tested)
41.   import static attribute bool  PixelPerfect;
42.   /// Get/set whether only Clickable AGS objects should be draggable
43.   import static attribute bool  TestClickable;
44.  
45.   /// Get/set the way object's drag around is represented
46.   import static attribute DragDropCommonMove DragMove;
47.   /// Get/set transparency of a representation used when DragStyle is NOT eDragDropMoveSelf
48.   import static attribute int   GhostTransparency;
49.   /// Get/set whether representation should keep sprite's alpha channel
50.   import static attribute bool  GhostAlpha;
51.   /// Get/set the GUI used to represent dragged object
52.   import static attribute GUI*  GhostGUI;
53.  
54.  
55.   ///////////////////////////////////////////////////////////////////////////
56.   //
57.   // State control
58.   // ------------------------------------------------------------------------
59.   // Properties and functions meant to tell about current drag'n'drop process
60.   // and control its state.
61.   //
62.   ///////////////////////////////////////////////////////////////////////////
63.  
64.   /// Gets current dragged character
65.   readonly import static attribute Character*   _Character;
66.   /// Gets current dragged GUI
67.   readonly import static attribute GUI*         _GUI;
68.   /// Gets current dragged GUIControl
69.   readonly import static attribute GUIControl*  _GUIControl;
70.   /// Gets current dragged room Object
71.   readonly import static attribute Object*      _RoomObject;
72.   /// Gets current dragged Inventory Item
73.   readonly import static attribute InventoryItem* _InvItem;
74.   /// Gets current dragged object's or its representation width
75.   readonly import static attribute int          ObjectWidth;
76.   /// Gets current dragged object's or its representation height
77.   readonly import static attribute int          ObjectHeight;
78.   /// Gets current dragged overlay's graphic (only if drag style is NOT eDragDropMoveSelf)
79.   readonly import static attribute int          UsedGhostGraphic;
80.  
81.   /// Start dragging a character under cursor
82.   import static bool  TryHookCharacter();
83.   /// Start dragging a GUI under cursor
84.   import static bool  TryHookGUI();
85.   /// Start dragging a GUI Control under cursor
86.   import static bool  TryHookGUIControl();
87.   /// Start dragging a room Object under cursor
88.   import static bool  TryHookRoomObject();
89.   /// Start dragging an Inventory Item under cursor
90.   import static bool  TryHookInventoryItem();
91.   /// Try to find an applicable object to drag under cursor, based on currently enabled modes
92.   import static bool  TryHookDraggableObject();
93. };
94.  

Enabling particular modes is needed for automatic object hookup. If you are going to hook objects manually (calling functions like TryHookCharacter(), etc), you do not need to enable these.

Depending on DragMove property value, this module either moves the actual object on screen at real-time (eDDCmnMoveSelf mode), or moves its "ghost" clone image on overlay (eDDCmnMoveGhostOverlay mode) or custom GUI (eDDCmnMoveGhostGUI mode). Overlay is created automatically, but you must assign GhostGUI if you want to use GUI mode.
In the first case you do not need to move object yourself, but in the last two cases you will have to script actual object repositioning yourself, presumably on receiving EvtWantDrop signal.


NOTE: it is possible to have DragDropCommon and your own custom drag modes in the same game, and even at the same time. But you should make sure that you choose a new mode IDs that do not mess up with DragDropCommon's mode numbers.


NOTE: DragDropCommon has a pixel perfect detection option, but it works only for characters and room objects now.



The modules are working in general, but still need more public testing.
Comments, critism, suggestions and bug reports are welcome.

[selmiak]

Now this sounds really useful! Especially for mobile games and even cooler ingame computerscreens with hacking!

[Crimson Wizard]

And hereby I release Drag & Drop module v1.0.0.
DOWNLOAD DragDrop 1.0.0 MODULE
DOWNLOAD DragDropCommon 1.0.0 MODULE
DOWNLOAD Demo game (needs AGS 3.2.1 or higher)
(Also updated first post)

Not sure how much this was popular, since I got only 1 response and no questions about module usage, but I keep hopes that it will be useful to some.

What's new in 1.0.0

This update was focused on making DragDropCommon module capable of dragging object images instead of objects themselves, which also let me implement dragging of InventoryItems.

1. Added DragDropCommon.DragMove property, which determines the way dragging is done. It can be:
- eDDCmnMoveSelf - drags the object itself at real time (does not work for Inventory Items);
- eDDCmnMoveGhostOverlay - drags overlay with object's image on it (won't work for GUI and Controls);
- eDDCmnMoveGhostGUI - drags supplied custom GUI with object's image on it (currently does not work for GUI and Controls, but this is ONLY way to make inventory items drag & drop);

2. Additionally to DragMove, following properties can be set:
- DragDropCommon.GhostTransparency - determines ghost mode image transparency;
- DragDropCommon.GhostAlpha - determines whether ghost mode uses images with alpha channel;
- DragDropCommon.GhostGUI - sets custom GUI to be used for eDDCmnMoveGhostGUI mode (this MUST be set, otherwise it won't work);

3. Following new properties are meant for reading current state:
- DragDropCommon._InvItem - pointer to inventory item (if one is being dragged);
- DragDropCommon.ObjectWidth - returns dragged object/representation width, either taken from its properties, or deduced from the image;
- DragDropCommon.ObjectHeight - returns dragged object/representation height, either taken from its properties, or deduced from the image;
- DragDropCommon.UsedGhostGraphic - returns actual graphic index used in ghost modes (or 0);

4. Added DragDropCommon.TryHookInventoryItem() function, which, naturally, tries to start dragging inventory item under DragDrop.DragStartX / DragStartY coordinates.


Extended and improved Demo Game. I was actually worried if those who downloaded it noticed there are more than 1 room. So this time I provided slightly better help messages and a kind of "startup menu".
Also, now there are 4 demo rooms.

[katie08cd]

thank you, but I can edit it like the deduction room, like Sherlock Holmes: Crimes & Punishments?

[Crimson Wizard]

thank you, but I can edit it like the deduction room, like Sherlock Holmes: Crimes & Punishments?

Yes of course. The module was created having extension in mind, that allows you to script dragging of both built-in AGS objects and also any kind of custom "entities" in your game, that you define yourself.

Before using it I recommend to first find out how do you set up the deduction room itself. After you know what kind of objects you will have there, and which AGS features will represent them, then I may be able to give more detailed advice for the use of this module.

[Cassiebsg]

Okay, I just installed this module as I got an idea where this will be perfect.
But after following your instrucs from the first post:

1. Add both DragDrop and DragDropCommon modules to your game. DragDrop should be higher in the module list, or your game won't compile.
2. In one of the rooms add following code to the "After Fade-in" event handler:
Code: Adventure Game Studio

      DragDrop.Enabled = true;
      DragDropCommon.ModeEnabled[eDragDropCharacter] = true;
      DragDropCommon.ModeEnabled[eDragDropRoomObject] = true;
     

3. Just in case, add following code to the "Leave room" event handler:
Code: Adventure Game Studio

      DragDropCommon.DisableAllModes();
      DragDrop.Enabled = false;
     

4. That's it! Now you can drag and drop characters and objects with your mouse in that room. Have fun .

I immediately get a crash when trying to click on a character or object.
It fails on line 67, 147, 270 & 632 of DragDropCommon.asc with "Error running function 'repeatedly_execute_always': Error: Null pointer refenced

I'm using the latest AGS, 3.5.0.24

I haven't tried anything else or look at the demo yet... but since you wrote that was all that was needed to try it... 
I'll check the demo now.

[Crimson Wizard]

@Cassiebsg, looks like it works in "Ghost GUI" mode by default (don't know why :/), which requires you to set a GUI object to the module.

Change to another mode as

Code: Adventure Game Studio

1. DragDropCommon.DragMove = eDDCmnMoveSelf;
2.    OR
3. DragDropCommon.DragMove = eDDCmnMoveGhostOverlay;
4.  

I must update this module when I get spare time, with fixes and maybe also better tutorial.

[Cassiebsg]

Thanks, I'll give a try later on, but will add the lines already before the forum crashes again. 

Edit: Works now! So guess I can now play with programming the game.