A turn-based, grid-based Star Trek strategy game inspired by the classic retro games Star Trek (1971) and Super Star Trek (1973). Command a Federation starship, explore the galaxy, engage in tactical combat, and complete missions in the Kirk-era 23rd century.

• Turn-based tactical combat with detailed ship systems
• 3D grid-based exploration with multiple z-levels
• Hybrid State Machine + Game Object + Component architecture
• Classic Star Trek setting (Kirk-era 23rd century)
• Multiple gameplay modes (Galaxy Map, Sector Map, Combat)
• Resource management and ship customization
• PyGame game engine with PySide6 UI framework

Navigate between sectors, plan missions, and manage fleet resources with a strategic view of Federation space.

Explore individual sectors on a 3D grid (up to 20x20x5), encounter alien species, dock at starbases, and discover anomalies.

Engage in tactical turn-based combat on specialized combat grids with environmental factors and detailed ship system management.

• Platform: Linux (primary target)
• Python: 3.14+ (uses latest language features)
• RAM: 512MB minimum for base assets
• Storage: 200MB for full installation

• PyGame 2.5+: Core game engine for rendering and game loop
• PySide6 6.7+: UI framework for menus, dialogs, and main window
• Qt Designer: Visual UI design tool (included with PySide6)
• Python Standard Library: Primary dependency approach

# Ensure Python 3.14+ is installed
python3 --version

# Install core dependencies
pip install pygame>=2.5 PySide6>=6.7

# Clone the repository
git clone https://github.com/L3DigitalNet/Star-Trek-Retro-Remake.git
cd Star-Trek-Retro-Remake

# Install package with dependencies (recommended)
pip install -e .

# Or install manually
pip install pygame>=2.5 PySide6>=6.7

# Run the game
cd star_trek_retro_remake
python3 main.py

# Install with development dependencies
pip install -e .[dev]

# Set up pre-commit hooks
pre-commit install

# Run tests to verify installation
cd star_trek_retro_remake
python3 -m pytest tests/ -v

# Run with coverage report
python3 -m pytest tests/ --cov=src --cov-report=term-missing

# Use Make commands for common tasks
make test          # Run tests
make lint          # Check code quality
make format        # Format code
make check         # Run all checks

• Mouse: Primary interaction method for all game elements
• Keyboard Shortcuts: Access common actions and menus
• Right-click: Context menus for detailed object information

1. Launch the game and select "New Game" from the main menu
2. Your ship (USS Enterprise) begins in a starting sector
3. Use the Sector Map to explore and find missions
4. Engage enemies in Combat Mode for tactical battles
5. Return to Galaxy Map for long-distance travel

• Energy Management: Allocate power between shields, weapons, and engines
• Turn-based Movement: Plan your moves strategically on the grid
• Ship Systems: Monitor and repair weapons, shields, engines, and sensors
• Resource Management: Manage fuel, supplies, and crew morale

Hybrid State Machine + Game Object + Component + MVC

┌─────────────────────────────────────────┐
│            PySide6 UI Layer             │
│        (Menus, Dialogs, Windows)        │
├─────────────────────────────────────────┤
│             Controller Layer            │
│        (Input, State Management)        │
├─────────────────────────────────────────┤
│              Model Layer                │
│         (Game Logic, Data)              │
├─────────────────────────────────────────┤
│             View Layer                  │
│        (PyGame Rendering)               │
└─────────────────────────────────────────┘

• Game State Machine: Manages transitions between Galaxy/Sector/Combat modes
• Game Objects: Starships, stations, and crew with natural hierarchies
• Component Systems: Modular ship systems (weapons, shields, engines, sensors)
• MVC Separation: Pure game logic isolated from UI for testability

star_trek_retro_remake/
├── main.py                 # Game entry point
├── src/
│   ├── game/
│   │   ├── application.py   # Main application controller
│   │   ├── model.py         # Core game logic and state
│   │   ├── view.py          # PySide6 UI and PyGame rendering
│   │   └── controller.py    # Input handling and coordination
│   ├── entities/           # Game objects (ships, stations)
│   ├── components/         # Ship systems and components
│   ├── states/            # State machine implementation
│   └── maps/              # Galaxy, sector, and combat maps
├── config/                # JSON configuration files
├── assets/               # Graphics, audio, and data
├── tests/               # Pytest test suite
└── docs/               # Documentation

The project uses pytest with AAA (Arrange-Act-Assert) pattern for comprehensive testing:

# Run all tests
python3 -m pytest tests/ -v

# Run specific test categories
python3 -m pytest tests/test_entities.py -v      # Entity system tests
python3 -m pytest tests/test_game_model.py -v   # Game logic tests

# Generate coverage report
python3 -m pytest tests/ --cov=src --cov-report=html

• Core Logic: 80%+ coverage for critical game mechanics
• Entity System: Full coverage for ship and station classes
• State Management: Complete state transition validation
• Component System: Comprehensive ship system testing

• Project structure and architecture setup
• Core MVC framework implementation
• Entity system with Game Object pattern
• Component system for ship subsystems
• State machine for game mode transitions
• TOML-based configuration system (migrated from JSON)
• Comprehensive test framework with pytest
• Development tooling (Makefile, pre-commit hooks, CI/CD)
• Custom exception hierarchy and event system
• Command pattern for undo/redo functionality

• PyGame rendering engine integration
• PySide6 UI implementation
• Galaxy and sector map generation
• Combat system implementation

• Basic ship movement and exploration
• Simple combat mechanics
• Resource management system
• Save/load functionality

This is currently a solo indie project for personal enjoyment. While not actively seeking contributors, suggestions and feedback are welcome through GitHub issues.

• Linux-Only: All code targets Linux exclusively (no Windows support)
• Python 3.14+: Use latest language features and modern syntax
• Type Hints: Comprehensive typing for all functions, variables, constants, collections
• PEP 8: Strict adherence to Python style guidelines
• F-strings Only: No .format() or % string formatting

• File Headers: All Python files must have proper shebang, encoding, and complete docstrings
• Per-File Docs: Every .py file in STRR/ has matching _doc.md file
• Inline Comments: Document significant code blocks, complex logic, and design decisions
• No Types in Docstrings: Rely on type hints instead
• See Documentation Standards for complete guidelines

• Write pytest tests for all new functionality (AAA pattern)
• 80%+ coverage for critical paths
• Design UI in Qt Designer - see Qt Designer Workflow

• Game Design Document: Complete game design specification
• Architecture Guide: Technical implementation details
• Qt Designer Workflow: UI design with Qt Designer
• Project Documentation: Detailed project information
• Change Log: Version history and updates

This is a fan-made project created for educational and entertainment purposes. All Star Trek intellectual property rights belong to their respective owners (Paramount/CBS). This project is not affiliated with or endorsed by the official Star Trek franchise.

• No commercial use: This game is completely free and open source
• Fair use: Content follows fan work guidelines and fair use principles
• Original content: Focuses on original implementations inspired by Star Trek
• No copyrighted assets: Avoids direct copying of official Star Trek material

This project is licensed under the MIT License - see the LICENSE file for details.

• Star Trek community for inspiration and decades of amazing content
• Classic games Star Trek (1971) and Super Star Trek (1973) for the foundational gameplay concepts
• Python gaming community for excellent frameworks and resources
• Open source contributors for the tools that make this project possible

Live long and prosper 🖖