ferravex
GitHub

Copper Greens

Twelve miniature-golf holes in two playable variants: Copper Greens 2D and Copper Greens 3D. Both use the same course, ball simulation and scorecard. The 3D version renders real extruded course geometry with an isometric camera; the rules use a planar rolling-ball model with a shared raised-green heightfield.

Play

cargo run --release -p mini-golf-2d
cargo run --release -p mini-golf-3d

Drag from the ball toward the target and release to putt. Distance controls power; a tap changes aim without shooting. You can instead use the on-screen angle and power buttons followed by PUTT. Keyboard defaults are arrows or WASD to aim and change power, Space to putt, P/Escape to pause, C for the scorecard, and R to return to the previous safe lie for one penalty stroke. Game menu → Controls (or F2) shows saved bindings and supports keyboard/controller remapping. In fullscreen, Shift+Tab reaches the game menu.

The HUD speaks in marks rather than words: a flag is par, the ball is strokes, pips are holes, a trophy is a personal best. The score chip shows the hole name over twelve hole pips (played holes in their result color, the current hole glowing), a flag with par, a ball with your strokes (copper once over par) and a tinted round-to-par badge that bumps when it changes; tap it for the full card. Each hole opens with a title card (its number on a copper tee sign, its name, and chips for par, water with its +1, sand, the raised green, moving copper and your best there) that fades as soon as you putt. The aim line grows and warms from mint to copper with power and ends in a target ring; the putter pulls back further for harder shots. A bolt-marked power meter, ticked at this hole's previous putt, and five shot controls sit below the course. Until your third putt, wide screens show the keys as caps beside their marks and narrow screens show a hand dragging from the ball to the target. Fullscreen fills the viewport with the app, without the website toolbar or a navigation rail. The course projection and pointer mapping use the same reserved scene region.

Feel and personality

Every celebration comes from an accepted rules event:

Between holes, a sheet slides up while the course re-fits above it, so the cup drop stays visible. It shows the score name and quip, strokes and par, tag pills (bank or trick shot, the copper assist, a flame streak, a trophy for a hole best), a twelve-cell strip in scorecard notation (circles under par, squares over, a gold medal for an ace) and NEXT HOLE. The scorecard uses the same notation. The round ends on a results card with a rank title (from "Duck Pond Patron" to "Copper Deity"), your total beside its to-par badge, a personal-best comparison, the next title and the strokes it needs, and round stats as mark-and-number tiles.

Reduced motion (shared player preference) removes particles, rings, the rolling trail, shake, squash/stretch, the flag wave and every bounce or slide; text callouts stay readable. Reduced flash removes the ace flash. Effects live in course coordinates, so both views draw the same moments.

Twelve greens

HoleNameParRead the course
1First Light2Learn aim, distance and power on an open green.
2The Bank3Pass around the lower end of a stone wall.
3Sand & Stone3Bunkers slow a ball much faster than grass.
4Canal Crossing3Cross between two pools on a narrow bridge.
5Split Decision3Choose a route around a central stone island.
6The Windmill3Time a rotating barrier or go around it.
7Switchback4Follow alternating openings with controlled shots.
8High Road3Carry a raised green with slope acceleration.
9Clockwork4Read the moving copper gates.
10Island Links4Follow the dry ribbon between water hazards.
11Garden Spiral4Enter the walled inner green through its opening.
12Copper Cup4Combine bridge placement, sand and a moving gate.

Water adds one penalty and returns to the last safe lie. The cup captures a ball only within its radius and below its speed limit. The card and pause menu offer Take 12, conceding the hole at its stroke limit. At twelve strokes, a hole is automatically picked up and marked on the card. Completing all twelve holes records the full-round best locally when storage is available. Each holed (not picked-up) hole also records a per-hole best, shown on its title card; the demonstration never records anything. Practice can start at any hole and never replaces that record. Restart clears the current card and retains the saved best. Opening Controls/Details or losing focus suspends this local game; the paused ball and obstacles retain their state.

Shared rules

mini-golf contains course, game, card, quips, juice and presentation modules. The two front ends each own an ordinary GameSession loop: sample input once per display frame, advance fixed time, consume gameplay edges on executed ticks, draw the selected view. No wall clock or renderer enters the rules module. Moving obstacles use simulation time and freeze with the ball. Four collision substeps per 120 Hz tick bound travel at the maximum admitted speed and prevent thin-wall tunneling.

Rules ticks report observational events (rail/wall impact strength, copper contact, lip-out, sand entry) and per-stroke bank/assist counters; they never change the ball. card turns finished holes into score names, streaks, round stats, rank titles and personal-best lines; quips picks copy as a pure function of counters. While the ball rolls, effects age with accepted ticks; after a hole ends (rules frozen) the celebration ages with clamped render time.

use mini_golf::game::{Round, Phase};
use ferravex_math::Vec2;
let mut round = Round::new();
assert!(round.shoot(Vec2::X, 0.56));
assert!(!round.shoot(Vec2::X, 0.8)); // Already rolling; no second stroke.
for _ in 0..2000 {
    round.tick();
    if round.phase != Phase::Rolling { break; }
}
assert!(matches!(round.phase, Phase::Aiming | Phase::Holed));

The optional ?autoplay=1 browser demonstration (native --autoplay) predicts bounded candidate putts toward authored route points and then executes a legal shot through the real rules. It does not teleport the ball or assign scores. The read-only golf_status_v1 / golf_status_v1_len exports expose versioned UTF-8 JSON for diagnostics: hole, phase, strokes, total, power, position and card. Read the pointer and length together, then copy before advancing another frame. There are no exported game-state mutation or test-win functions.

Native debug builds read optional screenshot hooks (GOLF_WINDOW=390x700, GOLF_HOLE=9, GOLF_SHOT=DEG,POWER, GOLF_SKIP_WELCOME, GOLF_PAUSE_AT, GOLF_CARD_AT, GOLF_PRACTICE_AT, GOLF_TURBO, GOLF_FOCUS, GOLF_FAKE_BEST, GOLF_PLAYER_CARD); see src/capture.rs. Release and Wasm builds ignore them.

Verify

cargo test -p mini-golf -p mini-golf-2d -p mini-golf-3d --offline --locked -j 2
cargo clippy -p mini-golf -p mini-golf-2d -p mini-golf-3d --all-targets --offline --locked -j 2 -- -D warnings

The legal-putt regression finishes every authored hole through the same collision, surface and capture logic as a human. Further tests cover lip-outs, bank counting, the copper assist, sand entry, score names, streaks, ranks, quip rotation, reduced-motion clearing and the browser demonstration frame budget. Projection tests round-trip 2D/3D pointer coordinates inside the HUD reservations. Browser playtests remain distinct from those rules tests; physical touch, audio listening and platform coverage should only be claimed when actually exercised.