What is a "server-sent plugin"?Server-sent plugins are a new feature in GG2 version 2.5. They allow servers to have a set of plugins which the server and players automatically download.
Despite the name, "server-sent" plugins are not sent by the server. Rather, the server sends a list of plugin names, which are used to get the plugins from
http://www.ganggarrison.com/plugins/ (see "How safe are they?" below)
Why don't they work in Gang Garrison 2.5.x any more?See this topic:
http://www.ganggarrison.com/forums/index.php?topic=34113.0Why do I get an error when I extract it to my plugins folder and run it?Server-sent plugins are not supposed to be downloaded by you. Instead, just put the names of the plugins you want to use in your gg2.ini file (see "How do I use server-sent plugins?") and they will be automatically downloaded by your server and its players.
Plugins can detect whether they are running as server-sent plugins by checking whether "isServerSentPlugin" is set to true on their PluginEnvironment instance.
How do I use server-sent plugins?If you want to host a server using server-sent plugins, find out the names of the plugins you want to use. You don't need to download them. Just edit the following two lines in your gg2.ini file:
ServerPluginList=
ServerPluginsRequired=0After ServerPluginList you can put a comma-separated list of plugin names (see:
http://www.ganggarrison.com/plugins/). There must not be any spaces between the plugin names and the commas. Here's an example:
ServerPluginList=lowgravity,can_you_feel_the_sunshineAfter ServerPluginsRequired you can either put 1 (requires plugins to join server) or 0 (plugins are optional but suggested to client).
If you don't want any plugins, just leave the ServerPluginList= field blank.
If you want to join a server using server-sent plugins, you'll be prompted if you want to download them. If they are required, you can either download them or disconnect. If they aren't required, you can choose to continue connecting without downloading them. You can disable the prompts in the settings. If you do this, it will download them without asking you. However, this might be dangerous. (see "How safe are they?" below)
How safe are they?Plugins can do almost anything. They can download applications and execute them, delete files, spy on you, etc. Because of this, server-sent plugins are not downloaded like maps are, because then a server could send a malicious plugin. Instead, server-sent plugins are always downloaded from
http://www.ganggarrison.com/plugins/, which only has plugins that have been screened by me or other developers. Because of this you shouldn't need to worry, but we are not perfect and something might slip past us. If you are paranoid, avoid joining servers with plugins.
How do I make a server-sent plugin?A server-sent plugin is just a zip file with a plugin.gml file in it. When it is downloaded, it is extracted to a temporary folder, and plugin.gml is executed with argument0 being the path of the temporary folder (does NOT end in a backslash, add it yourself), so that the plugin can find any resource files that were in the zip file. The temporary folder is cleaned up for you when GG2 exits.
Plugin names must be composed only of lowercase letters, digits and underscores, and be a minimum of one letter long. If the plugin name doesn't fit this format, GG2 will error and won't load it.
When the user leaves that server, they have to quit or restart GG2, so don't worry about having to disable/enable your plugin. Server-sent plugins for a given host server are also executed on the host server itself, so you should account for this with global.isHost checks.
When you want to debug a server-sent plugin, you can create a special folder called ServerPluginsDebug in your GG2 folder, and place your plugin zip file in there with the correct .zip extension, e.g. lowgravity.zip. GG2 will check in that folder first before trying to download it.
Once you have made your server-sent plugin, you can get it reviewed and hopefully onto
http://www.ganggarrison.com/plugins/ so other people can use it. Send me a PM with a link to the forum thread for the plugin, its name and the zip file, and I'll review it and either add it or ask you to change some things before it can be added. Please
agree to the terms and conditions.
If you're looking for server-sent plugin examples, just download one of the existing plugins:
http://www.ganggarrison.com/plugins/How do I do networking with server-sent plugins?From Gang Garrison 2.7.3 onwards, server-sent plugins are executed within a PluginEnvironment instance with four properties: directory (directory the plugin was extracted to), packetID (the packetID value), isServerSentPlugin (set to 1) and isLocalPlugin (set to 0). Prior to 2.7.3, the only way to get the packetID and directory was from argument1 and argument0 respectively, which are still set for compatibility.
All server-sent plugins now get a special packetID that can be used with the PluginPacket* functions to send buffers encapsulated in the new PLUGIN_PACKET packet, and to receive them. Receiving, clients get just the buffer (from the server), servers get the buffer (from the client) and the Player object (corresponding to the client). Sending, servers send the buffer to all clients, or a specific client, and clients send the buffer to just the server.
The buffers mentioned here are Faucet Networking buffers, since Gang Garrison 2 uses MedO's Faucet Networking extension. Full documentation on Faucet Networking is provided in the form of a PDF included in the ZIP file for each release. You can find Faucet Networking releases here on GitHub:
https://github.com/Medo42/Faucet-Networking-Extension/releases (at the time of writing, GG2 used version 1.2.1). You need not concern yourself with any of the TCP or UDP functions, only how buffers work.
- When a server-sent plugin is run, `argument1` is a special packetID value
- PluginPacketSend(packetID, buffer[, loopback]) sends the buffer specified (maximum 65535 bytes), to the server (if client) or to all clients (if server), with that packetID, returns false on failure, else true. Since GG2 v2.6.9 there is an optional argument, loopback. If it is true on the server, the server will also send the buffer to itself. The buffer you give it will not be touched by GG2, you need to destroy it yourself.
- PluginPacketSendTo(packetID, buffer, player) (server-only) sends the buffer specified (maximum 65535 bytes), to the client specified by the player Player object, with that packetID, returns false on failure, else true. Since GG2 v2.6.9, player can be global.myself on the server and it will send the buffer to itself. The buffer you give it will not be touched by GG2, you need to destroy it yourself.
- PluginPacketPop(packetID) discards the data for the first packet received, from the server (if client) or from a client (if server), if any (returning false if not, true if so), for that packetID. This will destroy the buffer that PluginPacketGetBuffer would get you.
- PluginPacketGetBuffer(packetID) returns the buffer of the first packet received, from the server (if client) or from a client (if server), if any (returning -1 if not), for that packetID. Buffer should not be modified or destroyed by you, use PluginPacketPop.
- PluginPacketGetPlayer(packetID) returns the Player object representing the client responsible for the first packet received, from a client (if server, otherwise returns `noone`), if any (returning -1 if not), for that packetID.
How does plugin caching work?It "just works" and you don't have to worry about it. The first time your client sees a particular version of a plugin, it will save a copy in the cache. Later, if it needs that particular version of that plugin again, it will retrieve it from the cache, instead of downloading it again. If you delete the cache (the ServerPluginsCache folder), nothing bad will happen, but GG2 will have to redownload any plugins that were in that cache when it next needs them.
Author
Topic: Server-sent plugins FAQ (Read 53466 times)
