Bellum Totalis CLI

Bellum Totalis: CLI

A turn-based tactical battle simulation game inspired by the Total War series. Command armies, position units strategically, and defeat your enemies in this text-based warfare simulation.

Python Version badge: python-3.7+-blue.svg License badge: license-MIT-green.svg

Features

Army Management Four unit types: Infantry, Cavalry, Archers, and Siege units Each unit has distinct stats: health, damage, armor, speed, morale, and range Build your army with gold currency Balance different unit types for optimal strategy

Tactical Combat Alternating turn-based system for player and AI Position units on an ASCII grid battlefield Terrain effects: Hills (+30% defense), Forests (+20% defense), Rivers (impassable) Morale system where units break and flee when morale drops Strategic flanking and positioning affects combat effectiveness

AI Opponents Three difficulty levels: Easy, Normal, Hard AI chooses between aggressive, defensive, and flanking tactics AI uses terrain bonuses effectively

Battlefields Four unique maps: Open Plains: Simple open battlefield Forest Skirmish: Forest patches with cover River Crossing: Strategic choke points Hill Fortress: Defensive high ground

User Interface ASCII battlefield display with units shown as grid symbols Real-time status panels showing unit stats and army summaries Color coding: Green for player, Red for enemies Battle log tracks all combat actions Built-in help system with tutorial and command reference

Data Persistence Save and load battles in progress Automatic saves during battles Campaign mode to progress through multiple battles

Installation

Requirements Python 3.7 or higher

Setup Clone or download the game cd "Bellum Totalis CLI" Run the game python main.py

How to Play

Starting a Game

1. Run python main.py
2. Choose from the main menu: New Campaign: Build your army and fight through battles Quick Battle: Jump into a preset battle Load Game: Continue a saved game Tutorial: Learn the game mechanics

Unit Types

Symbol | Type | Strengths | Weaknesses [I] | Infantry | Balanced, good on hills | Vulnerable to cavalry charges [C] | Cavalry | Fast, strong on plains | Weak in forests [A] | Archers | Ranged attacks | Low health and armor [S] | Siege | Long range, high damage | Very slow

Terrain

Symbol | Type | Effect [.] | Plains | No bonuses [^] | Forest | +20% defense, slower movement [A] | Hills | +30% defense, vision bonus [~] | Water | Impassable

Controls

During combat: M - Move unit (within speed range) A - Attack enemy in range I - View unit information S - Skip unit's turn H - Show help Q - Quit battle

Victory Conditions Destroy all enemy units, OR Cause enemy army to rout (>50% of units fleeing)

Game Mechanics

Combat Damage = (Unit Damage x Morale Factor x Terrain Bonus) - (Target Armor x 0.5) Random variation: 90% to 110% of calculated damage Killing blows restore 10 morale to the attacker

Morale Units lose morale when taking damage Routing threshold: 25 morale Recovery threshold: 40 morale Army routs when >50% of units are routing

Terrain Bonuses Infantry: +10% on hills, +5% in forests Cavalry: +20% on plains, -20% in forests, -10% on hills Archers: +20% on hills, +10% in forests Siege: +30% on hills, -10% on plains

Project Structure

Bellum Totalis CLI/ main.py - Entry point game.py - Main game controller unit.py - Unit classes and stats army.py - Army management battlefield.py - Grid and terrain system ai.py - AI opponent controller ui.py - User interface and display save_manager.py - Save/load system saves/ - Save files directory README.md - This file requirements.txt - Dependencies

Tips & Strategy

1. Use terrain: Position units on favorable terrain for combat bonuses
2. Protect ranged units: Keep archers and siege behind infantry screens
3. Flank with cavalry: Use cavalry speed to attack from advantageous positions
4. Watch morale: Low morale units are ineffective and may flee
5. Balance your army: Don't rely on just one unit type
6. Secure high ground: Hills provide both defensive and offensive bonuses

Development

Extending the Game

Adding new unit types:

1. Add to UnitType enum in unit.py
2. Define stats in UNIT_STATS dictionary
3. Add symbol to UNIT_SYMBOLS
4. Define terrain bonuses

Adding new maps:

1. Create new method in MapPresets class in battlefield.py
2. Set terrain using set_terrain() method
3. Add to get_all_maps() and get_map_by_name() methods

License

MIT License - Feel free to modify and distribute!

Credits

Created as a learning project demonstrating: Object-oriented design in Python Turn-based game mechanics AI opponent algorithms ASCII user interfaces State management and persistence

Enjoy commanding your army! May your tactics prevail!