For all User Script Developers

First off I just want to thank all of you who have been developing user scripts for Planets Nu over the past couple of years. You've been doing some amazing work which has really helped to fill in the gaps of client functionality we have not had time to get to.. or didn't even know we needed.

You've also pioneered some awesome new designs and helped inspire our future additions to the user interface. I know that many of the players on Planets Nu can not imagine playing the game without some of your scripts. Seriously, thank you very much.  

In the coming days we are going to be upgrading all users to the version 3.xx edition. This release breaks many scripts which have been built and most of them have not been upgraded to version 3 yet as the changes in that release are so extensive. This unstable target makes creating userscripts a real challenge. We don't want that any more than you do. I am always excited to see the new things that are being produced. So it is time we start to formalize the plugin methodology so that we can begin to protect your hard work in the future. There is no way we'll be able to stop every script from being broken all the time. We need to be able to make changes to the UI as well (sometimes really big ones) but perhaps we can reduce the pain of upgrades in the future.  

  

That said, Into the latest version of the client we have added a new basic "plugins" model. To help prevent development issues going forward. The plugin model is very simple.

Usage:

You create a plugin object like so.
var myplugin = {

processload: function() {

//do something on load

},

loadplanet: function() {

//do something on load planet

}

... many other events

};

Then register it with the UI like so:

vgap.registerPlugin(myplugin, "nameofplugin");

Throughout the client we have added events where these methods can be called. You create a function for each event you need to hook into. The following events are available now and more can be added as needed (just let me know where you want them added):

Existing Events: processload, loadplanet, loadship, loadstarbase, loadmap, draw, showsummary, loaddashboard, showmap, showdashboard

When modifying the UI you should try to modify specific properties or sections directly by overwriting them using jquery for example: 

var shipnameplugin = { 

loadship: function() { 

$("#ShipStatusbar .SepTitle").text(vgap.shipScreen.ship.name);

}

};

vgap.registerPlugin(shipnameplugin, "changeshipname");

All map drawing must now be done using the HTML5 canvas element. The RaphaelJS paper has been removed and will not be coming back as we unify on a single technology.

To add something to the map use the "draw" event and access the vgap.map.ctx property for the canvas 2D context for HTML5 drawing.  

Example:

var drawsomething = { 

draw: function() {                

var x = 2000;

var y = 2000;

var radius = 5;  //5 is the # of map units, multiply by zoom to get screen pixels

//drawing an object with radius 5 at 2000, 2000 check to see if it is visible on the screen before drawing

if (vgap.map.isVisible(x, y, radius)) {

var ctx = vgap.map.ctx;

//convert to screen coordinates before drawing
var screenX = vgap.map.screenX(x);

var screenY = vgap.map.screenY(y);

//distances must be converted to screen pixels by multiplying by zoom amount
var screenRadius = radius * vgap.map.zoom;

//draw a circle with html5

ctx.fillStyle = "#fffff";

ctx.beginPath();                    

ctx.arc(screenX, screenY, screenRadius, 0, Math.PI * 2, false);

ctx.closePath();                    

ctx.fill();

}

};

vgap.plugins.push(drawsomething);

Additionally, each existing map element has been broken out into its own functions:

drawPlanet, drawShip, drawStar, drawNebula, drawMinefield, drawIon, drawDebris

These can be overridden like so:

vgapMap.prototype.drawPlanet = function(planet, ctx) { 

//your own draw function for planets on the 2D context (ctx)

};

Planet Screen, Ship Screen, Starbase Screen

If you want to add content to the planet screen, ship screen or starbase screen use the new api for adding sections which can be found in the leftContent function class:

Example (from planetScreen.load):

//Buildings        

//create button array for screens you need to do something

var buttons = new Array();        

buttons.push({ name: "Change Friendly", onclick: function () vgap.planetScreen.changeFriendly(); } });        

buttons.push({ name: "Build", onclick: function () { vgap.planetScreen.build(); } });       

//add the section to the screen

//parameters for addSection: params (sectionid, titletext, buttons, populatefunction)

//the populate function will be called whenever the screen is loaded or something happens that changes the data on the screen object, it should

//return the HTML you want to display in the section

vgap.planetScreen.addSection("Buildings", "Buildings", buttons,function () { return vgap.planetScreen.loadBuildings(); });

If you want to override what is there you can override the existing section population methods like so:

vgapPlanetScreen.prototype.loadBuildings = function() { 

//my own load buildings screen

};