[mod] Stellaris Portrait File Generator

[ModderWhoModsThings]

View File

Stellaris Portrait File Generator

---

Description:

The Stellaris Portrait File Generator (SPFG) is a powerful yet lightweight Java program specifically designed to handle the portrait file code for the mod Vanilla Framework Continued (hence the existence of a hardcoded futa field). Vanilla Framework handles over 6000 portraits spread over dozens of species, so it is not feasible to update the portrait files (the files found under Stellaris/gfx/portraits/portraits that define the images associated with a species) of that mod manually. The design of this program is highly optimized to reduce the amount of work a human user must put into managing large amounts of portraits. While it will take some initial effort to create the species files used by the program, once finished you can update hundreds of species’ codes at once with a few clicks. It uses special files called “species files” to store data about a Stellaris species. It uses another kind of file, templates, to determine how the portrait files are coded. Templates are easily interchangeable so can use a custom template to create code for any mod, though only male/female/futa genders are currently supported.

 

Requirements:

The sole requirement for this program is to have Java installed on your device. The program may not run if the Java installation is outdated, so if you have trouble running the executable try updating Java.

 

Compatibility:

This program is only supported for the Windows 10/11 operating systems. I do not know if it will work on other operating systems but I cannot provide any help if you want to try it.

 

Installation:

This program is as portable as it gets, it consists of a single executable file (Stellaris Portrait File Generator.jar). Simply download this executable and put it wherever you want it on your computer. To uninstall, just delete the executable.

 

How It Works:

If you are interested in this program it is best to download and read the manual. This section will only go over the basic ideas.

 

The Portrait File Generator is very simple, it reads data from a special species file and uses it to fill out a template. Species files are text documents that store all the necessary data about a set of portraits to make a portrait file. Species files are specific to the SPFG and can be created using the Species File Maker included in the program. Templates are basically the code for a species file, except actual values are replaced with indicators such as NAME or MALES so that the file generator knows where to put the data. You can create your own templates and use them to create custom-coded portrait files. There is also support for bulk species files, files that are used to generate many portrait files at once from many different species files, so you can update your entire mod in a few clicks!

 

VF Kit:

The VF Kit contains the templates, species files, and bulk species files used to make Vanilla Framework Continued. They serve as an example of working files and anyone who wants to make their own version of VF is free to use them.

 

The template(s) included in the VF Kit will up to date, however they will usually be labelled for an old version of VF as I rarely need to make changes to the templates when updating the mod.

 

The VF Kit will typically be updated every time an update is made to the SPFG. If you want a version of the kit that is up to date with VF Continued, just ask for it in the comments

 

Source Code:

The source code is a copy of the Eclipse project the program was made in.

 

Java Issues:

Any issue preventing you from opening the program in the first place is likely an issue with Java rather than my program itself. While you are welcome to ask for help here, I lack the expertise to help with Java issues, so you will need to troubleshoot the problem yourself. If you look up the error message you receive, you should find several actions you can take to help resolve any possible issues with Java. You can also try opening the source code in Eclipse IDE, and either trying to compile the code into an executable jar file yourself or simply running it inside of Eclipse (It works the same whether launched from an executable or an IDE). I really wish I could help everyone more, but I'm simply not an expert Java troubleshooter, and you are in a better position to resolve your issue than I am.

 

Known Issues:

• Currently the species file structure does not support any spaces in species names, portrait names, portrait greetings, or portrait filepaths as spaces are used to organize the file. This may be changed in future updates.

 

Included Tools:

The program includes some additional tools that are useful for making species mods.

• File Renaming Tool: you may select a group of files from the computer and rename them in a predictable pattern.

 

Changelog:

10/23/2025 - SPFG 1.3

• Added "extension" field to renaming tool, allowing you to change the extension of renamed files. Previous version would not affect extensions. 
• Fixed error when selected files on the renaming tool is null. 
• Manual updated for version 1.3. 

