Questions on Plugins - Gammon Forum

Rivius Wed 20 Apr 2011 03:22 AM #0

I'm sort of new to plugins, but I have some maybe basic questions:

-I noticed that in most plugins, people have ID numbers. Where does one generate these numbers?

-Is every function within a plugin performed in every step?

- I plan to use GCMP to get the variables of max hp and max mp from an IRE game. Is there a good tutorial or list of functions so I can get a basic idea of how I'd begin to do this? I want to study this to properly learn and understand it.

Twisol USA Wed 20 Apr 2011 04:40 AM #1

Rivius said:
-I noticed that in most plugins, people have ID numbers. Where does one generate these numbers?

In MUSHclient, Edit -> Generate Unique ID.

Rivius said:
-Is every function within a plugin performed in every step?

No, functions are blocks of code that aren't executed until they are called. There are also events that call functions, such as a plugin being closed (OnPluginClose) or a trigger being fired (whatever you specify), but in general functions are only called when you call them.

Rivius said:
- I plan to use GCMP to get the variables of max hp and max mp from an IRE game. Is there a good tutorial or list of functions so I can get a basic idea of how I'd begin to do this? I want to study this to properly learn and understand it.

GMCP, not GCMP. :D

I have a plugin that wraps the GMCP protocol (GMCP.plugin) that you can get at my website[1], and I also have a plugin you can look at to see how you use it (roomname.plugin). There should be a README in both.

If you're new to Lua, I highly recommend reading "Programming in Lua" [2], which you can find online.

[1] http://jonathan.com/mushclient-achaea-plugins
[2] http://www.lua.org/pil/

Nick Gammon Australia Forum Administrator Wed 20 Apr 2011 05:30 AM #2

Rivius said:

- I noticed that in most plugins, people have ID numbers. Where does one generate these numbers?

If you use the plugin wizard (you don't have to) then it generates a new ID for you.

Rivius Wed 20 Apr 2011 02:21 PM #3

Twisol said:

Rivius said:
-I noticed that in most plugins, people have ID numbers. Where does one generate these numbers?

In MUSHclient, Edit -> Generate Unique ID.

Rivius said:
-Is every function within a plugin performed in every step?

No, functions are blocks of code that aren't executed until they are called. There are also events that call functions, such as a plugin being closed (OnPluginClose) or a trigger being fired (whatever you specify), but in general functions are only called when you call them.

Rivius said:
- I plan to use GCMP to get the variables of max hp and max mp from an IRE game. Is there a good tutorial or list of functions so I can get a basic idea of how I'd begin to do this? I want to study this to properly learn and understand it.

GMCP, not GCMP. :D

I have a plugin that wraps the GMCP protocol (GMCP.plugin) that you can get at my website[1], and I also have a plugin you can look at to see how you use it (roomname.plugin). There should be a README in both.

If you're new to Lua, I highly recommend reading "Programming in Lua" [2], which you can find online.

[1] http://jonathan.com/mushclient-achaea-plugins
[2] http://www.lua.org/pil/

Nick and Twisol, thank you very much for your reply.

Firstly, sorry for the typo! :P

In regards to my experience with lua, I'm not terribly great with it, but I do know at least most of the basics. I've been learning it slowly over the past few months in my free time.

Thanks for the id generation thing, I admit I never saw that before. It helped a lot in preloading a plugin from the script file.

I looked at your GMCP plugin and I'm afraid I still don't quite 'get' it. Is there official documentation regarding these functions anywhere and how I can use them? My main goal is just to get character vitals, but I also want to fully understand what I'm writing so I'm learning something new.

Also, about the functions question, I was confused about how functions worked in plugins specifically (I didn't understand exactly what the application of a plugin was and assumed it was a means of executing a piece of code upon every step or something). When you mentioned OnPlugin, I figured there must be events to it, so thanks for pointing me in the right direction with that. Instead now, I'm using aliases to call functions from my prompt. So, so far I've learned a bit about plugins.

Twisol USA Wed 20 Apr 2011 06:52 PM #4

Rivius said:
I looked at your GMCP plugin and I'm afraid I still don't quite 'get' it. Is there official documentation regarding these functions anywhere and how I can use them? My main goal is just to get character vitals, but I also want to fully understand what I'm writing so I'm learning something new.

Well, my approach to GMCP deals with two different things. First there's obviously GMCP itelf. When data comes in from the MUD, my plugin processes it and broadcasts the data. Any other plugin that's listening for that broadcast can receive the data and act on it (almost like a trigger). Second is the broadcasting itself. I built a module (called PPI, for Plugin-to-Plugin Interface) that allows plugins to communicate more cleanly, which is used to listen for these broadcasts. Here's an example of how you'd set up a listener for a GMCP event:

local PPI = require("ppi") -- load the library

-- Tell PPI to alert us when the identified plugin is available.
PPI.OnLoad("29a4c0721bef6ae11c3e9a82", function(gmcp)
  -- This code is run when the GMCP plugin is ready.
  -- An interface object is passed as the first argument.
  -- This is where we set up listeners.
  
  -- Listen for the Room.Info message from GMCP.
  gmcp.Listen("Room.Info", function(message, content)
    -- This code is run when the Room.Info message is received.
    -- The first argument is the message name ("Room.Info")
    -- The second argument is the message's content, decoded from JSON into native Lua types.
    -- In this case, content is a table, and I want to display the room name.
    SetStatus(content.name .. ".")
  end)
end)

Does that help? [EDIT] There's official documentation from IRE on the GMCP messages themselves, if you want: http://www.ironrealms.com/gmcp-doc

Rivius said:
Also, about the functions question, I was confused about how functions worked in plugins specifically (I didn't understand exactly what the application of a plugin was and assumed it was a means of executing a piece of code upon every step or something). When you mentioned OnPlugin, I figured there must be events to it, so thanks for pointing me in the right direction with that. Instead now, I'm using aliases to call functions from my prompt. So, so far I've learned a bit about plugins.

Plugins are just bundles of code (and aliases and triggers and etc.) that you can distribute, really. You can think of the world file itself as a plugin, if that helps

Rivius Thu 21 Apr 2011 01:20 PM #5

Alright, thaks for the link. So from what I understand from that documentation on IRE GMCP, I should do (warning: pseudocode) to get started is:

SendPkt('Core.Hello{ "client": "Mushclient", "version": "4.72 (or whatever version we're on now)" }')

SendPkt('Core.Supports.Set [ "Char 1", "Char.Vitals 1" ]')

So according to this, I'm somehow supposed to get this sent to me:

Char.Vitals { "hp": "4500", "maxhp": "4800", "mp": "1200", "maxmp": "2500", "ep": "15000", "maxep": "16000", "wp": "14000", "maxwp": "15000", "nl": "10", "string": "H:4500/4800 M:1200/2500 E:15000/16000 W:14000/15000 NL:10/100" }

and from there I would be able to grab the variables I need to set the maxhp and maxmp.

My obviously dumb questions are:

1) How do I actually get a hold of that output.
2) Are the things I sent and what's in brackets more or less correct?
3) Are there more things I need to do beforehand to get the information I need from the server?

