---

From Zero to Hero: Mastering Bowling Game Logic in Crystal

Scoring a bowling game seems simple on the surface, but its rules for strikes and spares introduce a fascinating logical challenge. This guide provides a comprehensive solution in Crystal, breaking down the state management and scoring algorithm required to accurately calculate the score for any valid bowling game, from a gutter-ball disaster to a perfect 300.

---

The Agony and Ecstasy of Manual Scorekeeping

Remember standing at a bowling alley, pencil in hand, trying to decipher the scoring sheet? You roll a strike, and suddenly you're not just adding ten; you're waiting for the next two balls to figure out the frame's true value. A spare is similar, but different. It's a system of delayed gratification and look-ahead logic that can trip up even seasoned bowlers.

This complexity is precisely what makes it a perfect problem to solve with code. It forces us to think about state, manage a sequence of events, and apply conditional logic based on future information. It’s a microcosm of the challenges we face in larger applications, like processing event streams or calculating financial data.

In this deep dive, we will conquer this classic programming puzzle using the Crystal language. We'll build a robust, elegant, and efficient solution from the ground up. By the end, you won't just have a working bowling scorer; you'll have a deeper understanding of algorithmic thinking, object-oriented design, and the power of Crystal's expressive syntax.

---

What is the Bowling Game Challenge?

Before writing a single line of code, we must deeply understand the domain rules. The scoring logic is the heart of the problem, and any misunderstanding here will lead to a faulty program. Let's break down the rules as defined in the exclusive kodikra.com curriculum.

The Core Rules of Ten-Pin Bowling

• Game Structure: A game consists of 10 frames.
• Pins: Each frame starts with 10 pins. The goal is to knock down as many as possible.
• Rolls: A player gets one or two rolls to knock down all 10 pins in a frame.

Scoring Scenarios

The score for a frame depends entirely on how many pins are knocked down and in how many rolls. There are three primary scenarios:

1. Open Frame: If the player uses two rolls but fails to knock down all 10 pins, the frame is "open." The score for that frame is simply the total number of pins knocked down. For example, rolling a 3 and then a 4 results in a frame score of 7.
2. Spare: If the player knocks down all 10 pins with two rolls, it's a "spare." The score for this frame is 10, plus a bonus equal to the number of pins knocked down on the next single roll.
3. Strike: If the player knocks down all 10 pins on the first roll of the frame, it's a "strike." This is the best possible outcome. The score for this frame is 10, plus a bonus equal to the total number of pins knocked down on the next two rolls. A strike also concludes the frame immediately; there is no second roll.

The Special Tenth Frame

The 10th frame is unique. It's the final frame, so the bonus logic changes slightly:

• If a player rolls a spare in the 10th frame, they get one extra "fill ball" to determine the bonus for the spare.
• If a player rolls a strike in the 10th frame, they get two extra "fill balls" to determine the bonus for the strike.
• If the 10th frame is an open frame, the game ends immediately after the second roll. No extra balls are awarded.

Our algorithm must gracefully handle all these conditions, especially the edge cases surrounding the final frame and consecutive strikes.

---

Why Use Crystal for This Logic Puzzle?

Crystal is a phenomenal choice for this type of algorithmic task. It combines the developer-friendly, elegant syntax of Ruby with the performance and type-safety of a compiled language like C. This unique blend offers several key advantages for building our bowling scorer.

Key Advantages of Crystal

• Readability: Crystal code is often self-documenting. Its clean syntax allows us to express the complex scoring logic in a way that is easy to read and maintain. This is crucial for algorithms where the logic itself is the most complex part.
• Type Safety: The Crystal compiler checks types at compile time. This means we can prevent entire classes of bugs, like trying to add a string to an integer, before the program even runs. It ensures our @rolls array will always contain integers and our methods return the expected types.
• Performance: As a compiled language, Crystal runs incredibly fast. While performance isn't critical for a single game scorer, this efficiency becomes vital if you were to scale this logic to simulate thousands or millions of games for statistical analysis.
• Nil Safety: Crystal's compiler enforces checks for nil values. This helps prevent the infamous "undefined method for nil" error, forcing us to handle cases where we might access an array element that doesn't exist, a common pitfall in look-ahead algorithms.

