Register |  Notes |  Sign in...     

Software Documentation -> MQ2EmuRing
Reply to topic


Maudigan   Send PM
Project Lead






MQ2EmuRing

Sat Jul 22, 2017 12:03 pm      





Index


Overview
- Installation
- Update History
Commands
- ring
- rings
TLO: Ring
Type: TypeRing
Type: TypeExtRing
Macro Example
Dependencies
Limitations
Troubleshooting



Overview


MQ2EmuRing creates a way for you to generate a target ring (just like with a splash spell) and then retrieve and use the coordinates where you placed it. This lets you use the ring as a way to quickly reference a location in your macros and hot keys, e.g., moving a character to a location you clicked, setting up a camp location, etc. You can even script the whole process of generating the ring, placing it and then executing a subsequent command on a single line of a hot key. You can generate multiple rings in a zone and load/save them to an INI file.

[back to index]

Installation


Follow the normal MQ setup and startup process. Ensure you have the plugin loaded (/plugin mq2emuring). After that you should be able to use the command and TLO. You don't need to be logged in; this is a free plugin.

[back to index]

Update History


20170722: This is the initial revision of the plugin.
20170903: Added the ability to have multiple rings.

[back to index]

Commands



/ring [<name>] [<command>]


Generates the target ring for placement. After executing this command a red ring will be generated on the ground in-game. You can move the ring around with your cursor and can click to place the ring wherever you like. Once you place the ring the X, Y, and Z coordinates will be available via the Ring TLO properties. If you provide the optional command the command will be executed automatically after you place the ring. If you do not provide a name one will be generate automatically (e.g. "Ring1"). You will be able to recall the rings later by name or index via the TLO.

The command parameter will not have its variables parsed until after you place the ring. So if you have ${Ring.X} in the command parameter it will, when eventually executed, hold the value of where you placed the current ring, not the previous.



/ring
Generates a ring and lets you place it. After placement it's coordinates are available via the TLO.

/ring MyCamp
Generates a ring and lets you place it. After placement it's coordinates are available via the TLO under the name "MyCamp".

/ring MyCamp /moveto loc ${Ring.X} ${Ring.Y}
Will generate a ring named "MyCamp", allow you to place it, and then execute the moveto command (MQ2MoveUtils) and cause your character to run to that location where you clicked--Diablo style.

/ring /bct Maudigan //moveto loc ${Ring.X} ${Ring.Y}
Similar to above but the command will get sent remotely to "Maudigan" and cause that character to run to the location you clicked.

[back to index]

/rings help|first|last|next|previous|load|save|list|(delete [<id>|<name>])


Permits interaction with your list of rings within the current zone.

/rings help
Echoes the command help to the MQ chat window.

/rings first
Sets the ring pointer to the first ring in your list. You can access this through the "Current" element of the Ring TLO. See TypeExtRing for details.

/rings last
Sets the ring pointer to the last ring in your list. You can access this through the "Current" element of the Ring TLO. See TypeExtRing for details.

/rings next
Sets the ring pointer to the next ring in your list. You can access this through the "Current" element of the Ring TLO. See TypeExtRing for details.

/rings previous
Sets the ring pointer to the previous ring in your list. You can access this through the "Current" element of the Ring TLO. See TypeExtRing for details.

/rings delete
Deletes every ring in your list for the current zone.

/rings delete MyCamp
Deletes the ring named "MyCamp"

/rings delete 1
Deletes the first ring in your list.

/rings load
Reloads the current zone's ring list from the INI file.

/rings save
Saves any changes you've made to the current zone's ring list to the INI file.

/rings list
Echoes your list of rings to the MQ chat window. The current ring will be highlighted in red. If none are highlighted in red then your current ring pointer is pointing to the head or tail of the list.


[back to index]

Top-Level Object: ${Ring}



TypeRing Ring[<name>]


References the ring with the name <name>.

/echo MyCamp is at ${Ring[MyCamp].X}, ${Ring[MyCamp].Y}, ${Ring[MyCamp].Z}

TypeRing Ring[<ID>]


References the ring with the name index of <ID> (the first ring is ID 1, not ID 0).

/echo The 3rd ring is at ${Ring[3].X}, ${Ring[3].Y}, ${Ring[3].Z}

TypeExtRing Ring


References the last ring you placed. It also accesses some extended information such as the UpperBound, Ring Status, Linked List interface, etc. See TypeExtRing for details. This can be a little confusing since "Ring" references the last ring place and it also contains "Ring.Last" and "Ring.First" this was done for backwards compatibility. If you're confused look at the practical examples.

