[HowTo] Quick start for plugin development

[ImportBot]

Originally Posted by stajs*:

 

So, you have an idea for a Procon plugin, but you don't know where to begin? The aim of this guide is to help you set up your development environment and source control repositories so you can start turning your fantastic idea into an actual plugin that people can use.

 

Prerequisites

 

• A GitHub account. Sure, you could probably use other providers, but Procon is hosted on GitHub so it's much easier to just use that. This also implies some knowledge of git-based activities such as forking.
• Visual Studio. The solution file name hints at VS2008, but it runs fine with VS2013. This also implies some knowledge of programming in C# and how to use Visual Studio.

Plugin architecture

A plugin is a single C# file, that:

 

• is in the namespace PRoConEvents.
• implements PRoConPluginAPI and IPRoConPluginInterface.

When Procon starts up, it will scan its Plugins folder for files that fulfill those two requirements, compile them into their own DLLs and load them into their own AppDomains. A plugin can register events that it is interested in and Procon will forward those registered events to the plugin. What you do with these events is the fun part!

 

GitHub

Your plugin

Create a repo for your plugin. This might seem overkill for a single file, but it is great to have a list of releases directly from GitHub. All you need is your plugin and optionally a readme and license.

 

An example repo (feel free to fork it to get you started):

 

https://github.com/stajs/Stajs.Procon.TeamKillTracker

 

Example releases:

 

https://github.com/stajs/Stajs.Proco...acker/releases

 

Procon

Fork Procon:

 

https://github.com/Myrcon/Procon-1

 

Visual Studio

Update the Procon solution

If you are using a newer version of Visual Studio, you'll have to update the solution file to support it. I updated to VS2013 Ultimate without issue.

 

Add a project for your plugin

This is not strictly necessary, but I like to isolate my development from Procon core. Procon only supports .NET 3.5 so make sure your project is set to that. Add references to Procon core.

 

Add the C# file for your plugin to the project as a link. This is very important as you want the file to remain in the repo for your plugin and not in the repo for Procon.

 

Add a pre-build step to clear out any previous versions of your plugin, e.g.:

 

Code:

del "$(SolutionDir)..\builds\$(ConfigurationName)\Plugins\BF4\TeamKillTracker.*"

Add a post-build step to copy your plugin from its actual location to the build output location, e.g.:

 

Code:

xcopy "$(SolutionDir)..\..\Stajs.Procon.TeamKillTracker\TeamKillTracker.cs" "$(SolutionDir)..\builds\$(ConfigurationName)\Plugins\BF4\" /Y /E /I

Example fork:

 

https://github.com/stajs/Procon-1

 

Settings

Under "Tools > Options > Projects and Solutions > Build and Run", ensure

 

• "Only build startup projects and dependencies on Run" is unchecked.
• "On Run, when projects are out of date:" is "Always build".

Debugging

The first time you fire up Procon to debug, you'll have to enable the setting "Tools > Options > Plugins > Debugging > Enable plugin debugging", before Procon will generate debugging symbols for you.

 

When you want to step through code, you'll have to set a breakpoint in an unusual way. You won't have access to your source file directly, so you'll have to set a breakpoint by function name. This way it will break on the generated function that Procon makes when it compiles your plugin.

 

I've found it easiest to have the Breakpoints window open, copy the name of the function I want to break on, hit "New > Break at Function…" and paste the name. Once you've hit the function you'll be able to add breakpoints anywhere you want in the generated file.

 

Testing

If you normally connect to a Procon layer when administering your server, this is not what you want to connect to when developing. You need to connect directly to your game server, so that your local plugins are loaded.

 

Deploy

To deploy, FTP in to your layer and upload the plugin. You may have to stop/restart the layer if you try and delete the compiled DLLs.

 

What next?

For further help, start a thread in Plugin Development:

 

https://myrcon.net/index.php?/forum/11-plugin-development/

 

If you want to distribute your plugin through the forums, get it approved:

 

https://myrcon.net/index.php?/forum/12-plugin-approval/

[ImportBot]

Originally Posted by LCARSx64*:

 

Nice guide.

 

Prehaps this could be stickied.

[ImportBot]

Originally Posted by PapaCharlie9*:

 

Better yet, how about promoting it to Knowedge Base.