API System Overview

[SYSTEM] System Commands

Category: System & Debugging Commands: Logger (5 commands) + Testing (11 commands) API Version: 1.3.11.2 Status: STABLE

---

Overview

System commands provide essential debugging, logging, and testing capabilities for the Bannerlord GameMaster mod. These commands enable you to monitor command execution through comprehensive logging, validate command reliability through automated testing, and troubleshoot issues during development and gameplay.

The system command set is divided into two major subsystems: the Command Logger for tracking and auditing command execution, and the Automated Testing Framework for validating command functionality. Together, these tools ensure reliable operation, facilitate debugging, and maintain command quality across game updates and modifications.

All system commands work in campaign mode and are designed for developers, testers, and power users who need visibility into command operations. They do not modify gameplay directly but provide critical infrastructure for command management and validation.

---

Command Reference

Quick Reference Table

Logger Commands

Command	Description	Category	Status
gm.log.enable	Enable command logging	Logger Control	STABLE
gm.log.disable	Disable command logging	Logger Control	STABLE
gm.log.status	Show logging status	Logger Info	STABLE
gm.log.clear	Clear log file contents	Logger Management	STABLE
gm.log.help	Display logger help	Logger Info	STABLE

Testing Commands

Command	Description	Category	Status
gm.test.register_standard	Register standard tests	Registration	STABLE
gm.test.register_integration	Register integration tests	Registration	STABLE
gm.test.register_all	Register all tests	Registration	STABLE
gm.test.register_all_run	Register and run all tests	Quick Test	STABLE
gm.test.run_all	Execute all registered tests	Execution	STABLE
gm.test.run_category	Run tests in category	Execution	STABLE
gm.test.run_single	Run specific test	Execution	STABLE
gm.test.list	List registered tests	Management	STABLE
gm.test.last_results	Show last test results	Management	STABLE
gm.test.clear	Clear registered tests	Management	STABLE
gm.test.help	Display testing help	Management	STABLE

---

Command Categories

Logger Control Commands

Commands for managing the command logging system.

gm.log.enable - Activates command logging and initializes the log file. All subsequent GameMaster commands are recorded with timestamps, parameters, and results. Supports custom file paths or uses default location in Documents folder.

gm.log.disable - Deactivates command logging. Previously logged commands remain in the file, but new commands are not recorded. Does not delete existing log file.

Logger Information & Management

Commands for viewing logger status and managing log files.

gm.log.status - Displays current logging status, file location, file size, and entry count statistics. Quick overview without opening the log file.

gm.log.clear - Clears all content from the log file while keeping the file and logging system intact. Writes new session header after clearing. Permanent deletion of history.

gm.log.help - Displays comprehensive help information about logging commands with usage examples and integration notes.

Test Registration Commands

Commands for registering test suites into the testing framework.

gm.test.register_standard - Registers the standard test suite containing basic validation tests for core command functionality. Tests parameter validation, error handling, and basic execution.

gm.test.register_integration - Registers integration test suite that validates game state changes. Tests verify commands actually modify the game state as expected (modifies game, use on test saves).

gm.test.register_all - Registers all available test suites (standard + integration). Clears previously registered tests before registration.

gm.test.register_all_run - Convenience command that registers all tests and immediately runs them. Fastest way to validate the entire command system.

Test Execution Commands

Commands for running registered tests and generating reports.

gm.test.run_all - Executes all currently registered tests and generates comprehensive report with pass/fail statistics, success rate, and detailed results for each test.

gm.test.run_category - Executes all tests in a specific category (e.g., HeroQuery, ClanManagement). Useful for focused testing of specific command groups.

gm.test.run_single - Executes a single specific test by its unique test ID. Ideal for debugging failed tests or re-running specific scenarios.

Test Management Commands

Commands for managing registered tests and viewing results.

gm.test.list - Lists all registered tests organized by category. Optionally filter by specific category. Shows test IDs, descriptions, commands being tested, and expected outcomes.

gm.test.last_results - Displays results from the most recent test run. Supports both summary (quick stats) and verbose (detailed report) output modes.

gm.test.clear - Clears all registered tests from the test runner. Use to reset before registering a new test suite.

gm.test.help - Displays comprehensive help information about testing commands with usage examples and workflows.

---

Common Parameters

Logger Parameters

File Path (Optional)

• Custom log file location
• Default: Documents\Mount and Blade II Bannerlord\Configs\GameMaster\command_log.txt
• Supports full file paths

Verbosity

• All commands provide detailed output
• Status command shows file statistics

Testing Parameters

Category Name

• Category identifier (e.g., "HeroQuery", "ClanManagement")
• Case-sensitive
• Use list command to see available categories

Test ID