/echo The LAST ring is at ${Ring.X}, ${Ring.Y}, ${Ring.Z}
/echo The FIRST ring is at ${Ring.X}, ${Ring.First.Y}, ${Ring.First.Z}
/echo I have a total of ${Ring.UpperBound} rings.

[back to index]

Type: TypeRing



string ring


Returns name of the ring.

string ring.ID


Returns ID of the ring. The first ring is ID 1, not ID 0.

string ring.Name


Returns name of the ring.

string ring.ToString


Returns name of the ring.

float ring.X


Returns the X coordinate of the ring being referenced. If the ring doesn't exist this will return a NULL.

/ring /echo I just placed a ring at ${Ring.X}, ${Ring.Y}, ${Ring.Z\}

float ring.Y


Returns the Y coordinate of the ring being referenced. If the ring doesn't exist this will return a NULL.

/ring /echo I just placed a ring at ${Ring.X}, ${Ring.Y}, ${Ring.Z}

float ring.Z


Returns the Z coordinate of the ring being referenced. If the ring doesn't exist this will return a NULL.

/ring /echo I just placed a ring at ${Ring.X}, ${Ring.Y}, ${Ring.Z}

[back to index]

Type: TypeExtRing :: Extends TypeRing



TypeRing Ring.Current


References the current ring in the list. You can set and advance this reference using the /rings first|last|next|previous command.

/ring last
/echo I just placed a ring at ${Ring.Current.X}, ${Ring.Current.Y}, ${Ring.Current.Z}

/ring first
/echo My first ring is at ${Ring.Current.X}, ${Ring.Current.Y}, ${Ring.Current.Z}


TypeRing Ring.First


References the first ring in the list.

/echo My first ring is at ${Ring.First.X}, ${Ring.First.Y}, ${Ring.First.Z}

TypeRing Ring.Last


References the first last in the list.

/echo My last ring is at ${Ring.First.X}, ${Ring.First.Y}, ${Ring.First.Z}

string Ring.State


Returns a string value describing what the status of the pending the plugin is in. Those values follow:

  • NONE: The plugin is in its initial state, or you've not placed a ring in the current zone yet and the X, Y and Z properties will return a NULL.
  • SET: A ring has been placed and will return its location via the X, Y, and Z properties.
  • PENDING: A ring is pending. It's still visible on the screen and waiting for you to click and place it. The X, Y, and Z properties will return the previous rings location while pending.
  • FAILED: The previous ring command failed to generate a ring for some reason. the X, Y and Z properties will continue use to return the last successful rings location.


/echo ${If[${Ring.State.Equal[SET],"The ring has been set","The ring is NOT set"]}

int Ring.UpperBound


Returns the count of how many rings you have in the current zone.

/echo I have a total of ${Ring.UpperBound} rings.

[back to index]

Macro Example




Macro
| generate a target ring, allow its placement
| and then command my group to that location

Sub Main
   |generate a ring
   /ring

   |wait for the ring to be placed
   :waitring
   /if (${Ring.State.NotEqual[SET]}) /goto :waitring

   |once the ring is placed move my group to the ring coordinates
   /bca //moveto loc ${Ring.X} ${Ring.Y}
/return




Macro
| loop through every ring like an array

Sub Main
/declare i int

/for i 1 to ${Ring.UpperBound}
   /echo ${Ring[${i}].Name} is at ${Ring[${i}].X}, ${Ring[${i}].Y}, ${Ring[${i}].Z}
/next i
/return




Macro
| loop FORWARD through every ring like a linked list

Sub Main
/rings first
:loop
   /echo ${Ring.Current.Name} is at ${Ring.Current.X}, ${Ring.Current.Y}, ${Ring.Current.Z}
   /rings next
/if (${Ring.Current.ID}) /goto :loop
/return




Macro
| loop BACKWARD through every ring like a linked list

Sub Main
/rings last
:loop
   /echo ${Ring.Current.Name} is at ${Ring.Current.X}, ${Ring.Current.Y}, ${Ring.Current.Z}
   /rings previous
/if (${Ring.Current.ID}) /goto :loop
/return



[back to index]

Dependencies


This plugin has no inherent dependencies on other plugins.
This plugin does NOT require a membership.

[back to index]

Limitations


Presently only available on the ROF2 build. It will eventually be added to the other builds that have the target ring available. Not sure which builds that will be but probably not Titanium or SOF.

[back to index]


Troubleshooting



The ring command or TLO doesn't work
  • Make sure MQ is loaded.
  • Make sure MQ2EmuRing is loaded (/plugin MQ2EmuRing).
  • Report the problems here.


[back to index]
 



Reply to topic