reze-engine 0.69.1 → 0.69.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,3 +1,5 @@
1
+ import { bezierInterpolate } from "./animation"
2
+
1
3
  /**
2
4
  * A material parameter over time.
3
5
  *
@@ -26,10 +28,20 @@
26
28
  /** A parameter value: a scalar, or a vector for the vec3 params. */
27
29
  export type ParamValue = number | [number, number, number]
28
30
 
31
+ /** How the way INTO a key runs: straight, eased in and out, or held at the
32
+ * previous key's value and stepped on arrival. Absent is linear. */
33
+ export type ParamEase = "linear" | "ease" | "hold"
34
+
29
35
  export type ParamKey = {
30
36
  /** Seconds on the SCENE clock — the same clock an export steps. */
31
37
  t: number
32
38
  v: ParamValue
39
+ /** The segment from the previous key to this one — VMD's rule, where a key
40
+ * carries the curve that arrives at it. */
41
+ e?: ParamEase
42
+ /** That segment as a bezier — x1, y1, x2, y2 in 0..1, VMD's own curve — in
43
+ * place of `e` when it is not a hold. */
44
+ b?: [number, number, number, number]
33
45
  }
34
46
 
35
47
  const lerp = (a: number, b: number, k: number): number => a + (b - a) * k
@@ -65,7 +77,15 @@ export function sampleParamTrack(keys: ParamKey[], t: number): ParamValue | null
65
77
  // Two keys at the same instant are a STEP, and the later one wins. Dividing
66
78
  // by the zero span would be a NaN written into a uniform every frame.
67
79
  if (span <= 0) return b.v
68
- const k = (t - a.t) / span
80
+ if (b.e === "hold") return a.v
81
+ const u = (t - a.t) / span
82
+ // Smoothstep: no jump in speed at either key, which is what makes a dial
83
+ // that eases between two values read as a move rather than as a ramp.
84
+ const k = b.b
85
+ ? bezierInterpolate(b.b[0], b.b[2], b.b[1], b.b[3], u)
86
+ : b.e === "ease"
87
+ ? u * u * (3 - 2 * u)
88
+ : u
69
89
  if (typeof a.v === "number" && typeof b.v === "number") return lerp(a.v, b.v, k)
70
90
  // Mixed scalar and vector keys are an authoring mistake, not something to
71
91
  // guess at: hold the segment's start rather than inventing a conversion.
@@ -52,15 +52,35 @@
52
52
  */
53
53
  export type EffectAnchor = { bone: string; trail: boolean; along?: number; step?: number }
54
54
 
55
- /** A knob an effect exposes, for a host to build a control from. */
55
+ /** One choice of an `enum` dial: its id, and a Chinese label after a `|`. */
56
+ export type EffectParamOption = { id: string; labelZh?: string }
57
+
58
+ /**
59
+ * A knob an effect exposes, for a host to build a control from.
60
+ *
61
+ * `bool` and `enum` are one f32 in the shader like `float`: a switch reads 0 or
62
+ * 1, a choice reads its option's index. They differ only in the control a host
63
+ * draws — a switch, a list — which is the whole reason to declare them: a
64
+ * slider from 0 to 3 that means "rain, dots, circuit, grid" is a dial nobody
65
+ * can read.
66
+ *
67
+ * `label`/`labelZh` come from a note written `— English | 中文`. A note without
68
+ * the `|` is only a note, as it always was.
69
+ */
56
70
  export type EffectParamDecl = {
57
71
  name: string
58
- kind: "float" | "color" | "vec3"
59
- /** Numbers for float/vec3; `#rrggbb` for a colour, which the host converts. */
72
+ kind: "float" | "color" | "vec3" | "bool" | "enum" | "int" | "point" | "bone"
73
+ /** Numbers for float/vec3/int/point, 0 or 1 for bool, the option's index for
74
+ * enum, a bone's NAME for bone; `#rrggbb` for a colour, which the host
75
+ * converts. */
60
76
  value: number | [number, number, number] | string
61
- /** float only, and only when the author gave a range. */
77
+ /** float and int only, and only when the author gave a range. */
62
78
  min?: number
63
79
  max?: number
80
+ /** enum only: the choices, in index order. */
81
+ options?: EffectParamOption[]
82
+ label?: string
83
+ labelZh?: string
64
84
  }
65
85
 
