HardYards/DESIGN.md

SHADES — design brainstorm

You run a small landscaping outfit. Every callout is a different site, a different client, and a different fight with geometry, water, and weather. Shade sails, retaining walls, drainage — build it right, because the season will test it.

---

The core insight

Real landscape engineering is already a game system. Almost nothing has to be invented — it just has to be surfaced:

• A sail's strength comes from its geometry, not its material. Tension, twist, anchor angles.
• Every corner is a chain of components (ring → shackle → turnbuckle → pad eye → anchor), and the chain fails at its weakest link.
• Water always wins eventually. Retaining walls aren't pushed over by soil — they're pushed over by the water trapped behind them. Drainage is the invisible half of every job.
• The two things a sail must do — cast shade and survive wind — are in direct opposition. Big, flat, low = great shade, death in a storm. Small, twisted, steep = storm-proof, patchy shade.

You're never building the right thing; you're building the least wrong thing for the weather that's coming — on this site, in this season, on this client's budget.

---

The frame: a landscaper service

You're a one-person (later small-crew) landscaping business. Work arrives as callouts — each one a hand-designed or generated site with existing conditions, a client brief, a budget, and a forecast window. This is the level-select structure, and it generates variety for free:

Job types:

• Shade install (summer bread-and-butter) — pure geometry puzzle: sun path, anchor options, client constraints ("nothing attached to the house", "must clear the pool fence").
• Storm-proofing — a storm is 36 hours out; harden an existing site. Often someone else's bad work: the cowboy-job level type, where half the puzzle is finding what's about to fail.
• Drainage fix — client's yard flooded last month. Read the terrain, find where the water wants to go, build it a path: grading, swales, French drains, ag pipe, catch basins.
• Retaining wall — build or rebuild. Boulder, sleeper, or block; and every wall job is secretly also a drainage job.
• Emergency callout — mid-storm, right now, double rates. The chaos levels. Someone's sail is flogging itself to death over their glasshouse.
• Warranty callout — your own past work failed. Unpaid. See Reputation, below.

Reputation & warranty — the consequence loop. Your finished work persists and gets weather-tested after you leave. Skimp on a shackle or skip the weep holes to pad your margin, and next storm you're driving back to do a free repair in the rain while your rating drops. Quality vs profit is the economy's real tension — not "can you afford good hardware" but "can you afford to find out you needed it."

Economy: earnings buy gear tiers (hardware, fabrics, drainage pipe, wall block), tools (a petrol auger vs a hand shovel is a life-changing upgrade when digging is time-boxed; laser level; power winch), truck/trailer upgrades (carry more per site trip — feeds the limited-hands mechanic), forecast subscriptions (radar!), and eventually an apprentice — a second pair of hands (AI helper, or the co-op slot).

---

Threat spectrum — not every level is a violent storm

Weather is a spectrum from slow pressure to acute chaos, and the game's rhythm comes from mixing them:

Threat	Tempo	What it tests
Heatwave / extreme UV	slow burn, days	shade coverage over time — the sun moves, your shadow map must track it
Steady rain	slow, cumulative	drainage capacity, ponding, saturated-ground anchor strength
Wind event	acute, hours	rigging quality, tension choices, weakest links
Thunderstorm	acute + chaotic	everything at once: gusts, dump rain, debris
Hail	sharp burst	coverage gaps + fabric choice
Frost / cold snap	slow	footings (frost heave), plant protection, brittle old fittings

Heatwaves are real levels, not downtime. UV index climbs, unshaded plants scorch by the hour, café customers won't sit in sun, and the shadow puzzle is dynamic because the sun arcs across the sky — a sail that covers the seedlings at 10am covers the fence at 3pm. Heat also affects you: work slows in the midday blaze, you need water breaks, and the smart landscaper works dawn and dusk. Slow-pressure levels are where the geometry brain gets to shine — and they make the storm levels land harder by contrast.

---

Core loop (per callout)

1. The brief — client wants X, budget Y, forecast Z. Site inspection: walk it, probe soil, check trees, find the existing sins (crumbling wall, buried downspout that drains toward the house).
2. Plan & build (timed) — the tower-defense build phase. Everything costs your time and your legs: trips to the trailer, digging, cure times, ladder work. Choose what to do well and what to gamble on.
3. Weather test — sometimes you're on-site when it hits (storm defense: repairs, releases, chaos), sometimes it happens after you leave and you get the phone call.
4. Aftermath — payment, reputation delta, warranty exposure, shop, next callout.

---

Geometry mechanics (the planning game)

Triangles vs quads — a real distinction, for free

• A triangle through 3 points is always a flat plane. Cheap, easy, can't be twisted — so it ponds water unless pitched steeply, and presents a flat face to wind.
• A quad with 4 anchors can be twisted into a hypar (raise two opposite corners, drop the other two). Hypars shed wind and water dramatically better. The 4th anchor point means something.

