Ship File Design

[royfalk]

General

• This applies both to original ship files and to save games.
• It will be a JSON or yaml file.
• There will be a version object. However, JSON/yaml also provides support for adding and removing attributes.

Format

For now, this will be a JSON file, in the following format.

[ {"version": 1}, { ship 1}, { ship 2}, { ship 3}, ... ]

General Ship Format

Attributes in bold need to be considered further. See relevant comment in italics.

`{
"Key": "Fighter_Barracks__rlaan",
"Directory": "./installations/Rlaan_Fighter_Barracks",
"Name": "Fighter_Barracks__rlaan",
"Object_Type": "Installation", Is it used?
"Combat_Role": "BASE", Is it used?
"Textual_Description": ""WRITEME"\n", Merge stuff from master parts or remove fields taken from there.
"Hud_image": "rlaan_fighter_barracks-hud.sprite",
"Unit_Scale": "200",
"Mesh": ["rlaan_fighter_barracks.bfxm"}], An array. Simplifies processing in C++ or python. Check if there is support for more than one mesh.
"Mass": "8241769.5",
"Moment_Of_Inertia": "8241769.5", Same as mass. Check if used.

    "Components": [], _See below_
    "Mounts": [], _See below_
    "Docks": [], _See below_
    "Cargo": [], _See below_

    "Hold_Volume": "100000000000", _Remove for installations and non-player ships._
    "Slide_Start": "0",
    "Slide_End": "0",
    "Sound": ";;;;;;",
    "Num_Animation_Stages": "0",
    "Upgrade_Storage_Volume": "1000000", _Remove for installations and non-player ships._
    "Heat_Sink_Rating": "0", _what does it do?_
    "Spec_Interdiction": "0.75", _Move to FTL drive?_
    "Tractorability": "pPiI" _what does it do?_

}`

Ship Format Short Form

In order to improve readability, ease of editing and game balance, the following is supported:
TBD

Consider this carefully. You can inherit one ship from another, but will this improve readability?

Components

• In version 0, we will maintain the attribute names used in the previous format. e.g. Reactor_Recharge.
• "Jump_Drive_Present": "FALSE" will be replaced by not writing the component.
• Components will record damage in a consistent format, supported by the Resource class. Therefore, the component class will offload parsing of a damaged (or undamaged?) attribute of a component to the Resource class.

Component List

• Fuel
  • Fuel_Capacity
• Hull
• Armor
• Shield
  • Shield_Recharge
  • Shield_Leak
• Capacitor
  • Primary_Capacitor
• Reactor
  • Reactor_Recharge
• Jump_Drive
  "Jump_Drive_Present": "FALSE",
• Drive
• Radar
• Hud Replace the obscure string with something better. TBD
  • "Hud_Functionality": "1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1",
  • "Max_Hud_Functionality": "1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1",
• Lifesupport
• Comm
• Fire Control
• FTL Drive

Integrated Components Short Form

{ "Fuel_Capacity": 100} Will take other fields from a template file. e.g. integrated=true.

{ "Armor": 15000}
will expand to
{ "Armor_Front_Top_Right": "15000", "Armor_Front_Top_Left": "15000", "Armor_Front_Bottom_Right": "15000", "Armor_Front_Bottom_Left": "15000", "Armor_Back_Top_Right": "15000", "Armor_Back_Top_Left": "15000", "Armor_Back_Bottom_Right": "15000", "Armor_Back_Bottom_Left": "15000"}

Mounts TBD

Replace "{Zhuangzong;40;;special-missile;0;0;.28;;;0;0;1;0;1;0;1;1}" with

"Mounts": [ { _TBD_ } ]

Docks TBD

Replace "Dock": "{10;-2.99;-0.01;0.0;0.57;0}{20;-11.96;-0.04;0.0;0.57;0}" with

"Docks": [ { _TBD_ } ]

Cargo TBD

Replace ""Cargo_Import": "{Consumer_and_Commercial_Goods/Domestic;.9;.2;;2}{Consumer_and_Commercial_Goods/Electronics;1.2;.2;;4}" with

"Cargo": [ { _TBD_ } ]

[evertvorster]

I don't understand the file formats that much, but what I know that people who play VegaStrike tend to keep their save files for a long time.
Whatever is chosen for the future, we need to keep backward compatibility in mind, or have a utility that can convert an old save file into the new format.

[royfalk]