First time at all messing with this GMCP thing.

Twisol USA Thu 21 Apr 2011 09:38 PM #6

Rivius said:
Alright, thaks for the link. So from what I understand from that documentation on IRE GMCP, I should do (warning: pseudocode) to get started is:

SendPkt('Core.Hello{ "client": "Mushclient", "version": "4.72 (or whatever version we're on now)" }')

SendPkt('Core.Supports.Set [ "Char 1", "Char.Vitals 1" ]')

The GMCP plugin already handles this part.

Rivius said:
1) How do I actually get a hold of that output.

When GMCP is enabled, the Char.Vitals message is sent with every prompt. You just set up a listener with the GMCP plugin for "Char.Vitals" in order to catch that message as it's received.

Rivius said:
2) Are the things I sent and what's in brackets more or less correct?

Technically correct, yes. That's how GMCP support is enabled. Then you need an OnPluginTelnetRequest callback to enable GMCP (it's option code 201), and an OnPluginTelnetSubnegotiation to accept the raw GMCP data (which you then need to split into message/content and decode the content from JSON).

Rivius said:
3) Are there more things I need to do beforehand to get the information I need from the server?

Some messages require you to request the data, or do specific things. For example, the Char.Items.List message is only sent when you request it with Char.Items.Inv. But Char.Vitals is automatically sent with each prompt, so it's fairly basic.

Is there any particular reason you're not interested in using the GMCP plugin?

Rivius Fri 22 Apr 2011 01:00 AM #7

Twisol said:

Is there any particular reason you're not interested in using the GMCP plugin?

I just really want to learn how this works. I feel like I'll get a lot more out of this if I have some background knowledge of the basics. I don't even really need to make this plugin since I have access to a ready-made system. But for self-educational purposes (and boredom...and for the fun of it) I want to learn how to do these things too.

I hope I'm not frustrating or offending you, I know just using your plugin would make life easier for me if I really was just intending to get functionality.

Nick Gammon Australia Forum Administrator Fri 22 Apr 2011 01:22 AM #8

Another "take" on GMCP is the GMCP_handler.xml plugin that Lasher wrote for Aardwolf.

In both cases there will be a OnPluginTelnetSubnegotiation callback function which picks up the telnet sequence (IAC SB <whatever> IAC SE) and the plugin looks at the <whatever> part to work out what the message is, breaks it up, does the JSON stuff, etc.

Even if you don't use Aardwolf, you will find that as part of the "Aardwolf client" which is a version of MUSHclient packaged up with various plugins like that one.

Another fairly simple example of the general idea is the ATCP_NJG.xml plugin which I think ships with MUSHclient these days.

Twisol USA Fri 22 Apr 2011 02:10 AM #9

Rivius said:
I hope I'm not frustrating or offending you, I know just using your plugin would make life easier for me if I really was just intending to get functionality.

No no, not at all! I just didn't realize you were interested in learning about GMCP itself, not just using it for things.

At a low level, GMCP takes advantage of telnet subnegotiation to transmit data to the client without it being seen in the output window. This part is built in to MUSHclient, but to get at the data you need to use two plugin callbacks. One agrees to the negotiation of GMCP, and another actually receives the data.


local GMCP_OPTION = 201

function OnPluginTelnetRequest(option, status)
  -- Skip anything that's not GMCP
  if opt ~= GMCP_OPTION then
    return false
  end
  
  -- After negotiation ("SENT_DO"), send the Core.* messages.
  if status == "SENT_DO" then
    -- ...
  end
  
  -- Agree to negotiation
  return true
end

function OnPluginTelnetSubnegotiation(option, data)
  -- Skip anything that's not GMCP
  if opt ~= GMCP_OPTION then
    return false
  end
  
  -- Handle the data here.
end

Now, since Telnet doesn't itself know anything about GMCP, the data you get is just text. The GMCP protocol follows a format of "<message name> <content as JSON>", however, so you can just split at the first space (if any), and decode the JSON content.