HowTo:Add Cargo

From VsWiki
Jump to: navigation, search
arrow_left.png Add Upgrades arrow_up.png HowTos Edit Systems arrow_right.png

Note: In Vega Strike, there is an ongoing effort to make the economy much more sophisticated. This file discusses adding cargo using Privateer 1.2 as the example, but Vega Strike 0.4.3 should be similar. [FIXME Add VS data.]

The cargo system is driven primarily by two files: master_parts_list.csv, located in the game root directory, and units.csv, located in the \units directory. There are other files provided for convenience: cargo.csv shows the buy/sell prices at different base types, but doesn’t actually affect the game.

All the cargo types used in the game are defined in master_parts_list.csv. Each type of cargo has its own row, which includes a filename, category name, base price, mass, volume, and description. The mass and volume entries don’t appear to do anything—if they’re changed, nothing changes in the Commodity Exchange, and there’s no obvious difference in ship handling characteristics. Category name maps to the “Cat” entry in units.csv. The price is the base price for that cargo type; units.csv contains modifiers for the price, depending on base type.

The description includes the location and name of the graphics file to be for displaying this cargo in the Commodity Exchange, e.g. cargo\tungsten.png. These are located off the \textures directory (so this example points to \textures\cargo\tungsten.png). Note that the graphics files may be .png or .jpg format, and should be 128 x 128 pixels. If the graphic is not 128 x 128 pixels, there will be a noticeable loss of performance while that cargo item is selected in Commodity Exchange.

In Privateer, whether or not cargo is available for sale at bases/planets is determined by the units.csv file, column DB, “cargo_import”. Recall the second row in units.csv provides a basic definition for the format of the various entries. In Vega Strike 0.4.3, the same data is in column DA. Column DB, “cargo” is different, and describes various attributes of the cargo itself. [FIXME Add description of differences for VS.]

For the cargo_import column in units.csv, the entries are: {Cat; price%; pricestddev%; quant%; quantstddev%}

Cat” is the category (type) of cargo: grain, generic foods, plastics, contraband/brilliance, etc. (Note the keyword Contraband in front of the specific cargo type—more on these later.) The category name links to the associated data in master_parts_list.csv. The “file” name in master_parts_list.csv is the name displayed in the Commodity Exchange. Note that the Commodity Exchange won’t indicate whether the item is considered contraband. Master_parts_list.csv also includes a description for the item which appears in the Commodity Exchange. (If you’re adding a new type of cargo, note that Microsoft Excel won’t like the symbols in the description field. You can use Notepad to edit that field, if you don’t have a .csv editor.)

Price%” is a multiplier. The base price for an item, defined in master_parts_list.csv, is multiplied by Price% to arrive at the buy/sell price for that item on a given base/planet. Typical range is 0.8 to 1.8. Note that the master_parts_list.csv also defines the mass and volume of the cargo item, as seen in the Commodity Exchange. (In Privateer 1.2, cargo is simply 0.01 metric ton and 1.0 m3 per unit.) If the multiplier is 0, the base/planet does not buy this item (e.g. New Constantinople does not buy construction equipment or slaves).

Pricestddev%” is a modifier for the price at a base/planet, so the price varies a little. It doesn’t appear to actually be standard deviation. The equation to determine the overall price is approximated by: Absolute value(Price% - (Price% * Pricestddev%)) The minimal amount of price variation in Privateer 1.2 is due to the very small values of Pricestddev%. When nonzero, typical values of Pricestddev% are 0.02 to 0.05 in Privateer 1.2, leading to variations of just a few tenths of a credit. [FIXME Add Vega Strike info for comparison.]

Quant%” is the average number of units available for sale, as modified by Quantstddev%. If zero, the item is not sold at this base/planet. If the total of Quant% and Quantstddev% is not an integer, it is rounded to the nearest integer for display in Commodity Exchange.

Quantstddev%” specifies the range, plus or minus around Quant%, of units available. Often nonzero even when quant% is zero, although then it has no effect. It does not appear to actually be standard deviation; it appears that a random number within the range is selected to vary from Quant%. (25 samples did not suggest a normal distribution around Quant%.) If the total of Quant% and Quantstddev% is not an integer, the total is rounded to the nearest integer for display in Commodity Exchange.

[FIXME] The Quantstddev% column also appears to be used to define how much cargo will be carried on cargo missions and something about asteroid fragments—perhaps what they’re worth? Or, how many units of ore come out?


In order to make cargo into Contraband, you must do two things. First, add the “Contraband” keyword in front of the cargo name in master_parts_list.csv. Then, add that cargo type to list of contraband items found in the lines “Contraband_xxx” in units.csv, column DB, cargo_import. There are types of contraband specified for Confed, Militia, and Retros. Note that if you misspell Contraband, that cargo won’t be available for purchase at the usual places.[FIXME There are several fields in the contraband description, including a 1 at the end. Determine what these are for--e.g. do any determine the probability of the contraband being detected?]

In addition to the “Contraband” keyword, “Starships” indicates what types of vessels are available for purchase at this location, e.g. {starships/Merchant/Light;1;;12;6}, and the keyword “upgrades” indicates what ship upgrades will be available at the Ship Dealer, e.g. {upgrades/Reactors/Medium;1;.1;3;1}.

[FIXME Identify differences for Vega Strike.]

Cargo outside the ship

That just leaves the image to be used for cargo floating in space. All cargo is loaded in small containers, so all cargo types floating outside a ship are displayed the same. The graphics to be used are specified by the row entry “generic_cargo_upgrades” in units.csv. [FIXME What is the units.csv entry “cargo” used for?]

In units,csv, the Directory column specifies the location of the files called out in other columns. For generic_cargo_upgrades, this location is ./objects/cargo, which is found under the /units folder. Hud_image specifies the file name of the sprite used to display cargo boxes on your ship’s MFD (i.e. cargo-hud.spr). Mesh specifies the file name of the 3D .bfxm mesh to be used. Here, then, the container mesh is located in \units\objects\cargo, generic_cargo.bfxm. The entry in the Name column does not appear to be used; when an object is targeted on the MFD, the entry in the “Key” column is displayed.

Internally, the 3D mesh file specifies the graphics files to be used to overlay the mesh. For example, generic_cargo.bfxm specifies textures cargopod.jpg and cargopodPPL.jpg. So, if a different file is used for “cargopod.jpg,” the cargo boxes have a different appearance. But, they are all the same.

As a side note, the /objects folder also contains subfolders for asteroid, ejected pilot, and derelict ship objects. Each folder contains the 3D .bfxm mesh, the graphics which overlay the mesh, and sprites for the cockpit HUD image for each type of object.


So, to add a new type of cargo, you need a couple ideas, and one file. You need a name for your new cargo, the base price, a description, and the picture to be displayed in Commodity Exchange. These go in master_parts_list.csv. The graphics file goes in /textures/cargo.

You also need to decide where your cargo will be available and where buyers will take it off your hands. At bases which supply your cargo, use the Price% multiplier to set the price low. At bases which demand your cargo, use the Price multiplier to set the price higher. At both, set the price variability using Pricestddev%. Be careful not to create a price differential that’s unbalancing. At bases which supply your cargo, use the Quant% and Quantstddev% to determine how much of your commodity is normally available, and the range this quantity can vary. These entries go in units.csv, in the cargo_import column for each base. Note that if you don’t put an entry for your cargo at a base, then that base will buy your cargo at the base price set in master_parts_list.csv. If you don't want a base to by a cargo item, you must give that item a zero price multiplier in the cargo_import column for that base type.

arrow_left.png Add Upgrades arrow_up.png HowTos Edit Systems arrow_right.png