Sample TP2 Proposal

This is a sample TP2 submission for a hypothetical student project, following the sample TP0 and TP1 proposals. 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: MVP, about 1,050 lines. Animated swaps, clears, and falls; 20 moves, 1,500 target, ×2 cascade bonus; Title and Results screens; reshuffling.
• Different from proposed: popups from simultaneous matches overlapped. Each now sits at the center of its own run.
• Bug fixed: R during a fall left half-fallen gems on the new board. I’d blocked clicks during animations but not keys; onKeyPress now checks app.phase too.
• Open questions answered: reshuffles averaged under 2 tries (max 6) over 1,000 tests, so the 100-try limit stays as a safety net. All falls stay at 0.3 s; long falls looked fine.
• Not finished: nothing.
• Sources and AI help: random.shuffle from the Python standard library. Claude implemented the animation phases from my Algorithm 3 table; its first version moved falling gems at a fixed speed, so I had it use my fall formula instead. Claude explained how to measure reshuffle tries; I wrote that test myself.

Section 2: By next week: Advanced features

Part A: What these features do

1. Overview

By TP3: special gems that chain, hints, a How to Play screen, and a saved high score. Special gems reward planning; hints help stuck players; the high score encourages replay.

2. Screens and modes

Title (changed): adds a How to Play button below Play, and “High score: 2340” (or “none yet”) at the bottom.

• How to Play: go to How to Play.

How to Play (new): five short rule lines (swapping, scoring, move limit, special gems, H key), drawings of each special gem, and a Back button.

• Back or Escape: back to Title.

Main Board (changed):

• Line gems have a white stripe (horizontal or vertical, matching what they clear). Bomb gems have a thick black ring.
• “Hints: 3” below the board.
• H: show a hint.

Results (changed): high score under the final score; “New high score!” in gold when beaten.

3. Rules and behavior

Special gems

• A straight match of 4+ makes a line gem at the swapped cell: horizontal match → clears its row; vertical → clears its column.
• An L or T (horizontal and vertical runs of one color sharing a cell) makes a bomb gem at the shared cell. It clears the 3×3 square around it.
• The special gem keeps the match’s color and stays; the rest of the match clears.
• Only the player’s swap creates special gems, not cascades.
• A special gem activates when cleared. Special gems it clears activate too (chains).
• Special gems fall and move like ordinary gems.

Scoring changes

• L or T match: 100 (answers my TP0 open question).
• Each extra gem cleared by a special gem: 10. Cascade ×2 still applies.

Hints

• H outlines a random valid swap in pulsing yellow for 2 s.
• 3 per game. No effect when none are left or one is showing. Free.
• Making a move removes the hint.

High score

• Saved in highscore.txt (one number) next to the game. Updated when a game beats it.

4. Edge cases

5. Design decisions

• Special gems only from swaps (vs. from any match): they should reward planning. Cascade-made gems would be luck, and would fill the board.
• Random hint (vs. the first valid move found): the first move is always near the top left, which feels predictable.
• Two special gem types (vs. adding a color bomb for 5-matches): chains are already the hardest part. Do two well; add a third only if time allows.

6. Out of scope this week

• If time allows: color bombs for 5-matches
• Not planned: drag-to-swap, multiple levels, sound

Part B: Core algorithms

Special gems live in specials, a 2D list the same size as the board: None, 'rowLine', 'colLine', or 'bomb'. It must move with the board whenever gems fall, refill, or shuffle.

Algorithm 1: Creating special gems

1. The problem. After the player’s swap, decide which matches make special gems, and where.

2. Data. In: the board, the two swapped cells, and the runs found. Each run now records its direction ('h' or 'v') and its cells. Out: updated specials, toClear, points.

3. Steps. (First cascade step only.)

1. Mark all runs unused.
2. For each horizontal and vertical run of one color sharing a cell X: bomb at X; mark both used; +100.
3. For each unused run of 4+: line gem at the swapped cell in the run ('rowLine' if horizontal, 'colLine' if vertical); mark used; score normally.
4. Score remaining runs normally.
5. toClear = all run cells, minus the new special gem cells.

