This guide explains how to format and lint code in Cataclysm: Bright Nights.

Quick Reference

Scope Tool Command
Staged files all formatters just fmt
All files all formatters just fmt --all
C++ (.cpp/.h) astyle/clang-format just fmt-cpp
JSON json_formatter just fmt-json
Markdown/TS deno fmt just fmt-docs
Lua dprint just fmt-lua

Automated Formatting

Pull requests are automatically formatted by autofix.ci. If your code has style violations, a commit will be pushed to fix them.

Tip

To avoid merge conflicts after autofix commits, either:

  1. Run git pull to merge the autofix commit, then continue working
  2. Format locally before pushing, then git push --force if needed

C++ Formatting

Top-level C++ files are formatted with astyle. C++ files in source subdirectories are formatted with clang-format.

# Install formatters (Ubuntu/Debian)
sudo apt install astyle clang-format

# Install formatters (Fedora)
sudo dnf install astyle clang-tools-extra

# Install formatters (macOS)
brew install astyle clang-format

Using the script

just fmt-cpp
# or
build-scripts/format-cpp.sh

The style configurations are in .astylerc and .clang-format at the repository root.

JSON Formatting

JSON files are formatted with json_formatter, a custom tool built from the project source.

Using the script

just fmt-json
# or
build-scripts/format-json.sh

The script builds json_formatter in out/build/json-format and formats JSON files. It does not require a configured game build or a CMake preset. Override the helper build directory with CATA_JSON_FORMAT_BUILD_DIR if needed.

Note

The data/names/ directory is excluded from formatting because name files have special formatting requirements.

JSON Syntax Validation

Before formatting, you can validate JSON syntax:

build-scripts/lint-json.sh

This runs Python's json.tool on all JSON files to catch syntax errors.

Markdown & TypeScript Formatting

Markdown and TypeScript files are formatted with Deno.

# Install Deno
curl -fsSL https://deno.land/install.sh | sh

# Format Markdown and TypeScript
deno fmt

Lua Formatting

Lua files are formatted with dprint via Deno.

# Format Lua files
deno task dprint fmt

Dialogue Validation

NPC dialogue files have additional validation:

tools/dialogue_validator.py data/json/npcs/* data/json/npcs/*/* data/json/npcs/*/*/*

Pre-commit Workflow

Install the optional pre-commit hook with prek:

prek install
# or
just hooks-setup

When you commit, the hook runs just fmt: Deno and dprint run normally, while C++ and JSON formatters run only on staged created/updated files. Formatted staged files are re-added so the commit includes the formatted result.

To run the same formatting manually against staged files:

just fmt

Before committing without the hook, run these checks:

# Format staged files
just fmt

# Format all formattable files
just fmt --all

CI Integration

The CI pipeline runs these checks automatically:

  1. JSON syntax validation - build-scripts/lint-json.sh
  2. JSON formatting - build-scripts/format-json.sh
  3. Dialogue validation - tools/dialogue_validator.py

If any check fails, the build will fail. Use the commands above to fix issues locally before pushing.

Editor Integration

VS Code

Install these extensions for automatic formatting:

  • C++: C/C++ with astyle integration
  • Deno: Deno for Markdown/TypeScript

Visual Studio

Install the formatters once from PowerShell. LLVM provides clang-format and clang-tidy.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex
scoop install llvm astyle
clang-format --version
clang-tidy --version
astyle --version

If Scoop is already installed, run only scoop install llvm astyle. If any version command is not found, close and reopen PowerShell and Visual Studio so they reload PATH.

After installing the tools:

  1. Open the repository folder in Visual Studio as a CMake project.
  2. Configure CMake. If Visual Studio already configured the project before installing the formatters, reconfigure the CMake cache.
  3. Open View > Other Windows > CMake Targets View.
  4. Build the format target before committing.

Visual Studio's normal Format Document command does not run this target. Use the format target for repository style: it runs astyle for top-level C++ files and clang-format for C++ files in src/ subdirectories.

Vim/Neovim

Add to your config:

" Format C++ with astyle on save
autocmd BufWritePre *.cpp,*.h !astyle --options=.astylerc %

" Format with deno
autocmd BufWritePre *.md,*.ts !deno fmt %

Troubleshooting

"json_formatter not found"

Run the JSON formatter script. It configures and builds the formatter helper automatically:

build-scripts/format-json.sh

C++ formatter not found

Make sure astyle and clang-format are installed and in your PATH:

# Check if formatters are available
which astyle
which clang-format

# Install if missing (Ubuntu/Debian)
sudo apt install astyle clang-format

Then rerun:

build-scripts/format-cpp.sh

C++ formatters produce different results

Make sure you're using the formatter configs from the repository root:

astyle --options=.astylerc src/*.cpp
clang-format -i src/utils/*.cpp src/utils/*.h