LOTRAOM - Lord of the Rings: Age of Men

A comprehensive Mount & Blade II: Bannerlord modification that brings the world of Middle-earth to life with authentic Lord of the Rings races, gameplay systems, and strategic depth.

---

Table of Contents

• About
• Features
• Technical Highlights
• Getting Started
• Development Workflow
  • Branching Strategy
  • Build Commands
  • Testing
• Contributing
• Documentation
• Community

---

About

LOTRAOM (Lord of the Rings: Age of Men) is a feature-rich Bannerlord mod that transforms the game into a Middle-earth experience. Built with modern software engineering practices, the mod features a robust C# architecture with dependency injection, comprehensive testing, and performance optimizations designed for large-scale battles and complex campaign gameplay.

This project is designed for collaborative development, with a well-defined branching strategy that supports multiple developers working simultaneously on features and bug fixes.

---

Features

Gameplay Systems

• Race-Based Combat Bonuses - Authentic LOTR racial abilities affecting damage, defense, and tactics

  • Men, Elves, Dwarves, Orcs, Uruk-hai, and more
  • Dynamic bonus calculations based on attacker/defender race combinations
  • Indexed rule parsing engine for performance

• Custom Battles - Enhanced battle configuration with LOTR factions

  • Faction-specific troop rosters
  • Custom battle scenarios

• Advanced AI Systems

  • Strategic intelligence for settlement targeting
  • Diplomatic decision-making
  • Enhanced warfare behaviors

• Custom Wanderers - LOTR-themed wandering companions with unique backstories

• Messenger System - In-game messenger management integrated with the encyclopedia

• Warg System - AI-controlled wargs with custom behavior trees

• Strategic Gameplay

  • Troop weight-based party size limits
  • Custom starting conditions (funds, influence, equipment)
  • Enhanced bandit behaviors

Factions & Cultures

Playable factions include:

• Free Peoples: Rohan, Gondor, Erebor, Rivendell, Mirkwood
• Forces of Darkness: Mordor, Isengard, Gundabad, Dol Guldur, Harad, Rhûn, Umbar
• Independent: Dunland, and more

---

Technical Highlights

Architecture

• Modern C# Design: Built on .NET Framework 4.7.2 with nullable reference types enabled
• Dependency Injection: DryIoC container for clean, testable architecture
• Design Patterns: Hook pattern, Strategy pattern, Builder/Fluent APIs, Registry pattern
• Harmony Patching: Non-destructive game modifications using Harmony 2.x
• UIExtender Integration: Custom UI extensions for encyclopedia and game menus
• Mod Configuration Menu (MCM): In-game configuration options

Performance Optimizations

• Object Pooling: Reduces garbage collection pressure in combat-heavy scenarios
• String Caching: Pre-computed enum-to-string mappings with concurrent dictionary caching
• Indexed Rule Parsing: Fast bonus calculation engine
• Optimized Hook Coordination: Efficient game event handling

Quality Assurance

• Test-Driven Development: 2039 unit tests (MSTest + NSubstitute); 26.89% line coverage today, held above a 26% pre-commit floor that ratchets up as coverage climbs
• Code Quality Standards: SOLID principles, interface segregation, constructor injection
• CI/CD Ready: Automated build scripts for Windows (PowerShell) and Linux (Bash)
• Documentation: XML docs, Architecture Decision Records (ADR), inline comments

---

Getting Started

For Developers

Prerequisites

