Contributing to Millennium Dawn - Millennium Dawn: A Modern Day Mod

This page is a quick reference for contributing to Millennium Dawn. For the complete guide, see the full CONTRIBUTING.md (opens in new tab) on GitHub.

Supporting Resources:

Code Stylization Guide

Content Review Guide

Focus Tree Lifecycle Checklist

AI-Assisted Modding Guide

What We Accept

Area	Examples
Focus Trees	New trees, branch reworks, prerequisite fixes
Events & Decisions	Event chains, decision categories, triggered events
Ideas & National Spirits	New ideas, modifier tuning, icon assignments
AI & Balance	Strategy plans, equipment variants, stat tweaks
Localisation	English string fixes, tooltip accuracy
Graphics	Portraits, focus icons, event pictures, 3D models
Map & History	State boundaries, country history, OOBs
Documentation	Guides, tutorials, dev diaries
Tooling	Python scripts, CI improvements, pre-commit hooks
Bug Fixes	Crash fixes, trigger errors, typos

Non-English localisation is managed through Paratranz (opens in new tab) — do not submit translations directly.

Fork Workflow (Outside Contributors)

Fork the repo on GitHub.

Clone your fork and add the upstream remote:

git clone https://github.com/<your-username>/Millennium-Dawn.git
cd Millennium-Dawn
git remote add upstream https://github.com/MillenniumDawn/Millennium-Dawn.git

Branch from main:
```
git checkout -b my-feature main
```
Make changes, following code standards.
Commit — pre-commit hooks run automatically.
Push and open a PR against main on the upstream repo.

Sync before starting new work:

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

Setup

python3 tools/setup.py          # install hooks and dependencies
python3 tools/setup.py --check  # verify environment

See the full CONTRIBUTING.md (opens in new tab) for VSCode workspace setup, docs site instructions, and dev tools.

AI Policy Summary

AI tooling is welcome under the following rules. See the full AI Policy (opens in new tab) for details.

Code and Scripts

AI coding assistants (Copilot, Claude, ChatGPT, local models) may be used to draft, refactor, or debug HOI4 script code. Requirements:

Review all AI output line-by-line before submission.
Enforce project standards (tabs, naming, logging, ai_will_do, is_triggered_only).
Run pre-commit hooks. Do not submit raw AI output.
Verify triggers, effects, and modifiers exist. AI models hallucinate non-existent game objects.

Localisation

AI may draft or proofread English strings. All output requires human review for accuracy, tone, and style compliance. Non-English localisation is managed through Paratranz and must not be AI-generated.

Graphics

Pure AI-generated art is not allowed under any circumstances.
AI-generated military vehicle side profiles are acceptable only when no existing profile is available, and the final asset must be manually finalized and reviewed by a GFX team member.

Documentation and PR Descriptions

AI may draft documentation and PR descriptions. Review for accuracy — AI frequently references files or tools that do not exist in this repo. Do not add “Generated with” footers or co-author trailers.

For questions, join the Discord (opens in new tab) or open an issue on GitHub.