There's some confusion here about what this is. The save game is really 2 or more files. A save game holding location, money, quests, position in the campaign, etc. The 2nd is a CSV file with a ship. Originally the same as units.csv but with one row.

We're only touching the 2nd. The meaningful change here is that we're moving away from the original paradigm of stock unit and upgrades. In that paradigm, you save the current state of the ship, damage and all. When you repair something, you check against the stock ship/upgrade to figure out your new stats.

In the new change, we break the unit into components. Each stores the current and max values of stats. The three big advantages:

1. Code is broken into easy to understand chunks.
2. Each component can be unit tested. e.g. You can write a unit test for a llama and find out how much fuel it consumes in 10 minutes of game play.
3. Use of Resource class and better architecture can get rid of some bad code.
   • A lot of code is: if > max then max. if < 0 then 0. Resource class does that automatically.
   • WC fuel hack - fuel and spec are the same so the game constantly checks to make sure they are. In the new paradigm, you just define the source of the jump drive to be fuel and you're done.

It's probably better to have the backward compatibility as a python utility. The code is complicated enough.

Having said all of that, if you understand unit.csv and the above isn't clear, I'm doing something wrong. It's supposed to be easy to understand and hack by players.

[BenjamenMeyer]

There's some confusion here about what this is. The save game is really 2 or more files. A save game holding location, money, quests, position in the campaign, etc. The 2nd is a CSV file with a ship. Originally the same as units.csv but with one row.

this is why I'd like to eventually turn the save game into a ZIP file so everything can be contained together. It'll make it cleaner all around about what exactly constitutes a saved game; and may make it easier to version the saves too.

[evertvorster]

Thank you for the explanation. From this, would it be possible to port out the current code that loads the savegame, and once it is in memory put it in the new format?
This would enable you to cut it from the current game engine and reduce the complexity there, right?

[royfalk]

I think you want to separate the load saved ship code and reduce the complexity by leaving it in but isolated. This is already the case.

However, the problem with this idea and the old format is that it doesn't hold enough information about the ship. For example, let's say I have a damaged shield generator. The old format only saves the damaged numbers. When you fix the shield generator, it compares the numbers against an undamaged shield generator listed in another file or row.

If we want to improve other parts of the engine code, we need to change this file format.

[evertvorster]

No, I agree that a newer and more better save file is needed. I agree that the save file does not have high enough fidelity.
My only concern is what about the people that spent countless hours exploring their galaxy? Those save files have a lot invested in them.
It would be nice if there was a utility, separate from the game engine, that could load the soon to be old format of the save file, and save the file in the new format. I don't think there is a requirement to be able to go the other way, from old to new.

[royfalk]

As noted before, "It's probably better to have the backward compatibility as a python utility. " I will provide said utility as part of the change.

[BenjamenMeyer]

NOTE: #169 is about changing the saved game file format. I'd like to use some kind of ZIP file - think JARs, ODF, OOXML, etc - where we create a virtual saved game FS inside the ZIP and then store all the information for the saved game together.

[royfalk]

The main save file is in /save/<save_filename> and I have not yet looked at the format at all. It looks like pseudo text with some binary stuff.
The ships are in serialized_xml/<save_filename>/<ship_name>.csv and there may be more than one. I think I can fix #757 and merge all CSV files into one with a relatively simple PR.

The zip file is another relatively simple task (assuming we have zip support in C++) and would bundle the two or more files in a zip.

The real issue is one of priorities. The stuff I'm working on now (lib component) has the potential to reduce a lot of the complexity from the engine. For example, a lot of the clamp functions in Movable are simply if a>max a=max & a<0 a=0 stuff.

[BenjamenMeyer]

Priority -not high right now; but I'd like it before we declare 1.0.

Between https://www.zlib.net/, https://gitlab.com/federicomenaquintero/bzip2, and https://www.boost.org/doc/libs/1_86_0/libs/iostreams/doc/index.html (gzip, bzip2, zlib) we should be able to use something - https://cplusplus.com/forum/general/246479/ has a decent example for using Boost iostream filters for compression; but we'd still have to apply something about that. More design is almost certainly needed before we implement it.

[royfalk]

That's fine. I don't see me getting to it in the next three months. OTOH, we may well implement this in python by then.
I see no reason why a single operation like load/save should be in C++. The speed advantage is negligible and the advantages in readability, development speed and testing are all in favor of python.