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.
4. Overriding cloud images and overlays
    Define what image to use for "clouds" when descending to dock, and for overlays that add a filter to the landing site image.

** 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.
                // adding a blank entry will revert to using the default randomised locations
                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)
                // a blank entry means "pick a random name"
                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

If you want to override the various images used for the landing VFX, do the following:

** worldscript **
this.startUpComplete = function() {
    // overriding the landing VFX images is done on a per-planet basis.
    // pick the planet for which you want to override images.
    // this this example, we are using the main planet
    var pl = system.mainPlanet;
    // if there's no main planet, just return at this point
    if (!pl) return;

    pl._pf2_landingImageOverrides = {
        clouds: {
            // this is the filename used for the "clouds" when descending to dock on the sunlit side of the planet
            normal: "normal_clouds.png",
            // this is the filename used for the "clouds" when descending to dock on the dark side of the planet
            night: "night_clouds.png"
        },
        dock: {
            // this is the filename used for the "dock" image used when descending to dock on the planet
            normal: "normal_clouds.png"
            // there is no "night" side docking pad image. docks are assumed to be well lit
        },
        overlay: {
            // this is the overlay to use on top of the landing image on the sunlit side of the planet
            normal: "normal_overlay.png",
            // this is the overlay to use on top of the landing image on the dark side of the planet
            night: "night_overlay.png"
        },
    };
}

Cloud and dock images should have dimensions of 1024x2048 px. Overlay images should be 2048x1024 px.

If you want to scale the maximum turbulence factor on a planet, do the following:

** worldscript **
this.startUpComplete = function() {
    // this this example, we are using the main planet
    var pl = system.mainPlanet;
    // if there's no main planet, just return at this point
    if (!pl) return;

    // this would increase the default maximum turbulence factor by 10%
    pl._pf2_turbulence = {scaleMax: 1.1};
}
