Fractal Softworks Forum

Please login or register.

Login with username, password and session length
Advanced search  


Starsector 0.95.1a is out! (12/10/21); Blog post: Hyperspace Topography (10/12/22)

Author Topic: [0.95.1a] Variants Lib v0.1.1  (Read 1093 times)


  • Lieutenant
  • **
  • Posts: 80
    • View Profile
[0.95.1a] Variants Lib v0.1.1
« on: August 26, 2022, 08:58:22 AM »

Variants Lib v0.1.2

git repo

Variants Lib is a library that provides a fleet creation and spawning system that allows for more specifications than what is provided with the vannila game. Major features include:
- a file system that allows for fleets to be built based on groups of ship variants that are allotted a portion of the fleets total fp
- an officer spawning system that can be used to specify the skills and personality of officers that pilot specific ship variants
- a fleet spawning system that allows for fleets specified in this mod's file format to spawn among regular fleets
- useful classes for fleet building with this mod's features

This mod can be used to implement themed fleets that appear randomly or on special occasions. The features in this lib were primarily made for my mod Better Variants, which you could check out as an example mod for this lib.

Safe to add and remove, but you might see a lot of nebula civilian transports.
Quick Start Guide
This section covers how to get a fleet using this mod's features to spawn in the game. Being a quick start guide, this does not cover all features; read the other sections of this post for a full list. First, navigate into the "data" folder of this mod and copy the folder named "variants_lib" to the "data" folder of your mod. Second, navigate to "data/variants_lib/fleets" of your mods folder and create a copy of "example_fleet.json" in the same folder. Open the file, and fill out the fields listed in it. There are instructions on how to fill the fields in the file. Lets say you name the file "unique_fleet.json" and give it the fleetDataId "unique_fleet". Third, open "data/variants_lib/fleets/fleets.csv". Put the name of the file you made with its extension (ie. "unique_fleet.json") in the fileName field, and specify spawning weights for the numerous fleet types listed. A blank cell is equivalent to filling in a zero and will prevent "unique_fleet" from spawning among fleets of the specified type. I would recommend using 10 as a base line value for non-zero spawn weights. Last, navigate to "data/variants_lib" and open "faction_tags.csv". Put the faction you want "unique_fleet" to spawn in the factionID column, put "unique_fleet" in the fleets column, and put a number between zero and one in the specialFleetSpawnRate column. Include multiple fleet types in the fleets field by writing them in a comma separated list (ie. "unique_fleet, more_unique_fleet"). The number in the specialFleetSpawnRate column is the fraction of fleets that will spawn as the fleets specified in the fleets column. Remember to save all your files and "unique_fleet" should start spawning in the game.

