Skip to content

Contributing

Jump to bottom
Thomas Boby edited this page Jan 26, 2020 · 4 revisions

Thanks for considering contributing to cwtools! Depending on your familiarity with Paradox modding, cwtools and F#, you might want to take different approaches to getting started. This guide is intended to suggest what those routes might be.

My first recommendation is to try using the main consumer of the cwtools library, VS Code's cwtools-vscode extension.

Getting cwtools-vscode set up

  1. Have you used the cwtools extension for VS Code?
    1. Yes: Skip to 4
    2. No: Install it from here then continue to 2
  2. Are you familiar with Paradox modding?
    1. Yes: Following the instructions on the extension page to point this at your mod, have a play, then continue to 4
    2. No: The scripting language used by Paradox games is less of a programming language and more of a data structure. It is comparable to writing complicated logic using .yml or JSON. This wiki page provides a reasonable overview and might be helpful as a glossary. Continue to 3
  3. Do you own a copy of a modern Paradox game (EU4, Stellaris, CK2, HOI4, Imperator)? Try downloading the suggested mod:
    1. HOI4: https://github.com/EaW-Team/equestria_dev
    2. Stellaris: https://github.com/MoreEventsMod/More_Events_Mod_Beta
    3. No:
      1. Create a folder called "Hearts of Iron IV" somewhere (e.g. D:\Temp\Hearts of Iron IV)
      2. Download the equestria_dev mod above and extract it below that folder (D:\Temp\Hearts of Iron IV\equestria_dev)
      3. Open VS Code, and "Open folder" on equestria_dev.
      4. Open a file in the events folder.
      5. Dismiss the prompts to select a vanilla installation directory (things will break, but not too much).

You should place the mod in your user mod folder if you have one: C:\Users\<your_username>\Documents\Paradox Interactive\<game name>\mod\<mod folder>. Then, open VS Code, open that mod folder, then open a .txt file (I recommend an "event" file in the "events" folder).

Try the features

  1. CWTools implements the Language server protocol. Have a look at the spec and try out the different features (event files are a good place to experiment). I link to the specification, but VS Code provides a useful visual guide here.
    1. Diagnostics: Try generating errors by mangling syntax, changing LHS keys randomly, or changing RHS values to be out of range.
    2. Completion: Trigger completion using ctrl-space. See how it is limited to context relevant values, and sorted roughly by usage.
    3. Hover: Hover over a few random elements. country_event or similar should show you the related localisation keys. is_neighbour_of or similar triggers should show you usage information as well as some context.
    4. Go to definition: Find a line like country_event = { id = my_event.5 } and press F12 on my_event.5. See how it takes you to the definition
    5. Outline: Open the explorer panel on the left and view the "Outline" section to see defined symbols in this document.
    6. Actions: Change the RHS value of a title, description or name field so that you get a CW100 missing localisation error. Click in the error text and see the "lightbulb" appear. Select a "generate localisation .yml" option in that menu.

5. Learn F#

If you're familiar with C#/.NET: F# is just another language that uses the same libraries and is completely compatible.

If you're familiar with Haskell/ML/etc: F# is an impure and more pragmatic functional language (sometimes mutable state is really handy for performance).

For others: It's just another programming language :)

Resources:

Build/Run cwtools

See Build and Run for getting set up

What next?

The following articles go into more details on various aspects of cwtools:

Clone this wiki locally