1/31/2025 - SPFG 1.2

• Added renaming tool useful for renaming large amounts of files in a predictable pattern.
• Manual updated for version 1.2.

10/23/2024 - SPFG 1.1

• Added status label informing users if there are unsaved changes.
• Added repetition tool useful for generating portrait names to copy and paste into SFM inputs.
• SFM save button now shows popup message if there is no file opened.
• Species are now prevented from being created with blank names.
• UI now updates properly when a file fails to open.
• Version 1.0 manual still in use as no major changes were implemented this update. The only new tool is the repetition tool, which is fairly simple and doesn't affect the rest of the program so users can safely experiment to see how it works (it literally just generates some text so you can copy/paste portrait names rather than type them out manually).

---

• Submitter
  ModderWhoModsThings
• Submitted
  05/27/2024
• Category
  Stellaris
• Requirements
  Java

 

[Sabo Sabo]

👍

[vanas_1111]

source? don't want to run closed source tool like this

[ModderWhoModsThings]

11 hours ago, vanas_1111 said:

source? don't want to run closed source tool like this

understandable, I'll have the source code up in a few minutes.

[cocendic]

I was googling for something like this yesterday! Thank you!

[ModderWhoModsThings]

15 minutes ago, cocendic said:

I was googling for something like this yesterday! Thank you!

You're welcome! I'm surprised that several people have already taken notice of the program, as it is a very specific tool and there's probably only a few dozen portrait mods on the website.

[DairuggerXV]

I'm getting an error: Virtual Machine Launcher: A Java Error has occurred. I have the latest version of Java on my machine, so hopefully that's the right version. I've tried redownloading and rebooting.

[ModderWhoModsThings]

1 hour ago, DairuggerXV said:

I'm getting an error: Virtual Machine Launcher: A Java Error has occurred. I have the latest version of Java on my machine, so hopefully that's the right version. I've tried redownloading and rebooting.

Is this error preventing you from launching the program in the first place? Because if so, there's unfortunately not much I can do to help. I simply not an expert in Java, and I can't figure out how to get the program working on everyone's systems. Supporting standalone programs is a lot harder than supporting a mod, as I have no idea what kind of environment my program will be operating in. You're just going to have to look up your issue and troubleshoot it on your own. I did a quick search and it looks like virtual machine issues in Java aren't uncommon and there are many ways to try and fix them.

 

You could also try downloading the source code, opening it in a code editor such as Eclipse, and compiling an executable jar file yourself to see if you can get a working version. I can explain how to open and compile a project on Eclipse if you have trouble figuring it out. Also, the latest version of Java should always be able to run this program, so Java version isn't likely the issue.

[DairuggerXV]

I can get it to run in Eclipse at the very least. Any attempt to compile seems doomed to failure. Thank you.

 

[megaera]

Keeps crashing/Not starting (A Java Exception Occurred). Windows 11. Java up to date.
 

 

Edited May 30, 2024 by megaera

[ModderWhoModsThings]

3 minutes ago, megaera said:

Keeps crashing/Not starting (A Java Exception Occurred). Windows 11. Java up to date.

I don't have the expertise to help with any Java issues. You will have to look up the issue yourself and troubleshoot it, there are usually numerous steps you can take to try resolving Java malfunctions. Alternatively, you can open the source code in Eclipse and try to compile it yourself or simply run it through Eclipse like the other guy did.

[Dragen_Heir]

This 100% is why I despise Java... well that and it's monolithic codebase that tries to do everything but only manages to make a basic Hello World take 12-15 lines of code.

 

For your debugging purposes, here's the output when you run the command: java -jar 'Stellaris Portrait File Generator.jar'

Error: LinkageError occurred while loading main class Program.Program
        java.lang.UnsupportedClassVersionError: Program/Program has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 55.0

 

In other words: This jar file was built with the blazing newest Java version that Eclipse could foist on you... something that you have to install because Java likes to keep all it's old versions as standalones... think .NET on steroids.

 

