n

This plan targets a small playable MVP slice before the game grows into a larger roguelike. The slice should prove drag putting, generated course pieces, basic hazards/devices, run health, rewards, and phone-friendly readability.

MVP Definition

The first playable slice should include:

A title/menu entry that starts a short run.
Three roguelike run modes, not separate campaigns:
- Tutorial Run: 3 holes, unlocked by default.
- 9-Hole Run: unlocked by completing Tutorial Run.
- 18-Hole Run: unlocked by completing 9-Hole Run.
A generated normal hole built from editable 3x3 course pieces: start pad on the bottom row, putting green pieces in the middle row, and cup/hole on the top row.
Mini-boss markers inside the run sequence: hole 3 in Tutorial Run and hole 9 in both longer runs. Mini-boss holes will later start with exploration through a fogged large room, then transition into a ball-based minigame such as Breakout or Arcade Pong.
A final boss marker on hole 18 of the 18-Hole Run for a longer scripted boss fight after the exploration dungeon.
Drag-to-aim putting with readable shot preview and consistent physics.
Solid walls, water hazards, cup detection, and at least one angled bank wall.
A small set of placeable course devices, beginning with bumpers and bounce pads before more complex entry-sensitive devices such as windmills or loops.
Health-cost shots, hole completion, Good/Bad wheel resolution, and run win/fail state.
Save-friendly dictionaries for run state, current hole/course, golfer, club, selected run mode, encounter markers, artifacts, and stats.
Smoke coverage for course generation, run progression, and scene boot.

Sprint G1: Course Generation Foundation

Status: complete for the first playable scaffold.

Goal: bridge the editor-authored module JSON into playable course data.

Work:

Add a reusable Putt-Putt course manager that loads palette, module, and course piece JSON.
Compose start, green, and finish pieces into a single save-friendly 3x3 normal course.
Preserve tee/cup locations, module ranges, collision-shape ids, and placeable object metadata.
Preserve piece connection metadata so adjacent pieces can be validated for matching navigable sides.
Add smoke coverage for module loading and generated course integrity.

Exit criteria:

A generated course contains a 3x3 grid, a start piece, at least one green piece, a finish/cup piece, tee and cup cells, angled collision metadata, and matched neighbor connections.
The scene can move from normalized prototype holes toward generated tile courses without changing the save shape later.

Sprint G2: Tile Rendering And Core Collisions

Status: in progress.

Goal: make the generated course visible and physically meaningful.

Work:

Render the generated tile course in the Putt-Putt scene.
Convert tile metadata into collision surfaces.
Add rectangular wall collision, 45-degree bank collision, and 30-degree bank collision.
Keep void tiles visually empty/black so non-course areas can shape rooms.
Add settings for ball friction, shot power, and bounce damping.

Exit criteria:

The player can complete a generated course using tile collisions instead of only normalized rectangle obstacles.
Angled banks visibly and mechanically redirect the ball.

Current progress:

Done: the scene renders generated tile courses from the course manager.
Done: generated course placement sizes the tile grid to the viewport.
Done: tile surfaces apply per-tile friction.
Done: rectangular walls and angle-bank collision now resolve from tile metadata.
Done: normal holes now compose a 3x3 piece grid where each piece expands to a 16x16 tile slot area. The scene exposes camera controls for zooming and centering the camera on the ball so the larger course can remain playable on small screens.
Done: course devices can now be authored on tile cells or generated at freeform positions on valid green tiles. This keeps grid pieces useful for terrain while letting bounce pads, bumpers, and future obstacles be placed more naturally across the putting surface.
Next: tune collision feel through settings and add more test courses that make each wall angle easy to playtest.

Sprint G3: Course Devices

Status: started.

Goal: add the first interactive course objects.

Work:

Add bumpers and bounce pads.
Add windmill timing and blocked/open collision windows.
Add water wheel or fan as the first entry-sensitive redirect object.
Keep device definitions in JSON and device behavior in reusable manager code.

Exit criteria:

At least three object types can be placed in the shared level editor and function in-game.
Device state is save-friendly and deterministic enough for testing.

Current progress:

Done: added a reusable Putt-Putt device manager.
Done: bumper, bounce pad, fan, water wheel, and basic windmill blocker behavior are wired into the generated course scene path.
Done: generated modules include device-placement examples for the level editor and course generator to share.

Sprint G4: Roguelike Run Loop

Status: started.

Goal: make the run structure interesting enough to replay.

Work:

Add golfer/club selection or random starting loadout.
Show hole summary and Good/Bad wheel choices between holes.
Apply artifacts and consequences to health, ball physics, cup size, or reward odds.
Add run stats and achievements for first cup, first run win, low-putt clear, and survival milestones.

Exit criteria:

A 3-5 hole run can be won or lost.
Rewards and consequences materially change later holes.

Current progress:

