Contribution Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the technical standards and procedures for contributing to the ChapterMaster project. Contributions primarily focus on content expansion through JSON-based data definition files and code maintenance through automated formatting tools. Developers are expected to adhere to the existing data structures and utilize the provided automation scripts to ensure consistency across the codebase.
The project relies heavily on a structured data-driven architecture, where game entities such as Space Marine Chapters, weaponry, and traits are defined in discrete JSON files located within the datafiles/ directory.
Code Formatting Standards
The project uses Gobo, a GML (GameMaker Language) formatter, to maintain code consistency. Contributors must run the formatting script before submitting pull requests to ensure that all .gml files adhere to the project's style guidelines.
Automated Formatting Workflow
A PowerShell script, run_gobo.ps1, is provided to automate the formatting process. This script performs the following actions:
- Dependency Management: Checks for the existence of
gobo.exe. If missing, it fetches the latest release from theEttyKitty/Goborepository. - File Gathering: Recursively identifies all
*.gmlfiles while excluding specific directories such asextensions,.git,.svn, andprefabs. - Batch Processing: Executes the formatter on each identified file and reports any exit code errors.
Sources: run_gobo.ps1:1-85
Data Definition Contributions
Much of the project's content is defined via JSON. When contributing new Chapters or modifying existing ones, developers must follow the schema established in the datafiles/main/chapters/ directory.
Chapter Definition Structure
Each chapter file (e.g., 33.json, 37.json) contains a root chapter object with specific attributes for gameplay balance and visual representation.
| Field | Description | Type |
|---|---|---|
id | Unique identifier for the chapter. | Integer |
flavor | Lore description of the chapter. | String |
origin | Founding type (1: Founding, 2: Successor, 3: Other, 4: Custom). | Integer |
fleet_type | Deployment style (1: Homeworld, 2: Fleet-based, 3: Penitent). | Integer |
disposition | Starting relationship values with factions like Imperium, Admech, and Inquisition. | Array[Int] |
Sources: datafiles/main/chapters/37.json:4-160, datafiles/main/chapters/33.json:4-130
Defining Traits and Doctrines
New advantages and disadvantages must be added to chapter_advantages.json and chapter_disadvantages.json. These definitions affect Chapter Master stats, unit availability, and faction relationships.
| Trait Component | Description |
|---|---|
name | The unique name of the trait. |
points | The point cost/reward for selecting the trait. |
meta | Category tags (e.g., "Weapon Specialty", "Doctrine"). |
faction_disp_mods | Objects defining starting disposition and interest modifiers for specific factions. |
Sources: datafiles/main/chapter_advantages.json:1-322, datafiles/main/chapter_disadvantages.json:1-210
Weaponry and Gear Implementation
Weapons are defined in datafiles/data/weapons.json. Each entry supports multiple quality tiers (Standard, Master-crafted, Artifact) and specific tags that interact with Chapter advantages.
Weapon Profile Logic
Weapons utilize "second profiles" to represent integrated systems (e.g., a Combi-weapon or a Power Fist with a built-in Flamer).
Sources: datafiles/data/weapons.json:1-120
Integration Requirements
When adding a new weapon, contributors must ensure:
- Technology Requirements: If the weapon is forgeable, it must reference a
requires_to_forgekey corresponding to entries indatafiles/data/technologies.json. - Tagging: Appropriate tags (e.g.,
bolt,plasma,heavy_ranged) must be applied to ensure compatibility with Chapter doctrines like "Bolter Drilling" or "Devastator Doctrine".
Sources: datafiles/data/weapons.json:151-168, datafiles/main/chapter_advantages.json:14-25
Conclusion
Contributions to ChapterMaster require a blend of data-driven content creation and adherence to automated quality control. By following these guidelines and utilizing the provided JSON schemas and formatting tools, contributors can ensure their additions are technically sound and properly integrated into the game's systems.