Fleet Jsons
Fleet jsons are the files in which fleets are specified. They must be put in data/variants_lib/fleets in a mod's folder. An annotated example of one can be found in data/variants_lib/fleets of this mod's folder. As a brief overview, the files allow you to partition a fleet's fleet points into groups that will be dedicated to specific lists of ship variants. Fleet jsons are not merged, and the game will not load if an attempt is made to load two of them with the same id. For this reason, I would recommend prefacing all of your fleetDataIds with some unique string to avoid conflicts similar to how you would give ids to modded ships. Below is an example fleet json with an explanation of all the fields.
   # mods that need to be enabled for this file to be loaded. Use this to make fleets with content
   # from other mods which may not be enabled. Put .variant files with content from other mods in
   # data/variants_lib/modded_variants and ensure its file name is the same as its variant id
   # DEFAULT: no mods. If your mod is enabled the fleet will be loaded
   # String used to identify this fleet variant. Must be unique
   # minimum dp of fleet to be edited to this fleet variant
   # maximum dp of fleet to be edited to this fleet variant

   # If the fp of the fleet being edited is above minDP but below this field, set the DP of the fleet
   # to the value of this field
   # DEFAULT: 0, DP is not changed

   # Whether to allow auto fit on the fleet. The option here takes priority over all other features
   # in this mod that affect autofit
   # DEFAUT: no preference, do what other settings around autofit say

   # Whether to spawn this fleet json if the faction the fleets is spawning as has no heavy industry
   # DEFAULT: true

   # Personality unofficered ships in this fleet will have in combat
   # DEFAULT: the factions officer aggressiveness specified in doctrine

   # commander skills that will be added to the fleet's captain
   # DEFAULT: no additional skills

   # automatically generate freighters for this fleet, with the float being the fraction of dp given to them
   # DEFAULT: feature is not enabled

   # automatically generate tankers for this fleet, with the float being the fraction of dp given to them
   # DEFAULT: feature is not enabled

   # automatically generate personnel carriers for this fleet, with the float being the fraction of dp given to them
   # DEFAULT: feature is not enabled

   # automatically generate civilian liners for this fleet, with the float being the fraction of dp given to them
   # DEFAULT: feature is not enabled

   # variants and their amount to always add to fleets of this type
   # DEFAULT: no additional ships
   "alwaysInclude":{"ox_Standard":2, "atlas_Standard":1},

   # a script that will be run after a fleet of this type is spawned the script must implement the
   # interface variants_lib.scripts.FleetEditingScript scripts are run in the order that they are listed
   # DEFAULT: no scripts

   # Specify what portion of the fleet's dp should be dedicated to different groups of ships
   # Based on how the fleet generation system works, it's best to have ships with similar dp
   # in each partition and have the higher average dp partitions before lower dp ones
      # a partition
         # specifies the fraction of the fleets dp that will be occupied by ships in this partition.
         # So partitionWeight / sumOfAllPartitionWeights of the fleets dp will be dedicated to ships
         # in this partition. Any unused dp is given to be used by the next partition down
         # A list of variants in the partition and their respective weights. Each variant has a
         # variantWeight / sumOfAllVariantWeightsInThisPartition chance of spawning. Note that
         # spawning probabilities can be skewed if some variants can't be spawned with the partitions
         # allotted dp
      # another partition
         # Maximum amount of the fleet's dp that will be dedicated to ships in this partition.
         # Useful for capping the amount of certain ships can spawn.
         # DEFAULT: no limit on dp
         # Maximum amount of ships that will be dedicated to ships in this partition
         # Useful for capping the amount of certain ships can spawn.
         # DEFAULT: no limit on ships spawned
            # ghetto way of spawning logistics of appropriate size

fleets.csv is used to specify which fleet jsons to load and the spawning weights that correspond to each fleet. Enter the file name of a fleet json including its extension to tell the mod to load the file. The other fields in the csv are spawning weights for specific fleet types, which are strings found under the "$fleetType" memkey in the memory of ingame fleets. Enter a weight in a fleet type field to determine how likely the fleet json will appear compared to others. Leaving a fleet type field blank or set to zero prevents its corresponding fleet json from spawning as that fleet type. The blank fleets.csv in this mods folder contains all vanilla fleet types and some nexerlin fleet types as columns. Add an additional fleet types fields to the csv by adding a column with what will be stored under the "$fleetType" memkey. This file is merged with those of all other enabled mods with no overriding allowed. A filled in fleets.csv file looks something like this:

factions_tags.csv is primarily used to define spawning details for fleet jsons. The factionID field is self explanatory. The fleets field defines what fleet jsons should spawn in certain factions. Define what fleet jsons you want to spawn with a comma separated list of fleetDataIds. The specialFleetSpawnRate field is the fraction of fleets that will spawn as fleet jsons specified in the fleets field. Input a decimal number between zero and one. The tags field is input as a list of comma separated strings which can be anything. The only tag that does anything at the moment is "no_autofit", which disables autofit for all fleets of the faction. The specialFleetSpawnRateOverrides is more or less a specialFleetSpawnRate for specific fleet types. Input a comma separated list of fleet types incased in quotation marks followed by a colon and a number between one and zero (ie. "taskForce":0.8, "patrolLarge":0.5, "inspectionFleet":1.0). This file is merged with those of all other enabled mods with proper appending and overriding. A filled in factions_tags.csv should look something like this.