Anchor angle = force multiplication

Force on each anchor depends on the angle the sail's edges make at the corner. Pull two edges nearly parallel and the corner load multiplies. Show it with live force arrows during planning — the player learns vector decomposition without ever hearing the words.

Tension is a dial, not a checkbox

• Drum tight: no flapping, but gusts transmit as shock loads straight into the anchors. Rigid systems break suddenly.
• Loose: soaks up gusts, but flogs — continuous fatigue damage, and flapping slowly unscrews unmoused shackle pins (real).
• Right answer depends on the forecast. There is no globally correct setting.

Height, pitch, and runoff

• Low sails = better shade angle, more wind load.
• One corner low = you choose where the rain goes. Sail runoff is an input to the site's drainage plan — dump onto the gravel swale you built, not the client's veggie bed. Sails and drainage are one system.

Layering and wind shadow

Sails shield each other. A cheap sacrificial windbreak sail on the windward edge drops the load on everything behind it — defense in depth, literal tower-defense lanes for wind.

---

The water layer: terrain, drainage, and earthworks

Rain doesn't disappear when it misses your sails — it lands on a heightmap and flows downhill. This is the second big system, and it's what makes the landscaper frame more than a reskin.

Surface flow

Coarse-grid flow sim over the terrain: water runs, gathers in low spots, pools, and erodes. Pooling drowns plants, floods the paved area the client paid for, undermines footings, and turns soil to the weak saturated state that lets posts pull out mid-storm. During heavy rain you can see the water finding every mistake in your grading.

Your drainage toolkit

• Grading / re-sloping — the shovel-and-time solution; move the problem, don't fight it
• Swales — shallow gravel channels; cheap, capacity-limited, visible
• French drains / ag pipe — buried perforated pipe in gravel; expensive, digging time, but invisible and high-capacity. Where does the pipe discharge? Daylight it downslope, or you've just moved the flood
• Catch basins & grates — point capture for hard surfaces and sail runoff
• Rain garden / soakage pit — capacity buffer; overflows in the big one if undersized

Maintenance mechanic: drains clog. Autumn leaves are the classic — a perfect French drain full of leaf litter is a decorative trench. Return-visit upkeep jobs, and a reason grated inlets and cleanouts are premium parts.

Retaining walls — geometry meets hydrostatics

Boulder and block walls are the earthwork sibling of shade sails: pure applied geometry with legible failure.

• Boulder walls: biggest stones on the bottom, batter (lean the wall back into the slope), interlock. Stacking is a physical placement puzzle — your chaos engine already knows how to make a bad wall fall over.
• Timber sleeper walls: cheap, fast, and they rot — a wall you built in year one is a warranty callout in year three.
• Block/masonry: strong, expensive, unforgiving of bad footings.
• The killer is water, not soil. Rain saturates the backfill, hydrostatic pressure builds, and the wall bulges → weeps mud → blows out. Telegraphed by cracks and creaks, survivable if you run out and relieve it. Prevention is drainage: gravel backfill, ag pipe behind the base, weep holes. A wall without weep holes is a dam that doesn't know it yet.
• Surcharge: weight above the wall (parked trailer, boulder pile, the shed the client wants "right at the edge") multiplies the load. Another live-force-arrow teaching moment.
• Wall failure mid-storm = boulders and a mudslide entering the debris system. The chaos layers compound: wall fails → mud flow undermines a sail post → sail goes → sail wraps the neighbor's fence.

---

Anchors (the tower slots)

Trees — free, tall, already there. But they move: sway adds dynamic load spikes, branch strength is uncertain (inspection = intel), and big storms shed limbs that become debris. Rigid-strapping to a big tree snaps turnbuckles like wishbones; the counter is a spring/shock absorber component. Tree roots also invade drainage pipes over seasons — the systems touch.

Buildings — rigid and reliable, but only at real structural points. The fascia board is a lie: holds until the first real gust, then rips off taking the gutter with it (collateral cost + new flying debris you created). Strong points are scarce and fixed.

Posts you place — full freedom, full cost. Footing quality (dirt < gravel < concrete), concrete cure time (a post poured 2 hours before landfall is coming out of the ground), digging time, and correct practice is to rake the post away from the load. Saturated soil weakens footings mid-storm — a post in wet ground pulls out slowly, with creaking: an audible warning you can run toward. Good site drainage literally makes your anchors stronger.

Plus guy lines and screw-in ground anchors as the cheap patch layer.

---

Hardware — the weakest link game

Every corner is a chain: sail ring → shackle → turnbuckle → chain/wire → pad eye → anchor. Each component has a working load limit and a failure mode:

Component	Cheap version fails by	Notes
Shackle	pin unscrews (if not moused), then shears	flogging accelerates unscrewing
Turnbuckle	thread strips, or bends then snaps	also your tension adjuster — dual use
Wire rope	frays first (visible warning), then parts	inspect for fray = free intel
Chain	honest — holds to rating, breaks clean	heavy to carry
Carabiner	fast to clip, weak, gate flutters open	the "I ran out of time" option
Sail ring / stitching	corner rips out of fabric	worst outcome — ruins the sail

Design rule: the failure chain must be legible. One corner lets go → sail flogs → load on remaining corners roughly triples → cascade → the loose sail is a 30 m² kite hunting the rest of your work. Every disaster should replay in the player's head as "…the shackle. I knew about the shackle."

Budget tension: good hardware everywhere is unaffordable. You will field one dodgy corner — the game is choosing which one, and where the blast radius is smallest.

---

Storm phase (the chaos engine)

Wind

Base vector + gust spectrum. Gust fronts are readable — a wave of motion crosses the grass and trees a beat before it hits your sails. Lulls are repair windows. Direction can veer mid-storm ("southerly change at 2am") — the rig that was perfect for a westerly is now loaded backwards.

Rain → ponding and flow

Flat sails collect water; water is heavy; the belly collects more (positive feedback) until sudden dump, tear, or corner failure. Counter: run out and poke the pond with a broom — the funniest correct mechanic in the game. Meanwhile every drop that lands is running through your drainage plan, and heavy rain finds what you skimped on.

Hail

Punishes coverage gaps directly, loads sails, punctures cheap fabric. Fabric choice is a forecast bet:

• Shade cloth (porous): wind blows partly through — much lower load. Useless against rain.
• Waterproof membrane: stops rain and hail, takes full wind load, ponds if flat.

Debris

Branches, wheelie bins, the neighbor's trampoline (arrives in act two of any big storm), mud and boulders from a failed wall, and worst of all: anything of yours that failed earlier. Pre-emptable in prep — strap the bins, ask about the trampoline. Reward players who defend against the map, not just the weather.

You, the small person

Weather affects you: gusts shove you, rain slows you, heat exhausts you, ladder work at height in wind is genuinely tense, and standing under a failing sail is a bad place to stand.

Tools (limited hands — choose a loadout): wrench (tension/hardware), broom (ponding), patch kit (stop tears before they run), shovel (emergency drainage relief — cut a channel, relieve a wall), knife (cut a sail loose — lose the sail, save the anchors), quick-release corner (installed in prep: deliberately depower a sail mid-storm). The signature decision under load: release, cut, or ride it out.

---

Site features & side-systems — the yard is a puzzle box

Every callout site is assembled from features that each carry a mechanic. The more of these on one site, the more the systems collide:

Lawn mowing — filler income between big jobs, and a reveal mechanic: long grass hides sprinkler heads, buried pipe, stakes, and rocks. Mow blind and you eat blade damage — or worse, the mower throws a stone, and if there's a glasshouse in range you just bought new panels. Mowed ground also shows the terrain's true fall lines (drainage intel), and stripes are their own reward.

Leaf blowing — the autumn side-game, and secretly a wind-geometry tutorial: blowing against the breeze is comedy, working with it is technique. Leaves clog drain inlets, gutters, and pools; piles you don't bag in time get re-scattered by the next gust. Clearing the inlets before the rain arrives is a real defense action, not chores.

Tree pruning — the order puzzle. Branches have weight, lean, and a fall arc you can read. Every cut re-balances the limb and the tree, so sequence matters: right order drops limbs into the clear zone (or exactly where you wanted a log); wrong order puts one through the glasshouse, the fence, or your own sail. Rope-assisted directional felling for the big stuff. Strategic layer: pruning reduces the tree's wind load and storm-debris risk, but a removed branch is an anchor point lost forever — and sometimes the right cut unlocks something: a new anchor line, morning sun onto a shaded bed, clearance for the sail you couldn't fit before.

Glasshouses — the maximum-fragility asset. Hail apocalypse, mower ejecta, branch drops, debris. Jobs: hail nets and mesh sails rigged over glass, where your own failure is the worst debris of all. Highest pay on the board, highest collateral. Achievement: Don't Throw Stones.

Wet concrete — pours are timed commitments. Fresh slab must be kept clear of rain, hail, leaves, the client's dog, and your own feet until cured — rig a sail over the pour, plan your walking routes, and check the forecast before you commit, because a ruined slab is a jackhammer day. Pour-deadline vs incoming-weather is a beautiful pressure decision.

Trampolines — secure the client's (tie-down kit, sandbags) or it will be the storm's opening projectile. Fun-over-realism option: a bounce route to a high anchor you can't reach by ladder.

