Footprints

Install

Please install the @canvasengine/presets package first.

npm install @canvasengine/presets

Then, you can use the presets in your project.

Overview

Footprints adds fading footprints behind moving sprites.

• No footprint image is required: realistic prints are drawn procedurally — boot (treaded sole), shoe, bare foot, paw and hoof.
• Each print has a crisp depression, a softened layer and a raised edge lit from the top-left. A print stays well marked for most of its life (erosionStart), then erodes: the crisp detail goes first and the soft imprint lingers.
• Boot prints show a treaded sole and a separate heel, like real shoe prints.
• Prints point their toe in the walking direction and alternate left / right.
• Footprints are emitted from sprites tagged with footprintCaster.
• You can tune rendering per surface profile (built-in sand, snow, mud, dirt, grass, or custom names).
• No filter runs per print, so hundreds of prints stay cheap.

Basic Usage

<Canvas>
  <Viewport worldWidth={2048} worldHeight={1280} sortableChildren={true}>
    <Footprints
      profiles={surfaceProfiles}
      defaultSurface="sand"
      updateHz={45}
      maxFootprints={320}
    />

    <Sprite
      x={heroX}
      y={heroY}
      controls={heroControls}
      sheet={heroSheet}
      footprintCaster={heroFootprintCaster}
    />
  </Viewport>
</Canvas>

<script>
  import { signal } from 'canvasengine'
  import { Footprints } from '@canvasengine/presets'

  const heroY = signal(840)
  const snowLine = 560

  const heroFootprintCaster = {
    minStepDistance: 16,
    stepIntervalMs: 70,
    leftOffset: { x: -10, y: 2 },
    rightOffset: { x: 10, y: 2 },
    surface: () => (heroY() <= snowLine ? 'snow' : 'sand'),
  }

  const surfaceProfiles = {
    sand: {
      tint: '#7f5d34',
      lifetimeMs: 1800,
      startAlpha: 0.34,
      blurStart: 0.35,
      blurEnd: 1.6,
      erosionStart: 0.62,
      blendMode: 'multiply',
    },
    snow: {
      tint: '#889db6',
      lifetimeMs: 2600,
      startAlpha: 0.26,
      blurStart: 0.62,
      blurEnd: 2.35,
      erosionStart: 0.43,
      blendMode: 'multiply',
    },
  }
</script>

Preset Props

Prop	Type	Default	Description
profiles	Record<string, SurfaceProfile> | Signal<Record> | () => Record	Built-in (default, sand, snow, mud, dirt, grass)	Surface rendering profiles
defaultSurface	string | Signal<string> | () => string	'default'	Fallback profile name
maxFootprints	number | Signal<number> | () => number	260	Maximum active footprints before recycling oldest
updateHz	number | Signal<number> | () => number	30	Recompute/update frequency

SurfaceProfile

Field	Type	Default	Description
lifetimeMs	number	1800	Lifetime before disappearance
startAlpha	number	0.32	Initial opacity
endAlpha	number	0	Final opacity
tint	string | number	0x2d2a26	Footprint tint color
blendMode	string | number	'multiply'	Blend mode used by footprint sprites
scale	number	1	Base scale multiplier
blurStart	number	0.45	Softness of a fresh print
blurEnd	number	1.9	How soft an old print gets (higher = the crisp detail fades faster)
erosionStart	number	0.54	Normalized time (0..1) where erosion starts
depth	number	0.58	Depression intensity (0..1) for center darkening
rimStrength	number	0.14	Strength of the soft raised edge highlight

footprintCaster Options

Attach on each sprite that should leave footprints:

<Sprite
  image="hero.png"
  footprintCaster={{
    minStepDistance: 16,
    minSpeed: 44,
    stepIntervalMs: 70,
    leftOffset: { x: -10, y: 2 },
    rightOffset: { x: 10, y: 2 },
    surface: 'sand',
    size: 0.94,
    alpha: 1,
    blur: 0.1,
    angleOffset: 0,
    jitter: 11,
  }}
/>

Field	Type	Default	Description
enabled	boolean	true	Enable/disable emitter on this sprite
footAnchor	{ x, y }	{ x: 0.5, y: 1 }	Ground anchor inside sprite bounds
leftOffset	{ x, y }	{ x: -10, y: 1 }	Offset for left foot (local walk basis)
rightOffset	{ x, y }	{ x: 10, y: 1 }	Offset for right foot (local walk basis)
minStepDistance	number	18	Distance needed before emitting a new footprint
minSpeed	number	36	Minimum movement speed in px/s required to emit
stepIntervalMs	number	85	Minimum delay between two emissions
size	number	1	Additional footprint size multiplier
alpha	number	1	Opacity multiplier
blur	number	0	Extra blur added to profile blur
surface	string	defaultSurface	Profile name for this caster
angleOffset	number	0	Extra rotation offset in degrees
jitter	number	6	Random rotation variation in degrees
print	'boot' | 'shoe' | 'bare' | 'paw' | 'hoof'	'boot'	Print shape

Prints point their toe in the walking direction. If your art needs the opposite, set angleOffset: 180.

Conditional Rules (Terrain / Zones / X-Y)

You can make all important footprintCaster fields reactive (functions/signals), so emission can change by zone, terrain, or position ranges.

<script>
  const zones = [
    { x1: 860, y1: 760, x2: 1260, y2: 980, surface: 'mud', enabled: true, step: 13 },
    { x1: 1460, y1: 840, x2: 1880, y2: 1100, surface: 'rock', enabled: false, step: 20 },
    { x1: 0, y1: 0, x2: 2048, y2: 560, surface: 'snow', enabled: true, step: 14 },
    { x1: 0, y1: 560, x2: 2048, y2: 1280, surface: 'sand', enabled: true, step: 18 },
  ]

  const inZone = (x, y, z) => x >= z.x1 && x <= z.x2 && y >= z.y1 && y <= z.y2
  const zoneAt = (x, y) => zones.find((z) => inZone(x, y, z)) ?? zones[zones.length - 1]

  const heroFootprintCaster = {
    enabled: () => zoneAt(heroX(), heroY()).enabled,
    surface: () => zoneAt(heroX(), heroY()).surface,
    minStepDistance: () => zoneAt(heroX(), heroY()).step,
  }
</script>

Tuning Tips

• Start with blendMode: 'multiply' for both sand and snow.
• Keep minStepDistance between 14 and 22 for readable spacing.
• In snow, use longer lifetimeMs and larger blurEnd.
• In sand, increase erosionStart so traces break up sooner.