# fx
Everything between the rules firing and the player feeling it, on the module
side. `DuelFx` is the component that uses it; `PisteCamera` uses the curves.
```luau
local Fx = require("fx")
```
## The event source
```luau
local source = Fx.source()
for _, ev in ipairs(source:poll(match, playerFencer, rivalFencer, dt)) do ... end
```
`poll` drains `DuelMatch.fxQueue` — every event of a frame, in the order the
umpire wrote it. The umpire empties that queue at the top of its own update and
fills it as the frame resolves, so any reader that runs after it sees the whole
frame. `source.path` reads `queue` once that read is live.
Beside the queue, the same vocabulary is derived from the umpire's frozen
public fields. That derivation is not a fallback that will be retired: **the
two measure faults never reach the bus at all.** `strikeFrom` writes an
exchange record for a `SHORT` or a `CROWDED` and returns without emitting, so
`short:*` and `crowded:*` exist only if someone derives them. Everything else
the derivation produces comes from a state edge in the same frame as the queued
event, so the two collapse together and nothing double-fires.
`crowded:player` / `crowded:rival` are in `Fx.DERIVED` rather than `Fx.EVENTS`:
they are read off a frozen public field, and the umpire's own vocabulary is
unchanged.
### Losslessness, in the umpire's own units
`fxSeq` counts every `emit()` the umpire has ever made. The source keeps:
- `produced` — how far `fxSeq` has advanced since the first poll
- `taken` — how many events it has drained off `fxQueue`
- `missed` — the difference, which is exactly the events that never arrived
`recordsMissed` is a separate count: exchange **records** overwritten inside
one frame. Those exchanges' events still arrive on the queue; only the detail
behind them is gone, so the reaction falls back to its default weight.
### The strike read
`source.strike` holds the last parsed verdict —
`{ who, action, riposte, verdict, defence, phase }` — from a record like
`player thrust RIPOSTE vs rival parry/active -> touch`. That is how the
reaction layer knows a lunge landed rather than a thrust.
`source.fault` holds the last `{ who, action, kind, gap, reach }`.
## The tell watcher
```luau
local tells = Fx.tells()
for _, tell in ipairs(tells:poll(pf, rf)) do ... end -- "player:lunge"
```
A commitment is fencer state, not a match event: it is the read the whole game
is about and it lasts a fifth of a second.
## Curves
`Fx.approach(v, target, rate, dt)`, `Fx.outCubic(t)`, `Fx.snap(t)` — shared by
`DuelFx` and `PisteCamera` so a recoil and a camera kick fall off on the same
shape.
## The synthesiser
Every sound in the assize is a sine, a noise burst, a formant resonance and an
envelope. Nothing is imported.
| primitive | for |
|---|---|
| `Fx.sine(buf, o)` | partials, gliding, optionally FM — bells, thuds, birdsong |
| `Fx.noise(buf, o)` | a band-shaped burst whose band may sweep — gravel, air, timber |
| `Fx.rumble(buf, o)` | lowpassed noise — soil, breath, distance |
| `Fx.voice(buf, o)` | a glottal pulse train through resonant formants — the umpire's calls and the fencers' efforts. `breath` trades the pulse for air, which is the difference between a shout and a grunt. |
| `Fx.bed(buf, o)` | a continuous lowpassed bed whose loudness breathes on a slow LFO |
| `Fx.finish(buf, peak)` | soft clip, peak-normalise, and 4 ms fades at both ends |
Vowels are three `{ centre, bandwidth, amplitude }` formants; `ah`, `ay`, `aw`,
`oy`, `uh`, `ee`, `oo`, `oh` and `er` are enough for the whole rite.
### The umpire's throat
The assize needs a dozen calls and not three: an umpire with four lines says
each of them eight times in a bout, and a rite that repeats is a metronome. So
a call is written as a list of syllables rather than as a stack of primitives —
a vowel, a length, and where the pitch starts and ends on it. `edge` puts a
consonant's noise in front of a syllable and `stop` puts one behind it, which
is the whole difference between a call that lands on a vowel and one that stops
dead on a T.
```luau
VOICES.umpire_hold = function()
return call({
seed = 9400,
syls = {
{ v = "oh", dur = 0.30, f = 178, f2 = 118, amp = 0.86,
glide = 0.7, edge = 0.26, edgeF = 3000, stop = 0.20 },
},
})
end
```
Fifteen calls are written that way: `umpire_salute`, `umpire_engarde`,
`umpire_ready` and `umpire_play` for opening and restarting; `umpire_come` for
a ground with no ceremony; `umpire_hold` and `umpire_arret` beside `halt`;
`umpire_touche`, `umpire_award_for` and `umpire_award_against` beside `point`;
`umpire_score` when the touches are level; `umpire_last` when one post ends the
assize; `umpire_verdict` to read it; and `breath_hard` / `breath_soft`, which
are the same throat with the pulse traded for air — the man behind the mask,
audible for the two seconds nobody is fencing.
`DuelFx` decides which of them is heard, from the beat `DuelMatch.ceremonyPhase`
publishes and the state of the bout.
```luau
Fx.bake() -- render every clip into /source/audio/
Fx.bake({ "umpire_halt" }) -- or just one
Fx.clipNames() -- what it can render
```
Baking is deterministic — the noise generator is a seeded LCG, so a re-bake
produces the same bytes and `overwrite = true` keeps each clip's guid.
**Peak normalisation is a trap for a bed.** A bed whose birds set the peak has
its wind crushed to silence, and `audio.info` reports nothing that would show
it. Decode the clip back and measure RMS in windows:
```luau
local pcm, sr = audio.decode(ref:getBytes()) -- little-endian f32, interleaved
```
`hedge_wall` was rewritten twice on that measurement: its wind bed read 0.021
RMS against a 0.055 pigeon until the birds came down and the bed came up.
# Fencer
One combatant in the fence duel. Attaches to a bare entity — it asks
`fencer_body` for its rig in `awake`, so it needs no Model or mesh of its own.
Owns footwork along the piste (world X, depth and height held) and the
windup → active → recover state machine behind the four commitments: `thrust`,
`sweep`, `lunge` and `parry`. Every commitment carries the body over its own
`advance`, so distance and commitment can be made in one action; the step stops
at the fencer's own `minReach` rather than carrying it inside its own measure.
Footwork is bounded by the other fencer, not by the property line: a man who has
drawn back into his own garden is still reachable, which is the whole reason to
hold the measure. Breaking ground is slower than taking it.
A commitment that reached nobody — short of its reach, or crowded inside it, or
a guard that turned nothing aside — enters recovery from a debt. So does one
that was parried. The debt is the commitment's own (`duel.whiffOf` /
`duel.parriedOf`), so it scales with what the commitment bought: a thrust turned
aside costs half a second and a lunge turned aside costs the better part of two.
That debt is the opening the other fencer is meant to punish, and
`phaseTime < 0` in `recover` is how a reader tells a real opening from an
ordinary recovery.
**The lunge is recovered to the line it was thrown from.** It is the one
commitment marked `recoil`: whatever of its 1.30 m of `advance` it managed to
cover, it gives back over its own recovery, travelling backwards at the pace it
went out and unable to answer anything while it does. `recoilLeft` is the ground
still owed. So the lunge buys half a metre of reach nothing else has, and buys
no position at all — which is what stops it being a free way to close the
measure.
A commitment made while `riposte` is open comes out at `RIPOSTE_QUICK` of its
wind-up, reaches `RIPOSTE_REACH` further, cannot be turned aside, and plants
`RIPOSTE_POSTS` posts instead of one.
The component is input-agnostic except for one case: a `role = "player"` fencer
on a local entity reads the `move` axis and the `thrust` / `sweep` / `lunge` /
`parry` actions itself. A `role = "rival"` fencer is driven by `FencerAI`
through the same public methods a human's input reaches.
Fields worth reading from outside: `role`, `action`, `phase`, `phaseTime`,
`riposte`, `ripostePending`, `whiffed`, `frozen`, `touches`, `facing`.
`action` is `""` while idle, not `"guard"`; the idle `phase` is `"guard"`.
Methods: `commit(name)`, `walk(dir, dt, line)`, `resetTo(line)`,
`receiveTouch()`, `beParried()`, `clash()`, `openRiposte()`, `markContact()`,
`freeze(on)`, `isStriking()`, `currentReach()`, `currentMinReach()`.
Requires the `duel` and `fencer_body` modules and `@builtin::modules.zinput`.
`DuelMatch` umpires between two of these; it is what calls `receiveTouch` /
`beParried` / `clash` / `openRiposte` / `markContact`.
# DuelFx
Everything between the rules firing and the player feeling it. The umpire
decides what happened; this decides what it feels like, and where in the garden
it sounded like it happened.
Attach it to `DuelDirector`. It reads `DuelMatch` and both `Fencer`s and writes
nothing back to either.
```luau
entity.find("DuelDirector").component.add("DuelFx", {})
```
## Four commitments, four weights
A thrust arrives on a point and is over. A sweep is a whole fence panel and it
turns the man it lands on. A lunge brings a body 1.30 m with it and tears grit
off the piste the whole way. A riposte comes off a guard rather than out of a
wind-up, and it costs two posts.
Which one landed is read out of `DuelMatch.lastExchange`, and every channel of
the reaction is driven from one row of the `PROFILE` table:
| | recoil | spin | shove | hitstop | dust | landing sound |
|---|---|---|---|---|---|---|
| thrust | 0.88 | 0.08 | ×1.0 | ×0.9 | a narrow plume at chest height | `touch_thud` +1.12, `panel_clack` |
| sweep | 1.00 | **1.00** | ×2.1 | ×1.6 | a low wide sheet across the piste | `touch_thud` −0.80, **`panel_crunch`** |
| lunge | 0.96 | 0.20 | **×3.2** | ×2.1 | a ground trail from the back foot to the contact | `touch_thud` −0.94, `panel_clack` |
| riposte | 0.92 | 0.30 | ×1.4 | ×1.3 | bright chips off the guard | `riposte_open`, `touch_thud` |
`spin` is the sweep's signature — only a broadside turns a fencer off the line,
so a still frame of a sweep is nameable without sound. `shove` is the lunge's:
it gives up three times the ground a thrust does.
## The chalk, and the hold
At the measure a touch resolves at, two men holding whitewashed fence panels
are one beige mass from side on. Two things put the read back into the frame,
and both of them last as long as the umpire holds the bout rather than as long
as an impact.
**The chalk.** Every panel in this garden is whitewashed timber, so a stroke
that lands leaves its coat behind. The mark runs FROM the man who struck TO the
man who took it, so which way the blow went is in the picture; its shape is
which stroke it was:
| | what it writes |
|---|---|
| thrust | one straight level line along the picket that led |
| lunge | a long low line off the back foot rising into the contact, with the point on the end of it |
| sweep | five strokes of a falling quarter circle, from above the shoulder it came off down onto the man |
| riposte | the guard it came off, crossed, and the answer out of it |
It is drawn 0.62 m nearer the camera than the piste, so it is never swallowed
by the two bodies it is describing, and it holds its length while it thins.
`chalk` turns it off; `chalkLife` is how long it hangs.
**The hold.** A reaction used to be gone in three tenths of a second, which at
this build's frame time is one frame — so the pose that names the commitment
was never in the picture. `contactHold` pins each fencer's recoil, spin, lean,
overreach and jam at the values the blow gave them, as a floor rather than an
assignment, so a shove still running out or a second event inside the beat
still reads on top of it.
`PisteCamera` swings off the piste axis for the same beat, which is the other
half of the same fix — see its README.
## The two faults, which are not touches
`SHORT` and `CROWDED` are recorded by the umpire and never reach the event bus,
so `fx` derives them from the exchange record. Their feedback is deliberately
built out of the opposite parts of the vocabulary from a touch, so the two can
never be confused:
- the reaction is on the **attacker**, not the defender
- there is **no hitstop**, **no contact flash** and **no rim**
- the shape left behind is a flat scuff disc lying on the piste — the only
thing this component ever draws on the ground
`SHORT` pitches the attacker forward through a stroke that found nothing
(`whiff_air` + `gravel_scuff`). `CROWDED` jams the panel and shoves both
fencers apart (`panel_scrape` + a tight `panel_clack`).
## The post is driven, not moved
The umpire awards a touch and the boundary is already somewhere else: the line
is a number, and `Garden.fence` rebuilds the run at its new value inside the
same frame. What the eye is given instead is the thing the rite is actually
about.
Over `driveTime`, the surveyor's cord walks from where the line stood to where
it now runs — `driveWalk` seconds of it, on a curve that leaves fast and
settles — carrying a post held clear of the turf. Then `driveBlows` mallet
blows put the post in, each one seating it further, throwing its own turf and
its own `post_drive` at a lower pitch than the last, until it is flush with the
boundary's own post.
`driveFrom`, `driveTo`, `drivePct` and `driveState` report it live, so a
photograph taken across the pause can be matched to exactly how far in the post
was. `driveFrom` is derived from the umpire's published `lastDrive` and
`lastTouch` rather than remembered, so it is exact.
## The rite
The umpire is on a beat at all times and `DuelMatch.ceremonyPhase` names it.
Each beat has its own calls, drawn from a bag — a call is not heard twice until
every other call on that beat has been heard once — and which calls are
eligible depends on the state of the bout:
| beat | calls | narrowed by |
|---|---|---|
| `salute` | `umpire_salute`, `umpire_engarde`, `umpire_ready` | |
| `enGarde` | `umpire_engarde`, `umpire_ready`, `umpire_score`, `umpire_last` | the score only when it is level; the last post only when one post ends it |
| `allez` | `umpire_allez`, `umpire_play`, `umpire_come` | "come on" only on a ground that does not stand on form |
| `halt` | `umpire_halt`, `umpire_hold`, `umpire_arret` | "arrêt" only on a ground that does |
| `post` | `umpire_point`, `umpire_touche`, `umpire_award_for`, `umpire_award_against` | the award reads for or against by who scored |
| `verdict` | `umpire_verdict` | |
Whether a ground stands on form is `Duel.ceremonyScale(neighbourKey)`, so the
umpire keeps a different rite in each of the six gardens without anybody
writing six rites.
`ceremonyLog` is the record: one line per call, numbered, with the beat it
belongs to and — where a frame was long enough to step over a 0.28 s beat
entirely — the beat the umpire said he was on, as `post@halt`.
**The bell counts.** One strike opens an assize; three close it, rising, with
the wall giving the last one back. **Both men breathe** in the pause, the one
who took it harder than the other, and both of them harder once the bout is six
touches deep.
**Every neighbour has their own throat.** `NEIGHBOUR_VOICE` pitches and weights
the rival's tells, efforts and breath per `neighbourKey` — Mrs Pettifer light
and high, Lady Ashcombe low and quiet, Young Tibb high and loud — so who you
are fencing is audible before you look.
## The soundstage
The lawn is thirty metres of piste between two hedges, and three of its places
can be heard:
| source | where | what |
|---|---|---|
| `amb_orchard` | west end, x −14 | the player's own orchard: leaf wash, bees, a blackbird |
| `amb_wall` | east end, x +14 | the neighbour's walled end: drier wind, a wood pigeon, a wren |
| `sfx_bell` | the garden wall, x 0 z −13 | the assize bell, and its return off the wall 0.40 s later |
| `sfx_umpire` | walks the piste beside the fight | `allez`, `halt`, `point` |
| `sfx_bed` | everywhere | the garden's own bed, non-spatial |
The two hedge beds crossfade on where the fight has got to, so a bout driven
into the player's garden sounds like the player's garden. `ambience` is the
readback: `focus=-10.00 near=orchard orchard=0.296 wall=0.171 bed=0.340`.
Footfall knows what it is standing on. The piste is raked gravel end to end,
but the ground within 1.05 m of a driven post is the spoil thrown out of its
hole, so a fencer standing on the boundary steps in broken turf. `stepSurface`
reports it.
## Clip → event
Every clip in `/source/audio/` and what fires it.
| clip | fired by |
|---|---|
| `bell_assize` | `salute`; `over:*` — three strikes, rising, at +0.55 / +1.05 / +1.55 s |
| `bell_return` | `salute` (+0.40 s); `over:*` (+1.95 s) — the wall giving it back |
| `umpire_allez` | the `allez` beat |
| `umpire_play` | the `allez` beat |
| `umpire_come` | the `allez` beat, on a ground with no ceremony to observe |
| `umpire_halt` | the `halt` beat, and the one that ends the assize |
| `umpire_hold` | the `halt` beat |
| `umpire_arret` | the `halt` beat, on a ground that stands on form |
| `umpire_point` | the `post` beat, 0.60 s after the stop |
| `umpire_touche` | the `post` beat, on a ground that stands on form |
| `umpire_award_for` | the `post` beat, when the touch was the player's |
| `umpire_award_against` | the `post` beat, when it was against |
| `umpire_salute` | the `salute` beat that opens an assize |
| `umpire_engarde` | the `salute` and `enGarde` beats |
| `umpire_ready` | the `salute` and `enGarde` beats |
| `umpire_score` | the `enGarde` beat, when the touches are level |
| `umpire_last` | the `enGarde` beat, when one post ends the assize |
| `umpire_verdict` | the `verdict` beat, read over the last of the bells |
| `breath_hard` | the fencer who took the touch, in the pause after it |
| `breath_soft` | the other one, and neither of them once the bout is deep |
| `post_drive` | `post`; `allez` (a light tap, pitched up) |
| `touch_thud` | `touch:*`, pitched by the commitment that landed |
| `panel_clack` | `touch:*` other than a sweep; `parry:*`; `clash`; `crowded:*` |
| `panel_crunch` | `touch:*` where the landing commitment was a **sweep** |
| `panel_scrape` | `crowded:*`; `clash` |
| `riposte_open` | `parry:*`; `riposte:*` |
| `whiff_air` | `short:*` |
| `gravel_scuff` | `short:*` — the foot saving the over-reach |
| `gravel_step` | `step:*` on the raked piste |
| `turf_step` | `step:*` within 1.05 m of the boundary post |
| `tell_thrust` | `<role>:thrust`, and any commitment with no voice of its own |
| `tell_sweep` | `<role>:sweep` |
| `tell_lunge` | `<role>:lunge` |
| `tell_parry` | `<role>:parry` |
| `effort_sweep` | `<role>:sweep` — the breath under the arc |
| `effort_lunge` | `<role>:lunge` — the breath of going the whole way |
| `garden_bed` | looping, non-spatial |
| `hedge_orchard` | looping at the west end, gain by focus |
| `hedge_wall` | looping at the east end, gain by focus |
## The flash
The rim is the `outline` channel on a struck fencer's models, and nothing else
in the world writes it. It marks the **body** that took the touch, so it skips
the two classes that are not one: what a fencer stands on, and what they are
holding. Both are matched by name (`panel`, `shoe`, `stocking`, `leg`, `foot`,
`sole`), because a name is the only property of a rig part that a pose does not
change — position and scale are rewritten every frame by `fencer_body.pose`, so
a geometric gate answers differently depending on which frame it is asked.
`flashState` reports the live rim level and how many models it is allowed on:
`player=0.64/11 rival=0.00/19`. A rim that stops appearing because a body module
renamed its parts is invisible in a screenshot and obvious there.
## Timing, and the frame rate it was tuned at
Every window here was tuned against a measured **104 ms frame — about 9.6 fps**
(`zero profiler retro --seconds 20`), and every one is expressed in real
seconds rather than frames, so it means the same thing when the frame rate
comes up. The hitstops run 0.09 s to 0.26 s: one to three frames at 9.6 fps,
five to sixteen at 60.
## Instruments
| field | what it says |
|---|---|
| `busProduced` / `busTaken` / `busMissed` | events the umpire emitted, events drained off `fxQueue`, and the difference. `busMissed` is zero when nothing is lost. |
| `recordsMissed` | exchange records overwritten inside one frame. The events still arrive; only the detail behind them is gone, and the reaction falls back to its default weight (`lastReaction` says `unread`). |
| `eventCount` | events dispatched, including the two derived faults. |
| `fxPath` | `queue` once the lossless read is live, `derived` before it. |
| `soundCount` / `lastSound` / `soundLog` | every clip that has played, stamped on the clock `capture` reports as `sceneTime` per cell. |
| `lastReaction` / `reactionLog` | every reaction, named — `touch:player lunge`, `short:rival overreach`, `crowded:player jam`. |
| `ambience` / `stepSurface` / `flashState` / `motesAlive` | the soundstage, the ground underfoot, the rim, the live mote count. |
| `ceremonyLog` / `ceremonyCount` / `lastLine` | every umpire line that has fired, in order, with the beat it fired on. What a rite that repeats looks like, as data. |
| `driveFrom` / `driveTo` / `drivePct` / `driveState` | where the line stood, where it now runs, and how far through putting the post in this frame is. |
## What it owns
A temporary `duel_fx` root holding the ears, seven emitters, the flash, the
turf puff, the scuff disc, a sixteen-mote pool, a nine-segment chalk pool and
the post, collar, mallet and cord of the drive; the `rig` child transform of
each fencer; the outline channel on their body models; `punch` / `kick` /
`shake` for `PisteCamera`; and `engine.timeScale`, for the length of one
hitstop and no longer.
The drive's post goes in at `z = -2.40`, which is where `garden.module` stands
the boundary's own post — the two are the same place on purpose, so what the
drive puts in is the post that is already there.
# duel
The rules of the Hedgerow Assizes, in one place: the ground plan of the walled
garden, the frame data of the four commitments, the measure each one works at,
the triangle that decides what a contact means, how far a post drives the
property line, and the roster of neighbours with the fencing each one keeps.
Every duel component reads its numbers from here, so the whole match is tuned in
one file.
Consumed by `Fencer`, `FencerAI`, `DuelMatch`, `DuelHud`, `DuelFx`, `garden` and
the main scene's entrypoint.
## The measure
Each action carries a band, not a range: `reach` is the furthest the blade
crosses and `minReach` the nearest — inside that, the panel is smothered and the
attack is *crowded out*. `advance` is the ground the commitment itself takes, so
every attack steps in and a defender cannot simply walk backwards out of the
sport. A commitment that reached nobody runs its recovery from a debt, and that
debt is the whole punishment for committing at the wrong distance.
| Action | windup | active | recover | reach | minReach | advance | whiff | parried |
|---|---|---|---|---|---|---|---|---|
| `thrust` | 0.22 | 0.10 | 0.42 | 2.55 | 1.55 | 0.35 | 0.35 | 0.45 |
| `sweep` | 0.34 | 0.20 | 0.58 | 2.15 | 0.00 | 0.25 | 0.55 | 0.65 |
| `lunge` | 0.30 | 0.16 | 0.95 | 3.05 | 1.75 | 1.30 † | 1.00 | 1.20 |
| `parry` | 0.05 | 0.34 | 0.40 | — | — | — | 0.30 | — |
† The lunge is marked `recoil`: whatever of its `advance` it managed to cover it
gives back over its own recovery, travelling backwards and unable to answer
anything while it does. It buys reach; it never buys position.
## The triangle
`parry` turns a `thrust` and a `lunge` aside and earns a riposte; a `sweep`
crashes through a held guard; a `thrust` arrives inside a `sweep`'s long
wind-up. A riposte cannot be turned at all.
**The guard answers from its first frame.** `resolveTouch` treats a `parry` in
`windup` exactly as it treats one in `active`, because a guard that only worked
once it had finished rising could be beaten by an attack thrown from further out
than the wind-up is long — which made a correct read lose to a committed attack,
the one outcome the triangle exists to prevent.
## What a post is worth
A post is not a fixed step. Three properties of the ground decide how far the
line moves, and between them they are what gives a bout its length:
| | | |
|---|---|---|
| `POST_STEP` | 1.15 | fresh mown lawn in the middle of a garden |
| `POST_ROOTED` | 0.60 | the last feet before a hedge are old rooted ground, and give up to this much of the step |
| `POST_RECLAIM` | 0.35 | lawn you already conceded holds somebody else's posts; they come out before the line passes back |
| `POST_CHURN` | 0.05 | each post already driven breaks the ground a little further, to `POST_CHURN_MAX` |
`postDrive(line, dir, posts, driven)` is the whole rule. Rooted ground stops a
garden being annexed by a short run of luck; conceded ground stops two even
fencers walking the line back and forth all afternoon. Chosen against a
simulation of the rule over 600 bouts a configuration, with the riposte rate and
touch cadence taken from played logs: a median bout of about 20 touches, 80 % of
bouts between 45 s and 120 s.
## The roster, and how each one fences
`NEIGHBOURS` is the roster — index, `key`, `skill` and `style`. `STYLES` is the
fencing attached to each key, and it is what makes three opponents rather than
one opponent at three settings:
| | `hold` | `think` | `patience` | `adapt` | `boundary` |
|---|---|---|---|---|---|
| `pettifer` | +0.55 | 1.45 | 2.4 | 0.6 | 0.0 |
| `wickham` | 0.00 | 0.90 | 1.0 | 2.2 | 0.15 |
| `ashcombe` | −0.35 | 0.75 | 0.6 | 1.1 | 1.0 |
`hold` moves the measure held at rest; `think` the pause between commitments;
`patience` how long an opponent who has offered nothing is indulged before the
touch is simply fetched; `adapt` how heavily a repeated stroke steers the answer
and how much faster the eye settles on one it has seen; `boundary` how far the
defence of one's own ground stiffens the fencing as the line comes back toward
one's own hedge. `w*` are the standing appetites for each commitment.
`style(key)` falls back to `wickham`'s for an unknown name rather than erroring.
## Surface
- `ACTIONS` — the table above.
- `isAttack(name)`, `reachOf(name, isRiposte)`, `windupOf(name, isRiposte)`,
`advanceSpeed(name)`, `whiffOf(name)`, `parriedOf(name)`.
- `resolveTouch(attack, defAction, defPhase, isRiposte)` — `"touch"` |
`"parried"` | `"nothing"`.
- `measureFault(name, gap, isRiposte)` — `"short"` | `"crowded"` | `nil`.
- `postDrive(line, dir, posts, driven)` — metres one touch moves the boundary.
- `resetX(line, side)` / `clampX(x, line, side, foeX)` — where a fencer stands,
and how far it may travel: bounded by the opponent, not by the line.
- `winner(line)` — `"player"` | `"rival"` | `nil` for the boundary's position.
- `NEIGHBOURS`, `neighbour(index)`, `neighbourIndexOf(key)`,
`neighbourNearestSkill(skill)`, `STYLES`, `style(key)`.
- `LAWN_HALF`, `LINE_LIMIT`, `POST_STEP`, `POST_ROOTED`, `POST_RECLAIM`,
`POST_CHURN`, `POST_CHURN_MAX`, `RIPOSTE_POSTS`, `STANCE`, `WALK_SPEED`,
`RETREAT_FACTOR`, `MIN_GAP`, `LEASH`, `RIPOSTE_WINDOW`, `RIPOSTE_QUICK`,
`RIPOSTE_REACH`, `CLASH_PUSHBACK`, `HIT_STUN`, `SALUTE_TIME`, `TOUCH_PAUSE`,
`SIDE`, `COLOR`.
# DuelMatch
The umpire nobody sees. One instance, on the `DuelDirector` entity.
Asks `garden` for the walled garden and the boundary fence, spawns the rival,
resolves every exchange between the two `Fencer`s through `duel.resolveTouch`,
plants a post and drives the property line into the loser's garden on a touch,
resets both fencers and runs the salute, and calls the match when the line
reaches a hedge.
The boundary is the health bar: `line` is the fence's leading post, and the
fence is rebuilt from the player's hedge out to it whenever `line` changes, so
the score is a physical object standing in the world.
## What a touch is worth
How far a post drives the line is `duel.postDrive`, and it is a property of the
ground rather than a constant: fresh lawn in the middle of a garden gives, the
last feet before a hedge are rooted and stubborn, lawn already conceded holds
somebody else's posts and has to be cleared before the line passes back over it,
and every post driven breaks the ground a little further for the next one.
`postsDriven` counts the posts this bout and `lastDrive` reports the metres the
last one bought. Between them these are what give a bout a length rather than
only a variance.
## Resolution
An attack whose blade is live inside its measure is an exchange. Two live
blades in the same tempo is a **clash**: neither scores and both pay for it,
which is what stops the umpire's own resolution order from deciding the bout.
An attack outside its measure is recorded as `SHORT` or `CROWDED` and never
touches its man, so the fencer who threw it pays the whiff debt.
A touch taken inside a riposte window plants `RIPOSTE_POSTS` posts rather than
one, and `lastPosts` reports which it was.
## The event bus
`fxEvent` names the moment and `fxSeq` moves on **every** write, including a
repeat of the same event — so a reader polls `fxSeq` against the last one it saw
rather than diffing fields for edges. Vocabulary: `salute`, `allez`,
`short:player`, `short:rival`, `clash`, `parry:player`, `parry:rival`,
`riposte:player`, `riposte:rival`, `touch:player`, `touch:rival`, `post`,
`over:player`, `over:rival`. `":player"` means *the player did it*.
`fxQueue` is the lossless read of the same vocabulary: every event since the
last frame, in the order it happened. `DuelMatch` empties it at the top of its
own update, and it runs before everything that reads it, so a reader gets the
whole of this frame's list — including a `touch:player` and the `post` that
follows it in the same frame, which a single slot cannot carry.
## The roster
`neighbour` (1..3), `neighbourKey` (`"pettifer"` | `"wickham"` | `"ashcombe"`)
and `skill` are one identity written three ways. Writing any of them settles the
other two off `duel.NEIGHBOURS` and pushes the matching `style` onto the live
rival's `FencerAI`, so a garden, a turnout and a verdict can all name the same
person without any of them guessing. `DuelHud` keeps ownership of the prose.
## Fields
`line`, `state` (`salute` | `fence` | `touch` | `over`), `lastTouch`, `winner`,
`playerTouches`, `rivalTouches`, `skill` (the rival's quality — writing it
retunes the live rival), `announce`, `lastPosts`, `postsDriven`, `lastDrive`,
`matchClock` (seconds since this bout's first `allez`), `neighbour`,
`neighbourKey`, `fxEvent` / `fxSeq` / `fxQueue`, and `lastExchange` /
`lastExchangeSeq` / `exchanges` — the tuning record, naming who struck into what
and what the triangle made of it, including attacks that fell short of their
reach or were smothered inside it.
## Method
`restart()` — a fresh assize, the line back to nought. Callable at any time,
including from `state == "over"`, where the `restart` action also reaches it.
Pairs with `DuelHud` on the same entity. Requires the `duel` and `garden`
modules and `@builtin::modules.zinput`.