Swimming pools — a constraint bundle: pool-fence compliance restricts where posts can legally go, chlorinated air corrodes cheap hardware faster, drainage must never discharge into the pool, leaves in the water make the client cold-call you, and falling in mid-storm dumps your carried tools.

Granny flat — a second roofline changes everything: more building anchor edges, shade-walkway jobs between the buildings, and the alley between house and flat funnels wind (venturi acceleration — locally faster wind in the gap, real and mechanically juicy). Plus an occupant NPC: granny brings lemonade during heatwaves.

---

Four seasons — the campaign clock

The year is the campaign structure. Each season biases the callout mix AND changes the physics:

Summer — heatwaves and UV jobs; shade is the product. Sun is high (short shadows — different coverage geometry). Soil is baked hard: digging is slow, but anchors hold well. Afternoon thunderstorms: short, violent, hail-prone. Peak earning season.

Autumn — the maintenance season. Leaves clog drains (upkeep callouts), steady soaking rains test every drainage job you did in summer, first big blows arrive. The season your warranty exposure comes due.

Winter — low sun means long shadows and a flipped brief: clients now want sun let through — removable/seasonal sails, and the deciduous-tree trick (nature's seasonal shade sail: leaves in summer, bare in winter — passive solar design as a mechanic). Frost heave attacks shallow footings, saturated ground is at its weakest, old fittings go brittle. Fewer jobs, harder conditions, plan-heavy.

Spring — everything grows: trees thicken (stronger anchors, more wind area), roots invade pipes, grass hides yesterday's problems. Wind season, hail season, mud season. New-build jobs surge.

The seasonal sun angle is the quiet unifier: a sail installed for the summer sun is wrong by winter, so seasonal-adjustment callouts are a natural job type, and players internalize real passive-solar thinking without a tutorial.

---

Score & economy

Earn per callout: brief fulfilled (shade-hours delivered, dry floor area, wall holds), speed bonus, weathered-the-event bonus, emergency rates. Lose: destroyed hardware, torn sails, collateral (your flying sail through their window, ripped guttering, flooded neighbor), warranty callouts (unpaid work), reputation. Spend: hardware tiers, fabrics, drainage stock, wall materials, power tools, truck/trailer capacity, forecast upgrades, the apprentice.

---

Modes

Campaign: four seasons, escalating regions — suburbs → hills (retaining wall country) → coast (salt corrosion, sea wind) → cyclone-region town. Storm season (roguelite): fixed budget, procedural callout + forecast sequence, survive the year solvent. Sandbox: unlimited budget, storm designer sliders, break things for fun — the chaos physics carries this mode by itself. Maybe: async multiplayer — weather a storm on a site another player built; their corner-cutting is your emergency callout.

---

Feel & tone

• Cozy-with-teeth. Heatwave days are gentle and puzzly; storms are loud, dark, genuinely stressful. The contrast is the hook — Overcooked pacing swings, Besiege structural failure.
• Failure is spectacular and funny, never bugged-feeling. A cascading sail failure is a firework you paid for.
• Sound does heavy lifting: rope creak, fabric flog, the tink…tink… of a shackle pin backing out, water starting to trickle behind a wall, the ripping note of a tear starting to run. Players learn to defend by ear.
• Real units (kN on load meters, real WLL ratings, actual fall ratios on drains) — the Kerbal trick. People should leave this game able to rig a real sail and drain a real yard.

---

Prototype scope (find the fun fast)

The landscaper service is the campaign wrapper — the prototype is still one yard and one storm:

1. Top-down or ¾ 2.5D single yard. One building edge, two trees, placeable posts.
2. Sail = spring-mass grid (even 4×4 nodes) with wind vector + gust noise per node. Tension = spring stiffness. This alone gives flapping, bellying, believable corner loads.
3. Corner loads vs component ratings → weakest-link failure → freed sail keeps simulating (chaos for free).
4. One protected thing, one storm with a gust track, one walking character with a wrench.
5. The test: does watching a load meter climb on a corner you know is under-shackled, while you sprint across the yard in the rain, feel great?

Then the second prototype spike is water: heightmap + coarse flow sim + one swale tool + one wall that can blow out. If both spikes are fun, the callout structure just multiplexes them.

Engine thought: Godot fits (cheap iteration, exports everywhere); spring-mass sails and grid flow are simple enough to hand-roll anywhere — even a web prototype proves the loop.

---

Open questions

• Camera: plan in top-down, weather the storm in ¾? (Current lean: yes.)
• Player damage: knockdown + lost time, never death — keep the stakes on the work.
• How simulated is water? Coarse grid flow is probably enough; full shallow-water sim is a trap.
• Night storms: lightning-flash-only visibility as a late-game modifier; lightning makes tall posts scary.
• Client personalities as soft constraints ("I don't care what it costs" vs "cheapest option, and I'll sue") — cheap flavor, real puzzle variation.