• Unique test identifier (e.g., "test_hero_query_001")
• Case-sensitive
• Use list command to see available test IDs

Verbose Mode

• Boolean or keyword "verbose"
• Controls detail level of results display
• Summary vs. detailed output

---

Usage Examples

Example 1: Basic Logging Workflow

Enable logging for debugging session:

gm.log.enable
gm.hero.set_gold player 10000
gm.clan.add_hero empire wanderer_1
gm.log.status
gm.log.disable

Result: All commands logged to file, status checked, logging disabled after session.

Example 2: Custom Log Location

Use custom log path for specific save game:

gm.log.enable C:\MyLogs\SaveGame1\commands.txt

Result: Commands logged to custom location for organized tracking.

Example 3: Quick Test Validation

Validate entire command system rapidly:

gm.test.register_all_run

Result: All tests registered and executed, comprehensive report generated.

Example 4: Focused Category Testing

Test specific command group after modifications:

gm.test.register_all
gm.test.list HeroQuery
gm.test.run_category HeroQuery
gm.test.last_results verbose

Result: Only hero query tests executed, detailed results reviewed.

Example 5: Debugging Failed Test

Investigate and re-run specific failing test:

gm.test.run_all
gm.test.run_single test_hero_query_001

Result: All tests run to identify failures, specific test re-executed for debugging.

---

Best Practices

TIP: Enable Logging for Troubleshooting

Always enable logging when troubleshooting issues or during important operations:

gm.log.enable

The log provides valuable diagnostic information for resolving problems.

TIP: Custom Paths for Organization

Use custom log paths to organize logs by save game or purpose:

gm.log.enable C:\MyLogs\Campaign1\session1.txt

Keeps command history organized and associated with specific gameplay sessions.

TIP: Regular Log Maintenance

Check log file size periodically and clear when needed:

gm.log.status
gm.log.clear

Prevents log files from growing excessively large.

TIP: Test After Game Updates

Run comprehensive tests after game updates or mod changes:

gm.test.register_all_run

Ensures all commands still function correctly after updates.

TIP: Integration Tests on Test Saves

Integration tests modify game state, so run on dedicated test saves:

gm.test.register_integration
gm.test.run_all

Protects main save games from test-induced modifications.

---

Notes & Warnings

WARNING: Integration Test State Changes

Integration tests MODIFY game state:

• Heroes have attributes changed
• Clans have properties modified
• Kingdoms may be affected
• Always run on test saves or backup main saves first

WARNING: Log File Overwrite

Enabling logging with a custom path overwrites existing files without warning. Backup important log files before reusing paths.

WARNING: Log Clear is Permanent

The gm.log.clear command permanently deletes all log history. Consider backing up log files before clearing if history is important.

NOTE: Logger Performance Impact

Command logging has minimal performance impact:

• Asynchronous file writes
• Only active when enabled
• Automatic error handling
• Negligible impact on command execution speed

NOTE: Test Categories

Tests are organized by categories:

• HeroQuery - Hero search tests
• ClanManagement - Clan operation tests
• KingdomManagement - Kingdom operation tests
• ItemManagement - Item operation tests
• Categories help focus testing on specific systems

NOTE: Log File Format

Log files use structured, human-readable format:

• Session headers with timestamps
• Command entries with timestamps
• Execution results
• Separator lines for readability

Format is designed for manual review and analysis.

NOTE: Test Result Persistence

Test results persist until next test run:

• Last results always available via last_results command
• Results cleared when new tests execute
• Verbose mode provides complete detail

---

Related Documentation

Command Groups

All system commands support the other command groups:

• Hero Management Commands
• Clan Management Commands
• Kingdom Management Commands
• Troop Management Commands
• Item Management Commands
• Query Commands

User Guides

• Quick Start Guide - Getting started with GameMaster
• Best Practices - Recommended usage patterns
• Troubleshooting - Use logging for troubleshooting

---

Common Workflows

Debugging Workflow

When investigating issues:

1. gm.log.enable
2. (execute problematic commands)
3. gm.log.status
4. (review log file in Documents folder)
5. gm.log.disable

Audit Trail Workflow

For important save games:

1. gm.log.enable C:\MySaves\campaign1_commands.txt
2. (gameplay session with commands)
3. (log maintained permanently)

Validation Workflow

After game updates or mod changes:

1. gm.test.register_all_run
2. (review results)
3. (re-run failed tests individually if needed)

Development Testing Workflow

For mod developers:

1. gm.test.clear
2. gm.test.register_all
3. gm.test.list
4. gm.test.run_category YourCategory
5. gm.test.last_results verbose

---

Last Updated: 2025-12-16 API Version: 1.3.11.2

Return to API Reference | Home