281 lines
12 KiB
TypeScript
281 lines
12 KiB
TypeScript
/**
|
|
* @medieval-kit/pitch-torch
|
|
*
|
|
* Pitch torch: a stout stick, pitch-soaked cloth bound onto its end with cord,
|
|
* a flame above. This was exactly the period's lighting — candles were
|
|
* expensive, torches were free.
|
|
*
|
|
* THIRD VERSION. What the earlier ones got wrong, so it is not tried again:
|
|
*
|
|
* - v1 flame tapered base-to-tip on one curve and rendered as a ROCKET NOSE.
|
|
* A flame has a swollen base, a waist, and a torn tip. The waist stays.
|
|
* - v2 head was a barrel widest at mid-height with a FLAT OPEN RIM, and its
|
|
* colourTop was charHot. In render that hot-coloured flat cap read as a
|
|
* stray detached flame-coloured quad lying across the rim. The head is now
|
|
* a teardrop widest in its upper third closing to a faceted dome, and the
|
|
* head carries char colours only. Nothing on the head is flame-coloured.
|
|
* - v2 flame ended its lathe at radius 0.22r with a capped fan, then
|
|
* roughened at 0.30r amplitude. The cap centre and its ring hash
|
|
* differently, which split the tip into a V notch, and the amplitude was
|
|
* enough to fold the waist into a self-intersection. The profile now ends
|
|
* at radius 0 (all tip triangles share one vertex position, so the
|
|
* position hash moves them together and no notch can open) and the
|
|
* amplitude is halved.
|
|
* - v2 had NO BINDING, so the bulb met the shaft as a bare cone point and
|
|
* the object read as a moulded club. The binding band of cord turns is the
|
|
* landmark that names a pitch torch, and it gets a zone about as long as
|
|
* the head, exactly as the reference gives it.
|
|
*
|
|
* The flame flickers via `update()` and the source of that flicker is NOT
|
|
* randomness but a sum of sines of elapsed time: randomness would break
|
|
* determinism, a single sine ticks like a metronome, and a self-driving timer
|
|
* would violate "the consumer owns the loop". The flame also EMITS NO LIGHT;
|
|
* a consumer who wants the torch to light the scene attaches a PointLight to
|
|
* `parts.flame.anchor`.
|
|
*
|
|
* The binding turn count is DERIVED (zone length over cord pitch), not a
|
|
* config integer: the zone fraction is the config surface, and any change to
|
|
* it moves the geometry continuously.
|
|
*/
|
|
import {
|
|
createKitModel,
|
|
createTinter,
|
|
jitter,
|
|
latheGeometry,
|
|
mergeColoured,
|
|
prismGeometry,
|
|
roughenGeometry,
|
|
type Level,
|
|
} from '../core/index.ts'
|
|
|
|
export interface PitchTorchConfig {
|
|
/** Total wood-plus-head length, butt to dome top, excluding flame (metres). */
|
|
readonly length: number
|
|
/** Shaft radius (metres). Near-constant along the shaft; a torch stick is not tapered. */
|
|
readonly radius: number
|
|
/** Length of the pitched head bulb, as a fraction of `length`. */
|
|
readonly wrapLength: number
|
|
/** Length of the cord binding zone, as a fraction of the head length. */
|
|
readonly binding: number
|
|
/** Flame height, as a fraction of the head length. */
|
|
readonly flameHeight: number
|
|
/** Amplitude of the flicker. 0 = steady flame. */
|
|
readonly flicker: number
|
|
readonly seed: number
|
|
}
|
|
|
|
export const pitchTorchDefaults: PitchTorchConfig = {
|
|
// Longer and thicker than v2: the critique measured the shaft at a fifth of
|
|
// the head's width where the reference is nearer a third, and short. The
|
|
// exposed shaft below the binding now comes to about 60% of the total.
|
|
length: 0.72,
|
|
radius: 0.024,
|
|
wrapLength: 0.22,
|
|
binding: 0.8,
|
|
// The flame stays LOWER than the head is long. A pitch torch burns with a
|
|
// low, fat, smoky flame, not a candle's spire.
|
|
flameHeight: 0.78,
|
|
flicker: 1,
|
|
seed: 37,
|
|
}
|
|
|
|
export type PitchTorchParts = 'shaft' | 'wrap' | 'flame'
|
|
|
|
export interface PitchTorchActions {
|
|
/** Lights/extinguishes the flame. When out, the `flame` part is fully hidden. */
|
|
setLit(lit: boolean): void
|
|
isLit(): boolean
|
|
}
|
|
|
|
export function createModel(overrides: Partial<PitchTorchConfig> = {}) {
|
|
// State lives OUTSIDE the build: `configure()` must not put the torch out.
|
|
let lit = true
|
|
let elapsed = 0
|
|
|
|
return createKitModel<PitchTorchConfig, 'oak' | 'char' | 'ember', PitchTorchParts, PitchTorchActions>({
|
|
id: 'pitch-torch',
|
|
defaults: pitchTorchDefaults,
|
|
slots: ['oak', 'char', 'ember'],
|
|
|
|
build: ({ config, random }) => {
|
|
const tint = createTinter(random)
|
|
const r = Math.max(config.radius, 0.004) // floored: derived divisions below
|
|
const half = config.length / 2
|
|
// Head bulb zone, then the cord binding zone immediately below it.
|
|
const headLength = Math.max(config.length * config.wrapLength, r * 3)
|
|
const headBase = half - headLength
|
|
const bindingLength = Math.max(headLength * config.binding, r * 2)
|
|
const bindingBase = headBase - bindingLength
|
|
|
|
// --- Shaft -----------------------------------------------------------
|
|
// Near-constant diameter with only a whisper of waver: a torch stick is
|
|
// a straight-cut stave, not a tapering tool handle. The butt closes with
|
|
// a short chamfer so the end reads slightly rounded, and the top ends
|
|
// INSIDE the bulb.
|
|
const shaftTop = headBase + headLength * 0.35
|
|
const shaftLevels: Level[] = [
|
|
{ y: -half, radius: r * 0.58 },
|
|
{ y: -half + 0.016, radius: r * (0.96 + jitter(random, 0.03)) },
|
|
]
|
|
const waverSteps = 4
|
|
for (let i = 1; i <= waverSteps; i += 1) {
|
|
const t = i / waverSteps
|
|
shaftLevels.push({
|
|
y: (-half + 0.016) + (shaftTop - (-half + 0.016)) * t,
|
|
radius: r * (1 + jitter(random, 0.05)) * (i === waverSteps ? 0.92 : 1),
|
|
})
|
|
}
|
|
const shaft = mergeColoured([latheGeometry(
|
|
shaftLevels, 7, [0, 0, 0], tint('oak', -0.06),
|
|
{ colourTop: tint('oak', 0.02) },
|
|
)])
|
|
|
|
// --- Binding + head --------------------------------------------------
|
|
// The binding: a stack of cord turns proud of the shaft by about a third
|
|
// of its radius. One wavy lathe rather than stacked rings, so no pair of
|
|
// coincident faces forms where turns touch. Turn count is derived from
|
|
// the zone length over a cord pitch tied to the shaft radius; the
|
|
// defaults give seven turns.
|
|
const pitch = r * 0.75
|
|
const turns = Math.min(12, Math.max(3, Math.round(bindingLength / pitch)))
|
|
const turnPitch = bindingLength / turns
|
|
const grooveR = r * 1.14
|
|
const bindingLevels: Level[] = [{ y: bindingBase, radius: grooveR }]
|
|
for (let k = 0; k < turns; k += 1) {
|
|
bindingLevels.push({
|
|
y: bindingBase + (k + 0.5) * turnPitch,
|
|
radius: r * (1.4 + jitter(random, 0.03)),
|
|
})
|
|
bindingLevels.push({
|
|
y: bindingBase + (k + 1) * turnPitch,
|
|
radius: grooveR * (1 + jitter(random, 0.015)),
|
|
})
|
|
}
|
|
// Soot creeps down the cord from the head, so the top of the binding
|
|
// lerps darker. Both tints are separate Colors (createTinter allocates).
|
|
const binding = latheGeometry(
|
|
bindingLevels, 8, [0, 0, 0], tint('leather', 0.02),
|
|
{ colourTop: tint('leather', -0.13) },
|
|
)
|
|
|
|
// Two loose cord ends angling off the binding: fat end buried inside a
|
|
// crest of the binding solid, thin tip dangling free like a lashing's
|
|
// cut end. Built at the origin along Y, rotated, then translated; the
|
|
// final rotateY swings each around the torch axis so they are not both
|
|
// on the same side.
|
|
const cordEnds = [
|
|
{ tilt: Math.PI + 0.22, len: bindingLength * 0.42, crest: turns - 2.5, swing: 0.6 },
|
|
{ tilt: Math.PI + 0.35, len: bindingLength * 0.34, crest: 2.5, swing: 3.9 },
|
|
].map(({ tilt, len, crest, swing }) => {
|
|
const cord = prismGeometry(r * 0.17, r * 0.06, len, 5, [0, 0, 0], tint('leather', -0.04))
|
|
cord.rotateZ(tilt)
|
|
// Where the fat (local bottom) end lands after the rotation, so it can
|
|
// be pinned to a crest of the binding.
|
|
const fatX = (len / 2) * Math.sin(tilt)
|
|
const fatY = -(len / 2) * Math.cos(tilt)
|
|
const anchorY = bindingBase + Math.min(Math.max(crest, 0.5), turns - 0.5) * turnPitch
|
|
cord.translate(r * 1.18 - fatX, anchorY - fatY, 0)
|
|
cord.rotateY(swing)
|
|
return cord
|
|
})
|
|
|
|
// The head: pitch-soaked rags bound into a teardrop, widest in its
|
|
// upper third, closing to a faceted dome. Its lowest level hides inside
|
|
// the binding's top turn, so the taper terminates in cord, not on bare
|
|
// shaft. The char slot is used because pitch gets coated in soot — an
|
|
// oak colour would be a lie here. No flame colour anywhere on the head.
|
|
const lump = () => 1 + jitter(random, 0.04)
|
|
const bulbLevels: Level[] = [
|
|
{ y: headBase - turnPitch * 0.6, radius: r * 1.1 },
|
|
{ y: headBase + headLength * 0.1, radius: r * 1.9 * lump() },
|
|
{ y: headBase + headLength * 0.3, radius: r * 2.5 * lump() },
|
|
{ y: headBase + headLength * 0.55, radius: r * 2.9 * lump() },
|
|
{ y: headBase + headLength * 0.7, radius: r * 3.0 },
|
|
{ y: headBase + headLength * 0.82, radius: r * 2.75 * lump() },
|
|
{ y: headBase + headLength * 0.92, radius: r * 2.15 * lump() },
|
|
{ y: headBase + headLength * 0.985, radius: r * 1.15 },
|
|
{ y: half, radius: r * 0.55 },
|
|
]
|
|
const bulb = latheGeometry(
|
|
bulbLevels, 8, [0, 0, 0], tint('char', 0.05),
|
|
{ colourTop: tint('char', 0.14) },
|
|
)
|
|
const wrap = mergeColoured([binding, ...cordEnds, bulb])
|
|
|
|
// --- Flame -----------------------------------------------------------
|
|
// Built at ITS OWN origin; the anchor sits just inside the dome. This is
|
|
// required because the flicker drives the anchor's scale: a flame whose
|
|
// origin is not at its base would sink into the wrap when scaled. The
|
|
// base ring is buried well inside the dome so the roughen displacement
|
|
// can never push it out into view.
|
|
const flameH = Math.max(headLength * config.flameHeight, 0.02)
|
|
const flameProfile: Level[] = [
|
|
{ y: 0, radius: r * 1.7 },
|
|
{ y: flameH * 0.15, radius: r * 2.35 },
|
|
{ y: flameH * 0.38, radius: r * 1.95 },
|
|
{ y: flameH * 0.55, radius: r * 2.05 },
|
|
{ y: flameH * 0.75, radius: r * 1.3 },
|
|
{ y: flameH * 0.9, radius: r * 0.7 },
|
|
{ y: flameH, radius: 0 }, // closes to a single shared point: no tip notch
|
|
]
|
|
const outer = latheGeometry(flameProfile, 7, [0, 0, 0], tint('ember', 0.04, 0.4),
|
|
{ colourTop: tint('emberTip', 0, 0.4), capBottom: true })
|
|
roughenGeometry(outer, r * 0.16, { salt: 7, scaleY: 1.25 })
|
|
|
|
const flame = mergeColoured([
|
|
outer,
|
|
// Inner core: smaller and whiter. Two layers give the flame depth — a
|
|
// single cone reads flat. Its base is NOT CAPPED: a cap was coplanar
|
|
// with the outer base and z-fought, and it is invisible anyway.
|
|
prismGeometry(
|
|
r * 1.1, r * 0.1, flameH * 0.5, 5,
|
|
[0, flameH * 0.32, 0], tint('ember', 0.22, 0.3),
|
|
{ capBottom: false },
|
|
),
|
|
])
|
|
|
|
return {
|
|
shaft: { slot: 'oak' as const, geometry: shaft },
|
|
wrap: { slot: 'char' as const, geometry: wrap },
|
|
flame: {
|
|
slot: 'ember' as const,
|
|
geometry: flame,
|
|
origin: [0, half - headLength * 0.1, 0] as const,
|
|
},
|
|
}
|
|
},
|
|
|
|
actions: ({ parts }) => {
|
|
parts.flame.anchor.visible = lit
|
|
return {
|
|
setLit: (next) => { lit = next; parts.flame.anchor.visible = next },
|
|
isLit: () => lit,
|
|
}
|
|
},
|
|
|
|
update: (dt, { parts, getConfig }) => {
|
|
// An extinguished torch does not advance: so that when it is relit the
|
|
// flame resumes from the same phase point rather than wherever it drifted
|
|
// to. Otherwise a torch left out for a long time would start at an
|
|
// arbitrary size when lit.
|
|
if (!lit) return
|
|
const config = getConfig()
|
|
const amount = config.flicker
|
|
if (amount === 0) return
|
|
elapsed += Math.max(0, dt)
|
|
|
|
// Incommensurate frequencies: 11.3 and 19.7 are not multiples of each
|
|
// other, so the period of the sum is too long for the eye to catch.
|
|
const pulse = Math.sin(elapsed * 11.3) * 0.09 + Math.sin(elapsed * 19.7 + 1.4) * 0.055
|
|
const sway = Math.sin(elapsed * 7.1 + 0.6) * 0.05 + Math.sin(elapsed * 13.9) * 0.028
|
|
|
|
const anchor = parts.flame.anchor
|
|
// Height and width move in OPPOSITE directions: a flame narrows as it
|
|
// stretches. Scaling them the same way made the flame look like a
|
|
// breathing balloon.
|
|
anchor.scale.set(1 - pulse * 0.55 * amount, 1 + pulse * amount, 1 - pulse * 0.55 * amount)
|
|
anchor.rotation.z = sway * amount
|
|
anchor.rotation.x = Math.sin(elapsed * 9.4 + 2.1) * 0.038 * amount
|
|
},
|
|
}, overrides)
|
|
}
|