refactor: make intent the step's input

The step derived the player's intent from raw input inside every tick,
twice, through the camera, so it read the surface, the orientation, and
the camera lean: client state a co-op room does not have.

The client frame loop moves to src/frame.ts: clampFrameDelta, the tick
carry, refreshIntent, the camera lean, and the cosmetics. It derives the
intent before each tick, and advanceTick in src/simulation.ts takes it as
given. The step only idles the intent while the player is at the stall's
counter or the exit's sign. The camera leans once a frame on the
display's time. simulation.ts no longer imports camera.ts or input.ts.

This changes mouse aim on purpose, as MULTIPLAYER.md predicts: aim now
comes from where the player stood when the tick began, not after the
tick's move, so with the camera held at a room's edge the aim point moves
by up to the player's one-tick step. determinism:diff against 59d0c96
first differs at frame 92 in a bullet's velocity, with intent, facing,
and the camera lean beside it and nothing else. Keyboard and stick aim do
not go through the camera.

Author: Tanner-Scadden

src/frame.ts

@@ -0,0 +1,118 @@
+import { modifyFields } from 'foldkit/struct'
+
+import { leanCamera, screenCameraOf } from './camera'
+import {
+  FIXED_STEP_MS,
+  MAX_FRAME_DELTA_MS,
+  MS_PER_SECOND,
+  STEP_EPSILON_MS,
+} from './constants'
+import { clamp } from './geometry'
+import { deriveIntent } from './input'
+import { advanceJuice } from './juice'
+import { type GameEvent, type Model, ShopState, idleIntent } from './model'
+import { advanceParticles } from './particles'
+import { advanceCallouts } from './powerups'
+import { advanceTick } from './simulation'
+import { isRoundActive } from './waves'
+
+// The client's frame: the display's time becomes whole 60 Hz ticks of the
+// world, each fed the intent the client derives from its own input and
+// camera, and the frame's cosmetics follow from the events of its ticks.
+
+export const clampFrameDelta = (deltaTime: number): number =>
+  clamp(deltaTime, 0, MAX_FRAME_DELTA_MS)
+
+// NOTE: the client turns raw input into intent: aim goes through the
+// camera, which only this device knows. A player at the stall's counter or
+// the exit's sign intends nothing.
+export const refreshIntent = (model: Model): Model =>
+  modifyFields(model, {
+    intent: () =>
+      ShopState.isAnyOf(['Browsing', 'AtExit'])(model.shop)
+        ? idleIntent
+        : deriveIntent(model.input, model.player, screenCameraOf(model)),
+  })
+
+type Ticks = Readonly<{ count: number; carryMs: number }>
+
+// NOTE: a 60 Hz frame on an empty carry is exactly one tick and leaves
+// exactly zero, so a 60 Hz display steps as it did before the fixed step.
+export const ticksIn = (carryMs: number, count = 0): Ticks =>
+  carryMs >= FIXED_STEP_MS - STEP_EPSILON_MS
+    ? ticksIn(carryMs - FIXED_STEP_MS, count + 1)
+    : { count, carryMs: Math.max(0, carryMs) }
+
+type Stepped = Readonly<{
+  model: Model
+  events: ReadonlyArray<GameEvent>
+  worldMs: number
+}>
+
+// NOTE: a tick that ends the round ends the frame's ticks.
+const runTicks = (stepped: Stepped, count: number): Stepped => {
+  if (count <= 0 || !isRoundActive(stepped.model.phase)) {
+    return stepped
+  }
+  const ticked = advanceTick(refreshIntent(stepped.model))
+  return runTicks(
+    {
+      model: ticked.model,
+      events: [...stepped.events, ...ticked.model.frameEvents],
+      worldMs: stepped.worldMs + ticked.worldMs,
+    },
+    count - 1,
+  )
+}
+
+// NOTE: what the frame looks like once its ticks ran: the camera lean,
+// particles, the walking dust, callouts, and the juice, all from the
+// frame's events and the cosmetic stream, so they never touch the World.
+const advanceCosmetics = (
+  model: Model,
+  frameMs: number,
+  worldMs: number,
+): Model =>
+  advanceJuice(
+    advanceCallouts(
+      worldMs > 0
+        ? advanceParticles(model, worldMs / MS_PER_SECOND, worldMs)
+        : model,
+      worldMs,
+    ),
+    frameMs,
+    worldMs,
+  )
+
+// NOTE: the camera leans toward the aim on the display's own time.
+const leanFor = (model: Model, frameMs: number): Model =>
+  modifyFields(model, {
+    cameraLean: lean => leanCamera(lean, model.intent.maybeAim, frameMs),
+  })
+
+// NOTE: a frame runs the whole ticks its time owes and carries the rest,
+// then makes its cosmetics. Its `frameEvents` are every tick's events in
+// order, so the cosmetics, sounds, stats, and lessons see each one.
+export const advanceGame = (model: Model, deltaTime: number): Model => {
+  const frameMs = clampFrameDelta(deltaTime)
+  const ticks = ticksIn(model.stepCarryMs + frameMs)
+  const stepped = runTicks(
+    {
+      model: modifyFields(model, {
+        stepCarryMs: () => ticks.carryMs,
+        frameEvents: () => [],
+      }),
+      events: [],
+      worldMs: 0,
+    },
+    ticks.count,
+  )
+  return advanceCosmetics(
+    leanFor(
+      modifyFields(stepped.model, { frameEvents: () => stepped.events }),
+      frameMs,
+    ),
+    frameMs,
+    stepped.worldMs,
+  )
+}

src/main.ts

@@ -80,7 +80,7 @@ import { LinkFlow } from './playerSync'
 import { forgetTutorial } from './save'
 import { isUsingServiceWorker } from './serviceWorker'
 import { isAtCounter, isBrowsing } from './shop'
-import { advanceGame, clampFrameDelta, refreshIntent } from './simulation'
+import { advanceGame, clampFrameDelta, refreshIntent } from './frame'
 import { tallyFrame } from './stats'
 import { PlayerStore } from './store'
 import { foldCharacter } from './update/character'

src/simulation.ts

@@ -17,7 +17,6 @@ import {
   puddleSlowAt,
   woundScaleOf,
 } from './boss'
-import { leanCamera, screenCameraOf } from './camera'
 import { advanceChuckers, maybeChuckerHeading, maybeShieldFor } from './chucker'
 import {
   hitEvent,
@@ -33,12 +32,10 @@ import {
   DRY_FIRE_DELAY_MS,
   FIXED_STEP_MS,
   KNOCKBACK_REST_SPEED,
-  MAX_FRAME_DELTA_MS,
   MS_PER_SECOND,
   PLAYER_KNOCKBACK_DECAY_PER_SECOND,
   PLAYER_RADIUS,
   SEPARATION_SPEED,
-  STEP_EPSILON_MS,
   ZOMBIE_BUMP_SPEED,
   ZOMBIE_KNOCKBACK_DECAY_PER_SECOND,
 } from './constants'
@@ -56,8 +53,7 @@ import {
   scaleVector,
   vectorLength,
 } from './geometry'
-import { deriveIntent } from './input'
-import { advanceJuice, stopForHits, thawTick } from './juice'
+import { stopForHits, thawTick } from './juice'
 import { advanceKitchen, soupSkid } from './kitchen'
 import {
   Arsenal,
@@ -80,7 +76,6 @@ import {
   idleIntent,
 } from './model'
 import { advanceIntensity } from './pacing'
-import { advanceParticles } from './particles'
 import {
   type Clearance,
   maybeNearestBait,
@@ -90,7 +85,6 @@ import {
   steerToward,
 } from './pathing'
 import {
-  advanceCallouts,
   advancePowerUps,
   bulletGlaze,
   bulletPierce,
@@ -111,7 +105,7 @@ import {
   tollsOf,
   trapBlockers,
 } from './traps'
-import { advanceRound, endWhenDefeated, isRoundActive } from './waves'
+import { advanceRound, endWhenDefeated } from './waves'
 import {
   SIDEARM,
   type WeaponStats,
@@ -137,13 +131,12 @@ import {
 
 // INTENT
 
-export const refreshIntent = (model: Model): Model =>
-  modifyFields(model, {
-    intent: () =>
-      ShopState.isAnyOf(['Browsing', 'AtExit'])(model.shop)
-        ? idleIntent
-        : deriveIntent(model.input, model.player, screenCameraOf(model)),
-  })
+// NOTE: the player's intent is the step's input. A player at the stall's
+// counter or the exit's sign does nothing else, whatever they hold.
+const gateIntent = (model: Model): Model =>
+  ShopState.isAnyOf(['Browsing', 'AtExit'])(model.shop)
+    ? modifyFields(model, { intent: () => idleIntent })
+    : model
 
 // TIMERS
 
@@ -1261,16 +1254,13 @@ const feelIntensity = (before: Model, after: Model, deltaMs: number): Model =>
 
 // FRAME
 
-export const clampFrameDelta = (deltaTime: number): number =>
-  clamp(deltaTime, 0, MAX_FRAME_DELTA_MS)
-
 const advanceWorld = (model: Model, deltaMs: number): Model => {
   const seconds = deltaMs / MS_PER_SECOND
 
   const level = levelOf(model)
   const blockers = trapBlockers(level, model.traps)
   const tolls = tollsOf(level, model.traps)
-  const moved = refreshIntent(
+  const moved = gateIntent(
     modifyFields(model, {
       player: player =>
         movePlayer(
@@ -1288,7 +1278,7 @@ const advanceWorld = (model: Model, deltaMs: number): Model => {
       frameEvents: () => [],
     }),
   )
-  const routed = refreshIntent(
+  const routed = gateIntent(
     refreshShopPresence(
       modifyFields(moved, {
         flowField: flowField =>
@@ -1326,94 +1316,17 @@ const advanceWorld = (model: Model, deltaMs: number): Model => {
   )
 }
 
-// NOTE: one 60 Hz tick: hit-stop decides whether the world steps, then
-// the camera lean follows and the tick's events decide the next hit-stop.
-type Tick = Readonly<{ model: Model; worldMs: number }>
+// NOTE: one 60 Hz tick of the world from the player's intent: hit-stop
+// decides whether the world steps, then the tick's events decide the next
+// hit-stop.
+export type Tick = Readonly<{ model: Model; worldMs: number }>
 
-const advanceTick = (model: Model): Tick => {
+export const advanceTick = (model: Model): Tick => {
   const thaw = thawTick(model.hitStop, FIXED_STEP_MS)
   const thawed = modifyFields(model, {
     hitStop: () => thaw.hitStop,
     frameEvents: () => [],
   })
   const stepped = thaw.worldMs > 0 ? advanceWorld(thawed, thaw.worldMs) : thawed
-  const leaned = modifyFields(stepped, {
-    cameraLean: lean =>
-      leanCamera(lean, stepped.intent.maybeAim, FIXED_STEP_MS),
-  })
-  return { model: stopForHits(leaned, thaw.worldMs), worldMs: thaw.worldMs }
-}
-
-type Ticks = Readonly<{ count: number; carryMs: number }>
-
-// NOTE: a 60 Hz frame on an empty carry is exactly one tick and leaves
-// exactly zero, so a 60 Hz display steps as it did before the fixed step.
-export const ticksIn = (carryMs: number, count = 0): Ticks =>
-  carryMs >= FIXED_STEP_MS - STEP_EPSILON_MS
-    ? ticksIn(carryMs - FIXED_STEP_MS, count + 1)
-    : { count, carryMs: Math.max(0, carryMs) }
-
-type Stepped = Readonly<{
-  model: Model
-  events: ReadonlyArray<GameEvent>
-  worldMs: number
-}>
-
-// NOTE: a tick that ends the round ends the frame's ticks.
-const runTicks = (stepped: Stepped, count: number): Stepped => {
-  if (count <= 0 || !isRoundActive(stepped.model.phase)) {
-    return stepped
-  }
-  const ticked = advanceTick(stepped.model)
-  return runTicks(
-    {
-      model: ticked.model,
-      events: [...stepped.events, ...ticked.model.frameEvents],
-      worldMs: stepped.worldMs + ticked.worldMs,
-    },
-    count - 1,
-  )
-}
-
-// NOTE: what the frame looks like once its ticks ran: particles, the
-// walking dust, callouts, and the juice, all from the frame's events and
-// the cosmetic stream, so they never touch the World.
-const advanceCosmetics = (
-  model: Model,
-  frameMs: number,
-  worldMs: number,
-): Model =>
-  advanceJuice(
-    advanceCallouts(
-      worldMs > 0
-        ? advanceParticles(model, worldMs / MS_PER_SECOND, worldMs)
-        : model,
-      worldMs,
-    ),
-    frameMs,
-    worldMs,
-  )
-
-// NOTE: a frame runs the whole ticks its time owes and carries the rest,
-// then makes its cosmetics. Its `frameEvents` are every tick's events in
-// order, so the cosmetics, sounds, stats, and lessons see each one.
-export const advanceGame = (model: Model, deltaTime: number): Model => {
-  const frameMs = clampFrameDelta(deltaTime)
-  const ticks = ticksIn(model.stepCarryMs + frameMs)
-  const stepped = runTicks(
-    {
-      model: modifyFields(model, {
-        stepCarryMs: () => ticks.carryMs,
-        frameEvents: () => [],
-      }),
-      events: [],
-      worldMs: 0,
-    },
-    ticks.count,
-  )
-  return advanceCosmetics(
-    modifyFields(stepped.model, { frameEvents: () => stepped.events }),
-    frameMs,
-    stepped.worldMs,
-  )
+  return { model: stopForHits(stepped, thaw.worldMs), worldMs: thaw.worldMs }
 }

src/update/exit.ts

@@ -11,7 +11,7 @@ import { releaseAll } from '../input'
 import { Message } from '../message'
 import { type ExitId, type Model, ShopState } from '../model'
 import { burstCoins, smashBoards } from '../particles'
-import { refreshIntent } from '../simulation'
+import { refreshIntent } from '../frame'
 import { playSounds, uiCue } from './sound'
 import { type UpdateReturn, type UpdateStep, withInput } from './step'
 

src/update/shop.ts

@@ -28,7 +28,7 @@ import {
   shopItem,
   stockTag,
 } from '../shop'
-import { refreshIntent } from '../simulation'
+import { refreshIntent } from '../frame'
 import { closeExit } from './exit'
 import { type SoundCue, playSounds, uiCue } from './sound'
 import { type UpdateReturn, type UpdateStep, withInput } from './step'

src/update/step.ts

@@ -4,7 +4,7 @@ import { modifyFields } from 'foldkit/struct'
 import type { AppServices } from '../commands'
 import type { Message } from '../message'
 import type { Input, Model } from '../model'
-import { refreshIntent } from '../simulation'
+import { refreshIntent } from '../frame'
 
 export type UpdateReturn = Update.Return<Model, Message, AppServices>
 export type UpdateStep = Update.Step<Model, Message, AppServices>