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.