Yacht in Arm64-assembly: Complete Solution & Deep Dive Guide

Mastering Logic in Arm64 Assembly: The Complete Guide to the Yacht Dice Game

This guide provides a comprehensive walkthrough on how to calculate the score for the Yacht dice game using Arm64 assembly. We cover sorting dice values, counting frequencies, and implementing logic for categories like Full House, Straights, and Yacht to determine the final score based on five given dice.

Venturing into the world of Arm64 assembly can feel like learning to speak a new language, one understood only by the machine's core. You're no longer working with convenient abstractions like variables and functions but directly manipulating registers and memory. This can be daunting, especially when faced with a problem that requires complex logical branching. You might find yourself staring at a sea of mnemonics, wondering how to translate a simple set of game rules into a functional program.

This is a common struggle, but it's also where true mastery begins. The Yacht dice game module from the exclusive kodikra.com curriculum is the perfect crucible for forging your low-level programming skills. It’s more than just a game; it's a practical exercise in algorithmic thinking, data manipulation, and control flow. This guide will demystify the process, transforming what seems like a complex challenge into a series of manageable, understandable steps. We will build a complete solution from the ground up, turning raw assembly instructions into a robust scoring engine.

What is the Yacht Dice Game?

The Yacht dice game is a classic game of chance and strategy belonging to the same family as Yahtzee and Poker Dice. The fundamental goal is to score points by rolling five dice and then selecting a category that best matches the outcome of the roll. The challenge, and the core of this programming task, lies in correctly interpreting the dice and calculating the score for a given category.

The game is played over twelve rounds, but for our purposes, we are focused on the logic of a single round: given five dice values and one category, what is the score? The dice are standard six-sided dice, so each die will have a value from 1 to 6.

Understanding the Scoring Categories

The heart of the problem is the twelve distinct scoring categories. Each has a unique rule for calculating the score. Let's break them down in detail. A solid understanding of these rules is the prerequisite to writing any code.

Why Solve This in Arm64 Assembly?

Tackling a logic-heavy problem like Yacht in a high-level language such as Python or Java would be relatively straightforward. You'd have access to built-in sorting functions, dictionaries or hashmaps for counting frequencies, and a simple `if/else` or `switch` structure. So, why descend to the level of assembly?

The answer lies in building a deep, fundamental understanding of how computers actually work. When you write in assembly, you are not just solving a problem; you are orchestrating the CPU's core operations.

• Direct Hardware Control: You gain an unparalleled appreciation for what the processor is doing. Every instruction corresponds to a direct action: moving data between registers, loading from memory, performing arithmetic, or changing the flow of execution.
• Performance Optimization: While not critical for this specific problem, learning assembly is the key to wringing every last drop of performance out of a system. You learn about instruction pipelines, cache efficiency, and how to structure code for maximum speed.
• Understanding Abstractions: By building logic from scratch, you see what high-level languages do for you. You'll never look at a simple `for` loop or a `sort()` function the same way again after implementing them yourself with jumps and comparisons.
• Essential for Specialized Fields: This knowledge is not just academic. It's crucial for careers in embedded systems, operating system development, compiler design, reverse engineering, and cybersecurity.

This kodikra module is designed to be a bridge. It uses a familiar, tangible problem (a dice game) to teach these profound, low-level concepts, making them accessible and practical.

How to Structure the Scoring Logic: A High-Level Plan

Before we dive into a single line of Arm64 code, we must devise a clear algorithm. A common mistake in assembly programming is to start coding without a solid plan, which quickly leads to a tangled mess of labels and jumps. Our strategy will be methodical and broken into distinct phases.

The core function, let's call it score, will take two arguments: a pointer to an array of five dice values and an integer representing the chosen category.

    ● Start: score(dice_array_ptr, category_id)
    │
    ▼
  ┌───────────────────┐
  │  1. Sort the Dice │
  │ (e.g., [4,1,3,1,4] │
  │  becomes [1,1,3,4,4])│
  └─────────┬─────────┘
            │
            ▼
  ┌───────────────────┐
  │ 2. Count Frequencies│
  │ (e.g., two 1s,    │
  │ one 3, two 4s)    │
  └─────────┬─────────┘
            │
            ▼
  ◆   3. Check Category ID   ◆
  │ (Branch to specific logic) │
  ├────────────┬─────────────┤
  │            │             │
  ▼            ▼             ▼
[Full House?] [Straight?] [Yacht?] ... etc.
  │            │             │
  ├────────────┴─────────────┘
  │
  ▼
┌───────────────────┐
│ 4. Calculate Score│
│ (Based on category logic) │
└─────────┬─────────┘
          │
          ▼
    ● End: Return Score

Phase 1: Sorting the Dice

Many of the scoring categories become trivial to check if the dice are sorted. For example, checking for a "Little Straight" (1, 2, 3, 4, 5) is as simple as verifying that the sorted array is exactly `[1, 2, 3, 4, 5]`. Sorting also groups identical dice together, which simplifies counting for pairs, three of a kind, etc.

For an array of only five elements, a simple algorithm like Insertion Sort is more than sufficient. It's easy to implement and has very little overhead.

Phase 2: Counting Frequencies (Optional but Recommended)

After sorting, we can iterate through the dice to count the occurrences of each number. A more direct approach is to create a "frequency map" or an array of 6 counters (one for each possible die face). We can iterate through the five dice and increment the corresponding counter. For example, if the dice are `[1, 3, 3, 5, 5]`, our frequency array would look like this: `[1, 0, 2, 0, 2, 0]`, indicating one '1', zero '2's, two '3's, etc.

This frequency data makes checking for "Full House" (is there a count of 3 and a count of 2?) or "Four of a Kind" (is there a count of 4?) incredibly efficient.

Phase 3: The Main Dispatcher

This is the central nervous system of our function. It will look at the `category_id` and use it to jump to the correct block of code that handles the logic for that specific category. In assembly, this is typically implemented with a series of compare-and-branch instructions or, for more advanced implementations, a jump table.

Phase 4: Category-Specific Logic

Each block of code will perform the final checks and calculations.

• Simple Sums (Ones-Sixes, Choice): These are the easiest. We just iterate through the dice and add to a running total if they match the category or, for "Choice", add all of them.
• Fixed Value (Straights, Yacht): These are boolean checks. If the condition is met (e.g., dice are `[1, 2, 3, 4, 5]`), return a fixed score (30). Otherwise, return 0.
• Frequency-Based (Full House, Four of a Kind): These will use the frequency counts we calculated earlier to determine if the condition is met and then calculate the score accordingly.

Where the Magic Happens: A Deep Dive into the Arm64 Code

Now, let's translate our high-level plan into concrete Arm64 assembly code. We'll analyze the solution provided in the kodikra learning path, explaining each instruction and its purpose. The code follows the standard ARM64 Procedure Call Standard (PCS), where the first arguments are passed in registers x0, x1, etc., and the return value is placed in x0.

Our function signature in C would look like this:

int score(uint16_t* dice, int category);

This means the pointer to the dice array will be in register x0, and the category ID will be in register w1.

Defining Constants

Good assembly code starts with clear definitions. Using the .equ directive, we create symbolic names for the category IDs. This makes the code infinitely more readable than using magic numbers like 7, 8, 9, etc.

.equ CHOICE, 0
.equ ONES, 1
.equ TWOS, 2
.equ THREES, 3
.equ FOURS, 4
.equ FIVES, 5
.equ SIXES, 6
.equ LITTLE_STRAIGHT, 7
.equ BIG_STRAIGHT, 8
.equ FULL_HOUSE, 9
.equ FOUR_OF_A_KIND, 10
.equ YACHT, 11

The `sort` Subroutine: An Insertion Sort Implementation

The first logical step is sorting. The provided solution uses a helper function, sort, which implements the Insertion Sort algorithm. It takes the pointer to the dice array in x0.

/* void sort(uint16_t *dice) */
sort:
    mov w9, #1              // Outer loop counter 'i', starts from the second element (index 1)
.outer_loop:
    cmp w9, #5              // Compare i with 5. Loop while i < 5.
    b.ge .sort_done         // If i >= 5, sorting is finished.

    ldrh w12, [x0, w9, uxtw #1] // Load the current element dice[i] into w12.
                                // uxtw #1 is like multiplying w9 by 2 (size of halfword).
    mov w10, w9             // Inner loop counter 'j' = i.

.inner_loop:
    cmp w10, #0             // Compare j with 0. Loop while j > 0.
    b.le .inner_done        // If j <= 0, exit inner loop.

    sub w11, w10, #1        // Calculate index for the element to the left: j - 1.
    ldrh w13, [x0, w11, uxtw #1] // Load dice[j-1] into w13.

    cmp w13, w12            // Compare dice[j-1] with the current element (dice[i]).
    b.le .inner_done        // If dice[j-1] <= current_element, it's in the right place.

    // Shift the element dice[j-1] to the right
    strh w13, [x0, w10, uxtw #1] // Store dice[j-1] at position j.
    sub w10, w10, #1        // Decrement j.
    b .inner_loop           // Repeat inner loop.

.inner_done:
    // Insert the original element at its correct sorted position
    strh w12, [x0, w10, uxtw #1] // Store current_element at position j.

    add w9, w9, #1          // Increment outer loop counter i.
    b .outer_loop           // Repeat outer loop.

.sort_done:
    ret                     // Return from subroutine.

Code Walkthrough: `sort`

• mov w9, #1: The outer loop counter, which we can call `i`, is initialized in register w9. We start at 1 because an array with one element is already sorted.
• .outer_loop: This label marks the beginning of the main loop that iterates from the second to the last element of the array.
• ldrh w12, [x0, w9, uxtw #1]: This is a key instruction. ldrh means "load halfword (16 bits)". x0 is the base address of the array. The address being accessed is `x0 + (w9 * 2)`. The `uxtw #1` part is a scaled-register offset, which effectively multiplies the index in w9 by 2 (the size of a `uint16_t`). The value at `dice[i]` is loaded into register w12. We'll call this our `key` value.
• mov w10, w9: The inner loop counter, `j`, is initialized in w10 with the value of `i`.
• .inner_loop: This loop's job is to find the correct position for our `key` value by shifting all larger elements to its right.
• sub w11, w10, #1: Calculates the index `j-1`.
• ldrh w13, [x0, w11, uxtw #1]: Loads the element to the left, `dice[j-1]`, into w13.
• cmp w13, w12: Compares `dice[j-1]` with our `key`. If `dice[j-1]` is less than or equal to our `key`, we've found the insertion point, and we branch to .inner_done.
• strh w13, [x0, w10, uxtw #1]: If `dice[j-1]` was larger, we "shift" it to the right by storing it at the address for `dice[j]`.
• sub w10, w10, #1: Decrement `j` and loop again.
• .inner_done: When the inner loop finishes, w10 holds the correct index for our `key`.
• strh w12, [x0, w10, uxtw #1]: We store the `key` value (from w12) into its final sorted position.
• ret: Standard instruction to return from a subroutine.

The Main `score` Function

Now for the main event. The score function orchestrates the entire process. It calls sort, then branches to the appropriate logic based on the category.

.text
.globl score

score:
    stp x29, x30, [sp, #-32]!   // Save frame pointer and link register to the stack
    mov x29, sp                 // Set up new frame pointer
    stp x19, x20, [sp, #16]     // Save callee-saved registers we will use

    // Arguments: x0 = dice*, w1 = category
    mov x19, x0                 // Save dice pointer in x19
    mov w20, w1                 // Save category in w20

    // Step 1: Sort the dice array
    bl sort                     // Call the sort subroutine. x0 is already the first arg.

    // After sorting, the dice are in order. Now we can implement the main logic.
    // We'll use x19 (which holds the dice pointer) from now on.

    // Step 2: Main dispatcher - check category in w20
    cmp w20, #ONES
    b.eq handle_ones_to_sixes
    cmp w20, #TWOS
    b.eq handle_ones_to_sixes
    cmp w20, #THREES
    b.eq handle_ones_to_sixes
    cmp w20, #FOURS
    b.eq handle_ones_to_sixes
    cmp w20, #FIVES
    b.eq handle_ones_to_sixes
    cmp w20, #SIXES
    b.eq handle_ones_to_sixes
    
    cmp w20, #CHOICE
    b.eq handle_choice

    cmp w20, #LITTLE_STRAIGHT
    b.eq handle_little_straight
    
    cmp w20, #BIG_STRAIGHT
    b.eq handle_big_straight

    cmp w20, #YACHT
    b.eq handle_yacht
    
    cmp w20, #FULL_HOUSE
    b.eq handle_full_house
    
    cmp w20, #FOUR_OF_A_KIND
    b.eq handle_four_of_a_kind

    // Default case (should not happen with valid input)
    mov w0, #0
    b exit_score

// --- Implementation of Handlers ---

handle_ones_to_sixes:
    mov w0, #0                  // Initialize score = 0
    mov w2, #0                  // Loop counter i = 0
.sum_loop:
    cmp w2, #5
    b.ge exit_score             // Exit if i >= 5
    ldrh w3, [x19, w2, uxtw #1] // Load dice[i]
    cmp w3, w20                 // Compare dice[i] with category (1 for ONES, 2 for TWOS, etc.)
    b.ne .sum_loop_next         // If not equal, skip add
    add w0, w0, w3              // Add to score
.sum_loop_next:
    add w2, w2, #1
    b .sum_loop

handle_choice:
    mov w0, #0                  // score = 0
    mov w2, #0                  // i = 0
.choice_loop:
    cmp w2, #5
    b.ge exit_score
    ldrh w3, [x19, w2, uxtw #1] // Load dice[i]
    add w0, w0, w3              // Add to score
    add w2, w2, #1
    b .choice_loop

handle_little_straight:
    // Sorted dice must be [1, 2, 3, 4, 5]
    ldrh w2, [x19]              // dice[0]
    ldrh w3, [x19, #2]          // dice[1]
    ldrh w4, [x19, #4]          // dice[2]
    ldrh w5, [x19, #6]          // dice[3]
    ldrh w6, [x19, #8]          // dice[4]
    cmp w2, #1
    b.ne .straight_fail
    cmp w3, #2
    b.ne .straight_fail
    cmp w4, #3
    b.ne .straight_fail
    cmp w5, #4
    b.ne .straight_fail
    cmp w6, #5
    b.ne .straight_fail
    
    // Success
    mov w0, #30
    b exit_score
.straight_fail:
    mov w0, #0
    b exit_score

handle_big_straight:
    // Sorted dice must be [2, 3, 4, 5, 6]
    ldrh w2, [x19]
    ldrh w3, [x19, #2]
    ldrh w4, [x19, #4]
    ldrh w5, [x19, #6]
    ldrh w6, [x19, #8]
    cmp w2, #2
    b.ne .straight_fail
    cmp w3, #3
    b.ne .straight_fail
    cmp w4, #4
    b.ne .straight_fail
    cmp w5, #5
    b.ne .straight_fail
    cmp w6, #6
    b.ne .straight_fail
    
    // Success
    mov w0, #30
    b exit_score

handle_yacht:
    // All 5 dice must be the same. Since it's sorted, just check dice[0] == dice[4]
    ldrh w2, [x19]              // dice[0]
    ldrh w3, [x19, #8]          // dice[4]
    cmp w2, w3
    b.ne .yacht_fail
    
    // Success
    mov w0, #50
    b exit_score
.yacht_fail:
    mov w0, #0
    b exit_score
    
// ... More complex handlers for Full House and Four of a Kind below ...

exit_score:
    ldp x19, x20, [sp, #16]     // Restore callee-saved registers
    ldp x29, x30, [sp], #32     // Restore frame pointer and link register
    ret                         // Return with score in w0

Code Walkthrough: `score` and Simple Handlers

• Prologue: The first few lines (stp, mov x29, sp) are standard function prologue code. They save the previous frame pointer (x29) and the link register (x30, which holds the return address) to the stack, creating a new stack frame for this function. We also save x19 and x20 because the ARM64 calling convention requires us to preserve their original values.
• Argument Saving: We copy the arguments from x0 and w1 into callee-saved registers x19 and w20. This is good practice because the call to sort will overwrite x0.
• bl sort: Branch with Link. This instruction calls our sort subroutine. The address of the next instruction is stored in x30 so ret knows where to return.
• Dispatcher: The series of cmp and b.eq instructions acts as a switch statement, directing the program flow to the correct handler based on the category ID in w20.
• handle_ones_to_sixes: This single block of code cleverly handles all six of the simple sum categories. It iterates through the dice, and for each die, it compares its value (w3) to the category ID (w20). Since we defined ONES=1, TWOS=2, etc., this comparison works perfectly. If they match, the die's value is added to the score in w0.
• handle_choice: Even simpler. It just loops through all five dice and adds their values to the score in w0.
• handle_little_straight: Because the array is sorted, this check is straightforward. We load each of the five dice into separate registers and compare them to the expected sequence: 1, 2, 3, 4, 5. If any check fails, we branch to .straight_fail to set the score to 0. Otherwise, we set the score to 30.
• handle_yacht: Sorting makes this check incredibly easy. If all five dice are the same, then after sorting, the first element must be equal to the last element. We compare `dice[0]` and `dice[4]`. If they match, it's a Yacht.
• Epilogue: The ldp and ret instructions at the end are the function epilogue. They restore the saved registers and the previous stack frame, then return control to the caller. The final score is left in w0 as per the calling convention.

Handling Complex Categories: Full House and Four of a Kind

These categories are trickier because they depend on counts of dice, not just their values. The most robust way to handle this is by analyzing the sorted array.

    ● Start "Full House" Check
    │ (Dice are sorted, e.g., [3,3,5,5,5])
    ▼
  ┌───────────────────────────┐
  │ Load dice[0] and dice[4]  │
  └────────────┬──────────────┘
               │
               ▼
  ◆ Are dice[0] and dice[4] different? ◆
  ╱             (Must be two distinct groups)      ╲
 Yes                                                 No (It's a Yacht)
  │                                                  │
  ▼                                                  ▼
┌──────────────────┐                            ┌───────────┐
│ Check Pattern 1: │                            │ Score = 0 │
│ XX YYY           │                            └─────┬─────┘
└────────┬─────────┘                                  │
         │                                            │
         ▼                                            │
 ◆ dice[0]==dice[1] AND dice[2]==dice[4] ? ◆          │
╱                     ╲                               │
Yes (It's a Full House) No                            │
 │                      │                             │
 ▼                      ▼                             │
┌──────────────┐   ┌──────────────────┐               │
│ Sum all dice │   │ Check Pattern 2: │               │
│ Return Score │   │ XXX YY           │               │
└──────┬───────┘   └────────┬─────────┘               │
       │                    │                         │
       │                    ▼                         │
       │     ◆ dice[0]==dice[2] AND dice[3]==dice[4] ? ◆
       │    ╱                     ╲                     │
       │   Yes (It's a Full House) No (Not a Full House) │
       │    │                      │                     │
       │    ▼                      ▼                     │
       │   ┌──────────────┐   ┌───────────┐             │
       │   │ Sum all dice │   │ Score = 0 │             │
       │   │ Return Score │   └─────┬─────┘             │
       │   └──────┬───────┘         │                   │
       └──────────┼─────────────────┼───────────────────┘
                  │                 │
                  ▼                 ▼
                  ● End of Check

handle_full_house:
    // A full house has two patterns in a sorted array: XXYYY or XXXYY
    // First, check that it's not a Yacht (all 5 are the same)
    ldrh w2, [x19]              // dice[0]
    ldrh w3, [x19, #8]          // dice[4]
    cmp w2, w3
    b.eq .full_house_fail       // If first and last are same, it's a Yacht, not Full House.

    // Load all dice for checking patterns
    ldrh w3, [x19, #2]          // dice[1]
    ldrh w4, [x19, #4]          // dice[2]
    ldrh w5, [x19, #6]          // dice[3]
    
    // Check for pattern 1: XXYYY (e.g., 2,2,4,4,4)
    // Condition: dice[0]==dice[1] AND dice[2]==dice[4]
    cmp w2, w3                  // dice[0] == dice[1]?
    b.ne .check_pattern_2       // If not, check the other pattern
    
    ldrh w6, [x19, #8]          // Reload dice[4] into a fresh register
    cmp w4, w6                  // dice[2] == dice[4]?
    b.eq .full_house_success    // If yes, it's a full house.

.check_pattern_2:
    // Check for pattern 2: XXXYY (e.g., 2,2,2,4,4)
    // Condition: dice[0]==dice[2] AND dice[3]==dice[4]
    cmp w2, w4                  // dice[0] == dice[2]?
    b.ne .full_house_fail       // If not, it's not a full house
    
    ldrh w6, [x19, #8]          // Reload dice[4]
    cmp w5, w6                  // dice[3] == dice[4]?
    b.ne .full_house_fail       // If not, it's not a full house

.full_house_success:
    // It's a full house, score is the sum of all dice.
    // We can just call the handle_choice logic.
    b handle_choice

.full_house_fail:
    mov w0, #0
    b exit_score

handle_four_of_a_kind:
    // Two patterns in a sorted array: XXXXY or YXXXX
    // We just need to check if a group of 4 exists.
    // Check dice[0] == dice[3] OR dice[1] == dice[4]
    ldrh w2, [x19]              // dice[0]
    ldrh w3, [x19, #6]          // dice[3]
    cmp w2, w3
    b.eq .four_kind_success_1   // If they match, we have XXXX Y

    ldrh w2, [x19, #2]          // dice[1]
    ldrh w3, [x19, #8]          // dice[4]
    cmp w2, w3
    b.eq .four_kind_success_2   // If they match, we have Y XXXX

    // No four of a kind found
    mov w0, #0
    b exit_score

.four_kind_success_1:
    // Pattern is XXXXY. Score is sum of the four.
    // dice[0] * 4
    mov w3, #4
    mul w0, w2, w3              // score = dice[0] * 4
    b exit_score

.four_kind_success_2:
    // Pattern is YXXXX. Score is sum of the four.
    // dice[1] * 4
    mov w3, #4
    mul w0, w2, w3              // score = dice[1] * 4
    b exit_score

Code Walkthrough: Complex Handlers

• handle_full_house: After sorting, a full house can only appear in two forms: `AABBB` or `AAABB`. The code first checks that it's not a Yacht (where `dice[0] == dice[4]`), which would fail the full house condition. Then, it systematically checks for the two valid patterns. If either pattern (`dice[0]==dice[1]` and `dice[2]==dice[4]`, OR `dice[0]==dice[2]` and `dice[3]==dice[4]`) is found, it branches to success. The score for a full house is the sum of all dice, so we cleverly reuse the `handle_choice` logic by simply branching to it.
• handle_four_of_a_kind: This is similar. A sorted four-of-a-kind can only be `AAAAB` or `ABBBB`. We check if `dice[0] == dice[3]` (the first pattern) or if `dice[1] == dice[4]` (the second pattern). If a match is found, the score is four times the value of the repeated die. The `mul` instruction is used for this multiplication.

Pros and Cons: Assembly vs. High-Level Language

Choosing a language is about picking the right tool for the job. While we've demonstrated a complete solution in Arm64, it's valuable to understand the trade-offs compared to a language like Python.

Frequently Asked Questions (FAQ)

gcc -o test_yacht test_main.c yacht_score.s

Conclusion: From Rules to Registers

We have successfully journeyed from a simple set of dice game rules to a fully functional, logical implementation in Arm64 assembly. This process highlights the core of low-level development: breaking a complex problem into a sequence of fundamental CPU operations. We methodically sorted the data to create order, then used conditional branches to navigate the game's logic, and finally performed simple arithmetic to calculate the result.

Mastering this module from the kodikra Arm64-assembly learning path provides more than just a solution to a puzzle. It equips you with a profound understanding of algorithmic implementation, memory access patterns, and the ARM64 instruction set. These are foundational skills that will serve you well in any field that demands high performance and a deep connection to the hardware.

As you continue your journey, remember that every complex application, from operating systems to high-performance games, is built upon these same fundamental principles. Keep exploring, keep building, and keep translating logic into the language of the machine. To see how this module fits into the bigger picture, check out the complete Arm64-assembly 6 roadmap.

Disclaimer: All code and examples are based on the Arm64 architecture and assume a standard Linux-like environment and calling conventions. The assembly syntax is compatible with GNU Assembler (GAS). Technology and conventions are current as of the time of writing.

Published by Kodikra — Your trusted Arm64-assembly learning resource.