66
86
  export type EffectDirectives = {
@@ -196,6 +216,22 @@ const LINE = DIRECTIVE_LINE
196
216
  */
197
217
  export const DIRECTIVE_NOTE = /(?:^|\s)(?:—|--|\/\/|#)\s/
198
218
 
219
+ /** The note after the arguments, or "" — see DIRECTIVE_NOTE. */
220
+ function noteOf(rest: string): string {
221
+ const m = DIRECTIVE_NOTE.exec(rest)
222
+ return m ? rest.slice(m.index + m[0].length).trim() : ""
223
+ }
224
+
225
+ /** A dial's labels from its note, when the note is written `English | 中文`. */
226
+ function labelsOf(rest: string): { label?: string; labelZh?: string } {
227
+ const note = noteOf(rest)
228
+ const bar = note.indexOf("|")
229
+ if (bar < 0) return {}
230
+ const label = note.slice(0, bar).trim()
231
+ const labelZh = note.slice(bar + 1).trim()
232
+ return { ...(label ? { label } : {}), ...(labelZh ? { labelZh } : {}) }
233
+ }
234
+
199
235
  function argsOf(rest: string): string[] {
200
236
  // `^` as well as `\s`: the tag's own trailing space is eaten by LINE, so a
201
237
  // note can begin at the very first character — which is what
@@ -304,12 +340,85 @@ export function parseDirectives(wgsl: string): DirectiveResult {
304
340
  errors.push(`${at}: #param needs a WGSL identifier for a name`)
305
341
  return
306
342
  }
343
+ const labels = labelsOf(m[2])
344
+ if (kind === "bool") {
345
+ const v = rest[0]?.toLowerCase()
346
+ const on = v === "true" || v === "1" || v === "on"
347
+ const off = v === "false" || v === "0" || v === "off"
348
+ if (rest.length !== 1 || (!on && !off)) {
349
+ errors.push(`${at}: #param bool ${name} needs a default, true or false`)
350
+ return
351
+ }
352
+ d.params.push({ name, kind: "bool", value: on ? 1 : 0, ...labels })
353
+ return
354
+ }
355
+ if (kind === "int") {
356
+ // A count: strands, rows, petals. One f32 in the shader like a
357
+ // slider, but whole — the host steps it and a key never lands between.
358
+ const v = num(rest[0])
359
+ if (v === null || !Number.isInteger(v)) {
360
+ errors.push(`${at}: #param int ${name} needs a whole-number default`)
361
+ return
362
+ }
363
+ const lo = num(rest[1])
364
+ const hi = num(rest[2])
365
+ if ((rest[1] !== undefined) !== (rest[2] !== undefined) || (rest[1] !== undefined && (lo === null || hi === null))) {
366
+ errors.push(`${at}: #param int ${name} takes both a min and a max, or neither`)
367
+ return
368
+ }
369
+ d.params.push({ name, kind: "int", value: v, ...(lo !== null && hi !== null ? { min: lo, max: hi } : {}), ...labels })
370
+ return
371
+ }
372
+ if (kind === "point") {
373
+ // A place in the world, in world units — set by dragging it in the
374
+ // scene, and able to follow a character. One vec3f in the shader.
375
+ const v = rest.slice(0, 3).map(num)
376
+ if (rest.length !== 3 || v.some((x) => x === null)) {
377
+ errors.push(`${at}: #param point ${name} needs three numbers, a position like "0 10 0"`)
378
+ return
379
+ }
380
+ d.params.push({ name, kind: "point", value: v as [number, number, number], ...labels })
381
+ return
382
+ }
383
+ if (kind === "bone") {
384
+ // A bone of a character, picked by the host: read as rzBone_NAME(),
385
+ // a position, a forward and whether that rig has it. The default is
386
+ // the bone's name; whose bone it is, the host decides.
387
+ if (rest.length !== 1) {
388
+ errors.push(`${at}: #param bone ${name} needs one bone name, like 右手首`)
389
+ return
390
+ }
391
+ d.params.push({ name, kind: "bone", value: rest[0], ...labels })
392
+ return
393
+ }
394
+ if (kind === "enum") {
395
+ // Each choice is `id` or `id|中文`; a leading `*` marks the default,
396
+ // else the first is.
397
+ const options: EffectParamOption[] = []
398
+ let value = 0
399
+ for (const raw of rest) {
400
+ const star = raw.startsWith("*")
401
+ const [id, zh] = (star ? raw.slice(1) : raw).split("|")
402
+ if (!id) {
403
+ errors.push(`${at}: #param enum ${name} has an empty choice`)
404
+ return
405
+ }
406
+ if (star) value = options.length
407
+ options.push({ id, ...(zh ? { labelZh: zh } : {}) })
408
+ }
409
+ if (options.length < 2) {
410
+ errors.push(`${at}: #param enum ${name} needs at least two choices, like "rain|数字雨 dots|点阵"`)
411
+ return
412
+ }
413
+ d.params.push({ name, kind: "enum", value, options, ...labels })
414
+ return
415
+ }
307
416
  if (kind === "color") {
308
417
  if (!/^#[0-9a-fA-F]{6}$/.test(rest[0] ?? "")) {
309
418
  errors.push(`${at}: #param color ${name} needs a default like #3b82f6`)
310
419
  return
311
420
  }
312
- d.params.push({ name, kind: "color", value: rest[0] })
421
+ d.params.push({ name, kind: "color", value: rest[0], ...labels })
313
422
  return
314
423
  }
315
424
  if (kind === "vec3") {
@@ -318,7 +427,7 @@ export function parseDirectives(wgsl: string): DirectiveResult {
318
427
  errors.push(`${at}: #param vec3 ${name} needs three numbers`)
319
428
  return
320
429
  }
321
- d.params.push({ name, kind: "vec3", value: v as [number, number, number] })
430
+ d.params.push({ name, kind: "vec3", value: v as [number, number, number], ...labels })
322
431
  return
323
432
  }
324
433
  if (kind === "float") {
@@ -335,10 +444,10 @@ export function parseDirectives(wgsl: string): DirectiveResult {
335
444
  errors.push(`${at}: #param float ${name} takes both a min and a max, or neither`)
336
445
  return
337
446
  }
338
- d.params.push({ name, kind: "float", value: v, ...(lo !== null && hi !== null ? { min: lo, max: hi } : {}) })
447
+ d.params.push({ name, kind: "float", value: v, ...(lo !== null && hi !== null ? { min: lo, max: hi } : {}), ...labels })
339
448
  return
340
449
  }
341
- errors.push(`${at}: #param kind must be float, color or vec3`)
450
+ errors.push(`${at}: #param kind must be float, int, color, vec3, point, bone, bool or enum`)
342
451
  return
343
452
  }
344
453
  case "halfres":