Skip to content

Home

Jump to bottom
IrateRedKite edited this page Jan 22, 2024 · 10 revisions

Development: Getting Started

This wiki is aimed at developers looking to set up and work with the bmod-client repository. This repository contains the mod's content, but is not a functional client on it's own. The repository comes with an assistive Python script that does a number of things:

  • Generates some INI files from a Google Sheet.
  • Builds UTF (3DB, ALE, CMP, TXM, MAT, ANM and DFM files) from XML so they can be tracked via source control.
  • Builds the infocard DLL from a provided .frc file.
  • Copies the game files on top of your chosen Freelancer directory.
  • Runs the game from this location, tails the log and does some additional logging and crash handling functions.

The script also does a number of additional things, many of which we're not using right now. The main function we use outside of the above is the UTF to XML conversion, which converts binary UTF files to XML for upload to git when we're done editing them.

Using Script Functions

This guide assumes you've already got the script running using the instructions in the readme. We are currently in the process of updating these for Miniconda with a YAML file, as installing Python straight onto your system without virtual environments is a bad idea.

The script is controlled primarily by the args field of the launch.json script, which can be found in the .vscode folder. It's possible to ignore adjustments made to these files and thus avoid risking committing them to the repository by running the following command from the root directory of the repository: git update-index --skip-worktree .\.vscode\

Arguments are listed in with a double dash prefix in quotes in a comma separated list. A default launch.json is provided as an example. To change the args, just adjust the list of them to your liking, save the file, and run the script.

The default arguments used in the script are as follows:

  • --skip_checks: This skips a number of checks that will ensure the script will succeed (That %FL_PATH% is set, Freelancer isn't already running). Generally leave this argument in unless you're having trouble getting the script to run.
  • --ignore_xml: This argument tells the script to ignore the XML files. If this flag is in, UTF files will not be refreshed from XML. This only needs to be removed from the list first time, or if you're updating changes someone else has made to UTF files from GitHub.
  • --ignore_utf: This argument tells the script to ignore the UTF files. Only run the script without this argument when you've made changes to UTF files (i.e. hardpoints) and want to upload them to GitHub as XML.
  • --csv_to_ini, --master_sheet: These two arguments together, combined with a URL or file path in quotes after maser sheet, will download the sheet file and generate the equipment, ship, npcship and commodity files. RUNNING THE SCRIPT WITH THIS ARGUMENT WILL OVERWRITE ANY LOCAL CHANGES YOU HAVE MADE TO THESE FILES. These files also append static content to the generated inis, which can be found in the STATIC folder. More information on how this is governed can be found here.

Caveats

There's a few things to be aware of when you use the script:

  • Using --csv_to_ini will overwrite any changes in those files. Treat the master sheet like it's the word of god and make sure any changes you make go into there. When you're finished making bulk or generative changes with the sheet, commit them to the repository.
  • If you want to make quick, on the fly changes without overwriting stuff, remove the --csv_to_ini flag. At the end of your tweaking session, just make sure you update the spreadsheet accordingly before running with the --csv_to_ini flag again and overwriting any changes.
  • GIT DOES NOT TRACK UTF FILES. If you want to commit any changes to a cmp, 3db or ale file, you will need to run the script with --ignore_utf removed and upload the XML files the script creates.

Additional Functions

  • --no_start: If the script is launched with this argument, it won't launch the game when it finishes everything else.
  • --no_copy: If the script is launch with this argument, it won't copy the client files over to your Freelancer install.
  • --ignore_infocards: If the script is launched with this argument, it won't attempt to generate an infocard dll from infocard_imports.frc.
  • --lua_to_thorn: If the script is launched with this argument, it will convert any lua files to compiled thn ones. We don't use this for BMOD.
  • --ini_to_bini: If the script is launched with this argument, it will convert any ini files to compiled bini ones. We don't use this for BMOD.
  • --no_crc: If the script is launched with this argument, it won't attempt to generate a hashmap on launch.

Generated Files

--csv_to_ini generates the following files:

  • ./mod-assets/DATA/BMOD/EQUIPMENT/bmod_equip_blaster.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/bmod_good_blaster.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/bmod_equip_fleet_blaster.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/bmod_good_fleet_blaster.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/bmod_equip_aux.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/bmod_good_aux.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/bmod_equip_shield.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/bmod_good_shield.ini
  • ./mod-assets/DATA/SHIPS/shiparch.ini
  • ./mod-assets/DATA/BMOD/SHIPS/bmod_ship_good.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/FIXED/bmod_equip_engine.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/FIXED/bmod_good_engine.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/FIXED/bmod_equip_powerplant.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/FIXED/bmod_good_powerplant.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/FIXED/bmod_equip_tractor.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/FIXED/bmod_good_tractor.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/FIXED/bmod_equip_scanner.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/FIXED/bmod_good_scanner.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/bmod_equip_solar.ini
  • ./mod-assets/DATA/MISSIONS/npcships.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/bmod_equip_npc_only.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/bmod_good_npc_only.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/bmod_good_commodities.ini
  • ./mod-assets/DATA/BMOD/EQUIPMENT/bmod_equip_commodities.ini
Clone this wiki locally