Component Blueprints

Components and Json

These define both Ship components, and Installations. The core of the game engine sees ShipComponents and Installations as the same type of object. The engine code reads the json files, json files which are labled "ComponentTemplates" ie: "Type": "ComponentTemplates", at the top of the file are treated as a json dictionary of components. the key is a guid which represents the component template's ID, and the value is data which makes up the component. (at some point I might change this and make it save to a list instead of a kvp dictionary) Most of the entries at the start of each json ComponentTemplate should make sense:

"Name": a text field for the name of the component "Description": a text field for the description of the component "ID": a guid entry, this should match the key "MassFormula": a formula entry which calculates the mass of the component "VolumeFormula": a formula entry which calculates the volume of the component "HTKFormula": a formula entry which calculates the hitpoints of the component "CrewReqFormula": a formula entry which calculates the crew requirement of the component "ResourceCostFormula": this should be a key,value pair dictionary. the key should be the ID of a mineral or refined material. The value is the amount, and can be a formula. "ResearchCostFormula": a formula entry which calculates the research cost requirement of the component (components typicaly need to be researched after they've been designed by the player, can be 0) "CreditCostFormula": a formula entry which calculates the credit cost requirement of the component (not currently used anywhere) "BuildPointCostFormula": a formula entry which calculates the construction cost requirement of the component "MountType": this should be a comma separated list, see bellow for a list of ComponentMountTypes, describes what this can be installed on. "CargoTypeID": if the above list includes "ShipCargo" this should have a guid which matches one of the CargoType guid in CargoTypes.json "IndustryTypeID": this should match one of the IndustryType guid from the IndustryTypes.json an industry component which can construct this type of industry item will be able to make this. "ComponentAbilitySDs": this is a list of "ComponentAbilitySD" each of these "attributes" (should be attributes, note to self to fix this) help define what the component design ui displays in game. if one of these attributesis tagged as DataBlobArgs() and has the AbilityDataBlobType it will attempt to create a hardcode attribute of the datablobtype (needs renaming) when the component template is loaded. these define what the component is actualy capable of doing once installed on a ship or colony.

ComponentSD Parameters:

As of this writing there are:

• [Size] (renamed to [Mass])
• [Mass]
• [Volume]
• [Crew]
• [HTK]
• [ResearchCost]
• [MineralCosts]
• [CreditCost]
• [GuidDict] This is a special one used to get a dictionary for the DataBlobArgs() function

GuiHints

Each Property can have a GuiHint which tell the ui what to display, This is an enum which are defined here: https://github.com/Pulsar4xDevs/Pulsar4x/blob/Master/Pulsar4X/GameEngine/Engine/DataStructures/Enums.cs These are defined as [flags] but I don't think the ui currently uses them as such. As of writing this we have:

Function Name	Description
null	eg json property doesnt have this line, Don't display anything
None	Don't display anything
GuiDisplayBool	Unused
GuiTechSelectionList	Allows selection from a list of techs (unsure if working properly)
GuiSelectionMaxMin	Displays a float slider allowing the user to tweak between a in and max
GuiTextDisplay	Displays the PropertyFormula, used to show the player non (directly) tweakable data
GuiEnumSelectionList	Displays a list the user can select from, currently not working/unusued
GuiOrdnanceSelectionList	Displays a list of ordnances
GuiTextSelectionFormula	Displays a list of selectable strings
GuiSelectionMaxMinInt	Displays an int slider
GuiFuelTypeSelection	Displays a list of fuel types
GuiTechCategorySelection	??

ComponentSD Formula

As well as the built in ones found here: https://github.com/ncalc/ncalc/wiki/Functions We also have:

• Ability(int index) this returns the ability at the given index
• PropertyValue('Ability Name') this returns the PropertyFormula value of the given name.
• TechData(Guid techGuid)
• DataBlobArgs() this will return a list filled with each of the parameters fed it. used in an AbilitySD that has the DataBlobType set.
• GuidString(Guid someGuid) this will return a guid, used in conjunction with DataBlobArgs when a guid needs to be passed as an argument for datablob creation.
• EnumDict(EnumType) this is used in conjunction with the dictionary.

ComponentMountTypes:

• ShipComponent
• ShipCargo
• PlanetInstallation
• PDC
• Fighter

Component Json Example: Engine

{
  "Type": "ComponentTemplate",
  "Payload": {
    "UniqueID": "conventional-engine",
    "Name": "Conventional Rocket Engine",
    "Formulas": {
      "Description": "A Newtonian Thruster",
      "Mass": "PropertyValue('Mass')",
      "Volume": "Max(1, [Mass] / 150)",
      "HTK": "Max(1, [Mass] / 100)",
      "CrewReq": "0",
      "ResearchCost": "[Mass] * 0.5",
      "CreditCost": "[Mass]",
      "BuildPointCost": "[Mass]"
    },
    "ResourceCost": {
      "stainless-steel": "[Mass] * 0.15",
      "titanium": "[Mass] * .25",
      "aluminium": "[Mass] * .3",
      "tungsten": "[Mass] * .05",
      "copper": "[Mass] * .25"
    },
    "ComponentType": "Engine",
    "MountType": "ShipComponent, ShipCargo, Fighter",
    "CargoTypeID": "general-storage",
    "IndustryTypeID": "component-construction",
    "Properties": [
      {
        "Name": "Mass",
        "Units": "kg",
        "DescriptionFormula": "'The size of the engine in kg'",
        "GuiHint": "GuiSelectionMaxMinInt",
        "MaxFormula": "TechData('tech-conventional-engine-max-size')",
        "MinFormula": "TechData('tech-conventional-engine-min-size')",
        "StepFormula": "1",
        "PropertyFormula": "250"
      },
      {
        "Name": "Exhaust Velocity",
        "Units": "m/s",
        "DescriptionFormula": "'Specific Impulse in m/s, can be increased by research'",
        "GuiHint": "GuiTextDisplay",
        "PropertyFormula": "ExhaustVelocityLookup(PropertyValue('Fuel Type')) + TechData('tech-conventional-engine-exhaust-velocity')"
      },
      {
        "Name": "Thrust",
        "Units": "N",
        "DescriptionFormula": "'The maximum thrust output of this engine'",
        "GuiHint": "GuiTextDisplay",
        "PropertyFormula": "PropertyValue('Exhaust Velocity') * PropertyValue('Fuel Consumption')"
      },
      {
        "Name": "Fuel Type",
        "DescriptionFormula": "'The type of fuel the engine burns'",
        "GuiHint": "GuiFuelTypeSelection",
        "GuidDictionary": {
          "fuel-storage": "'conventional'"
        },
        "PropertyFormula": "GuidString('rp-1')"
      },
      {
        "Name": "Fuel Consumption",
        "Units": "kg/s",
        "DescriptionFormula": "'Fuel Consumption per second'",
        "GuiHint": "GuiTextDisplay",
        "PropertyFormula": "[Mass] * 0.3 * TechData('tech-conventional-engine-fuel-consumption')"
      },
      {
        "Name": "DataBlob",
        "DescriptionFormula": "''",
        "GuiHint": "None",
        "PropertyFormula": "AtbConstrArgs(PropertyValue('Exhaust Velocity'), PropertyValue('Fuel Type'), PropertyValue('Fuel Consumption'))",
        "AttributeType": "Pulsar4X.Movement.NewtonionThrustAtb"
      },

      {
        "Name": "Sensor Signature",
        "Units": "unknown",
        "DescriptionFormula": "''",
        "GuiHint": "None",
        "PropertyFormula": "AtbConstrArgs(3500, PropertyValue('Thrust'))",
        "AttributeType": "Pulsar4X.Sensors.SensorSignatureAtb"
      }
    ]
  }
}

ComponentTemplateSD is made up of a list of ComponentTemplateAbilitySD:

This describes a ship components attributes and sets formulas and guihints to define whether an ability is player adjustable and/or/if it derives it's values from other abilities or tech.

StaticToDesign factory:

This Takes a ComponentTemplateSD, factionTechDB, and the StaticDataStore, and builds a ComponentDesignDB and ComponentAbilityDesignDBs doing so it creates a ChanedExpression parser for each formula in the ComponentTemplateSD and ComponentTemplateAbilitySD The Gui will take this, allow teh user to input values where defined, re-calculating the formula and returning the ComponentDesignDB back to the lib, passing it to:

DesignToDesignEntity factory:

Takes the ComponentDesignDB, builds ability Datablobs and adds them to an Entity, creating a Component Entity of that type of component. it also creates a TechSD* and adds it to the factions ResserchableTechs dictionary.

*Arguably SDs should not be created in the middle of the game, however this SD does not go into the static datastore, only into the faction's TechDB. we could create another DB for this, however it'd be an almost exact mirror of the SD, so it seems a little pointless...