Done: the between-hole wheel now exposes explicit health, artifact, and bad result controls instead of resolving through one generic Next button.
Done: Big Cup and Rubber Ball artifacts affect cup size and bounce behavior in the active scene.
Done: run start now exposes golfer and club choices instead of always silently starting with the default loadout.
Done: run win/fail uses the reusable results screen controller with New Run and Menu actions.
Done: run stats now record holes completed, runs played, wins/failures, furthest hole, best low-putt win, and best finish health.
Done: Putt-Putt achievements are loaded from game-local JSON and persisted through the shared global achievement profile.
Done: early unlock progression now opens Precision Club after 1 completed hole, Power Club after 3 completed holes, and Lucky Lefty after a run win.
Done: newly unlocked golfers/clubs are surfaced in HUD/result text and in the reusable result panel reward section.
Done: owned artifacts now render in the top HUD as sprite-backed icons with fallback badges, and artifact-specific sprite ids are emitted for the mapper.
Done: artifact icons are clickable and open a small details popup with the artifact description and mechanical effect.
Done: artifact badges now avoid unclear two-letter fallback labels; missing art uses a neutral badge while still exposing the full name and description through the details popup.
Done: hole completion now reports strokes, par, and net health restored before asking the player to resolve the wheel and continue.
Done: Putt-Putt settings now include two shot modes: drag/release and an accessibility confirm-shot mode where release stores the aim and a button performs the putt.
Done: the active scene exposes a reusable stats popup for run totals, records, and unlocked loadout counts.
Done: the active scene exposes a reusable achievements popup filtered to Putt-Putt achievements.
Done: between-hole wheel choices now render in a compact reward panel with a clear title, completed-hole summary, and explicit health/artifact/consequence choices instead of relying on raw bottom buttons.
Done: the run setup/loadout popup now shows compact summary cards for the selected run length, golfer stats, and club modifiers while keeping selection controls fast.
Done: the in-run menu now uses the framework scrollable popup shell, keeping secondary actions scrollable while Resume stays fixed and reachable on small screens.
Next: continue MVP browser/mobile polish against playtest feedback.

Sprint G5: MVP Polish

Goal: harden the slice for browser/mobile playtest.

Work:

Improve readable HUD, pause/results menus, and restart/new-run flow.
Add starter sprites and sprite mappings for ball, cup, tee, surfaces, and common devices.
Add sound effects for putt, bounce, cup, water, reward, and failure.
Profile browser performance and reduce draw/update work where needed.

Current progress:

Done: sprites.json now lists required ball, cup, tee, surface, wall-angle, hazard, pickup, wheel, artifact, and course-device sprite ids for the mapper.
Done: the active course renderer now loads the game sprite pack and draws mapped sprites through the shared sprite render manager, falling back to prototype shapes while art is missing.
Done: the Putt-Putt sprite manifest now includes starter mappings for every current required sprite id, using shared framework art until dedicated golf art is produced.
Done: gameplay calls the shared audio manager for putt, bounce/device, cup, water, reward, and failure events. Missing authored clips safely fall back to generated framework tones.
Done: mini-boss and final-boss holes now create save-friendly encounter state. The active scene blocks normal putting and exposes encounter controls.
Done: added the first reusable fog-room exploration manager. Boss exploration now creates save-friendly room state, revealed cells, current position, target room, and progress. Explore Room reveals/enters rooms until the Minigame/Boss phase unlocks.
Done: added the first reusable ball-minigame adapter manager. Breakout, Arcade Pong, and scripted boss placeholders now create save-friendly adapter state, progress by score/turns, render lightweight previews in the Putt-Putt scene, and complete back into the run flow.
Done: minigame adapters now load their display name, type, preview, target score, and step score from data/games/putt_putt_roguelike/minigames.json. Code fallbacks remain for prototype ids, but boss/minigame tuning should be data-first from here.
Done: the play HUD has been simplified to a Slay-the-Spire-style status strip: health, artifacts, and one Menu button. Stats, achievements, new run, resume, and main-menu actions now live behind the in-run menu.
Done: camera zoom and center controls now appear as compact overlay buttons on the playfield instead of crowding the top navigation bar.
Done: the run setup popup now uses a mobile-safe shell with scrollable setup content and fixed Start/Cancel buttons so it cannot extend past the viewport.
Done: ball drawing and collision radius now scale with course camera zoom, and moving putts use bounded substeps so fast balls are less likely to skip across collisions or feel choppy.
Done: the camera now follows the ball during active putts while keeping tee and cup positions aligned to the generated course.
Done: blocking prototype device pieces are disabled from normal procedural holes for MVP playtesting; device concepts remain in the editor/palette for later tuning.
Done: course objects now render from visual bounds instead of tile anchors, so future tall/cosmetic sprites can overhang their collision tile and still draw correctly as the camera moves.
Done: generated courses now cache static tile draw records once per hole and render the camera window from that cache, instead of reparsing tile strings and metadata in every draw pass.
Done: generated courses now also build merged same-color tile fill runs through levelManager, reducing background draw work while keeping per-tile detail records for sprites, grid overlays, and collision markers.
Done: generated course objects now cache sprite ids, visual rects, centers, categories, and tags once per hole through levelManager.build_object_draw_records, so object culling/rendering does not recompute visual bounds every frame.
Done: the Godot RGF Levels plugin now includes a Putt-Putt Pieces target. Existing course_modules.json pieces can be built as editable 2D bridge scenes, green/empty cells are rendered for visual editing, and exports fold changes back into the matching course piece. The plugin's New action creates a starter 16x16 course piece directly in the course module catalog.
Done: Putt-Putt plugin bridge scenes now use the course catalog's fixed 16x16 piece grid at 32x32 pixels. Smaller prototype source pieces are expanded into that grid on open, and export preserves the full tile grid instead of shrinking to node bounds.
Done: the level intro camera now pauses briefly on the full-course overview and then zooms/centers more slowly so players can read the generated map before putting.
Next: assign starter art for the required sprite ids and tune tile/device readability in a browser build.
Next: replace the lightweight minigame adapter previews with richer reusable Breakout/Pong/Boss playfields.
Next: tune mobile HUD/results layout after browser playtest.

Exit criteria:

The MVP slice is playable on desktop browser and a phone-sized viewport.
Build profile validation and headless smoke stay green.

Deferred Until After MVP

Complex multi-loop geometry.
Full procedural difficulty director.
Large artifact pools.
Boss holes or themed course biomes.
Multiplayer or asynchronous score attack.