By leveraging these features, we can build a solution that is not only correct but also robust, efficient, and a pleasure to write. For more in-depth information on the language, dive deeper into our Crystal programming guides.

---

How to Model and Solve the Bowling Game

Our approach will be to create a Game class that encapsulates the state (the list of rolls) and the behavior (rolling a ball and calculating the score). This is a clean, object-oriented approach that makes the code reusable and easy to test.

Data Structure: Simplicity is Key

The only state we truly need to track is the sequence of pins knocked down in each roll. A simple Array(Int32) is the perfect data structure for this. We don't need to create complex Frame objects; we can deduce all the necessary information by iterating through this single array of rolls.

The Scoring Algorithm: A State Machine

The core of our solution is the score method. It acts like a state machine, moving through the rolls and calculating the score frame by frame. The key is to manage an index that points to the first roll of the current frame being scored. Based on whether that frame is a strike, spare, or open frame, we calculate its value and advance the index appropriately.

Here is a high-level visualization of the scoring loop's logic:

● Start Score Calculation (Frame 1, Roll Index 0)
│
▼
┌──────────────────┐
│ Loop 10 Times    │
│ (For Each Frame) │
└────────┬─────────┘
         │
         ▼
    ◆ Is it a Strike? (@rolls[index] == 10)
   ╱                   ╲
  Yes (Strike)          No
  │                      │
  ▼                      ▼
┌───────────────────┐  ◆ Is it a Spare? (@rolls[index] + @rolls[index+1] == 10)
│ Score = 10 +       │ ╱                   ╲
│ rolls[index+1] +   │Yes (Spare)            No (Open Frame)
│ rolls[index+2]     ││                       │
├────────────────────┤▼                       ▼
│ Advance index by 1 │┌───────────────────┐   ┌───────────────────┐
└────────┬───────────┘│ Score = 10 +       │   │ Score =            │
         │            │ rolls[index+2]     │   │ rolls[index] +     │
         │            ├────────────────────┤   │ rolls[index+1]     │
         │            │ Advance index by 2 │   ├────────────────────┤
         │            └────────┬───────────┘   │ Advance index by 2 │
         │                     │               └────────┬───────────┘
         └─────────────┼───────┘                        │
                       │                                │
                       └──────────────┬─────────────────┘
                                      │
                                      ▼
                                 ◆ Last Frame?
                               ╱               ╲
                              Yes               No
                              │                  │
                              ▼                  ▼
                         ● End Loop         Continue Loop

The Complete Crystal Solution

Let's put all the pieces together into a complete, well-commented Crystal class. We'll include robust error handling to make our class production-ready.

# Custom error class for bowling-specific issues
class BowlingError < Exception
end

class Game
  # The @rolls array stores the number of pins knocked down in each roll.
  @rolls : Array(Int32)

  def initialize
    @rolls = [] of Int32
  end

  # Records a roll.
  # Validates the number of pins to ensure it's between 0 and 10.
  def roll(pins : Int32)
    raise BowlingError.new("Pins must have a value from 0 to 10") unless pins.in?(0..10)
    @rolls << pins
    validate_frame_rolls
  end

  # Calculates the total score for the game.
  # Iterates through 10 frames, calculating the score for each based on
  # the rules for strikes, spares, and open frames.
  def score : Int32
    raise BowlingError.new("Score cannot be taken until the game is over") unless game_over?
    
    total_score = 0
    roll_index = 0

    10.times do
      if strike?(roll_index)
        total_score += 10 + strike_bonus(roll_index)
        roll_index += 1
      elsif spare?(roll_index)
        total_score += 10 + spare_bonus(roll_index)
        roll_index += 2
      else # Open frame
        total_score += open_frame_score(roll_index)
        roll_index += 2
      end
    end

    total_score
  end

  private

  # Helper to check if a frame is a strike.
  def strike?(roll_index)
    @rolls[roll_index]? == 10
  end

  # Helper to check if a frame is a spare.
  def spare?(roll_index)
    (@rolls[roll_index]? || 0) + (@rolls[roll_index + 1]? || 0) == 10
  end

  # Calculates the bonus for a strike (next two rolls).
  def strike_bonus(roll_index)
    (@rolls[roll_index + 1]? || 0) + (@rolls[roll_index + 2]? || 0)
  end

  # Calculates the bonus for a spare (next one roll).
  def spare_bonus(roll_index)
    @rolls[roll_index + 2]? || 0
  end

  # Calculates the score for an open frame (sum of two rolls).
  def open_frame_score(roll_index)
    (@rolls[roll_index]? || 0) + (@rolls[roll_index + 1]? || 0)
  end

  # Validates that the rolls for the current frame are logical.
  # For example, two rolls in a frame cannot sum to more than 10.
  def validate_frame_rolls
    pins_in_frame = 0
    frame_roll_count = 0
    is_tenth_frame = false
    frame_index = 0

    @rolls.each_with_index do |pins, i|
      # Don't validate bonus balls in the 10th frame yet
      next if is_tenth_frame && frame_roll_count > 1

      pins_in_frame += pins
      frame_roll_count += 1

      if pins_in_frame > 10
          raise BowlingError.new("Pin count exceeds 10 in a frame")
      end

      # Move to next frame
      if frame_roll_count == 2 || pins_in_frame == 10
        frame_index += 1
        is_tenth_frame = frame_index == 9
        pins_in_frame = 0
        frame_roll_count = 0
      end
    end
  end

  # Determines if the game is complete.
  # This logic is complex because the number of rolls can vary.
  def game_over? : Bool
    roll_index = 0
    frames = 0
    while frames < 10 && roll_index < @rolls.size
      if strike?(roll_index)
        roll_index += 1
      else
        # Need at least two rolls for a non-strike frame
        return false if roll_index + 1 >= @rolls.size
        roll_index += 2
      end
      frames += 1
    end
    # If we completed 10 frames, the game is over.
    frames == 10
  end
end

---

Where the Logic Comes Alive: A Code Walkthrough

Let's dissect the `score` method, as it contains the most critical logic. Understanding its flow is key to grasping the solution.

Step 1: Initialization and Loop

We start with a total_score of 0 and a roll_index of 0. The roll_index is our pointer; it tells us which position in the @rolls array marks the beginning of the frame we are currently scoring. We then begin a loop that will run exactly 10 times, once for each frame.

Step 2: Checking for a Strike

Inside the loop, the first thing we do is check if the current frame is a strike:

if strike?(roll_index)
  total_score += 10 + strike_bonus(roll_index)
  roll_index += 1
end

If @rolls[roll_index] is 10, we know it's a strike. We add 10 to the score, plus the bonus calculated by the strike_bonus helper method. This helper simply looks ahead and sums the next two rolls. Critically, we only advance the roll_index by 1, because a strike frame only consists of a single roll.

This "look-ahead" is the secret sauce of the algorithm:

   Current Frame
   (roll_index)
        │
        ▼
      ┌───┐
      │ 10│  ← Strike!
      └───┘
        │
        ├─► Look ahead one roll for bonus...
        │
        ▼
      ┌───┐
      │ 7 │
      └───┘
        │
        ├─► Look ahead two rolls for bonus...
        │
        ▼
      ┌───┐
      │ 2 │
      └───┘

  Frame Score = 10 (strike) + 7 + 2 = 19

Step 3: Checking for a Spare

If it's not a strike, we check for a spare. A spare occurs if the two rolls in the frame sum to 10.

elsif spare?(roll_index)
  total_score += 10 + spare_bonus(roll_index)
  roll_index += 2
end

The logic is similar to a strike, but the bonus is only the next single roll after the frame. The spare_bonus helper method retrieves this value. For a spare, we advance the roll_index by 2, as a spare frame always consists of two rolls.

Step 4: Handling an Open Frame

If the frame is neither a strike nor a spare, it's an open frame. This is the simplest case:

else # Open frame
  total_score += open_frame_score(roll_index)
  roll_index += 2
end

We simply sum the two rolls of the frame and add them to the total score. We then advance the roll_index by 2 to move to the next frame.

Running the Code

To use this class, you would save it as a file (e.g., bowling.cr), create an instance, record the rolls, and then call the score method.

Here's how you might test a perfect game:

# In a file named `main.cr`
require "./bowling.cr"

game = Game.new
12.times { game.roll(10) }
puts "Score of a perfect game: #{game.score}" #=> Should print 300

You can compile and run this from your terminal:

$ crystal run main.cr
Score of a perfect game: 300

---

Alternative Approaches and Considerations

While our single-array approach is efficient and elegant, it's not the only way to solve this problem. It's useful to consider alternatives to understand the design trade-offs.

Frame-Based Object Model

An alternative is to create a `Frame` class. As rolls are added, you could parse them into `Frame` objects. Each `Frame` object could store its own rolls and perhaps even a reference to the next frame to help calculate bonuses.

Approach	Pros	Cons
Single Array of Rolls (Our Method)	- Simple data structure. - Low memory overhead. - Logic is centralized in the `score` method.	- Scoring logic can feel complex due to manual index management. - State is less explicit.
Array of Frame Objects	- State is more explicit and encapsulated. - Can make calculating frame-specific scores easier. - Might be more readable for very complex rules.	- More complex to implement (parsing rolls into frames). - Higher memory usage due to object creation. - Can introduce complexity with object references (e.g., linking frames).

For this specific problem, the simplicity of the single array approach outweighs the benefits of a more complex object model. It perfectly solves the problem without unnecessary abstraction. This is a key lesson in software design: choose the simplest solution that works.

To continue your journey and tackle more challenges, explore the full Crystal Learning Path on kodikra.

---

Frequently Asked Questions (FAQ)

How is the 10th frame handled in this algorithm?

The beauty of this algorithm is that it doesn't need special logic for the 10th frame. The main loop runs 10 times. If the 10th frame is a strike or spare, the `strike_bonus` and `spare_bonus` methods will naturally read the "fill balls" from the end of the `@rolls` array, as they are simply the next rolls in the sequence. The game is considered "over" only when enough rolls are present to score all 10 frames, including any bonuses.

What happens if I enter an invalid number of pins, like 11 or -1?

The `roll` method includes validation. The line `raise BowlingError.new(...) unless pins.in?(0..10)` will immediately stop the program and raise a custom `BowlingError` if an invalid number of pins is provided, preventing the game from entering an invalid state.

Can this logic correctly score a perfect game (300)?

Yes. A perfect game is 12 consecutive strikes (10 strikes for the first 9 frames, and a strike plus two bonus strikes in the 10th). Our loop will correctly identify each of the first 9 frames as a strike, and for each one, the `strike_bonus` will be 20 (10 + 10 from the next two strikes). The 10th frame itself is a strike, and its bonus is also 20. This sums up to 300.

What is the time complexity of this scoring algorithm?

The time complexity is O(N), where N is the number of rolls in the game. Although we have a loop that runs a constant 10 times, the helper methods (`strike_bonus`, `spare_bonus`, etc.) access elements in the `@rolls` array. Since the number of rolls in a game is small and capped (at most 21 rolls), for all practical purposes, the algorithm runs in constant time, O(1).

How does Crystal's nil-safety help in this problem?

Look at the bonus calculation methods, like `(@rolls[roll_index + 1]? || 0)`. The `?` is the nil-safe call operator. It prevents a crash if we try to access an index that is out of bounds (which would return `nil`). The `|| 0` then provides a default value of 0. This makes the code much more resilient, especially when scoring an incomplete game or calculating bonuses near the end of the roll list.

Is Crystal a good language for beginners learning algorithms?

Absolutely. Its syntax is clean and approachable, much like Ruby or Python, which lowers the barrier to entry. However, its static typing and compile-time checks introduce beginners to important concepts of type safety and robust software design early on, which is incredibly valuable for long-term growth as a developer.

---

Conclusion: More Than Just a Game

We've successfully built a complete and robust bowling game scorer in Crystal. In doing so, we've explored fundamental programming concepts: state management with a simple array, algorithmic thinking with a look-ahead state machine, and robust design through error handling and helper methods.

The solution demonstrates the elegance of Crystal, where readable syntax and powerful compile-time guarantees work together to help you write correct and maintainable code. The problem of scoring a bowling game, while seemingly trivial, is a perfect exercise from the kodikra module for honing your ability to translate complex rules into clean, functional code.

Disclaimer: The code and concepts presented are based on Crystal version 1.12.x. While the core logic is timeless, always consult the official Crystal documentation for the latest syntax and best practices.

---

Published by Kodikra — Your trusted Crystal learning resource.