4. Worked examples.

Run of 4: R swapped from (2,2) to (3,2); row 3 has R at columns 1–4.

• No vertical runs, so no bomb.
• Swapped cell in the run: (3,2) → 'rowLine'. +60.
• toClear = {(3,1), (3,3), (3,4)}.

L-shape: G runs (5,2), (5,3), (5,4) and (3,4), (4,4), (5,4).

• Shared cell (5,4) → 'bomb'. +100.
• toClear = {(5,2), (5,3), (3,4), (4,4)}.

5. Edge cases.

• A run of 4 that’s part of an L gets only a bomb (step 2 marks it used first).
• Both swapped gems in separate runs of 4: two line gems.
• New special gems aren’t in toClear, so they don’t activate immediately.

6. Open questions. If the swapped cell already holds a special gem in the new match, does the old one activate or get replaced?

Algorithm 2: Activating special gems in chains

1. The problem. Expand toClear with each cleared special gem’s area, activating any special gems caught in it, until none are left.

2. Data. In: toClear, specials. Out: expanded toClear, count of extra gems. queue: list of special gems waiting. activated: set of those done.

3. Steps.

1. queue = special gems in toClear. activated = empty. extra = 0.
2. While queue isn’t empty:
   1. Take the first cell. Skip it if in activated; otherwise add it.
   2. Area: its row ('rowLine'), column ('colLine'), or on-board 3×3 ('bomb').
   3. For each area cell not in toClear: add it, extra += 1, and queue it if it holds an unactivated special gem.
3. Score 10 per extra gem (×2 in cascade steps 2+).

4. Worked example. A vertical match clears (1,5), (2,5), (3,5). (2,5) is a 'rowLine'; (2,1) is a 'bomb'.

• queue = [(2,5)].
• (2,5): row 2 adds 7 new cells. extra = 7. Bomb at (2,1) → queue = [(2,1)].
• (2,1): rows 1–3, columns 0–2. Row 2 is already in; rows 1 and 3 add 6. extra = 13.
• Queue empty. Points: 30 + 130 = 160.

5. Edge cases.

• Two line gems crossing each other: activated stops an infinite loop.
• Bombs at edges: only on-board cells.
• A special gem already in toClear still activates, since step 1 queues it.

6. Open questions. Animate a chain all at once, or one gem at a time (needs a new phase)?

Algorithm 3: Choosing a hint

1. The problem. Pick a random valid swap to highlight.

2. Data. In: the board. Out: app.hintPair; app.hintTimer counts down 60 steps (2 s).

3. Steps.

1. Change TP1’s valid-move search to return a list of all valid swaps.
2. If empty, do nothing (shouldn’t happen, thanks to reshuffling).
3. app.hintPair = random.choice(list), app.hintTimer = 60, app.hintsLeft -= 1.
4. Each step, decrease the timer; at 0, clear app.hintPair.
5. Draw a yellow outline on both cells, alternating 6 px and 3 px every 10 steps.

4. Worked example (TP1’s 3×3 board).

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

• Of 12 neighbor pairs, only (0,0)–(1,0) works (row 1 → G G G). List: [((0,0), (1,0))].
• random.choice returns it. Hints left: 3 → 2.
• Outlined for 60 steps, then cleared.

5. Edge cases.

• H does nothing with 0 hints, a hint showing, or an animation playing.
• A move clears app.hintPair, so no stale hints.

6. Open questions. Should hints prefer swaps that make special gems?

Part C: Hand-drawn sketches

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

• Sketch 1 — Main Board: close-ups of horizontal and vertical line gems and a bomb gem, plus a yellow-outlined hint pair and “Hints: 3.”
• Sketch 2 — Algorithm 2: an 8×8 grid of the chain example, with row 2 and the bomb’s 3×3 shaded differently and queue written at each step.