Creating Custom Systems
=======================

This document is designed to help OXP devs to create fully custom systems. The older method, using the "planetFallOverride" flag and the "overrideRole" role will still work, but this new protocol allows for more sites per planet to be created and named.

Start by defining in shipdata.plist all the unique locations you want the player to be able to land at.
Remember there is a difference between main planet locations, extra planet locations and moon locations.

There are three components to making a fully custom system.
1. shipdata.plist entries
    Create any unique landing sites in this file.
2. landing images
    If you want the arrival report to have a custom image for your unique landing site, they can be added to the worldScripts.PlanetFall2.landingImages dictionary
3. System definition
    Define what sites you want to have on the main planet, give each location a name, and additionally define sites for any extra planets and moons as well.

** shipdata.plist **
    // this is the shipdata definition for the Royal Court in Feudal systems
    // this is a main planet entity
    "feudal-planetFall_mainSurface_FSRoyalCourt" = {
        condition_script = "feudal-planetfall-conditions.js"; // we can add a condition script for this item, so it can only be spawned in certain locations
        like_ship = "planetFall2_genericSurface"; // this is required
        is_external_dependency = yes;
        name = "Royal Court";
        // ensure there is a unique role included in "roles" that can be used to select this entry later
        // in this case, "planetFall2_mainSurface_FSRoyalCourt" is being used
        roles = "planetFall2_mainSurface_FSRoyalCourt planetFall_feudalStates planetFall2_mainSurface_externalOXP(1000) station(0) planetFall2_surface planetFall_surface";
        script_info = {
            telescope = 0; // we don't want telescope to be able to see this ship
            beacon_code = "R"; // this defines the character used on the Advanced Space Compass
            market_key = "planetFall2_mainSurface_capitalCity"; // this key allows us to mirror the market of one of the default locations
            market_type = 3; // this defines the type of market this location will have 
                            // (0 = none, 1 = like main station, 2 = SFEP style, 3 = use key to lookup original market definition)
                            // note: if you want to use the market_definition key in shipdata to define your market, market_type should
                            // be set to 1.
            landing_image_set = "feudalCourt"; // this defines the set of images to be used when landing at this site
        };
    };

    // this is the shipdata definition for a Feudal Cathedral, which is also a main planet entity
    "feudal-planetFall2_mainSurface_Cathedral" = {
        condition_script = "feudal-planetfall-conditions.js";
        like_ship = "planetFall2_genericSurface";
        is_external_dependency = yes;
        name = "Cathedral";
        // our unique role here is "planetFall2_mainSurface_Cathedral"
        roles = "planetFall2_mainSurface_Cathedral planetFall_feudalStates station(0) planetFall2_surface planetFall_surface";
        script_info = {
            telescope = 0;
            beacon_code = "C";
            market_type = 2; // because this type of market (SFEP) doesn't need a market key, we don't need to define it here.
            landing_image_set = "feudalCathedral"; // a different set of images.
        };
    };

** worldscript **
this.startUp = function() {
    var pf = worldScripts.PlanetFall2;

    // first we'll create the 2 landing image sets to match what's in shipdata
    // all the images must be placed in the "Images" folder, *not* in "Textures"
    // the entries can either be a simple string eg "feudalCourt_1.png" or a dictionary eg {name:"feudalCourt_1.png", height:568}
    pf._landingImages["feudalCourt"] = [
        "feudalCourt_1.png", "feudalCourt_2.png", "feudalCourt_3.png","feudalCourt_4.png", "feudalCourt_5.png", "feudalCourt_6.png",
        "feudalCourt_7.png", "feudalCourt_8.png", "feudalCourt_9.png","feudalCourt_10.png", "feudalCourt_11.png", "feudalCourt_12.png",
        "feudalCourt_13.png", "feudalCourt_14.png", "feudalCourt_15.png"
    ];
    pf._landingImages["feudalCathedral"] = [
        { name: "feudalCathedral_1.png", height: 568 }, { name: "feudalCathedral_2.png", height: 568 }, { name: "feudalCathedral_3.png", height: 568 }, 
        { name: "feudalCathedral_4.png", height: 568 }, { name: "feudalCathedral_5.png", height: 568 }
    ];

    // we can now add the custom definition to the location overrides dictionary
    // "0 96" is the galaxynumber followed by a space and then the system ID
    pf._locationOverrides["0 96"] = { 
        // you can define 3 sections: main, planet and moon
        // each section is an array of dictionary objects
        // for "main", the array will only have 1 element, because there is only ever 1 main planet
		main: [
            { 
                // the "roles" array lists each type of landing site to be created
                // you can specify default sites types (see list below), or unique *roles* from your shipdata. 
                roles: ["planetFall2_mainSurface_FSRoyalCourt", "capitalCity", "planetFall2_mainSurface_Cathedral", "capitalCity"],
                // the "names" array must have the same number of elements as the roles array, or left out completely
                // if left out, random names will attempt to be generated (random for default sites, "name" property from shipdata for others)
                names: ["Sir Ffoliot Cary Port, Lesser Walsingham (Royal Court)", "Lesser Walsingham (Capital City)", "Greater Walsingham (Cathedral)", "Lancaster (City)"],
		    },
        ], 
        // for planets and moons, multiple dictionaries can be defined, and they will be applied in turn to any planets/moons that get created
        // if you create 2 planet definitions, but only 1 extra planet is created, only the first definition will be used.
        // if you create 1 planet definition, and 2 extra planets are created, the first extra planet will get the first definition, while the second will 
        //    default to fully random.
        // if the section is left out, default random sites will be created based on the current spawning rules.
        /*planet: [
            {

            }
        ],
        moon: [
            {

            }
        ],*/
	};
}

List of default roles that can be used:
Main Planet: capitalCity, militaryBase, leisureComplex, factory, dump
Extra Planets: colony, militaryBase, leisureComplex, factory, dump
Moons: colonyDome, leisureDome, mine, prison, researchComplex, factory, wasteLand