This callback will be one of the most powerful new tools when it comes to creating custom actions in the game.

 

UIObject_Input_ActionTargetScript(), new in 1.06, will let you make 'GUI actions' similar to the 'actions' that are created when you click on a spell or feat button to cast it, or on a button in the DM Choser that then has you select a target to do the action to.

 

Once the user clicks on a valid target, a bunch of data will be sent to the server along with a request to execute a script associated with the click.

 

Anyway, enough summary, here's the details:

 

UIObject_Input_ActionTargetScript("sValidTargetTypes",nValidCursor,nInvalidCursor,nSpellTargetIndex,bUseHostile,"sScriptName", script parameter list...)

 

sValidTargetTypes

This parameter is a string that will list the types of objects that will be valid to click on. If you enter a "", that means all targets are valid for this action. Otherwise, you can enter a list, seperated by commas or any other deliminator you want to use. The valid target names are:

self

creature

ground

item

door

placeable

trigger

 

For example: "creature,placeable" would mean that valid targets would include clicking on placeables and clicking on creatures.

 

nValidCursor

This is an integer constant to point to one of the cursors that the engine understands. You can only really use the cursors compiled into the game's executable. I will make a list of those constants at the end of this post. This is the cursor that you want to use when the cursor is over a valid target.

 

nInvalidCursor

Just like the nValidCursor parameter, except this is the cursor you want displayed when the mouse is over an invalid target. For example, if my valid targets were creatures and placeables, but the mouse was over open ground, this is the cursor that would be shown.

 

nSpellTargetIndex

This is a reference into the spelltarget.2da to indicate that you want to use one of the spell targeting projected textures like the ones used when targeting Area of Effect spells. If you do not want an AoE texture around the cursor, just enter -1 for this parameter.

 

bIsHostile

This tells the engine if you want to use the Hostile Texture column from spelltarget.2da or not. If you entered -1 for nSpellTargetIndex, then this parameter doesn't mean anything. You must enter either "true" or "false", even if you entered -1 for nSpellTargetIndex.

 

sScriptName

The name of the script you want to follow. This follows the same restrictions that UIObject_Misc_ExecuteServerScript() usese, in that the script name must start with 'gui_', or else the server will reject the request.

 

Parameter List

This is an unlimited list of parameters just like ExecuteServerScript() supports. However, there are a few extra parameters that this function can support:

target.object - This will replace the parameter with the OBJECT_ID of the object that the user clicked on.

target.x - This will replace the parameter with the X value of the position that the user clicked on as a float. If the user clicked on a specific object, instead of open ground, then this X will be the position of that object as far as the client knows. Since the client could be a few milliseconds out of synch with the server, the server may consider this object at a slightly different position than the client does.

target.y - Same as X, except for the Y value of the position vector.

target.z - Same as X, except for the Z value of the position vector.

 

For example, if I wanted to create a DM Action button that deleted whatever placeable the DM targetted as well as all placeables within 15 yards of the target, I would create a UIButton with the following callback:

OnLeftClick=UIObject_Input_ActionTargetScript("placeable",51,53,17,"true","gui_eraseplaceables","target:object")

 

The number 51 would be for the CURSOR_KILL cursor, the number 53 would be for the CURSOR_NOKILL cursor, the number 17 would be for row 17 in spelltarget.2da whcih is a large circle with a 30 yard width (so 15 yard radius), and the "true" is because I want it to use the hostile texture out of that 2DA. I want to use the clicked on placeable as my starting point, so I go ahead and pass that along as a parameter as well. It will be passed into gui_eraseplaceables as either a string or an int, depending on what parameter I have that script expecting.

 

Anyway, the list of cursor constants is:

 

#define MOUSECURSOR_DEFAULT 1

#define MOUSECURSOR_DEFAULT_DOWN 2

#define MOUSECURSOR_WALK 3

#define MOUSECURSOR_WALK_DOWN 4

#define MOUSECURSOR_NOWALK 5

#define MOUSECURSOR_NOWALK_DOWN 6

#define MOUSECURSOR_ATTACK 7

#define MOUSECURSOR_ATTACK_DOWN 8

#define MOUSECURSOR_NOATTACK 9

#define MOUSECURSOR_NOATTACK_DOWN 10

#define MOUSECURSOR_TALK 11

#define MOUSECURSOR_TALK_DOWN 12

#define MOUSECURSOR_NOTALK 13

#define MOUSECURSOR_NOTALK_DOWN 14

#define MOUSECURSOR_FOLLOW 15

#define MOUSECURSOR_FOLLOW_DOWN 16

#define MOUSECURSOR_EXAMINE 17

#define MOUSECURSOR_EXAMINE_DOWN 18

#define MOUSECURSOR_NOEXAMINE 19

#define MOUSECURSOR_NOEXAMINE_DOWN 20

#define MOUSECURSOR_TRANSITION 21

#define MOUSECURSOR_TRANSITION_DOWN 22

#define MOUSECURSOR_DOOR 23

#define MOUSECURSOR_DOOR_DOWN 24

#define MOUSECURSOR_USE 25

#define MOUSECURSOR_USE_DOWN 26

#define MOUSECURSOR_NOUSE 27

#define MOUSECURSOR_NOUSE_DOWN 28

#define MOUSECURSOR_MAGIC 29

#define MOUSECURSOR_MAGIC_DOWN 30

#define MOUSECURSOR_NOMAGIC 31

#define MOUSECURSOR_NOMAGIC_DOWN 32

#define MOUSECURSOR_DISARM 33

#define MOUSECURSOR_DISARM_DOWN 34

#define MOUSECURSOR_NODISARM 35

#define MOUSECURSOR_NODISARM_DOWN 36

#define MOUSECURSOR_ACTION 37

#define MOUSECURSOR_ACTION_DOWN 38

#define MOUSECURSOR_NOACTION 39

#define MOUSECURSOR_NOACTION_DOWN 40

#define MOUSECURSOR_LOCK 41

#define MOUSECURSOR_LOCK_DOWN 42

#define MOUSECURSOR_NOLOCK 43

#define MOUSECURSOR_NOLOCK_DOWN 44

#define MOUSECURSOR_PUSHPIN 45

#define MOUSECURSOR_PUSHPIN_DOWN 46

#define MOUSECURSOR_CREATE 47

#define MOUSECURSOR_CREATE_DOWN 48

#define MOUSECURSOR_NOCREATE 49

#define MOUSECURSOR_NOCREATE_DOWN 50

#define MOUSECURSOR_KILL 51

#define MOUSECURSOR_KILL_DOWN 52

#define MOUSECURSOR_NOKILL 53

#define MOUSECURSOR_NOKILL_DOWN 54

#define MOUSECURSOR_HEAL 55

#define MOUSECURSOR_HEAL_DOWN 56

#define MOUSECURSOR_NOHEAL 57

#define MOUSECURSOR_NOHEAL_DOWN 58

#define MOUSECURSOR_RUNARROW 59

#define MOUSECURSOR_WALKARROW 75

#define MOUSECURSOR_PICKUP 91

#define MOUSECURSOR_PICKUP_DOWN 92

#define MOUSECURSOR_CHATBOX_SIZING 99

#define MOUSECURSOR_NODEFAULT 125

#define MOUSECURSOR_NODEFAULT_DOWN 126

#define MOUSECURSOR_MAP 128

#define MOUSECURSOR_MAP_DOWN 127

#define MOUSECURSOR_NOMAP 130

#define MOUSECURSOR_NOMAP_DOWN 129

#define MOUSECURSOR_WAIT_DOWN 131

#define MOUSECURSOR_WAIT 132