Troubleshooting & Error Logs
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The troubleshooting and logging system in ChapterMaster provides developers and users with the necessary tools to identify, track, and resolve issues within the game environment and its associated data files. This system encompasses localized log storage, real-time console styling for debugging, and automated scripts for maintaining data integrity.
The primary goal of this system is to capture runtime errors, data parsing issues, and script execution failures. By providing structured logs and visual feedback through the game console, the project ensures that both game logic errors and data-driven configuration issues (such as those found in Chapter Data) can be addressed efficiently.
Sources: datafiles/README.md:16-22, stitch.config.json:2-10
Log Storage & Locations
Logs are stored locally on the user's machine to allow for post-mortem analysis of crashes or unexpected behavior. The system differentiates between general error logs and specific message histories.
Directory Structure
| Log Type | File Path | Description |
|---|---|---|
| General Logs | %AppData%\Local\ChapterMaster\Logs | Root directory for all generated log files. |
| Message Logs | %AppData%\Local\ChapterMaster\Logs\last_messages.log | Records the most recent history of in-game messages and communications. |
| Save Data | %AppData%\Local\ChapterMaster\ | The base directory where persistent game state and logs reside. |
Sources: datafiles/README.md:14-22
Game Console Logging & Styling
The system utilizes a structured console output with regex-based pattern matching to categorize and color-code log entries. This allows for immediate visual identification of different severity levels.
Console Severity Levels
The logger recognizes specific patterns to apply unique styles to the output, as defined in the stitch configuration:
- DEBUG: High-detail technical information, colored blue/light gray.
- INFO: Standard operational messages, colored green.
- WARNING: Potential issues that do not halt execution, colored yellow.
- ERROR: Execution failures that require attention, colored red.
- CRITICAL: Fatal failures, highlighted in bold red.
Log Pattern Logic
The following diagram illustrates how the logging system processes a raw string into a formatted console entry:
The system specifically targets patterns like ^ (?<time>[^|]+)\| (?<level>LEVEL) \| (?<caller>[^>]+)>>(?<msg>.*) to extract time, level, caller, and message for individual styling.
Sources: stitch.config.json:34-87
Data Integrity & Formatting Tools
The project includes tools for maintaining the technical health of source files, particularly GML (GameMaker Language) files.
Gobo Formatter
The run_gobo.ps1 script acts as a diagnostic and maintenance utility. It automates the formatting of .gml files and logs errors if a file cannot be processed.
- Update Logic: If the formatter (
gobo.exe) is missing, the script fetches the latest release from the GitHub API. - Error Reporting: The script tracks a
$Total,$Count, and$Errorsvariable, providing a summary of the operation's success or failure. - Exclusions: Certain directories like
.git,.svn, andprefabsare excluded from processing to prevent corruption of version control or engine metadata.
Sources: run_gobo.ps1:1-85
Data-Driven Error Prevention
Many potential issues are prevented by strict JSON schemas in the datafiles/ directory. For example, psychic powers and chapter configurations include "TODO" markers and structural examples to guide developers and prevent data parsing errors.
- Chapters: Files like
33.jsoninclude extensive comments on fleet composition and squad layouts to prevent invalid game states. - Psychic Powers: The
psychic_powers.jsonfile contains notes regarding the transition from named structs to arrays to simplify looping and reduce logic errors.
Sources: datafiles/main/chapters/33.json:173-185, datafiles/data/psychic_powers.json:1-5
Summary
Troubleshooting in ChapterMaster is a multi-layered process involving localized log files for user support, regex-styled console output for real-time debugging, and automated formatting scripts for developer maintenance. By centralizing logs in the %AppData% directory and enforcing data structures through commented JSON templates, the project maintains a robust environment for both play and development.