Sample TP1 Proposal

This is a sample TP1 submission for a hypothetical student project, following the sample TP0 proposal. It shows the level of detail expected; your proposal will describe your own project. The course staff expects this project would receive a term project grade of about 80%, assuming all proposals are submitted on time and all interviews receive a score of 1.

Section 1: Summary of progress

• Working: the Main Board plays without animation. Boards start match-free; select, swap, and undo invalid swaps; clear, fall, refill, and cascade; score; R restarts. Board generation and match finding have tests.
• Different from proposed: clicking outside the board deselected the gem. Fixed to keep the selection.
• Bug fixed: runs ending at the last cell of a row or column were missed. A test on G R R R caught it; I now check after each loop ends.
• Open questions answered: L-shapes stay as two runs (60) for MVP. The fall step now returns how far each gem fell, for animation.
• Not finished: nothing.
• Sources and AI help: no external code or assets. Claude implemented the drawing and click handling from my Part A specification; I changed its selection outline from 2 px to the 4 px I specified. Claude implemented both algorithms from my Part B steps and helped me find the end-of-row bug once my test failed.

Section 2: By next week: MVP

Part A: What these features do

1. Overview

By TP2: a complete game. Animated swaps, clears, and falls; 20 moves and a 1,500-point target; a cascade bonus; Title and Results screens; automatic reshuffling.

2. Screens and modes

Title (new): title, a row of six sample gems, and a Play button.

• Play or Enter: new game (score 0, 20 moves).

Main Board (changed): the top bar shows score (left), “Target: 1500” (middle), and moves remaining (right).

• Swaps are now animated.
• R: restart. Escape: back to Title; the game is lost.
• Moves = 0 and cascades done → Results.

Results (new): “You win!” (score ≥ 1,500) or “Out of moves”; final score; longest cascade; Play Again and Title buttons.

• Play Again or Enter: new game. Title or Escape: back to Title.

3. Rules and behavior

• One cascade step = one clear + one fall.
• Main Board input is ignored during animations.
• 20 moves per game; only valid swaps use one.
• At 0 moves, the last cascade finishes and scores, then Results.
• Win: final score ≥ 1,500. Reaching it early doesn’t end the game.
• Points as before (30 / 60 / 100). Cascade steps 2+ score double.
• Points pop up ("+60") over each match and float up 20 px over 0.5 s.
• No valid move (moves remaining) → reshuffle, at no move cost.
• New and reshuffled boards always have no matches and at least one valid move.

4. Edge cases

5. Design decisions

• Move limit (vs. a 60-second timer): reward thinking, not speed.
• Cascade bonus ×2 (vs. ×2, ×3, ×4…): long cascades are mostly luck, so an increasing bonus would make scores too random.
• Animate each cascade step (vs. animating only the final board): watching the chain is the fun part, even though the logic must pause between steps.

6. Out of scope this week

• After MVP: How to Play screen, hints, special gems, saved high score
• Not planned: sound and music

Part B: Core algorithms

Board format is unchanged from TP0.

Algorithm 1: Finding a valid move

1. The problem. Find a swap that would create a match, if one exists. Used to trigger reshuffles (and hints later).

2. Data. In: a board with no matches. Out: ((r1, c1), (r2, c2)), or None.

3. Steps.

1. For each cell, top left to bottom right, and each neighbor to its right and below (if on the board):
   1. Swap them.
   2. If either swapped cell is now in a match (helper below), swap back and return the pair.
   3. Swap back.
2. Return None.

Helper: count same-colored gems directly left and right of the cell, plus 1. If ≥ 3, it’s a match. Repeat for up and down.

Only right/below neighbors, so no pair is checked twice. Only the two swapped cells, since any new match must include one of them.

4. Worked example.

Row 0:  G  B  Y
Row 1:  R  G  G
Row 2:  B  Y  R

• (0,0)–(0,1): row 0 becomes B G Y. Counts: B 1 and 1; G 1 and 2. No match. Swap back.
• (0,0)–(1,0): row 1 becomes G G G. G count 3. Return ((0,0), (1,0)).

5. Edge cases.

• Skip neighbors off the right and bottom edges.
• Skip same-color pairs; they can’t make a match.
• Always swap back, so the board is unchanged.

6. Open questions. None for MVP. For hints: first valid move or a random one?

Algorithm 2: Reshuffling

1. The problem. Rearrange a board with no valid move into one with no matches and at least one valid move.

2. Data. In: the board. Out: the same 64 gems, rearranged.

3. Steps.

1. Put all 64 colors in a list.
2. random.shuffle it and refill the board row by row.
3. If the board has a match or no valid move (Algorithm 1), repeat step 2.
4. After 100 tries, generate a new board instead.

New boards from TP0’s generator are also checked with Algorithm 1 and regenerated if needed.

4. Worked example.

Row 0:  R  O  Y
Row 1:  G  B  P
Row 2:  Y  R  O

• Algorithm 1 returns None: no color appears 3 times, so no swap can make a match.
• No shuffle of these 9 gems can work either, so after 100 tries a new board is generated.
• On an 8×8 board each color appears about 10 times, so a few tries usually succeed.

5. Edge cases.

• Some gem sets can never work (as above). The 100-try limit prevents freezing.
• Color counts must match before and after. I’ll test this.

6. Open questions. How many tries does an 8×8 reshuffle usually take? I’ll measure over 1,000 reshuffles.

Algorithm 3: Playing animations in order

1. The problem. One swap can set off a chain: swap, clear, fall, clear again, fall again. Each animation must finish before the next one starts, and the player can’t act until everything stops.

2. Data.

• app.phase: what the game is doing now: 'idle' (waiting for the player), 'swapping', 'swappingBack', 'clearing', 'falling', or 'shuffling'.
• app.phaseTimer: how many steps the current phase has run. onStep runs 30 times per second.
• fallDistances: how many cells each gem fell, for drawing the fall.

3. Steps. Each phase lasts a fixed number of steps, from the animation table in Part A: swap 6, clear 8, fall 9, shuffle 15. In onStep, add 1 to app.phaseTimer. When the phase’s time is up, reset the timer and choose the next phase:

1. Swapping ends. If the swap made a match, use a move and go to clearing. If not, go to swapping back, which then ends in idle.
2. Clearing ends. Score the matches (doubled if this isn’t the move’s first clear). Remove them, drop the gems, refill the board, and save fallDistances. Go to falling.
3. Falling ends. If the board has new matches, go back to clearing. Otherwise the move is over:
   • 0 moves remaining → Results.
   • No valid move → shuffling, which then ends in idle.
   • Otherwise → idle.

The board changes all at once when clearing ends; falling only animates it. A gem that fell d cells starts d cells above its new cell and slides down: it is drawn d × 70 × (1 − phaseTimer / 9) px above it.

4. Worked example. The player has 20 moves and 0 points. They swap two gems, which makes a run of 3. When those gems clear and the gems above fall, the fallen gems make a second run of 3.

Total: 40 steps (about 1.3 s). Clicks and keys are ignored until the game goes idle.

5. Edge cases.

• Input is ignored unless the phase is 'idle'.
• On the last move, Results waits for the final fall.
• Gems that didn’t fall have d = 0 and stay in place.

6. Open questions. Should longer falls take longer than 0.3 s?

Part C: Hand-drawn sketches

We’ll be adding these shortly, sorry for the delay. We’re drawing as fast as we can.

Main Board Expansion

Screen Flow

Algorithm 3