reze-engine 0.69.9 → 0.70.0

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.
@@ -0,0 +1,281 @@
1
+ // The camera on a bone: her own eyes (POV), or a phone in her hand (selfie).
2
+ //
3
+ // A third way to hold the camera, beside the orbit and the follow. The follow
4
+ // moves the point the orbit turns about and leaves the orbit's own angle and
5
+ // distance to the person at the mouse; a mount places the EYE and the LOOK from
6
+ // the rig itself, every frame, so the shot is hers.
7
+ //
8
+ // Stepped by the engine after the pose and physics, before the camera uniforms
9
+ // (as the follow is), so it never trails her by a frame and an export renders
10
+ // what the editor showed. A camera VMD or setCameraPose still wins: they are
11
+ // scene data and an explicit host statement about where the camera IS.
12
+
13
+ import { Vec3 } from "./math"
14
+ import { Quat } from "./math"
15
+ import type { Model } from "./model"
16
+
17
+ export type CameraMountMode = "pov" | "selfie"
18
+
19
+ /** What setCameraMount asks for. */
20
+ export interface CameraMountOptions {
21
+ /** "pov": through her eyes, turning with her head. "selfie": held in her
22
+ * hand, aimed back at her face. */
23
+ mode: CameraMountMode
24
+ /** The bone the camera rides. POV 頭 (the head), selfie 右手首 (a wrist). */
25
+ bone?: string
26
+ /** Seconds the camera's turn trails the bone, eased (POV 0.12, selfie 0.25):
27
+ * a dance's head snaps read as a jolt without it. 0 is rigid. */
28
+ smoothing?: number
29
+ /** POV: keep the horizon level, dropping the head's tilt. Default true. */
30
+ level?: boolean
31
+ /** Selfie: how far from her face the phone is held at full stretch, model
32
+ * units (an arm's length is about 7). Closer when her hand is. Default 7. */
33
+ distance?: number
34
+ }
35
+
36
+ /** Where the mounted camera is this frame, world space. */
37
+ export interface MountPose {
38
+ eye: Vec3
39
+ forward: Vec3
40
+ up: Vec3
41
+ }
42
+
43
+ /** The bones a face is read from, and the head. */
44
+ const HEAD = "頭"
45
+ const EYES = ["左目", "右目"] as const
46
+ /** POV: how far in front of the eyeballs the lens sits, model units — past the
47
+ * eye's own surface, so nothing of her that is still drawn sits on the lens. */
48
+ const POV_FORWARD = 0.25
49
+ /** Where a rig without eye bones keeps its eyes: up the head bone, model units. */
50
+ const EYES_UP_FALLBACK = 1.1
51
+ /** Selfie: the nearest the phone comes to her face, as a share of `distance`. */
52
+ const SELFIE_MIN = 0.55
53
+ const UP = new Vec3(0, 1, 0)
54
+
55
+ export function resolveMountOptions(o: CameraMountOptions): Required<CameraMountOptions> {
56
+ const pov = o.mode !== "selfie"
57
+ return {
58
+ mode: pov ? "pov" : "selfie",
59
+ bone: o.bone || (pov ? HEAD : "右手首"),
60
+ smoothing: Math.min(2, Math.max(0, o.smoothing ?? (pov ? 0.12 : 0.25))),
61
+ level: o.level ?? true,
62
+ distance: Math.min(40, Math.max(2, o.distance ?? 7)),
63
+ }
64
+ }
65
+
66
+ /** A model-space point placed as the scene has the model (setModelTransform). */
67
+ function toWorld(m: Model, p: Vec3): Vec3 {
68
+ const s = m.scale
69
+ const out = new Vec3(p.x * s, p.y * s, p.z * s)
70
+ Quat.rotateVecInto(m.rotation, out, out)
71
+ out.setXYZ(out.x + m.position.x, out.y + m.position.y, out.z + m.position.z)
72
+ return out
73
+ }
74
+
75
+ /** A model-space direction turned as the model is; unit length. */
76
+ function dirToWorld(m: Model, x: number, y: number, z: number): Vec3 {
77
+ const out = new Vec3(x, y, z)
78
+ Quat.rotateVecInto(m.rotation, out, out)
79
+ const l = Math.hypot(out.x, out.y, out.z) || 1
80
+ out.setXYZ(out.x / l, out.y / l, out.z / l)
81
+ return out
82
+ }
83
+
84
+ /**
85
+ * Turn a unit vector toward another by k of the angle between them (a slerp).
86
+ * Not a straight blend: two opposite vectors blend to nothing, so a half turn
87
+ * — her spinning round — would never start to swing.
88
+ */
89
+ function ease(v: Vec3, to: Vec3, k: number): void {
90
+ if (k >= 1) {
91
+ v.set(to)
92
+ return
93
+ }
94
+ const d = Math.max(-1, Math.min(1, v.x * to.x + v.y * to.y + v.z * to.z))
95
+ const angle = Math.acos(d)
96
+ if (angle < 1e-5) return
97
+ // The axis to turn about: v × to, or for a half turn any axis square to v.
98
+ let ax = v.y * to.z - v.z * to.y
99
+ let ay = v.z * to.x - v.x * to.z
100
+ let az = v.x * to.y - v.y * to.x
101
+ let al = Math.hypot(ax, ay, az)
102
+ if (al < 1e-6) {
103
+ // Up, unless v is itself vertical.
104
+ if (Math.abs(v.y) < 0.9) {
105
+ ax = -v.z
106
+ ay = 0
107
+ az = v.x
108
+ } else {
109
+ ax = 0
110
+ ay = v.z
111
+ az = -v.y
112
+ }
113
+ al = Math.hypot(ax, ay, az)
114
+ }
115
+ ax /= al
116
+ ay /= al
117
+ az /= al
118
+ // Rodrigues: v cos θ + (a × v) sin θ + a (a·v)(1 − cos θ).
119
+ const t = angle * k
120
+ const c = Math.cos(t)
121
+ const s = Math.sin(t)
122
+ const dot = ax * v.x + ay * v.y + az * v.z
123
+ const cx = ay * v.z - az * v.y
124
+ const cy = az * v.x - ax * v.z
125
+ const cz = ax * v.y - ay * v.x
126
+ const x = v.x * c + cx * s + ax * dot * (1 - c)
127
+ const y = v.y * c + cy * s + ay * dot * (1 - c)
128
+ const z = v.z * c + cz * s + az * dot * (1 - c)
129
+ const l = Math.hypot(x, y, z) || 1
130
+ v.setXYZ(x / l, y / l, z / l)
131
+ }
132
+
133
+ /**
134
+ * Between her eyes, world space: the eye bones' midpoint, or up the head bone
135
+ * on a rig without them. Null without a head.
136
+ */
137
+ export function facePoint(m: Model): Vec3 | null {
138
+ const l = m.getBoneWorldPosition(EYES[0])
139
+ const r = m.getBoneWorldPosition(EYES[1])
140
+ if (l && r) return toWorld(m, new Vec3((l.x + r.x) / 2, (l.y + r.y) / 2, (l.z + r.z) / 2))
141
+ const h = m.getBoneWorldMatrix(HEAD)
142
+ if (!h) return null
143
+ const up = new Vec3(h[4], h[5], h[6])
144
+ const ul = Math.hypot(up.x, up.y, up.z) || 1
145
+ return toWorld(m, new Vec3(h[12] + (up.x / ul) * EYES_UP_FALLBACK, h[13] + (up.y / ul) * EYES_UP_FALLBACK, h[14] + (up.z / ul) * EYES_UP_FALLBACK))
146
+ }
147
+
148
+ export class CameraMount {
149
+ options: Required<CameraMountOptions>
150
+ private seeded = false
151
+ private readonly forward = new Vec3(0, 0, -1)
152
+ private readonly up = new Vec3(0, 1, 0)
153
+ /** Selfie: from her face toward the phone, eased. */
154
+ private readonly arm = new Vec3(0, 0, -1)
155
+ private reach = 0
156
+
157
+ constructor(
158
+ readonly model: Model,
159
+ options: CameraMountOptions,
160
+ ) {
161
+ this.options = resolveMountOptions(options)
162
+ }
163
+
164
+ setOptions(options: CameraMountOptions): void {
165
+ const next = resolveMountOptions(options)
166
+ // A new mode or bone starts from where the rig is, not from the old shot.
167
+ if (next.mode !== this.options.mode || next.bone !== this.options.bone) this.seeded = false
168
+ this.options = next
169
+ }
170
+
171
+ /** Snap to the rig on the next step: a seek or a cut is no camera move. */
172
+ reseed(): void {
173
+ this.seeded = false
174
+ }
175
+
176
+ /** This frame's pose, after her pose. Null when the rig lacks the bones. */
177
+ step(dt: number): MountPose | null {
178
+ const o = this.options
179
+ const k = !this.seeded || o.smoothing <= 0 || dt <= 0 ? 1 : 1 - Math.exp(-dt / o.smoothing)
180
+ // A big jump (a seek, a tab come back) is no move to glide through.
181
+ const snap = !this.seeded || dt > 0.25
182
+ return o.mode === "pov" ? this.pov(snap ? 1 : k) : this.selfie(snap ? 1 : k)
183
+ }
184
+
185
+ private pov(k: number): MountPose | null {
186
+ const m = this.model
187
+ const h = m.getBoneWorldMatrix(this.options.bone) ?? m.getBoneWorldMatrix(HEAD)
188
+ if (!h) return null
189
+ const face = this.options.bone === HEAD ? facePoint(m) : toWorld(m, new Vec3(h[12], h[13], h[14]))
190
+ if (!face) return null
191
+ // MMD rests facing −Z: forward is the head's negated third column, up its second.
192
+ const fwd = dirToWorld(m, -h[8], -h[9], -h[10])
193
+ const up = this.options.level && Math.abs(fwd.y) < 0.97 ? UP : dirToWorld(m, h[4], h[5], h[6])
194
+ ease(this.forward, fwd, k)
195
+ ease(this.up, up, k)
196
+ this.seeded = true
197
+ const f = this.forward
198
+ const s = POV_FORWARD * m.scale
199
+ return {
200
+ eye: new Vec3(face.x + f.x * s, face.y + f.y * s, face.z + f.z * s),
201
+ forward: new Vec3(f.x, f.y, f.z),
202
+ up: new Vec3(this.up.x, this.up.y, this.up.z),
203
+ }
204
+ }
205
+
206
+ private selfie(k: number): MountPose | null {
207
+ const m = this.model
208
+ const face = facePoint(m)
209
+ const hand = m.getBoneWorldPosition(this.options.bone)
210
+ if (!face || !hand) return null
211
+ const hw = toWorld(m, hand)
212
+ let ax = hw.x - face.x
213
+ let ay = hw.y - face.y
214
+ let az = hw.z - face.z
215
+ const d = Math.hypot(ax, ay, az)
216
+ if (d < 1e-4) {
217
+ // Hand on the face: hold the direction it last had.
218
+ ax = this.arm.x
219
+ ay = this.arm.y
220
+ az = this.arm.z
221
+ } else {
222
+ ax /= d
223
+ ay /= d
224
+ az /= d
225
+ }
226
+ const full = this.options.distance * m.scale
227
+ const reach = Math.min(full, Math.max(full * SELFIE_MIN, d))
228
+ ease(this.arm, new Vec3(ax, ay, az), k)
229
+ this.reach = this.seeded ? this.reach + (reach - this.reach) * k : reach
230
+ this.seeded = true
231
+ const a = this.arm
232
+ const eye = new Vec3(face.x + a.x * this.reach, face.y + a.y * this.reach, face.z + a.z * this.reach)
233
+ // Aimed back at her face, level: a phone is held upright, not at the wrist's twist.
234
+ const forward = new Vec3(-a.x, -a.y, -a.z)
235
+ const up = Math.abs(forward.y) < 0.97 ? new Vec3(0, 1, 0) : dirToWorld(m, 0, 0, -1)
236
+ return { eye, forward, up }
237
+ }
238
+ }
239
+
240
+ /**
241
+ * The materials that ARE her head — hair, face, eyes, brows — for a POV shot
242
+ * to leave out of the camera (and only the camera: her shadow and her mirror
243
+ * image keep them). A material is hers when most of its skinning weight rides
244
+ * 頭 or a bone under it. Computed once per mount.
245
+ */
246
+ export function headMaterials(m: Model): string[] {
247
+ const bones = m.getSkeleton().bones
248
+ const head = bones.findIndex((b) => b.name === HEAD)
249
+ if (head < 0) return []
250
+ const under = new Uint8Array(bones.length)
251
+ for (let i = 0; i < bones.length; i++) {
252
+ // Walk up to the root; a rig's chain is short.
253
+ for (let b = i, n = 0; b >= 0 && n < 256; b = bones[b].parentIndex, n++) {
254
+ if (b === head) {
255
+ under[i] = 1
256
+ break
257
+ }
258
+ }
259
+ }
260
+ const { joints, weights } = m.getSkinning()
261
+ const indices = m.getIndices()
262
+ const out: string[] = []
263
+ let start = 0
264
+ for (const mat of m.getMaterials()) {
265
+ const count = mat.vertexCount
266
+ let onHead = 0
267
+ let total = 0
268
+ for (let i = start; i < start + count; i++) {
269
+ const v = indices[i]
270
+ for (let j = 0; j < 4; j++) {
271
+ const w = weights[v * 4 + j]
272
+ if (w === 0) continue
273
+ total += w
274
+ if (under[joints[v * 4 + j]]) onHead += w
275
+ }
276
+ }
277
+ start += count
278
+ if (total > 0 && onHead / total > 0.5) out.push(mat.name)
279
+ }
280
+ return out
281
+ }
package/src/camera.ts CHANGED
@@ -219,10 +219,26 @@ export class Camera {
219
219
  * to be left.
220
220
  */
221
221
  getEyePosition(): Vec3 {
222
- return this.vmdDriven ? this.vmdEye() : this.getPosition()
222
+ if (this.vmdDriven) return this.vmdEye()
223
+ const m = this.mountPose
224
+ if (m) return new Vec3(m.eye.x, m.eye.y, m.eye.z)
225
+ return this.getPosition()
223
226
  }
224
227
 
228
+ /**
229
+ * The shot as a bone holds it (Engine.setCameraMount): an eye, a look and an
230
+ * up, set by the engine each frame. Outranks the orbit, not a VMD — the
231
+ * orbit's own alpha/beta/radius stay untouched underneath, so taking the
232
+ * mount off puts back the shot that was there. Null while unmounted.
233
+ */
234
+ mountPose: { eye: Vec3; forward: Vec3; up: Vec3 } | null = null
235
+
225
236
  getViewMatrix(): Mat4 {
237
+ if (!this.vmdDriven && this.mountPose) {
238
+ const { eye, forward: f, up: u } = this.mountPose
239
+ Mat4.lookAtInto(this._viewMat.values, eye.x, eye.y, eye.z, eye.x + f.x, eye.y + f.y, eye.z + f.z, u.x, u.y, u.z)
240
+ return this._viewMat
241
+ }
226
242
  if (this.vmdDriven) {
227
243
  const eye = this.vmdEye()
228
244
  const s = this._quatScratch
@@ -409,6 +425,12 @@ export class Camera {
409
425
  private updateNearFromRadius(): void {
410
426
  const lo = this.reversedZ ? NEAR_MIN_REVERSED : NEAR_MIN_UNORM
411
427
  const hi = this.reversedZ ? NEAR_MAX_REVERSED : NEAR_MAX_UNORM
428
+ // A mounted lens sits at her face or a hand's length from it: the orbit
429
+ // radius says nothing about that, and her own hands come right up to it.
430
+ if (this.mountPose && !this.vmdDriven) {
431
+ this.near = lo
432
+ return
433
+ }
412
434
  this.near = Math.min(hi, Math.max(lo, this.radius / 50))
413
435
  }
414
436
 
@@ -495,7 +517,8 @@ export class Camera {
495
517
  }
496
518
 
497
519
  private onMouseMove(e: MouseEvent) {
498
- if (this.inputLocked || this.vmdDriven) return // VMD owns the camera; orbit/pan is inert
520
+ // A VMD or a mount owns the camera; orbit/pan is inert.
521
+ if (this.inputLocked || this.vmdDriven || this.mountPose) return
499
522
  if (!this.isDragging) return
500
523
 
501
524
  const deltaX = e.clientX - this.lastMousePos.x
@@ -520,7 +543,7 @@ export class Camera {
520
543
 
521
544
  private onWheel(e: WheelEvent) {
522
545
  e.preventDefault()
523
- if (this.vmdDriven) return // VMD owns the camera; zoom is inert
546
+ if (this.vmdDriven || this.mountPose) return // VMD or mount owns the camera; zoom is inert
524
547
 
525
548
  // Update camera radius (zoom)
526
549
  this.radius += e.deltaY * this.wheelPrecision
@@ -572,7 +595,7 @@ export class Camera {
572
595
  // native touch scrolling in every UI panel layered above the canvas.
573
596
  if (!this.isDragging && !this.isPinching) return
574
597
  e.preventDefault()
575
- if (this.vmdDriven) return // VMD owns the camera; pinch/pan/rotate is inert
598
+ if (this.vmdDriven || this.mountPose) return // VMD or mount owns the camera; pinch/pan/rotate is inert
576
599
 
577
600
  if (this.isPinching && e.touches.length === 2) {
578
601
  // Two-finger gesture: can be pinch zoom or pan