Step by Step process to automate the creation of a habitat animal

[ilodev]

Process and steps so we can all correct/contribute if there is anything missing here. This will be heavily modified during the script creation so please use comments or discord to address any changes/suggestions to want to see happening.

Concept
To automate the creation of mods for games, where the input can stay at a high level (e.g. a Habitat Animal, or a Plant for Planet Zoo, etc.).

• The idea is to populate a JSON file with the mod information so the missing files of the mod can be re-created again.
• The JSON can be filled up manually, with an UI tool, or through reading an existing mod.
• The process will then use the JSON info to create the mod structure and add the existing assets to the mod (in this case just a habitat animal for now)
• Additionally, we can reverse the process and populate the JSON from an existing mod (will be used to duplicate species information).

Process

• Select your species basic info.
• Select the source species (for coding purposes, this is the species you'll reuse most of the fdb info) (or nothing disabled for now). If there is a source species the script will read that species info into an internal structure, if not that information needs to be provided manually.
• go through the several step to configure the new species
• save/generate files
• complete the pending manual steps

Step 1 (prepopulate with known species) will later be not required, but for now it is the easiest way to start.

Inputs
To create the mod the tool will need some input data. This is the expected input tree to populate the JSON file

Mod details

    "ContentPack": {
        "Name" : "TestMod",
        "Author" : "My Self",
        "Description" : "Empty description",
        "ID" : null, 
        "Requirements": {
            "ContentPacks" : [ "PZPlus", "Aoudad" ],
            "DLCFlags" : 256,
            "api" : {
                "acse" : 0.715,
            }
        },

• Mod Name: required
• ID: optional (the tool will generate one)
• Author: optional (the tool will generate one)
• Description: optional (the tool will generate one)
• Mod requirements: optional. Mod requires are checked during database setup time and allow disabling the mod if any of the listed elements is missing.
• ContentPacks: specify names of mods that need to be installed to enable this mod.
• DLCFlags: owned DLC (using flags) to enable this mod
• existing API minimun version to enable this mod

Note: just because a mod is installed it doesn't mean it is enabled. Combination of all requirements are possible, for example to enable one mod only if PZPlus and Audad are installed, if the DLC8 is owned and ACSE version is >= 0.715. If any of these conditions is missing the mod will not be enabled.
Note: if the mod provides content that is DLC locked through the fdb that should be enough in terms of DLC requirements.

Educational Content
Mods can provide educational content unrelated to animals.

  "Content": {
    "Education" : {
        "ExampleExhibitSpecies01": {
            "Category": "Exhibit"
        },
        "ExampleHabitatSpecies02": {
            "Category": "Habitat"
        },
        "ExampleExhibitCustomContent": {
            "Name": "Name of content (goes as loc string)",
            "Description": "Test that goes as loc string",
            "Category": "Conservation"
        }        
    }
  }

TODO: Document the names generated automatically
With this JSON setup we can rebuild the education.fdb

education.fdb
EducationalContentType: from [ContentName], [Category], [Animal|EducationalContentType][ContentName]
EducationResearchPacks [ContentName], [ContentName]Education[Level] (1 to 3) or empty row
InfoboardMaterials: [ContentName], [InfoboardMaterial] (or "ED[TYPE]_[CONTENTNAME]_Mat" if missing)

Zoopedia

  "Content": {
    "Zoopedia" : {
        "ExampleExhibitSpecies01": {
            "ContentPack": "BaseGame",
            "EnclosureType": "LargeExhibit",
            "Description": "Description",

            "Class": "MyCustomClass",
            "Order": "MyCustomOrder",
            "Family": "Camelidae",
            "Genus": "Vicugna",
            "ScientificName": "ScientificName",
            "Continents": "Continents",
            "Countries" : "Countries",
            "ConservationStatus": "Domesticated",
            "WildPopulation": "WildPopulation",

            "SocialNeedsDescription": "SocialNeedsDescription",
            "AverageLifeExpectancy": ["Male life expectancy", "Female life expectancy"],
            "AverageSize": ["Male Size", "Female Size"],
            "AverageWeight": ["Male Weight", "Female Weight"],

            "Dominance": "Dominance",
            "MatingType": "is this from an enum",
            "ReproductionDescription": "ReproductionDescription",
            "ReproductionInCaptivity": "ReproductionInCaptivity",
            "SexualMaturityAge": "SexualMaturityAge",
            "SexualSterilityAge": "SexualSterilityAge",

            "ExhibitFood" : "This type of food",
            "FunFacts": [
                "This is the fun fact 1",
                "This is the fun fact 2",
                "This is the fun fact 3",
                "This is the fun fact 4",
                "This is the fun fact 5"
            ]
        }
    }

However, the smallest json definition required for a zoopedia page looks like this:

  "Content": {
    "Zoopedia" : {
        "ExampleExhibitSpecies01": {
            "ContentPack": "BaseGame",
            "EnclosureType": "LargeExhibit"
        }
    }

The missing zoopedia attributes will be prepopulated with default strings. EnclosureType and ContentPack must be withing the expected Zoopedia column options.

This is used to generate all zoopedia loc files and zoopedia images (SpeciesImageZoopedia_ and ZoopediaMap_)

Research

This json is enough to generate both the .animalunlockresearchsettings and the fdb data, however; it assumes default education/breeding/zoopedia/enrichment research pack names:

    "Research": {
        "ExampleHabitatSpecies": {
            "AnimalType" : "Habitat",
            "HoursToComplete": 30,
            "UnlockSettings": [
                ["EN_Block_of_Ice", "EN_Dog_Ball_Feeder", "*ZoopediaL1"],
                ["EN_Large_Ball", "EN_Large_Ball_Snow", "*EducationL1", "*BreedingL1"],
                ["EN_Chew_Toy", "*ZoopediaL2", "DLC11_EN_PumpkinBall", "EN_Small_Ball", "EN_Small_Ball_Ice", "EN_Small_Ball_SouthAmerica", "*SupplementL1"],
                ["EN_Bamboo_Feeder", "*EducationL2", "EN_Cardboard_Box", "EN_Present"],
                ["EN_Blood_Trail", "*ZoopediaL3", "*SupplementL2"],
                ["EN_Pinata_Pronghorn", "EN_Sprinkler", "EN_Pinata", "*ZoopediaL4"],
                ["EN_Rotation_Line_Feeder", "EN_Rubber_Duck", "ArcticWolfBreedingL2"],
                ["EN_Prey_Scented_Sack", "*EducationL3", "*ZoopediaL5"]
            ],
            "BoostData":{
                "Breeding" : [0.15, 0.30],
                "Education": [0.5, 0.33, 0.25]
            }
        }
    }

Animals
One of the main differences between exhibit and habitat animals definition comes from the prefab, only habitat animals need to define nagivation setup in their Game prefab.

After going through all the animal game prefabs, they all can basically be reduced to:

[Habitat_Species_Game] = {
	Components = {
		AnimalBrain = {
			NavigationAreaCostsFilterName = 'Default', -- Default filter cost
			NavigationModeFilterName = 'Walk',  -- Default mode name
		}
	},
	Properties = {
		PrefabName = {
			Default = '[Habitat_Species_Game] '
		},
		AnimalSpecies = {
			Default = '[HabitatSpecies]'
		}
	},
	Prefab = 'AnimalBase_Game'
},

However, AnimalBase_Game has a few more variables that could be exposed for the tool, (including VisualsMotionType)

and

[Habitat_Species_Male_Visuals] = {
	Properties = {
		ModelName = {
			Default = 'CUSTOM_Model_Name'
		},
		HitcheckModel = {
			Default = 'CUSTOM_Model_Name'
		},
		AssetPackages = {
			Default = {
				'CUSTOM_Ovl',
				__inheritance = 'Append'
			}
		},
	},
	Prefab = 'AnimalBase_Male_Visuals'
},

Same case as for the game, there are other variables that could be interesting to export for the tool in the visuals prefab.

Finally, Prefabs will be separated to individual files, loaded from ACSEData.lua.

From mod files to JSON
TBD

From JSON to mod files

• Basic script setup
  • Created new repository for the JSON < > ContentPack conversion
  • Added support to use cobra-tools code through a config file (can be removed later when integrated with cobra-tools)
  • Add custom basic mime support
    • AssetPackage
    • UserInterfaceIconData
    • ..
  • Define the mod information section of the JSON file.

Main mod tasks

• Create mod structure

  • Create mod folder
  • Add manifest file (requires mod details input)
  • Add readme/license files
  • Add folder structure: [Main, Init, AssetPackagesExtrasList]

• Implement fdb manager

  • will add the main/*.fdb if if missing
  • will be the fdb interface for insert/update/select

Creating content

• Adding Educational Content (needs the fdb manager)

  • Populate education.fdb with content info
  • Populate research.fdb with content info

• Adding Zoopedia Content (needs the fdb manager)

• Adding habitat animal (if present in the JSON)

  • Game databases (needs the fdb manager)
    • populate animals.fdb with Animal information
    • populate research.fdb with species information
    • populate modularscenery.fdb with species information

• Research

  • Load/save animalunlockresearchsettings
  • Match research settings with fdb information

• Create prefab files (needs a prefab manager)

  • Separate prefabs to individual files.
  • Create Game Prefabs using original animal as linked prefab.
  • Create Visual prefabs using original animal as linked prefab.

• Create database files

  • Collect all prefabs and create the main/database.[modname]luadatabase.lua file
  • Collect all fdbs and create the init/databases.[modname].lua file

• Mod error checking

  • Message to inform the user when a mod is disabled due to missing requirements

Tool configuration

• If config is missing, show a dialog to setup the cobra-tools path, the ovldata path and the mods/ output folder
• if not input json is provided show the quick setup dialog to read from a vanilla species
• if json input is provided show the tool UI with the mod/species configurable options

Current Script steps

• 1 Basic mod structure (create Main, Init, AssetpackagesExtrasList and default loc folder)
• 2 manifest.xml
• 3 Readme.md
• 4 ovls.include (and create included folders AssetpackagesExtrasList and UI/Textures/Infoboards_{modName}/
• 5 UI .assetpkg files (and create assetpkg folders: Animal_Talk_Point_{modName}, AnimalSpecies_{modName}, Zoopedia_{modName})
• 6 Prepare databases (copy structure and default tables: Zoopedia, Research, Education are common, then also Exhibits or Animals&ModularScenery for Exhibit/Habitat animals)

Per Species (both exhibit and habitat)

• 8 Collect and create default species loc files
• 8.1 Add species colour variation loc strings based on variation type.
• 9 collect species UI images
• 9.1 Add species Thumbnail data based on colormorphs
• 9.2 Create assetpks, userinterfaceicondata, png and tex of all UI images
• 10 Add species default tags
• 11 Collect and create gender assetpackages
• 12 Collect and create prefabs (Game and Visual prefabs, with a table of options/properties)
• 13 Create animal unlock research settings
• Create education data
• Create Zoopedia data
• Create research data
• Create animal data
• Add additional tags

ModularScenery
Adding species tag to scenery items (still needs some more work)

• M0 Create assetpkg and fdb reference
• M1 Create the loc strings
• M2 Create the UI icon (png/tex/userinterfaceicondata)
• M3 add scenery data to the fdb
• M3.1 Add additional tag locs

Blueprint (built-in)
Adding species tag to blueprints

• B0 Create assetpkg and fdb reference
• B1 Create the loc strings
• B2 Create the UI icon (png/tex/userinterfaceicondata)
• B3 add blueprint data to the fdb
• B3.1 Add additional tag locs

Education (Species or Conservation)

• E1 Create the loc strings for Conservation type
• E2 Create the material (fgm,tex,png). If material name is not specified, create one.
• E2.1 add templates for conservation content type
• E3 Add the education data to the fdb
• E3.1 If Habitat/Exhibits content type is missing research data create it.

Zoopedia (Habitat/Exhibits)

• Z1 Create the loc strings
• Z1.2 Add missing zoopedia definition (class/family/order/genus)
• Z2 Create the Zoopedia UI images
• Z3 Add the zoopedia data to the fdb
• Z3.1 Add fun facts with research data.

Research Item (Animal/Mechanical)

• R1 Create the loc strings
• R2 Create Research Unlock file
• R3 Create the Research UI images
• R4 Add the research data to the fdb

ContentPack wrap up

• Create Databases.{modName}.lua with the mod databases
• Create ACSELuadatabase
• Create {modName}LuaDatabase

ACSE wrap up

• Create ACSELuadatabase
• Create {modName}LuaDatabase

Finishing TODO

• Allow composing a mod from separated json files
• Allow saving the png content for UI elements in the JSON file
• bring back the function to default loc files content to their txt name, I need it erroring for now so I know the data I'm missing.
• Allow selecting what data to regenerate so we don't overwrite half of the mod again