variants_tags.csv is used to specify details on how specific ship variants should spawn. The variantID field is for variant ids. The officerInfo field is for tags specify the skills and personality of officers that pilot the variant. Tags are input as a comma separated list. The tags hs, ce, im, dc, fm, pd, ta, bm, se, ms, gi, ew, oe, and pa correspond to the skills helmsmanship, combat endurance, impact mitigation, damage control, field modulation, point defense, target analysis, ballistic mastery, systems expertise, missile specialization, gunnery implants, energy weapon mastery, ordinance expert, and polarized armour respectively. If the ship variant has an officer, these skills are given to the officer in the order that they are written until the officer runs out of skill slots. There are also the tags ca, ti, st, ag, and re which correspond to the personalities cautious, timid, steady, aggressive, and reckless respectively. These tags specify the personality of the officer. The smods field specifies the smods a variant should be given and their order if they are to receive smods. Input the ids of the smods as a comma separated list and they will be added in the order that they are written. Note that this smods feature will only work on factions with the "no_autofit" tag in faction_tags.csv. This file is merged, but variants can not be defined twice. A filled in variant_tags.csv may look something like this:

variants_lib_settings.json contains settings for this mod. The enableNoAutofitFeatures field toggles no autofit features when spawning fleets. The enableOfficerEditing toggles officer editing features when spawning fleets. The enableFleetEditing toggles the appearance of naturally spawning fleet jsons entirely. The enableDefaultPersonalitySetting toggles whether to use the defaultFleetWidePersonality feature of fleet jsons. The universalPreModificationScripts field specifies a list of scripts that are run before fleets are processed by this mod's listener. The scripts run must implement the interface variants_lib.scripts.FleetEditingScript from the mod's api. The scripts do not run in any particular order. The universalPostModificationScripts field works the same thing as the universalPreModificationScripts except the scripts are run after fleets are processed by this mod's listener. This file is merged. Any boolean fields set to false are guaranteed to remain false after merging.

A folder for putting variants that appear in fleet jsons which require content from mods that may not be enabled. The file names of any variants in this folder must be identical to their ids.

Internal Details and Mod Compatibility
Variants Lib fleet spawning works by editing all fleets that spawn with a listener. All fleets that are processed by the listener are given the memkey "$vlmodified" which is mapped to a boolean value set to true. Additionally, all fleets spawned with fleet jsons are given the memkey "$vlType" which is mapped to the fleetDataId of the fleet json used. It's possible some may get edited and cause bad consequences. Variants Lib has some features that help prevent this. Fleets with MemFlags.ENTITY_MISSION_IMPORTANT, MemFlags.MEMORY_KEY_MISSION_IMPORTANT, MemFlags.STORY_CRITICAL, MemFlags.STATION_BASE_FLEET, or MemFlags.STATION_FLEET are never edited. Additionally, fleets from factions unregistered in faction_tags.csv are never edited. If a fleet meets none of these criteria and must not be edited, the simplest way to do so is to define the memkey "$vlmodified" in the fleet's memory before spawning it, which will prevent it from being edited by the listener entirely. Alternatively, you could set the fleet's fleet type to a unique string, but officer editing and no autofit features still run.

This is an overview of functions and fields in this mod that may be useful. If a field or function is not mentioned here you are not meant to use it. All static fields mentioned here are not intended to be edited during gameplay.
Contains constants that are relavent to this mod including memkeys.
public static final HashMap<String, FactionConfig> FACTION_DATA
It contains the data loaded from faction_tags.csv. The keys of the hashmap are faction ids which map to FactionData.FactionConfig objects.
public static final HashMap<String, FleetComposition> FLEET_DATA
It contains data from all loaded fleet jsons and fleets.csv. The hashmap maps the fleetDataId of a fleet json to its loaded json, which are stored as objects. Note that the additionalCommanderSkills, postModificationScripts, and alwaysInclude fields of FleetComposition objects can be null.
public static final HashMap<String, ShipVariantAPI> VARIANTS
It contains variants loaded from the modded_variants folder. The hashmap maps uses variant ids as keys. Variants in the modded_variants folder are only loaded if they occur in a loaded fleet json.
Functions for accessing settings relavent to this mod such as:
public static boolean OfficerEditingEnabled()
public static boolean noAutofitFeaturesEnabled()
public static boolean personalitySetEnabled()
public static float getSpecialFleetSpawnMult()
public static int getMaxShipsInAIFleet()
public static int getMaxOfficersInAIFleet()
public static boolean fleetEditingEnabled()
public static final HashMap<String, VariantDataMember> VARIANT_DATA
It contains the data from variant_tags.csv. The hashmap maps variant ids to VariantData.VariantDataMember objects.

