info2Wortsalat/todo.md

Word Salad Game - Comprehensive TODO List

Project Overview

A word search puzzle game where words are randomly placed in a grid (horizontally or vertically), and players must find them by drawing lines over the letters. Built with C and Raylib graphics library.

---

📋 Core Implementation Tasks

🔴 CRITICAL - Must be implemented for basic functionality

1. input.c - Word Reading Function ⚠️ HIGH PRIORITY

Function: readWords()

Requirements:

• Read words from file (words.txt) line by line
• Handle multiple delimiters: comma (,), semicolon (;), space ( ), newline (\n)
• Convert all words to uppercase for consistency
• Store words in the provided words[][] array
• Return the total count of words read
• Handle empty files gracefully (return 0)
• Validate max word count limit (maxWordCount)
• Trim whitespace from words
• Skip empty words/lines

Implementation Notes:

• Use fgets() to read lines (max MAX_LINE_LEN)
• Use strtok() for tokenizing with multiple delimiters: ", ;\n\t\r"
• Use toupper() to convert characters to uppercase
• Use isalpha() to validate word characters
• Handle buffer overflow protection

Test Coverage:

• test_readWords_simple() - Basic newline-separated words
• test_readWords_with_delimiters() - Multiple delimiter types
• test_readWords_empty_file() - Empty file handling

---

2. game.c - Word Salad Creation ⚠️ HIGH PRIORITY

Function: createWordSalad()

Requirements:

• Initialize the grid with EMPTY_CHAR (0)
• Seed random number generator with srand(time(NULL))
• For each word, attempt placement:
  • Try random positions and orientations (horizontal/vertical)
  • Max attempts: MAX_RAND_TRIES_PER_WORD (10)
  • Check if word fits without overlapping incorrectly
  • Place word character by character
• Fill remaining empty cells with random uppercase letters (A-Z)
• Return count of successfully placed words

Placement Algorithm:

1. Random orientation: 0 = horizontal, 1 = vertical
2. Random starting position within valid bounds
3. Check if entire word fits
4. Check for conflicts (can overwrite same letter, not different letters)
5. Place word if valid
6. Increment placed counter

Edge Cases:

• Words too long for grid size
• Grid too small for multiple words
• All positions occupied

Test Coverage:

• test_createWordSalad_all_fit() - All words fit in large grid
• test_createWordSalad_too_small() - Grid too small for some words
• test_createWordSalad_allWordsPlaced() - Verify words are actually in grid

---

3. game.c - Display Function 🟡 MEDIUM PRIORITY

Function: showWordSalad()

Requirements:

• Print grid to console in readable format
• Add spacing between characters for clarity
• Optional: Add row/column numbers for debugging
• Format: Each row on separate line

Example Output:

  0 1 2 3 4
0 Y E T I X
1 N A B C D
2 M O N S T E R
3 O G H I J

---

4. main.c - Game Validation & Launch ⚠️ HIGH PRIORITY

Requirements:

• Compare placedWords with wordCount
• If all words placed successfully:
  • Call startGame() with word salad and parameters
  • Pass SALAD_SIZE as search field size
  • Use appropriate window size (e.g., 800)
• If some words couldn't be placed:
  • Print error message to stderr
  • Indicate how many words failed
  • Set exitCode = EXIT_FAILURE
  • Don't start the game

Implementation:

// TODO: Complete this section
if (placedWords == wordCount) {
    // All words successfully placed - start the game
    showWordSalad(wordSalad, SALAD_SIZE);  // Optional: show in console
    startGame(wordSalad, SALAD_SIZE, words, wordCount, 800);
} else {
    // Error: Not all words could be placed
    fprintf(stderr, "Error: Only %u out of %u words could be placed in the grid.\n", 
            placedWords, wordCount);
    exitCode = EXIT_FAILURE;
}

---

🧪 Testing & Validation

Unit Tests

• Run all unit tests: ./unit_tests or make test
• Ensure all 6 tests pass:
  • test_readWords_simple
  • test_readWords_with_delimiters
  • test_readWords_empty_file
  • test_createWordSalad_all_fit
  • test_createWordSalad_too_small
  • test_createWordSalad_allWordsPlaced

Integration Testing

• Test with provided words.txt file
• Test with custom word lists
• Test with edge cases:
  • Empty file
  • Single word
  • Very long words
  • Maximum word count
  • Special characters/numbers (should be filtered)

---

🔧 Build & Compilation

Prerequisites

• GCC compiler installed
• Make utility available
• Raylib library (already included in project)
• Unity test framework (already included)

Build Commands

# Build main executable
make

# Build and run unit tests
make test

# Clean build artifacts
make clean

Platform-Specific Notes

• Windows: Use Start_Windows/ directory
• Linux: Use Start_Linux/ directory
• macOS: Use Start_Mac/ directory

---

📦 Additional Enhancements (Optional)

Nice-to-Have Features

• Add diagonal word placement
• Add backward word placement (reverse strings)
• Difficulty levels (grid size, word count)
• Save/load game state
• High score tracking
• Time-based gameplay
• Hint system
• Multiple language support

Code Quality

• Add comprehensive comments
• Follow consistent naming conventions
• Memory leak detection with Valgrind
• Static analysis with cppcheck
• Code formatting with clang-format

Documentation

• Update README.md with:
  • Build instructions
  • How to play
  • Screenshots
  • System requirements
• Add inline code documentation
• Create developer guide

---

🐛 Known Issues & Debugging

Common Problems

• Segmentation fault: Check array bounds, null pointers
• Words not found: Ensure uppercase conversion in both placement and search
• Random seed: Call srand(time(NULL)) only once
• File not found: Check relative paths, working directory

Debugging Tips

• Use printf() to trace execution
• Test functions individually
• Use debugger (gdb/lldb) for complex issues
• Enable compiler warnings: -Wall -Wextra

---

✅ Definition of Done

A task is considered complete when:

• Code compiles without warnings
• All relevant unit tests pass
• Function meets specification requirements
• Edge cases are handled
• Code is properly commented
• No memory leaks (verified with Valgrind on Linux/Mac)
• Integrated and tested with other components

---

📅 Suggested Implementation Order

1. ✅ Week 1: Implement readWords() in input.c

   • Start with simple parsing
   • Add delimiter handling
   • Test with unit tests

2. ✅ Week 2: Implement createWordSalad() in game.c

   • Grid initialization
   • Word placement algorithm
   • Random fill
   • Test with unit tests

3. ✅ Week 3: Implement showWordSalad() and complete main.c

   • Console display
   • Game validation logic
   • Integration testing

4. ✅ Week 4: Testing, debugging, and polish

   • Fix all unit test failures
   • Test with various word lists
   • Optimize performance
   • Code cleanup

---

📝 Notes

• The graphical interface (graphicalGame.c) is already implemented
• Raylib library handles all graphics rendering
• Focus on the core game logic implementation
• Test frequently to catch bugs early
• Use the provided Unity test framework

---

Last Updated: November 5, 2025
Project: Word Salad Game (Wortsalat)
Course: Informatik 2 - Programmierung (3. Semester)