For all User Script Developers

Thursday, January 10, 2013
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.  


New Plugin Model

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.


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.registerPlugin(shipnameplugin, "changeshipname");

Map Drawing

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 property for the canvas 2D context for HTML5 drawing.  


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 (, y, radius)) {
var ctx =;

//convert to screen coordinates before drawing
var screenX =;
var screenY =;

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

//draw a circle with html5
ctx.fillStyle = "#fffff";
ctx.arc(screenX, screenY, screenRadius, 0, Math.PI * 2, false);

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):


//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 () {; } });       

//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

Just a Start

This is our first attempt to start to standardize the plugin functionality and protect your hard work. Please let us know if you need more events or more API's to do specific things or let us know how we can extend or improve this approach to make it suit your needs better. We truly value the contribution you guys have made and want to make this as easy and painless as possible in the future. 

Regarding the current release, we are not planning on adding any more existing script functionality into the release before it goes to everyone.