---

The Complete Guide to Building Hangman in C# with Functional Reactive Programming

Discover how to build the classic Hangman game in C# using Functional Reactive Programming (FRP). This guide transforms complex, stateful game logic into a clean, declarative, and manageable stream of data, leveraging the power of System.Reactive (Rx.NET) to create elegant, responsive applications.

---

You’ve built a few applications, maybe even a simple game. You start with a button click event, update a variable here, change a label there. It feels straightforward at first. But as features pile on—timers, scorekeeping, complex win/loss conditions—your code becomes a tangled web of event handlers, mutable state flags, and hard-to-trace bugs. You're left wondering, "There has to be a better way to manage this chaos."

This struggle is a classic sign of imperative programming hitting its limits in interactive applications. The problem isn't your logic; it's the paradigm. What if you could stop manually managing state and instead describe your application's behavior as a series of transformations on data streams? This is the promise of Functional Reactive Programming (FRP), and by the end of this guide, you will not only understand its core principles but will have implemented a fully functional Hangman game that is robust, testable, and remarkably elegant. Let's start this journey and master the fundamentals of C# through a new, powerful lens.

---

What is Functional Reactive Programming (FRP)?

Functional Reactive Programming is a programming paradigm for handling asynchronous data flows, often called "streams." Think of it as "functional programming applied to streams of values that change over time." Instead of reacting to discrete events like a button click and manually changing variables, you model these events as a continuous stream.

In a traditional event-driven model, you might write code like this:

// Imperative, event-driven approach
private int guessCount = 0;
private void OnGuessButtonClicked(object sender, EventArgs e)
{
    guessCount++;
    UpdateGuessCountLabel(guessCount);
    // ... more logic
}

With FRP, you define the relationship declaratively:

// Declarative, FRP approach
IObservable<int> guessCountStream = guessButtonClickStream.Scan(0, (acc, click) => acc + 1);

// A UI element would "subscribe" to this stream
guessCountStream.Subscribe(count => UpdateGuessCountLabel(count));

The core components of FRP, especially in C# using the System.Reactive (Rx.NET) library, are:

• IObservable<T>: Represents the source of the data stream. It's the producer of events. Think of it as the counterpart to IEnumerable<T>, but for asynchronous, "pushed" data instead of synchronous, "pulled" data.
• IObserver<T>: Represents the consumer of the stream. It has methods like OnNext(T value), OnError(Exception ex), and OnCompleted() that are called by the IObservable.
• Subject<T>: A special type that is both an IObservable and an IObserver. It acts as a proxy, allowing you to manually push values into a stream and multicast them to multiple subscribers.
• LINQ Operators: The true power of FRP comes from a rich set of extension methods (like Select, Where, Scan, Merge, Buffer) that allow you to filter, transform, combine, and compose streams in a declarative way.

This paradigm shifts your focus from "what to do when X happens" to "what the value of Y is, based on the stream of X events."

  ● Event Source (e.g., User Input)
  │
  ├─ Event A (time=t1)
  │
  ├─ Event B (time=t2)
  │
  ▼