• Visual Studio 2022 or later (or VS Code with C# extension)
• .NET Framework 4.7.2 SDK
• Mount & Blade II: Bannerlord (for game references)
• Git

Initial Setup

1. Clone the repository

   git clone https://github.com/haterade22/LOTRAOM.git
   cd LOTRAOM

2. Set up environment variables

   # Windows PowerShell
   ./setup-dev-env.ps1

   This sets the BANNERLORD_GAME_DIR environment variable required for build scripts.

3. Build the project

   # Windows PowerShell
   ./build.ps1
   
   # Linux/WSL Bash
   ./build.sh

4. Run tests

   dotnet test LOTRAOM.Tests/LOTRAOM.Tests.csproj

5. Activate the pre-commit hook (once per clone)

   git config core.hooksPath .githooks

   .githooks/pre-commit builds, runs the tests and checks the coverage floor — for every committer, not only for the ones using Claude. It steps aside without gating when nothing is staged, when no .cs/.csproj/.sln/.props/.targets/.json/.xml file is staged, when the floor cannot be read, and when no PowerShell is on PATH — so a Linux/WSL setup that builds through ./build.sh may never be gated at all. Git will not honour a hooks path from tracked content on its own — a repository that ran code on checkout would be a supply-chain hole — so every clone has to opt in with this one command.

---

Development Workflow

Branching Strategy

We use a multi-tier branching strategy designed for collaborative development:

dev (main development branch)
 ├── feature/your-feature-name
 ├── bugfix/issue-description
 └── ... (merge back to dev after testing)
     ↓
alpha (internal team testing)
     ↓
beta (community testing)
     ↓
public (stable releases)

Branch Descriptions

• dev: The main development branch. All feature and bugfix branches are created from dev, and all pull requests merge back to dev.
• feature/*: Feature branches for new functionality
• bugfix/*: Bug fix branches for resolving issues
• alpha: Internal testing by the development team (merged from dev when ready)
• beta: Community testing with select testers (merged from alpha when stable)
• public: Stable public releases (merged from beta after validation)

Workflow

1. Create a branch from dev

   git checkout dev
   git pull origin dev
   git checkout -b feature/my-new-feature

2. Develop and test your changes

   • Write tests first (TDD approach)
   • Implement the feature
   • Ensure all tests pass
   • Build and verify in-game

3. Commit your changes

   git add .
   git commit -m "Add: Description of your feature"

4. Push your branch

   git push origin feature/my-new-feature

5. Create a Pull Request to dev

   • Describe your changes
   • Reference any related issues
   • Request code review

6. After approval, merge to dev

   • The team lead will merge to alpha, beta, and public at appropriate times

Build Commands

Windows (PowerShell)

# Build debug version (default)
./build.ps1

# Build release version
./build.ps1 -Configuration Release

# Build + tests + coverage floor (what the pre-commit hook runs)
./build.ps1 -RunTests -MinCoverage 26

Linux/WSL (Bash)

# Build debug version (default)
./build.sh

# Build release version
./build.sh Release

Build scripts automatically copy DLLs to the appropriate module folders.

That 26 is a ratchet floor — raised as real coverage climbs, never lowered. It is defined once, in .claude/hooks/pre-commit-tests.sh, and .githooks/pre-commit reads it from there so the two gates cannot drift apart.

Testing

# Run all tests
dotnet test LOTRAOM.Tests/LOTRAOM.Tests.csproj

# Run tests with specific configuration
dotnet test LOTRAOM.Tests/LOTRAOM.Tests.csproj -c Debug

# Run tests with specific framework target
dotnet test LOTRAOM.Tests/LOTRAOM.Tests.csproj -f net472

Code Quality Standards

• Follow SOLID principles
• Use constructor injection for dependencies
• Write unit tests for new features (TDD)
• Document public APIs with XML comments
• Use meaningful variable and method names
• Follow existing code patterns and conventions

See CLAUDE.md for detailed coding guidelines and architecture patterns.

---

Contributing

We welcome contributions from the community! Whether you're interested in:

• Adding new features
• Fixing bugs
• Improving documentation
• Optimizing performance
• Creating new LOTR content

How to Contribute

1. Join the team - Reach out on our Discord or open an issue expressing interest
2. Create an issue - Required: Before starting work, create an issue to be tracked by the team. This prevents duplicate efforts and ensures coordination across the development team.
3. Pick an issue - Check the Issues page for open tasks, or work on the issue you created
4. Follow the workflow - Use the branching strategy outlined above
5. Submit quality code - Follow our code quality standards and include tests
6. Engage in code review - Be open to feedback and iterate on your changes

Development Resources

• Architecture Overview - Technical documentation
• Architecture Decision Records (ADR) - Key design decisions
• CLAUDE.md - Comprehensive developer guide

---

Documentation

• Project Overview - Technical summary and architecture
• Branching Strategy - Detailed branching workflow
• Architecture Decision Records (ADR) - Design decisions and rationale
• CLAUDE.md - AI-assisted development guide with patterns and best practices

Project Structure

/Main/                    # Core mod implementation
  /Features/              # Feature modules (race bonuses, AI, combat, etc.)
  /Services/              # Core services (hooks, pooling, combat)
  /CampaignBehaviors/     # Campaign integration
  /Models/                # Custom game models
  /_Module/               # Module metadata and binaries
/ModuleData/              # XML game configuration
/GUI/                     # UI definitions
/Assets/                  # Textures and sprites
/LOTRAOM.Tests/           # Unit tests
/Decompiled/              # Decompiled v1.2.12 reference source (gitignored, generated)
/docs/                    # Documentation

---

Community

• Discord: Join our server
• Issues: Report bugs or request features
• Discussions: Join the conversation
• Releases: Download stable versions

---

License

This project uses split licensing to balance community access with protection of reusable infrastructure:

• Mod Content (Main/, ModuleData/, GUI/, Assets/) - MIT License
• Infrastructure & Tools (launcher/, devops/, web/) - Polyform Noncompete 1.0.0
• Documentation (docs/) - CC BY-SA 4.0

See LICENSE.md for complete licensing details, including what you can and cannot do with each component.

---

Acknowledgments

• TaleWorlds Entertainment for Mount & Blade II: Bannerlord
• The Bannerlord modding community
• LOTR Armory team for asset support
• Inspiration and contributions from:
  • Alliance - Bannerlord modding innovations
  • Shadows of the Past - LOTR mod development
  • The Old Realms (TOR) - Fantasy total conversion techniques
  • Realms of Thrones (ROT) - Campaign and faction systems
  • A Dance of Dragons (ADOD) - Advanced gameplay mechanics
  • Realms Forgotten (RF) - World-building and content design
• All contributors to this project

---

Note: This is a community mod and is not affiliated with or endorsed by TaleWorlds Entertainment, Middle-earth Enterprises, or any official Lord of the Rings license holders.