Firstly, I've been updating the Wiki, so hopefully between this tutorial and the Wiki, there should be enough information for people to start writing plugins.
and now the tutorial:
Writing your first plugin.
So, we're gonna make a nice, simple plugin that simply outputs everything happening on the servers/ports being listened to.
It'll do the following:
Properly set up it's window
Output all sent/recieved packets
Output when connections are opened/closed
Now, let me explain a little about the hook system BPE uses. there are two kinds of hooks:
Hooks called by BPE, and
Hooks called by the plugin.
Hooks called by BPE are utilized by creating a public function in the document class of the plugin.
eg:
public function sendPacketHook(packet:ByteArray,socketID:int):ByteArray
{
output.appendText("["+socketID+"] Sent:"+packet+"\n")
return packet;
}
That above code would be called every time a packet is sent by the client. the variable "packet" contains the payload (data) from the packet in the form of a ByteArray. socketID is an integer containing the ID of the socket. The function returns the unmodified packet, so no modification is made.
Hooks called by the plugin are utilized by creating a public Function variable in the document class of the plugin, and then calling that variable/Function when you need to.
eg:
public var updateWindow:Function;
public function someFunction():void
{
updateWindow(550,400,"Debug"); as
return;
}
That above code (when someFunction is called) will scale the size of the window so that the stage is 550 pixels wide and 400 pixels high, then set the plugins window title to say "Debug".
Also note that all used hooks must be specified in the .pep file that goes with the plugin (more on that later, though).
Anyways, I hope that's enough explanation for understanding the hooking system for now. let's get on to making the actual plugin!
I'm going to assume you know your way around Flash and know a little AS3 at this point.
So, create a new AS3 project and a document class called "BPEDebugPlugin".
now, we're gonna be using ByteArray's (for the sent and received data) and TextFields (for the output), so go ahead and add these lines to the includes:
import flash.text.TextField;
import flash.utils.ByteArray;
Now, we're gonna need to declare a couple variables in the class.
Firstly, since we want to set the window size and title, we want to use the updateWindow hook, so we need to add a Function variable with the name updateWindow.
Secondly, we want a TextField that we can write our outputted data to.
so, add these lines to your class variable declarations
public var updateWindow:Function;
private var output:TextField = new TextField();
we're gonna make use of the finishPluginSetup hook. this simple hook function is called after your plugins hooks have been set up and your plugin has been added to the stage. it basically tells you it is now safe to use hooks and access the stage.
Chuck this code right after the end of your constructor function:
public function finishPluginSetup()
{
updateWindow(550,400,"Debug");
output.x = 20;
output.y = 20;
output.width = 510;
output.height = 360;
output.background = true;
output.backgroundColor = 0xAAAAAA;
output.text = "Output\n";
this.addChild(output);
}
As stated before, this function will be called once, when BPE has added it to the stage and set up all it's hooks. it calls the updateWindow hook and changes the window size and label. it will then set up the output TextField for use.
Now, let's get to the actually useful hooks. We'll start with the send and receive hooks, since they're super-similar, and quite simple.
public function recievePacketHook(packet:ByteArray,socketID:int):ByteArray
{
output.appendText("["+socketID+"] Recieved:"+packet+"\n")
return packet;
}
public function sendPacketHook(packet:ByteArray,socketID:int):ByteArray
{
output.appendText("["+socketID+"] Sent:"+packet+"\n")
return packet;
}
These functions will be called by BPE every time a packet is sent by the client or received by the client. packet is the ByteArray containing the data payload of the packet, and socketID is the ID number for the socket. We'll output the data being sent in the packet.
This is probably a good time to introduce you to BPE's socket ID system. each socket that connects to BPE is given an ID to make them easy to keep track of.
The first socket to connect is given the ID 0
the second 1
the third 2
ect.
The functions then output the sent/recieved data along with the socket ID.
The ByteArray returned by these functions is then run through any remaining plugins and either sent to the client or server depending on whether the packet is being received or sent.
Since we're returning the same, unmodified ByteArray that was the input of the function, the packet is left untouched. if you return an empty ByteArray, the packet is dropped.
Onto the socketOpen and socketClose hooks.
public function socketOpenHook(socketID:int,address:String,port:int):void
{
output.appendText("["+socketID+"] Connected to:"+address+":"+port+"\n")
return;
}
The socketOpenHook is run every time a socket connects to BPE. it gives you the new socket's ID, the address it's attempting to connect to and the port on which it's attempting to connect to. We'll output the address and port on the server it's attempting to connect to.
Next is the socketCloseHook.
public function socketCloseHook(socketID:int,closeSocket:Boolean):Boolean
{
output.appendText("["+socketID+"] Disconnected, "+closeSocket+"\n")
return closeSocket;
}
The socketCloseHook is called when the server disconnects the client. The Boolean closeSocket tells you whether BPE plans on disconnecting the client. if true, the socket is to be disconnected, if false, the socket connected to the client will stay connected. We'll return the closeSocket value given to us to let the other plugins or BPE decide what to do with the socket connected to the client.
Now, compile that sucker and we're up to creating the .pep file to load our plugin.
PEP files are like an external header for the plugin. it tells BPE everything it needs to know to run your plugin.
I created a simple little tool making it easy to generate the .pep file for your plugin. you can get it here or on the downloads page.
Open the PEP Builder up (do it in your browser if you have to).
For plugin name, type "BPEDebug".
For SWF Filename, write the name of your SWF (mine is "BPEDebug.swf")
and we need to tick the box next to each hook we used
tick the box next to hookUpdateWindow, hookFinishPluginSetup, hookRecievePacket, hookSendPacket, hookSocketOpen and hookSocketClose.
Once you've done that, click the "Save PEP File" button, and save it to the same location as your plugin SWF.
You're done!
Load your plugin with BPE, hook a server and port (web servers are the easiest for testing), and if it works, give yourself a pat on the back.
If it doesn't work, try again or leave a comment.
Here's a link to my finished source.
No comments:
Post a Comment