Skip to content

🛠️ Troubleshooting Guide

Overview

This guide helps you resolve common issues you might encounter while working with Alien Invasion. If you don't find your issue here, please check our GitHub Issues or create a new one.

Installation Issues

1. Python Dependencies

Problem: Error installing Python dependencies

pip install -r requirements.txt
ERROR: Could not find a version that satisfies the requirement...

Solution:

  1. Ensure you have Python 3.8+ installed
  2. Update pip: python -m pip install --upgrade pip
  3. Try installing with: pip install -r requirements.txt --no-cache-dir

2. Node.js Dependencies

Problem: Error installing Node.js dependencies

npm install
npm ERR! code ENOENT

Solution:

  1. Ensure you have Node.js 14+ installed
  2. Clear npm cache: npm cache clean --force
  3. Try installing with: npm install --force

Build Issues

1. Pygame Installation

Problem: Error installing Pygame

error: command 'gcc' failed with exit status 1

Solution:

  • Windows: Install Visual C++ Build Tools
  • Linux: Install build essentials: sudo apt-get install build-essential
  • macOS: Install Xcode Command Line Tools: xcode-select --install

2. Asset Loading

Problem: Missing or corrupted assets

pygame.error: Couldn't open assets/images/ship.png

Solution:

  1. Verify asset paths in config/assets.json
  2. Check file permissions
  3. Ensure assets are in the correct directory structure

Runtime Issues

1. Game Crashes

Problem: Game crashes on startup

pygame.error: video system not initialized

Solution:

  1. Check if Pygame is properly initialized
  2. Verify display settings
  3. Update graphics drivers

2. Performance Issues

Problem: Low frame rate or lag

FPS: 30/60

Solution:

  1. Check system requirements
  2. Reduce graphics quality in settings
  3. Close background applications
  4. Update graphics drivers

3. Audio Issues

Problem: No sound or distorted audio

pygame.error: Unable to open audio device

Solution:

  1. Check audio device settings
  2. Verify audio file formats
  3. Update audio drivers
  4. Check volume settings

Development Issues

1. Entity System

Problem: Entities not rendering or updating

AttributeError: 'Entity' object has no attribute 'sprite'

Solution:

  1. Verify component registration
  2. Check system requirements
  3. Debug entity creation process

2. Physics System

Problem: Collision detection issues

Collision not detected between entities

Solution:

  1. Check collision masks
  2. Verify spatial partitioning
  3. Debug collision response

3. Input System

Problem: Input not registering

Key press not detected

Solution:

  1. Check input mapping
  2. Verify event handling
  3. Test with different input devices

Testing Issues

1. Unit Tests

Problem: Tests failing

AssertionError: Expected True, got False

Solution:

  1. Check test environment
  2. Verify test data
  3. Update test cases

2. Integration Tests

Problem: System integration issues

SystemA not communicating with SystemB

Solution:

  1. Check system dependencies
  2. Verify event handling
  3. Debug system communication

Documentation Issues

1. MkDocs

Problem: Documentation build fails

mkdocs build
ERROR: Config value 'theme'...

Solution:

  1. Check MkDocs configuration
  2. Verify theme installation
  3. Update MkDocs and plugins

2. API Documentation

Problem: Missing or incorrect documentation

No documentation found for function

Solution:

  1. Check docstring format
  2. Verify documentation generation
  3. Update documentation comments

Common Error Messages

1. Python Errors

# ImportError
ImportError: No module named 'pygame'

# Solution: Install missing package
pip install pygame

# TypeError
TypeError: unsupported operand type(s)

# Solution: Check variable types and conversions

2. Runtime Errors

# AttributeError
AttributeError: 'NoneType' object has no attribute

# Solution: Check for null references

# KeyError
KeyError: 'component_name'

# Solution: Verify component registration

Getting Help

1. Reporting Issues

When reporting an issue, please include:

  1. Error message or behavior
  2. Steps to reproduce
  3. Environment details
  4. Expected vs actual behavior

Next Steps