┌───────────────────┐
│ Operator (e.g.,   │
│ .Where(x => ...)  │
└────────┬──────────┘
         │
         ▼
  ● Transformed Stream
  │
  └─ Event B' (time=t2)
  │
  ▼
┌───────────────────┐
│ Subscriber        │
│ (e.g., UI Update) │
└───────────────────┘

---

Why Use FRP for a Game Like Hangman?

Hangman seems simple, but its state can quickly become complex. You need to track the secret word, the letters guessed so far (both correct and incorrect), the number of remaining attempts, and the overall game status (won, lost, or ongoing). In an imperative model, every guess requires you to manually update all these pieces of state and then refresh the UI accordingly. This can lead to bugs where one piece of state is updated but another is forgotten.

FRP elegantly solves this by defining the game's entire state as a derivative of a single stream: the player's guesses. Each new guess produces a new, immutable game state. Other values, like the masked word display ("h_ngm_n") or the remaining guesses count, are simply different "views" or "projections" of that core game state stream.

This approach offers several powerful advantages:

• Declarative Logic: Your code describes what the state is, not how to update it step-by-step. This makes the logic easier to read and reason about.
• Centralized State Management: All state changes flow through a single, predictable pipeline. There are no random methods modifying state from the side, which eliminates a whole class of bugs.
*Immutability: By treating each state as a new, immutable object, you prevent unexpected side effects and make debugging and testing far simpler.
• Compositionality: Streams can be easily combined and transformed. Need to add a timer? Create a timer stream and merge it with the guess stream to influence the game state. This is incredibly powerful for adding new features without rewriting existing logic.

Let's compare the two approaches directly for the Hangman problem.

FRP vs. Traditional Imperative Approach

Aspect	Functional Reactive Programming (FRP)	Traditional Imperative / Event-Driven
State Management	State is an immutable object derived from a stream of events. Logic is centralized and declarative.	State is a collection of mutable fields (e.g., int remainingGuesses;, List<char> guessedLetters;) updated manually in event handlers.
Data Flow	Unidirectional and predictable. Input stream -> State stream -> UI streams.	Often bidirectional and complex. UI events modify state, and state modifications trigger UI updates, which can sometimes trigger more events.
Code Example	gameStateStream = guessStream.Scan(initialState, UpdateState);	void OnGuess(char c) { remainingGuesses--; guessedLetters.Add(c); /* ... */ }
Concurrency	Rx.NET provides powerful schedulers (.ObserveOn(), .SubscribeOn()) to manage threading with ease.	Requires manual thread management with locks, semaphores, or async/await, which can be error-prone.
Testability	Highly testable. You can feed a controlled stream of guesses and assert the resulting state stream's output.	Can be harder to test due to reliance on UI events and mutable shared state. Requires more mocking and setup.
Learning Curve	Steeper initially. Requires a mental shift to "thinking in streams."	More intuitive for beginners as it maps directly to cause-and-effect actions.

---

How to Implement the C# Hangman Game with FRP

We'll build our solution using the System.Reactive library (often called Rx.NET), which is the standard for FRP in .NET. You can add it to your project via NuGet.

Terminal Command to add the dependency:

dotnet add package System.Reactive

Our implementation will be encapsulated in a single class, HangmanGame, which will expose various streams representing the game's state. A UI (console, WPF, MAUI, etc.) could then subscribe to these streams to display the game to the player.

Step 1: Define the Game State and Status

First, we need a way to represent the entire state of the game at any given moment. An immutable record is perfect for this. We also need an enum for the game's status.

// Represents the possible outcomes of the game
public enum GameStatus
{
    Ongoing,
    Won,
    Lost
}

// An immutable snapshot of the game's state at any point in time
public record GameState(
    string SecretWord,
    IReadOnlySet<char> Guesses,
    int RemainingGuesses)
{
    // Derived property for incorrect guesses
    public IReadOnlySet<char> IncorrectGuesses => 
        Guesses.Where(g => !SecretWord.Contains(g, StringComparison.OrdinalIgnoreCase)).ToHashSet();

    // Derived property for the masked word display (e.g., "p_o_ram")
    public string MaskedWord => 
        new string(SecretWord.Select(c => Guesses.Contains(char.ToLower(c)) ? c : '_').ToArray());

    // Derived property for the current game status
    public GameStatus Status
    {
        get
        {
            if (MaskedWord.Equals(SecretWord, StringComparison.OrdinalIgnoreCase))
                return GameStatus.Won;
            if (RemainingGuesses <= 0)
                return GameStatus.Lost;
            return GameStatus.Ongoing;
        }
    }
}

Notice how IncorrectGuesses, MaskedWord, and Status are derived from the core state (SecretWord, Guesses, RemainingGuesses). This is a key functional concept that prevents state desynchronization.

Step 2: Design the Core `HangmanGame` Class

This class will orchestrate our streams. It will take a secret word, manage an internal stream of guesses, and expose public streams for the UI to consume.

using System.Reactive.Linq;
using System.Reactive.Subjects;

public class HangmanGame : IDisposable
{
    private const int MaxIncorrectGuesses = 7;
    private readonly string _secretWord;
    
    // The Subject is our entry point for player guesses. It's both an Observer and an Observable.
    private readonly Subject<char> _guessSubject = new Subject<char>();
    
    // The core of our logic: a stream of GameState objects.
    private readonly IObservable<GameState> _gameStateStream;

    // Publicly exposed streams derived from the core game state stream.
    public IObservable<string> MaskedWordStream { get; }
    public IObservable<int> RemainingGuessesStream { get; }
    public IObservable<GameStatus> GameStatusStream { get; }
    public IObservable<IEnumerable<char>> IncorrectGuessesStream { get; }

    public HangmanGame(string secretWord)
    {
        _secretWord = secretWord.ToLower();

        var initialState = new GameState(
            SecretWord: _secretWord,
            Guesses: new HashSet<char>(),
            RemainingGuesses: MaxIncorrectGuesses
        );

        // The magic happens here with the Scan operator.
        // It accumulates state over time based on the stream of guesses.
        _gameStateStream = _guessSubject
            .Scan(initialState, (currentState, guess) => 
            {
                // Ignore guesses that have already been made
                if (currentState.Guesses.Contains(guess))
                {
                    return currentState;
                }

                var newGuesses = currentState.Guesses.ToHashSet();
                newGuesses.Add(guess);

                var isIncorrect = !_secretWord.Contains(guess);
                var remaining = isIncorrect 
                    ? currentState.RemainingGuesses - 1 
                    : currentState.RemainingGuesses;

                return new GameState(_secretWord, newGuesses, remaining);
            })
            // Publish().RefCount() makes sure multiple subscribers share a single underlying subscription.
            .Publish()
            .RefCount();

        // Derive the public streams from the main state stream.
        // DistinctUntilChanged() is a crucial optimization to prevent sending duplicate values.
        MaskedWordStream = _gameStateStream
            .Select(state => state.MaskedWord)
            .DistinctUntilChanged();

        RemainingGuessesStream = _gameStateStream
            .Select(state => state.RemainingGuesses)
            .DistinctUntilChanged();

        GameStatusStream = _gameStateStream
            .Select(state => state.Status)
            .DistinctUntilChanged()
            // Stop the stream once the game is won or lost.
            .TakeWhile(status => status == GameStatus.Ongoing, inclusive: true); 

        IncorrectGuessesStream = _gameStateStream
            .Select(state => state.IncorrectGuesses.AsEnumerable())
            .DistinctUntilChanged(new EnumerableComparer<char>());
    }

    // Public method for the player to make a guess.
    public void Guess(char letter)
    {
        // We only push to the subject if the game is still ongoing.
        // The check for status could also be built into the stream itself.
        if (_gameStateStream.Select(s => s.Status).FirstAsync().Wait() == GameStatus.Ongoing)
        {
            _guessSubject.OnNext(char.ToLower(letter));
        }
    }

    // Clean up the subject when the game object is disposed.
    public void Dispose()
    {
        _guessSubject.OnCompleted();
        _guessSubject.Dispose();
    }
}

// Helper class for comparing enumerables in DistinctUntilChanged
public class EnumerableComparer<T> : IEqualityComparer<IEnumerable<T>>
{
    public bool Equals(IEnumerable<T> x, IEnumerable<T> y)
    {
        return Enumerable.SequenceEqual(x, y);
    }

    public int GetHashCode(IEnumerable<T> obj)
    {
        return obj.Aggregate(0, (hash, item) => hash ^ item.GetHashCode());
    }
}

Step 3: Detailed Code Walkthrough

Let's dissect the core logic of the HangmanGame class. The entire architecture revolves around transforming the _guessSubject into the final state streams.

    ● Player Input
    │
    ▼
  ┌─────────────────┐
  │  Guess('a')     │
  └────────┬────────┘
           │
           ▼
  ┌─────────────────┐
  │ _guessSubject   │
  │ (Subject<char>) │
  └────────┬────────┘
           │
           ▼
  ┌─────────────────┐
  │ .Scan(          │
  │   initialState, │
  │   UpdateLogic   │
  │ )               │
  └────────┬────────┘
           │
           ▼
  ● _gameStateStream (IObservable<GameState>)
  │
  ├─────────┬──────────┬────────────┐
  │         │          │            │
  ▼         ▼          ▼            ▼
┌───────┐ ┌───────┐  ┌───────┐    ┌──────────┐
│.Select│ │.Select│  │.Select│    │.Select   │
│(Masked) │(Status) │  │(Guesses)│    │(Incorrect)│
└───────┘ └───────┘  └───────┘    └──────────┘
  │         │          │            │
  ▼         ▼          ▼            ▼
 Masked   Status    Remaining   Incorrect
  Word     Stream     Guesses      Guesses
 Stream              Stream        Stream

1. The Input: _guessSubject
   This is a Subject<char>, which acts as our reactive pipeline's entry point. The Guess(char letter) method simply pushes the player's guess into this subject using _guessSubject.OnNext(letter).
2. The Accumulator: .Scan()
   This is the heart of our state management. Scan is like Aggregate (or reduce/fold in other languages) but for streams. It takes an initial state (our initialState object) and an accumulator function. For every new item that comes through the _guessSubject stream (a new guess), Scan calls our function with the previous state and the new guess, and emits the new state returned by the function. This creates a new IObservable<GameState> where each emitted item is the next state of the game.
3. The Core Stream: _gameStateStream
   The result of the Scan operation is our single source of truth. Every piece of information about the game can be derived from this stream. We use Publish().RefCount() to ensure that if we have multiple subscribers to this stream (and its derived streams), the underlying Scan logic only executes once per guess. This is a common and important pattern in Rx.NET.
4. The Derived Streams: .Select() and .DistinctUntilChanged()
   We don't want the UI to have to deal with the entire complex GameState object. Instead, we expose simpler, dedicated streams.
   • MaskedWordStream is created by taking _gameStateStream and using .Select(state => state.MaskedWord). This projects the stream of GameState objects into a stream of strings.
   • We then chain .DistinctUntilChanged(). This is a critical optimization. It ensures that we only push a new masked word to subscribers if it has actually changed. For example, if the player guesses an incorrect letter, the masked word stays the same, and this stream won't emit a redundant value.
   • The same logic applies to RemainingGuessesStream, GameStatusStream, and IncorrectGuessesStream.
5. Ending the Game: .TakeWhile()
   On the GameStatusStream, we add .TakeWhile(status => status == GameStatus.Ongoing, inclusive: true). This operator will let status values pass through as long as the condition is met. Once the status becomes Won or Lost, the condition is false. The inclusive: true parameter ensures that the final status (the one that broke the condition) is also emitted before the stream completes. This automatically stops the game and prevents further updates.

---

Alternative Approaches

While FRP is a powerful and elegant solution, it's essential to understand how it compares to other common patterns.

Traditional Imperative/Event-Driven Model

This is the most common approach for beginners. You would have a class with mutable fields and methods that directly modify them.

public class HangmanImperative
{
    private readonly string _secretWord;
    private HashSet<char> _guesses = new HashSet<char>();
    private int _remainingGuesses = 7;

    // Events for the UI to subscribe to
    public event Action<string> MaskedWordChanged;
    public event Action<int> RemainingGuessesChanged;
    public event Action<GameStatus> GameStatusChanged;

    public void Guess(char letter)
    {
        if (_guesses.Contains(letter)) return;
        
        _guesses.Add(letter);

        if (!_secretWord.Contains(letter))
        {
            _remainingGuesses--;
            RemainingGuessesChanged?.Invoke(_remainingGuesses);
        }

        MaskedWordChanged?.Invoke(GetCurrentMaskedWord());
        
        var status = GetCurrentStatus();
        GameStatusChanged?.Invoke(status);
    }
    
    // ... helper methods to calculate masked word and status
}

Critique: This code is more verbose and error-prone. The order of operations matters. If you forget to call one of the ?.Invoke methods, the UI becomes out of sync. State is scattered across multiple fields, and logic is spread inside a single, monolithic method. Adding new features, like a game timer that also reduces remaining guesses, would require modifying this `Guess` method or introducing complex interactions, increasing the risk of bugs.

State Machine Pattern

Another alternative is to model the game using a formal State Machine. You would define states like Playing, Won, and Lost, and transitions between them based on player actions (guesses). This is a very robust pattern for managing well-defined states but can be overly formal and verbose for a simple game like Hangman. It excels when the transitions themselves have complex logic, but here, the "state" is more about the data (guesses, word) than a distinct operational mode.

The FRP approach effectively gives us the benefits of a state machine (clear transitions from one state to the next) with the conciseness of functional data transformation.

---

Frequently Asked Questions (FAQ)

What is System.Reactive (Rx.NET)?

System.Reactive, or Rx.NET, is the official .NET library for Functional Reactive Programming. It provides the core interfaces (IObservable<T>, IObserver<T>) and a massive library of LINQ-style extension methods for creating, composing, and querying observable streams.

Is FRP the same as Functional Programming?

Not exactly. FRP is a paradigm that applies concepts from functional programming (like pure functions, immutability, and composition) to the problem of handling asynchronous and event-driven data. You can think of it as a specialized application of functional principles.

How does the `Scan` operator really work?

Scan is an accumulator. Imagine an array `[1, 2, 3]` and an initial value of `0`. A `scan` with a `+` operation would produce a sequence of `[1, 3, 6]` (0+1=1, 1+2=3, 3+3=6). It's different from `Aggregate` (fold/reduce) because it emits each intermediate result, creating a stream of accumulated values, which is perfect for modeling state that changes over time.

Can I use this FRP logic with any UI framework (WPF, MAUI, Blazor)?

Absolutely. The HangmanGame class we built is completely decoupled from any UI framework. It is a "view model" or "logic controller." In your WPF, MAUI, or other UI code, you would create an instance of HangmanGame and simply subscribe to its public streams (e.g., MaskedWordStream) to update your UI controls. This separation of concerns is a major benefit of the pattern.

What's the difference between a `Subject` and an `IObservable`?

An IObservable is a "read-only" stream; you can only subscribe to it to receive notifications. A Subject is both an IObservable and an IObserver. This means you can subscribe to it, but you can also manually push values into it (using OnNext), making it a bridge between the imperative world (e.g., a button click handler) and the reactive world (the stream).

Is FRP only for front-end or UI development?

No. While it's extremely popular for UI development due to its power in managing user interactions, FRP is also widely used in backend systems for processing real-time data, handling streams of events from message queues (like Kafka or RabbitMQ), financial data processing, and complex event processing engines.

Why is immutability so important in this FRP approach?

Immutability ensures that each state is a complete, consistent snapshot. By creating a new GameState object for each guess instead of modifying an existing one, you eliminate the possibility of race conditions and side effects. It makes the data flow predictable and allows for features like undo/redo to be implemented trivially by simply navigating the stream of past states.

---

Conclusion: Thinking in Streams

We have successfully transformed the logic of Hangman from a series of imperative commands into a declarative, predictable, and robust data flow. By modeling player inputs as a stream and deriving the entire game state from it, we've created a system that is not only easier to reason about but also far more scalable and maintainable. The initial learning curve of "thinking in streams" pays immense dividends, enabling you to tackle complex, interactive application logic with confidence and clarity.

This pattern of using a subject for inputs, a Scan operator to accumulate state, and Select with DistinctUntilChanged to expose derived streams is a powerful and reusable blueprint for many applications. We encourage you to apply these principles to your own projects and continue your learning journey. To see how this module fits into the bigger picture, explore our complete C# Learning Roadmap for more challenges and concepts.

Disclaimer: The code in this article was developed and tested against .NET 8 and System.Reactive v6.0. While the core concepts are timeless, specific method signatures or library features may evolve in future versions.

---

Published by Kodikra — Your trusted Csharp learning resource.