Run CWTools on your Clausewitz mod PDXScript code in parallel to your builds.
If CWTools finds errors, warnings or suggestions in the mod code then they will be output.
It will also insert them as inline feedback into your PRs ("Files changed" tab):
GitHub: Can't use GitHub? Click here for GitLab installation instructions .
In most cases, no setup is required beyond adding the following workflow yml file to your project (.github/workflows folder) and setting the correct game. See below for advanced configuration and an explanation of the tools used.
The following games require no further setup:
- HOI4
- Stellaris
name: CWTools CI
on: [pull_request, push] # other events may work but are not supported
jobs:
cwtools_job:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1 # required
- uses: cwtools/[email protected]
with:
game: hoi4
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # required, secret is automatically set by github
This action will create a new job called "CWTools", which will be used to annotate your code. Its success or failure state depends on the CWTools output.
The full output.json log is saved to $GITHUB_WORKSPACE, and can be recovered with actions/upload-artifact.
- uses: cwtools/[email protected]
with:
game: hoi4
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Upload artifact
if: always() # so even if the check fails, the log is uploaded
uses: actions/[email protected]
with:
name: cwtools_output
path: output.jsonWhat game to use. Allowed values: hoi4, ck2, eu4, ir, stellaris, vic2.
- uses: cwtools/[email protected]
with:
game: hoi4
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}Path to the mod folder in $GITHUB_WORKSPACE (root of repository). (Default: "" - root of repository itself)
- uses: cwtools/[email protected]
with:
game: hoi4
modPath: "mod_folder"
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}Path to the full cache file (cwb.bz2) in $GITHUB_WORKSPACE (root of repository). Use an empty string to use metadata from cwtools/cwtools-cache-files (Default: use metadata)
- uses: cwtools/[email protected]
with:
game: hoi4
cache: "cache/hoi4.cwb.bz2"
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}Which languages to check localisation for, space separated, lowercase (eg. english spanish russian). Note: May be different from game to game. (Default: english)
- uses: cwtools/[email protected]
with:
game: hoi4
locLanguages: "english spanish russian"
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}Whether to not use cache, and instead treat the project as a vanilla game installation folder - if you are a modder, you probably should not be using this. If True, cache input will be ignored (Default: False, set to anything other than 0 or blank for True)
- uses: cwtools/[email protected]
with:
game: hoi4
vanillaMode: "1"
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}What rules repository to use (Default: https://github.com/cwtools/cwtools-$INPUT_GAME-config.git)
- uses: cwtools/[email protected]
with:
game: hoi4
rules: "https://github.com/Yard1/cwtools-hoi4-config.git"
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}What ref on rules repo to checkout (Default: master)
- uses: cwtools/[email protected]
with:
game: hoi4
rulesRef: "1.0.0"
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}By default will only annotate changed files in a push or a pull request. In order to annotate all files set changedFilesOnly input to "0".
- uses: cwtools/[email protected]
with:
game: hoi4
changedFilesOnly: "0"
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}You can choose to suppress annotations with chosen CWTools offence category IDs (CW###) per GitHub severity type (failure, warning, notice).
- uses: cwtools/[email protected]
with:
game: hoi4
suppressedOffenceCategories: '{"failure":["CW110", "CW210"], "warning":[], "notice":[]}' # will suppress CW110 and CW210 category failures, but will show those for warnings and notices
env:
default: ${{ secrets.GITHUB_TOKEN }}You can choose to suppress annotations completely in certain files. Use paths from root of repository, make sure to have no trailing whitespace. Globbing is not supported.
- uses: cwtools/[email protected]
with:
game: hoi4
suppressedFiles: '["common/scripted_effects/my_effects.txt", "events/EventFile.txt"]' # will completely suppress any annotations in those two files
env:
default: ${{ secrets.GITHUB_TOKEN }}Which CWTools.CLI version to use (Default: latest stable).
- uses: cwtools/[email protected]
with:
game: hoi4
CWToolsCLIVersion: '0.0.7'
env:
default: ${{ secrets.GITHUB_TOKEN }}Due to limitations with GitLab, this currently only works for merge requests to master
Running this action on GitLab is a bit more involved, requiring the creation of a bot account. It is also limited to providing comments on pull requests as shown here:
- Create a new GitLab account for this "bot" and give it "Reporter" access to your project.
- Log into the account, browse to the Personal Access Token page and generate a PAT with "api" scope. Make a note of the token.
- Log back into your primary account.
- Browse to your Project and go to "Settings", "CI / CD", and open the section "Variables".
- Create a variable called "REVIEWDOG_GITLAB_API_TOKEN". Put the PAT generated above as the Value, then set it as "Masked" but not Protected.
- Press "Save variables".
Please note: This PAT gives access to all projects the bot can access. If somebody gets access to your pipeline logs, it's possible (although not likely) that they could access the token.
- In the root of your project create a file called
.gitlab-ci.yml - Copy the contents of the example file GitLab_CWToolsCI.yml, found in /examples, into it.
- Configure the variables if desired (see above).
- Create a merge request and check it works!
If you're running your own instance of GitLab, you'll need to set the following two variables in addition to those in the default template:
- GITLAB_API: "https://example.gitlab.com/api/v4"
- REVIEWDOG_INSECURE_SKIP_VERIFY: true
CWTools is a .NET library that provides features to analyse and manipulate the scripting language used in Paradox Development Studio's games (PDXScript). This is mainly used in a VS Code extension, cwtools-vscode. CWTools also provides a CLI tool CWTools.CLI to allow automated anaylsis, which is what this action relies on.
This action relies on two things:
- A set of valiation rules written for the game your mod is for
- A cache file containing key information from vanilla files
The validation rules are taken from the master branch of the public repository for the game, e.g. https://github.com/cwtools/cwtools-hoi4-config. The settings rules and rulesRef can be used to specify an alternative repo, or to stay on an old version of the rules.
In order to validate correctly, CWTools requires certain data from the vanilla game files such as defined localisation, variables, etc. There are two formats of cache file:
The metadata format contains a limited set of information from vanilla, enough to run the main validator. For convenience CWTools automatically generates these metadata cache files for the latest public rules and latest version of each game. These are found here and are used by default in this action (please note that not all games may be supported yet).
The full format contains a more details, processed, version of the vanilla script files. This is required in order to provide accurate validation taking load order and file overrides into account. This is the same format used by cwtools-vscode. We do not provide these files, however this action can be configured to use them.
Created by Antoni Baum (Yard1).
Using tboby/cwtools.
Based on gimenete/rubocop-action by Alberto Gimeno.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent