Guidelines for Developer‐Led AI Tool Usage in MegaMek - MegaMek/megamek GitHub Wiki

Guidelines for Developer-Led AI Tool Usage in the MegaMek Suite

Purpose

These guidelines cover how we use AI tools across the MegaMek Suite of Programs: code, data, and content. AI is a tool. These guidelines help us use it the right way.

The MegaMek Suite operates under a dual license. Source code is GPLv3. Game data, artwork, and other non-code assets are CC-BY-NC-4.0. These guidelines apply to contributions under both licenses.

Core Principles

1. Why Only Established Developers Use AI Tools

Only established project developers may use AI tools for contributions to the project. An "established developer" is someone who has demonstrated familiarity with the MegaMek codebase or data standards and is an active member of the Dev team.

When a new human developer joins the project, we tell them to start small. Learn the codebase. Understand why things are built the way they are. Work up to bigger tasks as you build that knowledge. We would never let a brand new developer walk in and refactor one of our largest classes on day one.

AI tools face this same challenge in a different way. Every time an AI tool opens the codebase, it is seeing it for the first time. It doesn't carry knowledge from one session to the next. It doesn't remember why a class is structured a certain way, or what broke last time someone changed it. A human developer builds that understanding over time. AI starts fresh every time.

This is the fundamental reason we require established developers to be the ones using AI tools. The developer provides what the AI cannot: memory of past decisions, understanding of the codebase, knowledge of the BattleTech game system and tabletop rules, and the ability to research and interpret nuanced discussions across forums, chats, and community sources. They can guide the AI with the right context and catch its mistakes before they reach the project.

2. Mandatory Disclosure

All work that used AI tools must be clearly labeled.

  • PRs that involved AI tools must be labeled in the title or description (e.g., "[AI-Assisted]")
  • All such PRs will be labeled as AI Code or AI Data as appropriate
  • Any PR with AI help, the whole PR will be considered an AI implementation
  • Reviewers need to know so they can apply appropriate scrutiny

3. Responsibility

The developer who submits work that used AI tools owns the outcome.

If something breaks or needs to be corrected, the developer who submitted it is responsible for getting it resolved.

This means:

  • Understand what the contribution does and why
  • Be able to explain the implementation or content decisions
  • Have thoroughly tested or verified the output before submission
  • Be willing to iterate based on reviewer feedback

If you can't explain the work, verify the result, confirm it functions correctly in the programs, and demonstrate that it aligns with the tabletop rules (or provide documentation explaining any deviation to the player base), it's not ready to submit.

Part A: Code Development with AI Tools

A1. How We Use AI in Code

AI tools can assist with a wide range of coding tasks, from simple bug fixes to complex problem solving. We don't limit AI to simple tasks. The developers are the keepers of this codebase, and we will continue to explore how AI tools can help us maintain and improve it.

What matters is not whether AI touched the code, but whether the code meets our standards. The safeguard is the review and testing process, not restrictions on what AI is allowed to work on.

That said, the more complex a task is, the more rigorous the review needs to be. A simple errata fix following an established pattern needs a standard review. A change that touches core systems or interconnected components needs deeper scrutiny, more testing, and more eyes on it before it merges.

A2. Code Review Requirements

All code that used AI tools goes through the same review process, with extra attention where needed.

Reviewers should specifically check for:

  • Confident incorrectness: Does the code make assumptions that seem plausible but are wrong?
  • Style consistency: Is the AI copying outdated patterns from legacy code?
  • Architectural fit: Does the implementation integrate cleanly with existing systems?
  • Edge cases: Has the AI considered boundary conditions and error cases?
  • Test coverage: Are there comprehensive tests, not just happy-path scenarios?
  • Maintainability: Can a human developer understand and modify this code?

At least one active developer must review PRs that used AI tools.

A3. Code Testing Requirements

Code developed with AI tools must be thoroughly tested before submission.

Required evidence:

  • Multiple test games or scenarios exercising the new functionality
  • Edge case testing (boundary conditions, error states)
  • Integration testing showing it works with related systems
  • Test pilot validation for complex features (beyond just the author's testing)

Document your testing process in the PR description. The more complex the change, the more testing it needs.

A4. Style and Modernization

AI must not perpetuate outdated code patterns.

  • Train AI prompts to follow current MegaMek coding standards
  • Actively review for legacy patterns that AI might copy
  • When AI suggests outdated approaches, correct the prompts rather than accepting the code
  • Reviewers should reject PRs that introduce deprecated patterns, even if functionally correct

The project has invested significant effort in modernizing the codebase. Don't let AI undo that work.

Part B: Data and Content Development with AI Tools

This section covers all non-code contributions where AI tools are involved. That includes unit fluff text, factory and manufacturer data, component assignments, planetary and system data in MekHQ, and other game data across the MegaMek suite.

B1. Deriving Lore from Source Materials

The MegaMek suite is an unofficial program and is NOT a canon source of BattleTech material. Fluff text in MegaMek and system data in MekHQ should never be treated as official lore. MegaMek is a fan-created, unofficial project that is not affiliated with, endorsed by, or licensed by The Topps Company, Inc., Catalyst Game Labs, or Microsoft Corporation.

The fluff we write tells the story of a unit or system within the game to support the player's experience. The developers may create fluff that supports the story of a unit or system in-universe using derived canon material. For example, if canon lists an extinction date for a unit but the game needs context for why that unit might still appear on a battlefield, the fluff can address that. Similarly, MekHQ system descriptions are written from canonical source information to give players context for the worlds they operate in during campaigns. We are telling these stories for gameplay purposes, not publishing official lore. Where a system description has a known canonical source, that source is tagged in the data.

When a player clicks on a unit in MegaMek or views a system in MekHQ, they see a description of what it is and what it does. Those descriptions draw on widely known setting information like introduction dates, manufacturers, historical events, and planetary details. They are developed by human developers using AI tools and reviewed to produce original text.

Every unit in MegaMek includes a link to its entry on the Master Unit List. From there, players can find which books feature that unit and follow links to the official Catalyst Game Labs store. We want players to discover and support the published products that make this universe what it is.

Each unit description may draw from multiple sources: published books, Sarna, the MUL, MegaMek data files, and community knowledge. The result is compiled into a project-specific format with its own structure and constraints.

B2. How We Use AI in Data and Content

Developers use AI tools to assist with a wide range of data tasks across the MegaMek suite. The workflow looks like this: factual data is gathered from canonical or trusted sources (published books, Sarna, the MUL, MegaMek data files). AI tools assist the developer in drafting descriptions and compiling that data. The developer then reviews, verifies, and edits all output before submission.

As with code, what matters is not whether AI touched the data, but whether the result meets our standards. The more complex or narrative the content, the more careful the review needs to be.

The one hard rule: do not fabricate units, manufacturers, or factions that do not exist in the setting, and do not submit AI output without human review and editing.

B3. Data Review Requirements

All data developed with AI tools goes through review, with extra attention to accuracy and authenticity.

Reviewers and developers should check for:

  • Fabricated content: Units, manufacturers, factions, or dates that were invented rather than derived from canonical sources
  • Factual errors: Incorrect dates, wrong manufacturers, misattributed equipment names or faction affiliations
  • Source reproduction: Passages that closely mirror known published entries in wording or structure
  • Authenticity: Does the content feel like it belongs in the setting? Derived information should read like a canonical narrative.
  • Writing quality: Does the text read naturally? Drafts developed with AI tools should be edited to match the project's voice before submission.
  • Data consistency: Cross-referencing between data tabs and authoritative sources

B4. Content Standards

Content developed with AI tools must be original and authentic to the setting.

  • Content must not reproduce the specific wording, sentence structure, or narrative organization of any single published source. The developer is responsible for verifying this.
  • Content must be written in an in-universe tone with no meta-references.
  • Factory and component data must be validated against authoritative sources (MUL, MegaMek data files).

Part C: Art

C1. Policy

The MegaMek Suite will not accept generative AI art. This is a hard rule, not a guideline.

Generative AI art is any visual content produced by image generation tools such as Midjourney, Stable Diffusion, DALL-E, or any equivalent tool. This will not be accepted into the MegaMek Suite. This includes:

  • AI-generated portraits (see C3 for the existing portrait pack exception)
  • AI-generated sprites, tilesets, splash screens, or any other visual assets
  • AI-generated images used as placeholders, temporary assets, or proofs of concept

Any PR or contribution containing generative AI art will be rejected.

C2. How We Handle Art

We pay artists. We always have and we always will. When the suite needs art, we commission it, pay for it, and publicly credit the artists so the community can support them.

Artists who have contributed to the MegaMek Suite include Sp00ky777, Eldon Cowgur, Saxarba (tilesets), and Deadborder (sprites), among others.

C3. Portrait Packs

The pilot portrait packs are the one exception to the generative AI art rule. The base images were sourced in 2020 from Generated Photos, a licensed service that uses licensed source images for its training data. Those images were paid for and then substantially reworked by Saxarba, a paid human artist, into the final portraits.

Red Flags

Reviewers should be particularly cautious if they see:

Code red flags:

  • Code that "just works" but is hard to understand
  • Overly complex solutions to simple problems
  • Inconsistent naming or style within the PR
  • Missing error handling or edge cases
  • Tests that only cover happy paths
  • Code that duplicates existing functionality instead of reusing it
  • Comments that don't match what the code actually does

Data/content red flags:

  • Lore or events that can't be traced to a canonical source
  • Text that reads like a paraphrased version of a specific published entry
  • Dates, names, or facts that don't match known canonical references
  • Text that doesn't read naturally or doesn't match the project's voice
  • Format or naming convention violations
  • Missing or incomplete source verification

Questions or Concerns?

These guidelines are a living document. Feedback, suggestions, and concerns are welcome as we figure out how to use AI tools responsibly in MegaMek Suite development.