Fractal Softworks Forum

Please login or register.

Login with username, password and session length
Advanced search  

News:

Starsector 0.97a is out! (02/02/24); New blog post: Simulator Enhancements (03/13/24)

Author Topic: [0.97a] Variants Lib v0.5.2  (Read 32581 times)

itBeABruhMoment

  • Commander
  • ***
  • Posts: 157
    • View Profile
[0.97a] Variants Lib v0.5.2
« on: August 26, 2022, 08:58:22 AM »

Variants Lib v0.5.2

git repo
download


Variants Lib is a library that provides fleet generating and spawning utilities that allows for more control than what is provided with the base game. Major features include:
- a file system that allows for the building and spawning of custom fleets with no code required
- fleet building utility classes

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
Spoiler
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 better understanding of the fields you're going to be filling in. 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 mod's 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 column, 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. Using 10 as a base line value for non-zero spawn weights is recommended. 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 greater than 0 and less than 1 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.
[close]

Files
Spoiler
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 the previously mentioned example fleet json.
Spoiler
{
   # the classpath of the fleet factory to load this fleet json with, the class in this field must
   # extend variants_lib.data.VariantsLibFleetFactory
   # DEFAULT: variants_lib.data.VariantsLibFleetFactory
   "usingFactory":"variants_lib.data.VariantsLibFleetFactory",
   
   # 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
   "requiredMods":["variants_lib"],
   
   # String used to identify this fleet variant. Must be unique
   "fleetDataId":"example_fleet",
   # minimum dp of fleet to be edited to this fleet variant
   "minDP":70,
   # maximum dp of fleet to be edited to this fleet variant
   "maxDP":400,

   # 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
   "setDPToAtLeast":100,

   # 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
   "autofit":false,

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

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

   # commander skills that will be added to the fleet's captain
   # DEFAULT: no additional skills
   "additionalCommanderSkills":["support_doctrine"],

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

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

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

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

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

   # 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
   "fleetPartitions":[
      # 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
         "partitionWeight":30,
         # 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
         "variants":{
            "onslaught_xiv_Elite":50,
            "onslaught_Elite":50,
         }
      },
      # another partition
      {
         "partitionWeight":40,
         "variants":{
            "dominator_AntiCV":13.16,
            "dominator_Assault":13.16,
            "dominator_Support":13.16,
            "dominator_Outdated":13.16,
            "eagle_Assault":7.89,
            "eagle_xiv_Elite":18.42,
            "mora_Assault":10.53,
            "mora_Strike":10.53,
         }
      },
      {
         "partitionWeight":20,
         "variants":{
            "falcon_xiv_Elite":20,
            "enforcer_Assault":20,
         }
      },
      {
         # 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
         "maxDPForPartition":12,
         # 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
         "maxShipsForPartition":3,
         "partitionWeight":2,
         "variants":{
            "hound_Standard":100,
         }
      },
      {
         "partitionWeight":3,
         "variants":{
            # ghetto way of spawning logistics of appropriate size
            "colossus_Standard":10,
            "atlas_Standard":100,
            "buffalo_hegemony_Standard":1,
         }
      },
      {
         "partitionWeight":3,
         "variants":{
            "phaeton_Standard":1,
            "prometheus_Super":100,
         }
      },
   ],
}
[close]

data/variants_lib/fleets/fleets.csv
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 in game 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 additional fleet types fields to the csv by adding a column with the string that will 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:
Spoiler
[close]

data/variants_lib/factions_tags.csv
factions_tags.csv is primarily used to define spawning details for fleet jsons. The factionID field is self explanatory. The fleets field defines which fleet jsons should spawn in certain factions. Define which 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. 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 most fleets of the faction. The specialFleetSpawnRateOverrides is a specialFleetSpawnRate field 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.
Spoiler
[close]

data/variants_lib/variant_tags.csv
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 defence, target analysis, ballistic mastery, systems expertise, missile specialisation, gunnery implants, energy weapon mastery, ordinance expert, and polarised 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:
Spoiler
[close]

data/variants_lib/variants_lib_settings.json
variants_lib_settings.json contains settings for this mod. The enableNoAutofitFeatures field toggles no autofit 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.

data/variants_lib/modded_variants
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.
[close]

Internal Details and Mod Compatibility
Spoiler
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 create problems. 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.
[close]

Classes
Spoiler
There is documentation in jars/VariantsLibProject/build/docs/javadoc of this mod's folder. If you're looking to use this mod's fleet generation utilities the variants_lib.data package and the VariantsLibFleetFactory class are likely of interest to you. Also, note that you can use java's inheritance features to modify the logic of the variants_lib.data.VariantsLibFleetFactory by extending the class and overriding the methods you want to change. For example, if you wanted the VariantsLibFleetFactory to name every ship "bob" you could write something like this.
public class ExampleFleetFactory extends VariantsLibFleetFactory {
    @Override
    protected FleetMemberAPI createShip(final String variantId) {
        final FleetMemberAPI ship = super.createShip(variantId);
        ship.setShipName("bob");
        return ship;
    }
}
You can use this with the "usingFactory" field of fleet jsons to run your own logic when generating specific types of fleets.
[close]

Misc Features
Spoiler
- the console command vlSpawnFleet <faction> <fleetId> <fleet points> which allows you to generate and spawn a fleet with a fleet json
- the f8 dev reload reloads this mod's files
[close]

Change Log
Spoiler
v0.5.1
- may or may not have fixed an infinite loop

v0.5.0
- Updated to version 0.97 of Starsector
- Minor bug fixes

v0.4.0
- Fixed officers not getting generated correctly
- Reworked personality setting system
- Reworked variant data system

v0.3.0
- Updated to Starsector version 0.96a

v0.2.0
- made fleet generation system use a factory design pattern
- general refactoring
- created javadocs

v0.1.2
- 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
  maxShipsForPartition
[close]

Feel free to ask questions, report problems, or suggest features

« Last Edit: February 26, 2024, 07:58:05 AM by itBeABruhMoment »
Logged

BreenBB

  • Commander
  • ***
  • Posts: 150
    • View Profile
Re: [0.95.1a] Variants Lib v0.1.1
« Reply #1 on: December 04, 2022, 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: December 04, 2022, 12:27:38 AM by BreenBB »
Logged

itBeABruhMoment

  • Commander
  • ***
  • Posts: 157
    • View Profile
Re: [0.95.1a] Variants Lib v0.1.1
« Reply #2 on: December 05, 2022, 10:30:19 AM »

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.
Yes, just make sure you put the .variant files with modded stuff in data/variants_lib/modded_variants folder
Logged

itBeABruhMoment

  • Commander
  • ***
  • Posts: 157
    • View Profile
Re: [0.96a] Variants Lib v0.4.0
« Reply #3 on: June 18, 2023, 10:32:30 PM »

New release with some bug fixes
Logged