For those who are saying their Java is up-to-date, that probably is the case... for the version of Java you already have installed, however, in my case, as you can see, my Java version supports up to 55, whereas the boilerplate version packaged with Eclipse is 61, if you have a later version of Java, for example 62, or 63 if they even exist right now, they'll be supported, as the versioning is kinda additive, though a lot of older functions from the Sun days have been pruned from what I hear... but I'll not bore you with that gnawed bone.

 

Hold onto your assholes because this is where shit gets even dumber...

 

Alright, so recently (for Java, it happened in 2019), Oracle's gone and started changing the terms of service for Java, and for a long while JRE and JDK files were unified before this ToS change, so afterward, Eclipse has gone and started making their own "Version" of Java due to this schism, one that divides the JRE and JDK files again (users only need the JRE files, developers need the JDK), now I'll be fair here, I did a bunch of test installs and retries using the above command, and it seems I did a foul as Powershell did not update until after I closed it out, so any one of these steps could have solved this problem, but the last one is what probably did it because it changed keywords in windows.

 

1. Forcibly installing Java from the ORACLE website.
   • https://www.java.com/en/download/
2. Forcibly installing the Java JDK for version 17 (the major version tied to 61)
   • https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html
3. Installing the JRE for version 21 provided by Eclipse
   • https://adoptium.net/temurin/releases/?os=windows

Now, again, after this whole pile of crap, I have to re-iterate, I loathe this language, hated it in 2005 when I had to learn it, hated it when I tried to use that knowledge to tweak some mods in 2009, and hate it today, and I hope you can see above exactly why this language is a nightmare after I spent five minutes diagnosing the problem, then spent nearly an hour trying to find the solution, it's the Java way.

[ModderWhoModsThings]

On 6/1/2024 at 10:36 AM, Dragen_Heir said:

Now, again, after this whole pile of crap, I have to re-iterate, I loathe this language, hated it in 2005 when I had to learn it, hated it when I tried to use that knowledge to tweak some mods in 2009, and hate it today, and I hope you can see above exactly why this language is a nightmare after I spent five minutes diagnosing the problem, then spent nearly an hour trying to find the solution, it's the Java way.

This is the first thing I've published in Java, and now that I see all the problems people are having I'm probably going to be working in other languages for future projects. Thank you for posting an explanation of where some of the problems originate from, as well as some troubleshooting steps for the error.

[Dragen_Heir]

If you're intending to do future projects like this, I have a couple of suggestions / industry practices for you:

• For standalone apps, it's best to keep a config / memory file to store the last opened folder or operate from the PWD (Present Working Directory), having to directory traverse repeatedly can become tiresome, especially for a power tool.
• Maximize compatibility, don't just use the latest and greatest, make sure that a reasonable amount of your potential userbase can run it without issue.
• This application is somewhat confusing regarding what exactly it's supposed to do, does it upgrade old portrait mods to VF? Does it generate VF portrait mods based on specific rules that are tied to the filename? I get it reads the species files either from the maker or from the templates, but how is it sorting the files like 2122347.dds into a correct slot, how do I sort them in-app, or is it something that has to be done at the file-name level?
  • This point is more on clarity of purpose & description, if the users don't know how to operate the application, they will become frustrated with it quickly, as dismissive as it may sound, you have to treat all users like they're in kindergarten, because otherwise you'll get your head too far in the clouds and talk over the layman without even realizing it.
• I like the idea of separating the templates from the core code, so that you don't have to recompile if VF changes something, but instead of manually loading both the templates and the default species files, why not load them off-the-rip if they're present in the application's folder structure...
  • E.G.

    • SPFG > V1.1 > Lib
      SPFG > V1.1 > Lib > Species
      SPFG > V1.1 > Lib > Templates
      

      This once again ties back to the config file, if they have the "Lib" folder somewhere else, they could point to it, and have it saved with the portable file to read the Species and Template files. Then in the application the user selects which species and template to use for a particular folder in a portrait mod.