public static void addSmods(CampaignFleetAPI fleet, float averageSmods)
Adds smods to "fleet" based on "averageSmods" which uses the smods feature of variant_tags.csv.

public static void addDmods(CampaignFleetAPI fleet, float quality)
Adds dmods to "fleet" based on "quality" which is a float from 0.0 to 1.0, with 1.0 being the best quality.

public static CampaignFleetAPI createFleet(VariantsLibFleetParams params)
Create a fleet from a fleet json with a FleetBuilding.VariantsLibFleetParams object. The fleet created will have the memkeys $vlType and $vlmodified set. There are some constructors of it with less arguments than the number of fields that automatically generate some fields. The fields of the parameters object are:
String fleetName - the name of the fleet that will appear in game
String faction - a faction id
String fleetType - the string to store under the memkey $fleetType
String fleetDataId - the id of the fleet json you want to make a fleet with
int fleetPoints - fleet points of the fleet, note that whether this number is within the min and max dp of the fleet json is not checked
float quality - 0.0f being max dmods, 1.0f being the least
float averageSmods - average number of smods of ships in the fleet, civilian ships are not given smods
int numOfficers - number of officers to give the fleet not including the fleets commander
float averageOfficerLevel - average level of officers
PersonAPI commander - the commander of the fleet
boolean enableAutofit - whether to autofit the fleet. Disabling this does not prevent dmods or smods from being added
boolean enableOfficerEditing - whether to edit the officers in the fleet to be in line with what is specified in variant_tags.csv
boolean runAssociatedScripts  - whether to run the postModificationScripts specified in the fleet json used
Random rand - a random object to use for fleet generation

public static void editAllOfficers(CampaignFleetAPI fleet, String fleetCompId)
Edit all officers in a fleet to be in line with what is specified in variant_tags.csv, the additionalCommanderSkills field of a fleet json, and the defaultFleetWidePersonality field of a fleet json.

public static void editAllOfficers(CampaignFleetAPI fleet)
Edit all officers in a fleet to be in line with what is specified in variant_tags.csv.

public static void editOfficer(FleetMemberAPI fleetMember)
If the "fleetMember" has a officer, edit it to be in line with variant_tags.csv

public static void editOfficer(FleetMemberAPI fleetMember, String fleetCompId)
If the "fleetMember" has a officer, edit it to be in line with variant_tags.csv and the defaultFleetWidePersonality field of a fleet json


This mod includes the console command vlSpawnFleet <faction> <fleetId> <fleet points> which allows you to spawn a fleet with a fleet json. Useful for testing.

Change Log
- Fixed bug with fleet generation that caused fleets to spawn with no ships
- Made fleet editing use salvage seeds for random number generation
- Added Random field to FleetBuilding.VariantsLibFleetParams
- Added the optional fleet json fields setDPToAtLeast, autofit, spawnIfNoIndustry, autoLogitsticsFreighterDP, autoLogitsticsTankerDP, autoLogitsticsPersonnelDP, autoLogitsticsLinerDP, maxDPForPartition, and

Be free to make suggestions for features
« Last Edit: September 09, 2022, 01:36:02 PM by itBeABruhMoment »


  • Commander
  • ***
  • Posts: 133
    • View Profile
Re: [0.95.1a] Variants Lib v0.1.1
« Reply #1 on: Today at 12:22:21 AM »

Looks quite interesting, also I have some questions, can it be applied to remnant fleets as well? And this mod replace all fleets, or its possible to have chance of vanilla fleet generation?

Lets say I want add some Remnant fleets using ships from Amazigh's Ship Foundry and Scrapyard Armories, one fleet of ships with temporal abilities and second fleet of Remnant low-tech refits from second mod and maybe vanilla only fleet too, and still have vanilla mixed generations occasionally.

Also it is possible to set ships which is not present in faction file? Like make Remnant fleet with Tesseract and so on.
« Last Edit: Today at 12:27:38 AM by BreenBB »