• Separate your "Load" and "Run" functions, that way to the user it's clear exactly what they need to do and what they don't, there's a few ways to do this:

  • Left / Right split, all the load buttons on the left, with the "Generate" button on the right of the header with a clear divider / space between them so they don't blend into the load buttons.

  • Top / Bottom split, all the load buttons at the top of the application, and at the bottom the "Generate" button at the bottom-right (the right side is largely important only because that's how we're trained to read, so naturally our brains go to the "End" of a page by gravitating to the bottom right.

  • Color-Code your "Load", "Run", and "Cancel" buttons, this can also be important for the colorblind; however, subtle queues like that can help users understand that at the very least, the left button has a different use to the right button at a glance, giving them a reason to consider those differences.

These are mostly UI / UX suggestions, I can't speak much to the application's function itself because it doesn't quite seem to do what I want it to do (and that is to create VF races from existing portrait packs found on LL) without a lot of manual work that, if any of those portrait packs update, I'm boned on. No fault of the application here, just sayin' I can't speak to the code itself, just the front-end as that's as far as I got after I realized it didn't do what I thought it could do.

[ModderWhoModsThings]

8 hours ago, Dragen_Heir said:

If you're intending to do future projects like this, I have a couple of suggestions / industry practices for you:

Thanks for the advice, I'll definitely be taking all this into consideration if/when I make a new update.

 

8 hours ago, Dragen_Heir said:

These are mostly UI / UX suggestions, I can't speak much to the application's function itself because it doesn't quite seem to do what I want it to do (and that is to create VF races from existing portrait packs found on LL) without a lot of manual work that, if any of those portrait packs update, I'm boned on.

Making the species files is still a somewhat laborious process with this tool. In order to put a portrait (a single image) into a portrait file you need a greeting sound, a filepath, and a name for that portrait. The Species File Maker has you define a directory where you can find all the portraits you are adding to the species, so it automatically generates the filepath, and there is a similar automated process with greeting sounds. You have to manually enter or copy/paste the names of each portrait in a species into the Species File Maker. Other tools automatically find your dds images to define your portraits, while in this one you tell the program what portraits you want in a species and where to find them, allowing for greater control where you don't need to have a specific naming or file structure. Once you have the species files set up, they can easily be modified by loading them into the Species File Maker, or they can be loaded into the Portrait File Generator along with a template file to create a portrait file. The template included in the VF Kit can be used to make VF species that can use LV traits and VF policies to control which genders (including futa) are shown. Users can also create their own templates to create custom species files.

 

I'll look into making this program more clear and user-friendly when I have some extra time, thanks again for the valuable feedback.

[Yourmamu]

Does the portrait txt generator work with 3.12? A lot of portrait mods broke after that update. Also an aside from that, what's the ideal size for a portrait image? I have an image generators and Anubians that I simply must see contributed to the Stellaris forum.

[ModderWhoModsThings]

On 7/29/2024 at 11:14 PM, Yourmamu said:

Does the portrait txt generator work with 3.12? A lot of portrait mods broke after that update. Also an aside from that, what's the ideal size for a portrait image? I have an image generators and Anubians that I simply must see contributed to the Stellaris forum.

The portrait files did not change with the 3.12 update, so the vf2.1b template included in the vf kit still works for the current version of stellaris. The Portrait File Generator takes information about a species from a portrait file (created using the Species File Maker included in the program) and uses it to fill out a template containing the code structure for the species file. This means that even if an update changes the way portrait files work you just need a new template rather than an updated program. The user manual included in the SPFG download explains how the program works.

 

Vanilla Framework uses 500*320px dds (with mipmap) images, however I've heard that there may be other dimensions that work better. 500*320 will definitely work, though.

 

This forum contains additional information on how to create a species mod for stellaris:

 

[Yourmamu]

On 7/31/2024 at 7:20 PM, ModderWhoModsThings said:

The portrait files did not change with the 3.12 update, so the vf2.1b template included in the vf kit still works for the current version of stellaris. The Portrait File Generator takes information about a species from a portrait file (created using the Species File Maker included in the program) and uses it to fill out a template containing the code structure for the species file. This means that even if an update changes the way portrait files work you just need a new template rather than an updated program. The user manual included in the SPFG download explains how the program works.

 

Vanilla Framework uses 500*320px dds (with mipmap) images, however I've heard that there may be other dimensions that work better. 500*320 will definitely work, though.

 

This forum contains additional information on how to create a species mod for stellaris:

 

Thank you. I'll get to work on the weekend and hopefully make something. If you do see the Anubians on the Stellaris form, expect a share of the credit for explaining this to me :).

[ModderWhoModsThings]

6 hours ago, Yourmamu said:

Thank you. I'll get to work on the weekend and hopefully make something. If you do see the Anubians on the Stellaris form, expect a share of the credit for explaining this to me :).

No problem, you can ask here or at the forum I linked to if you have any further questions. Also, if you use SPFG for your race, keep in mind that the only template (template_vf2.1b) included in the VF kit is designed for males, females, and futas. If you do not have any futas but still want to use that template, just use your female images for both futas and females. I will add more template options in future updates when I have the time to create and test them.

[flamelordytheking]

How do i find the existing Species Files to edit using this tool?

[ModderWhoModsThings]

13 hours ago, flamelordytheking said:

How do i find the existing Species Files to edit using this tool?

The only species files published publicly are in the VF kit in the "Species Files" folder. To open a species file, click the "Species File" button in the Portrait File Generator or the "Open Species File" button in the Species File Maker, this will open a file chooser that you can use to navigate through your computer's hard drives to find the file you want to open, then you may click on it then click "open" in the file chooser or you may simply double click on the file in the file chooser.

[flamelordytheking]

1 hour ago, ModderWhoModsThings said:

The only species files published publicly are in the VF kit in the "Species Files" folder. To open a species file, click the "Species File" button in the Portrait File Generator or the "Open Species File" button in the Species File Maker, this will open a file chooser that you can use to navigate through your computer's hard drives to find the file you want to open, then you may click on it then click "open" in the file chooser or you may simply double click on the file in the file chooser.

okay, now how do I add a new species to VF using this tool? I'm trying my hardest, but I think the tool is assuming a greater level of familiarity with its systems and logic than I currently possess.

[ModderWhoModsThings]

5 hours ago, flamelordytheking said:

okay, now how do I add a new species to VF using this tool? I'm trying my hardest, but I think the tool is assuming a greater level of familiarity with its systems and logic than I currently possess.

There is an explanation of how species modding works in this forum:

 

 

Make sure you read the manual included with the SPFG. Species files and templates are two files that are used by the SPFG, not stellaris. The SPFG takes data from a species file and a template to create a portrait file, which is used to define species in Stellaris.

[flamelordytheking]

8 hours ago, ModderWhoModsThings said:

There is an explanation of how species modding works in this forum:

 

 

Make sure you read the manual included with the SPFG. Species files and templates are two files that are used by the SPFG, not stellaris. The SPFG takes data from a species file and a template to create a portrait file, which is used to define species in Stellaris.

My main problem was figuring out where to put the species file. It's probably going to be easier to create a new mod than figuring out which parts of VF I need to edit, so thank you for pointing me to this explanation!

[ModderWhoModsThings]

6 hours ago, flamelordytheking said:

My main problem was figuring out where to put the species file. It's probably going to be easier to create a new mod than figuring out which parts of VF I need to edit, so thank you for pointing me to this explanation!

You can store species files and templates wherever you want on your computer, you can use the file chooser to navigate to any folder on your device to open your files.