diff --git a/.agents/skills/puppetcontrol/SKILL.md b/.agents/skills/puppetcontrol/SKILL.md index 181de8f..3a50f0b 100644 --- a/.agents/skills/puppetcontrol/SKILL.md +++ b/.agents/skills/puppetcontrol/SKILL.md @@ -14,14 +14,15 @@ Read repo-root AGENTS.md, docs/TECHNICAL_CONCEPT.md, and docs/CHARACTER_IMPORT.m 5. Stage the proposal using `node dist/cli/index.js character landmarks stage --proposal `. Rev2D validates the isolated candidate and returns a work/overlay.png. **Actually inspect the overlay** before `character landmarks accept --candidate --reviewed`. Accepting replaces avatar.json with a backup and revokes all existing pose approvals. Never auto-pass --reviewed solely because a validator passed. 6. Build using node dist/cli/index.js character build (use --force if prior output exists). Inspect any geometryWarnings, particularly BODY_PIVOT_TOO_LOW and IRIS_LANDMARK_MISSING; these do not replace pixel inspection. Source/landmark/model/texture hashes are recorded in avatar-build.json and scene preflight rejects stale assets. Inspect every returned review/poses.png, turn.png, eyes.png and mouth.png. If incorrect, repair avatar.json and rebuild using --force; this resets the generated manifest and any edited scaffold. 7. To test optional drawn eye/mouth variants on a built actor, request edit masks, locally supply reviewed `variants/.png`, and explicitly import. With reviewed closed+half eye drawings, `character variants import eyes_closed eyes_half --experimental-short-fade --reviewed-art` shortens fade windows but makes poses change faster and may still ghost; it is a visual experiment, never a default or automatic quality fix. The import revokes prior approval and refreshes provenance only after re-rendering review sheets. -8. Before approving a verified imported rig, run `node dist/cli/index.js character qa blink ` to generate an ordered 25-frame actual eyelid transition contact sheet (`blink-eyes.png` and `blink-full.png`); inspect EyeOpen=0.19 and 0.69 and the real eye artwork seams. The QA report flags motion stalls but never passes visual approval. -9. A successful build intentionally leaves character.json with approved:false. A --force rebuild revokes approval *before* writing model/texture files, even if the rebuild later fails. Only after actual visual QA may an agent/user explicitly run `node dist/cli/index.js character approve --reviewed` (the flag is an acknowledgement, not evidence of review) to record neutral-pose approval. If there are torn eyelids, missing areas, extra contours or identity drift, LEAVE IT UNAPPROVED and report what needs correction. -10. For a reviewed reusable rig, use `node dist/cli/index.js scene new --character --seconds 12 --fps 15` to create a strict editable scene. Reuse the same character file in a second scene without rebuilding artwork. The generated preview-scene.json is also editable. Use node dist/cli/index.js scene validate and scene plan before rendering. Preview PNG frames, inspect key timestamps, then render and inspect the MP4. -11. Within a compatible shared rig, semantic pose events may interpolate through validated parameter presets (the neutral-to-pointing demo uses shoulder and elbow controls). Distinct pose models require explicit scene camera cuts; an authored bridge is NOT implemented. Never silently crossfade meshes or call a body cut a smooth physical transition. -12. For speech, prepare WAV, install Rhubarb separately, and use node dist/cli/index.js audio align --out [--binary ]. For exact-byte continuity, optionally run `audio bind --cues --out ` and include `--binding ` in `scene new`; bound scenes fail validation/render if cue or voice bytes change. A `scene new` voice track requires both `--voice` and the actual `--cues` file; no fabricated speech sync. Reference audio.path, audio.startMs and audio.cuesPath from the scene; review the actual mouth/audio timing. -13. Do not commit private character illustrations, full generated models, user voice recordings or secrets without checking redistribution rights. Demo:avatar generates pinned MIT-licensed sample artwork into ignored .cache. -14. For animation QA, compare real ordered PNGs with `node dist/cli/index.js character qa sequence ... [--region x,y,w,h] [--control-values v0,v1,...] [--cut-after i,j]`. Supply sampled control values when investigating invisible or stalled motion; label known cuts. Inspect the PNGs/video and report possible ghosting even if the motion statistics look normal. The QA report is not an approval. -15. Verified imported rigs and explicitly bound voice tracks are now consumed from fresh per-render copies, hashed against recorded inputs; see `docs/RENDER_INTEGRITY.md`. This is not protection against a malicious same-user process modifying temporary files, nor proof of visual quality. -16. State what actually rendered and which controls remain unsupported. Do not claim a flat PNG is automatically converted into production-quality animation without landmark review. +8. For a deliberately non-blended eye-art experiment, `character variants import eyes_closed eyes_half --experimental-stepped-eyes --reviewed-art` selects only one complete eye appearance outside tiny threshold windows. It can remove ghosted doubled lashes but creates visible pose pops; do not call it seamless or automatically approve. See `docs/EYE_TRANSITIONS.md` and compare actual frames. +9. Before approving a verified imported rig, run `node dist/cli/index.js character qa blink ` to generate an ordered 25-frame actual eyelid transition contact sheet (`blink-eyes.png` and `blink-full.png`); inspect EyeOpen=0.19 and 0.69 and the real eye artwork seams. The QA report flags motion stalls but never passes visual approval. +10. A successful build intentionally leaves character.json with approved:false. A --force rebuild revokes approval *before* writing model/texture files, even if the rebuild later fails. Only after actual visual QA may an agent/user explicitly run `node dist/cli/index.js character approve --reviewed` (the flag is an acknowledgement, not evidence of review) to record neutral-pose approval. If there are torn eyelids, missing areas, extra contours or identity drift, LEAVE IT UNAPPROVED and report what needs correction. +11. For a reviewed reusable rig, use `node dist/cli/index.js scene new --character --seconds 12 --fps 15` to create a strict editable scene. Reuse the same character file in a second scene without rebuilding artwork. The generated preview-scene.json is also editable. Use node dist/cli/index.js scene validate and scene plan before rendering. Preview PNG frames, inspect key timestamps, then render and inspect the MP4. +12. Within a compatible shared rig, semantic pose events may interpolate through validated parameter presets (the neutral-to-pointing demo uses shoulder and elbow controls). Distinct pose models require explicit scene camera cuts; an authored bridge is NOT implemented. Never silently crossfade meshes or call a body cut a smooth physical transition. +13. For speech, prepare WAV, install Rhubarb separately, and use node dist/cli/index.js audio align --out [--binary ]. For exact-byte continuity, optionally run `audio bind --cues --out ` and include `--binding ` in `scene new`; bound scenes fail validation/render if cue or voice bytes change. A `scene new` voice track requires both `--voice` and the actual `--cues` file; no fabricated speech sync. Reference audio.path, audio.startMs and audio.cuesPath from the scene; review the actual mouth/audio timing. +14. Do not commit private character illustrations, full generated models, user voice recordings or secrets without checking redistribution rights. Demo:avatar generates pinned MIT-licensed sample artwork into ignored .cache. +15. For animation QA, compare real ordered PNGs with `node dist/cli/index.js character qa sequence ... [--region x,y,w,h] [--control-values v0,v1,...] [--cut-after i,j]`. Supply sampled control values when investigating invisible or stalled motion; label known cuts. Inspect the PNGs/video and report possible ghosting even if the motion statistics look normal. The QA report is not an approval. +16. Verified imported rigs and explicitly bound voice tracks are now consumed from fresh per-render copies, hashed against recorded inputs; see `docs/RENDER_INTEGRITY.md`. This is not protection against a malicious same-user process modifying temporary files, nor proof of visual quality. +17. State what actually rendered and which controls remain unsupported. Do not claim a flat PNG is automatically converted into production-quality animation without landmark review. Keep edits small and testable. Run npm run verify and inspect visual evidence for any animation/asset changes. \ No newline at end of file diff --git a/README.md b/README.md index 0f93553..e347a08 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ The long-term goal: **generate artwork when necessary, animate and reuse it inde - Guarded **local drawn eye/mouth variant** request, status and import commands using Rev2D masks and sprites. Imported drawings revoke approval and require a fresh visual review; no image generation happens automatically. - An optional **experimental** short-fade profile for imported half/closed eye drawings; avoids prolonged duplicate lash outlines at the cost of faster pose changes, revokes approval and regenerates review sheets. - Local PNG pixel and ordered-frame QA (full frame or explicit region) reports RGB activity, unexpected transparency, candidate motion jumps and changed-control stalls; these metrics never auto-approve a rig. -- Import review can now render a 25-frame blink contact sheet focused on the actual eyelid transition boundaries, with pixel/motion diagnostics that never auto-approve a rig; see [Character Review](docs/CHARACTER_REVIEW.md). +- Import review can now render a 25-frame blink contact sheet focused on actual eyelid transition boundaries, with pixel/motion diagnostics that never auto-approve a rig; see [Character Review](docs/CHARACTER_REVIEW.md). An optional [stepped-eye visibility experiment](docs/EYE_TRANSITIONS.md) eliminates sampled double-sprite ghosting on one MIT sample but introduces noticeable pose switching; it is not a seamless eyelid morph. - Imported flat-image actors start with narrower editable head/gaze motion limits, with consistent vertical look direction and unchanged amplitude for existing layered rigs; see [Look Motion](docs/LOOK_MOTION.md). - Optional SHA-256 Rhubarb cue bindings can detect when audio or mouth-cue bytes are replaced after alignment; a bound scene fails validation/render instead of silently using stale lip sync. - Agent-readable CLI output, tests and CI. diff --git a/docs/CHARACTER_REVIEW.md b/docs/CHARACTER_REVIEW.md index 95f22fc..2f585c1 100644 --- a/docs/CHARACTER_REVIEW.md +++ b/docs/CHARACTER_REVIEW.md @@ -37,7 +37,13 @@ An **optional** short-fade experiment can reduce double contours by narrowing sp node dist/cli/index.js character variants import avatars/portrait eyes_closed eyes_half --experimental-short-fade --reviewed-art ~~~ -Both paths revoke any earlier approval and generate new review sheets and fingerprints. +Another **opt-in, sharp-switch** experiment avoids showing two eyelid drawings simultaneously. It removes the sampled translucent/double-lash effect in the Hana trial, but **introduces abrupt eye-pose jumps** and is *not* a smooth blink: + +~~~powershell +node dist/cli/index.js character variants import avatars/portrait eyes_closed eyes_half --experimental-stepped-eyes --reviewed-art +~~~ + +Choose **only one** experimental profile. Every import revokes earlier approval, regenerates review sheets and refreshes fingerprints. See [EYE_TRANSITIONS.md](EYE_TRANSITIONS.md) for the actual rendered comparison and trade-offs. ## 3. Inspect exact blink transition frames diff --git a/docs/EYE_TRANSITIONS.md b/docs/EYE_TRANSITIONS.md new file mode 100644 index 0000000..13604f5 --- /dev/null +++ b/docs/EYE_TRANSITIONS.md @@ -0,0 +1,70 @@ +# Experimental eye transitions: real visual comparison + +**Status:** opt-in mitigation, not a production-quality blink solution. +**Sample:** locally imported, MIT-licensed RevStudio/Rev2D Hana art (see [third-party notices](THIRD_PARTY_NOTICES.md)). +**Date:** 2026-11-07. + +## Why a shorter fade still ghosted + +The imported Rev2D eye rig has an open mesh plus separately drawn half-closed and fully closed sprites. The earlier short-fade experiment still made two complete, **misaligned eye drawings simultaneously translucent**: + +- Closed → half at `EyeOpen=0.18–0.20`. +- Half → open mesh at `EyeOpen=0.68–0.70`. + +Blending two different lash geometries yields duplicate contours, see-through eyes and pale iris fragments. Narrowing the fade merely shortens the duration of this artifact. + +## Opt-in stepped-eye profile + +`--experimental-stepped-eyes` replaces just those opacity controls with near-instant, complementary visibility switches: + +| EyeOpen parameter | Visible eye appearance | +|---|---| +| Below 0.195 | Closed drawing | +| 0.195 to below 0.69 | Half-closed drawing | +| At/above 0.69 | Original open mesh | + +A tiny `0.0001`-wide ramp is used instead of duplicate key coordinates because Rev2D requires well-defined interpolation keys. All other rig parameters, meshes, textures, expressions and mouth controls remain unchanged. The transformer accepts only the previously validated Rev2D two-eye sprite topology; unfamiliar rig bindings are rejected. + +**This stops the sampled double-image opacity problem, but it is *not smooth geometry morphing*.** The entire eye appearance can pop at either switch. Use only when that tradeoff actually looks better for the character and intended blink speed. + +To use it with **reviewed, user-provided** full-canvas half/closed drawings: + +~~~powershell +node dist/cli/index.js character variants import avatars/portrait eyes_closed eyes_half --experimental-stepped-eyes --reviewed-art +node dist/cli/index.js character qa blink avatars/portrait +~~~ + +Only one experimental profile is permitted; `--experimental-short-fade` and `--experimental-stepped-eyes` cannot be combined. The import revokes prior character approval, rebuilds the review images and refreshes provenance hashes. The program never grants approval or claims that a character has been visually reviewed. + +## Observed comparison + +![MIT-licensed derived Hana crop: old short fade (top) and new stepped profile (bottom) at four EyeOpen values](media/stepped-eye-before-after.png) + +*Source: actual Rev2D rendered pixels at identical `EyeOpen` values and identical source illustration. Top row: short fade. Bottom row: stepped. The original Hana asset is MIT-licensed (RevStudio).* + +In the local test the unapproved experimental Hana character's **translucent double lashes at 0.69** and **ghosted irises at 0.19** were absent in the matched stepped renders. The prior half-open and closed drawings still have a visibly stiff, imperfect outline. + +The same 25-frame, 13-real-render plus mirrored opening review sequence gave: + +| Pixel QA diagnostic | Short fade | Stepped | +|---|---:|---:| +| Possible abrupt changes | 0 | 4 | +| Possible changed-control motion stalls | 10 | 12 | + +The stepped profile deliberately creates jumps; the automated warning is expected and **should not be suppressed or relabeled as an artistic pass**. The stalled intervals reflect static sprite holds (some intentional). Neither diagnostic alone assesses visual acceptability. + +A separate **mesh-only** experiment—no replacement eye sprites, continuously deforming the original mesh—had fewer opacity artifacts, but noticeably squeezed/distorted the eyelids and irises near full closure. That was not selected. + +The full locally ignored A/B sequence video is: + +`outputs/qa/eye-profile-comparison-20261107/ordered-blink-comparison.mp4` + +This is a **non-uniform parameter-sweep review clip** (25 frames at 30 FPS), **not** a natural-timing performance demo. + +A separate disposable, **QA-only** copy of the stepped actor was temporarily marked approved solely for renderer integration testing. It exported a valid 3-second, 15 FPS, 512×640, 45-frame H.264 MP4 via the verified-rig snapshot path. That marker was never applied to the experimental source character. The source remains `approved:false`. + +## Acceptance boundary and next work + +Actual quality requires better curved, consistent eye artwork and/or a continuous eyelid-specific mesh with properly hidden irises. A reversible stepped visibility option is useful for stylized quick blinks, but shouldn't become a default or be described as Live2D-grade deformation. + +Do **not** approve this Hana trial, infer quality from geometry checks, or publish copied test art without preserving the MIT notice. Before approval, inspect the entire blink video, seam/iris/color consistency, gaze extremes, head movement and the surrounding face at target FPS. Compare at least two additional rights-cleared illustration styles. diff --git a/docs/IMPLEMENTATION_PLAN.md b/docs/IMPLEMENTATION_PLAN.md index f1a5bd8..72311be 100644 --- a/docs/IMPLEMENTATION_PLAN.md +++ b/docs/IMPLEMENTATION_PLAN.md @@ -83,6 +83,7 @@ - [x] Wrap local Rev2D drawn eye/mouth variant request/status/import with explicit reviewed-art selection, approval revocation before import, post-import provenance refresh, and new review sheets. A real Hana avatar produced correct edit masks; unchanged fake drawings were rejected. - [x] Test and expose an opt-in, validated short eye-sprite fade as a local derived-model experiment. Compare 13 actual Hana blink frames with native, immediate-switch and shortened fades: shorter fades visibly reduce double lashes at sampled midpoints, but introduce faster pose changes; never auto-approve. - [x] Add bounded per-character semantic head/eye look amplitudes with conservative imported-PNG starting values, schema validation, compiler tests and real Hana ±yaw/pitch/gaze frame comparisons. This does not establish visual approval. +- [x] Test an optional stepped-eye visibility profile that removes sampled double-sprite ghosting at EyeOpen 0.19/0.69 on refined MIT Hana artwork, with a 25-frame A/B render, explicit abrupt-change warnings and local 45-frame end-to-end smoke video. The source remains unapproved; **this trades ghosting for pose popping**, not a seamless morph. - [ ] Produce and visually approve high-quality closed/half eye and mouth artwork; demonstrate seamless real rendered transitions across full blink playback and multiple character styles. The local proof drawing stays unapproved. ## First video milestone — reproducible usable slice (2026-11-07) diff --git a/docs/THIRD_PARTY_NOTICES.md b/docs/THIRD_PARTY_NOTICES.md index 1e9bea9..2f71ee7 100644 --- a/docs/THIRD_PARTY_NOTICES.md +++ b/docs/THIRD_PARTY_NOTICES.md @@ -5,7 +5,7 @@ - Source project: https://github.com/RevStudio/Rev2D - Pinned source commit: f144581cdf1f12d781379c4df90d262b8c2dfa3d - File: examples/hana/hana.r2d.json in Rev2D upstream -- Use: local demo pose-rig generation and attributed sample MP4. PuppetControl's own source code does not bundle Hana's model/artwork. +- Use: local demo pose-rig generation, attributed sample MP4, and the derived eye-transition crop in `docs/media/stepped-eye-before-after.png`. PuppetControl's own source code does not bundle the original full Hana model/artwork. - Original license: MIT License, Copyright (c) 2026 RevStudio. ### MIT License (RevStudio) diff --git a/docs/media/stepped-eye-before-after.png b/docs/media/stepped-eye-before-after.png new file mode 100644 index 0000000..f1f80a2 Binary files /dev/null and b/docs/media/stepped-eye-before-after.png differ diff --git a/src/character/drawn-variants.ts b/src/character/drawn-variants.ts index ba07a9d..611b21d 100644 --- a/src/character/drawn-variants.ts +++ b/src/character/drawn-variants.ts @@ -10,6 +10,7 @@ import { randomUUID } from "node:crypto"; import { dirname, join } from "node:path"; import { characterSchema } from "../scene/schemas.js"; import { shortFadeDrawnEyes } from "./eye-short-fade.js"; +import { steppedDrawnEyes } from "./eye-stepped.js"; import { AvatarWorkflowError, checkedPath, parsePngSize, pinnedRev2D, runRev2D, } from "./avatar.js"; @@ -128,16 +129,18 @@ export async function statusDrawnVariants(projectDir: string, root = process.cwd * The calling import operation revokes visual approval before writing. * Validation and new fingerprints are required after this step. */ -async function applyExperimentalShortFade( +async function applyExperimentalEyeTransition( project: string, modelRelative: string, backend: string, + mode: "short-fade" | "stepped", ) { const modelPath = await checkedPath(project, join(project, modelRelative)); const file = await stat(modelPath); if (!file.isFile() || file.size > MAX_MODEL_BYTES) { - throw new AvatarWorkflowError("EYE_SHORT_FADE_UNSUPPORTED", "Invalid or oversized Rev2D model."); + throw new AvatarWorkflowError("EYE_TRANSITION_UNSUPPORTED", "Invalid or oversized Rev2D model."); } - const transformed = shortFadeDrawnEyes(JSON.parse(await readFile(modelPath, "utf8")) as unknown); - const temporary = join(dirname(modelPath), ".puppetcontrol-shortfade-" + randomUUID() + ".r2d.json"); + const input = JSON.parse(await readFile(modelPath, "utf8")) as unknown; + const transformed = mode === "stepped" ? steppedDrawnEyes(input) : shortFadeDrawnEyes(input); + const temporary = join(dirname(modelPath), ".puppetcontrol-eye-" + mode + "-" + randomUUID() + ".r2d.json"); try { await writeFile(temporary, JSON.stringify(transformed.model), { flag: "wx" }); await runRev2D(backend, ["validate", temporary]); @@ -145,13 +148,18 @@ async function applyExperimentalShortFade( } finally { await unlink(temporary).catch(() => undefined); } - return { profile: "experimental-short-fade" as const, ...transformed.profile, changedBindings: transformed.changedBindings }; + return { profile: mode === "stepped" ? "experimental-stepped-eyes" : "experimental-short-fade", + ...transformed.profile, changedBindings: transformed.changedBindings }; } /** Import reviewed artwork, leave unapproved; preserve stale hashes on a partial failure. */ export async function importDrawnVariants( projectDir: string, requested: readonly string[], root = process.cwd(), - options: { experimentalShortFade?: boolean } = {}, + options: { experimentalShortFade?: boolean; experimentalSteppedEyes?: boolean } = {}, ) { + if (options.experimentalShortFade && options.experimentalSteppedEyes) { + throw new AvatarWorkflowError("EYE_TRANSITION_FLAGS_CONFLICT", + "Choose one experimental eye transition profile, not both."); + } const ids = validateDrawnVariantIds(requested, true); const { project, manifestPath, manifest } = await verifiedImportedAvatar(projectDir, root); const source = await checkedPath(root, join(project, "source.png")); @@ -171,11 +179,12 @@ export async function importDrawnVariants( // IMPORTANT: revoke before Rev2D can touch model, layers or texture files. await revokeAvatarApprovalBeforeBuild(manifestPath); let imported: unknown; - let profile: Awaited> | undefined; + let profile: Awaited> | undefined; try { imported = await runRev2D(backend, ["avatar", "variants", "import", project, ...ids], 240_000); - if (options.experimentalShortFade) { - profile = await applyExperimentalShortFade(project, manifest.render!.modelPath, backend); + if (options.experimentalShortFade || options.experimentalSteppedEyes) { + profile = await applyExperimentalEyeTransition(project, manifest.render!.modelPath, backend, + options.experimentalSteppedEyes ? "stepped" : "short-fade"); } await runRev2D(backend, ["avatar", "poses", project], 240_000); const record = await createAvatarBuildRecord(project, manifest.render!.modelPath); diff --git a/src/character/eye-stepped.ts b/src/character/eye-stepped.ts new file mode 100644 index 0000000..c6e572f --- /dev/null +++ b/src/character/eye-stepped.ts @@ -0,0 +1,80 @@ +/** + * Optional ANIME-STYLE STEPPED transition for an imported Rev2D avatar whose + * half/closed eye sprites were separately drawn and visually reviewed. + * + * Root cause: fading complete eye pictures over the open-eye mesh creates + * visible double lashes and translucent irises when their contours differ. + * This profile selects exactly one of open mesh / half sprite / closed sprite + * at each normal sampled EyeOpen state. It sacrifices continuous blending: + * transitions can visibly pop. This is an experimental mitigation, not a + * claim of seamless or universally good blinking. + * + * The caller must revoke prior pose approval, regenerate review sheets, and + * record fresh source/rig/texture fingerprints before any reuse. + */ +import { shortFadeDrawnEyes } from "./eye-short-fade.js"; + +type Key = { at: number[]; value: number }; +type Binding = { + id: string; + target: string; + params: string[]; + keys: Key[]; +}; + +export const STEPPED_EYE_PROFILE = { + closedToHalf: 0.195, + halfToMesh: 0.69, + /** Tiny finite transition required by Rev2D (duplicate key positions unsupported). */ + stepWidth: 0.0001, + note: "One state visible per sampled control value; sharp switching may pop.", +} as const; + +const keys = (values: readonly (readonly [number, number])[]): Key[] => + values.map(([at, value]) => ({ at: [at], value })); + +function switchOn(threshold: number, width: number): Key[] { + return keys([[0, 0], [threshold - width, 0], [threshold, 1], [1, 1]]); +} + +function switchOff(threshold: number, width: number): Key[] { + return keys([[0, 1], [threshold - width, 1], [threshold, 0], [1, 0]]); +} + +/** + * Pure full-model transform. Reuses all of the short-fade topology checks, + * including both sides, correct param mapping and hide controls. No artwork + * or non-eye binding changes. + */ +export function steppedDrawnEyes(input: unknown): { + model: Record; + changedBindings: string[]; + profile: typeof STEPPED_EYE_PROFILE; +} { + // Validation of supported geometry/topology, not a visual acceptance. + const validated = shortFadeDrawnEyes(input); + const model = validated.model; + const bindings = model.bindings as Binding[]; + const { closedToHalf: c, halfToMesh: h, stepWidth: w } = STEPPED_EYE_PROFILE; + const changed: string[] = []; + + for (const binding of bindings) { + const id = binding.id; + if (id.startsWith("sprite_eyes_closed_") && id.endsWith("Show")) { + binding.keys = switchOff(c, w); + } else if (id.startsWith("sprite_eyes_half_") && id.endsWith("Show")) { + binding.keys = keys([[0, 0], [c - w, 0], [c, 1], [h - w, 1], [h, 0], [1, 0]]); + } else if (validated.changedBindings.includes(id) && id.endsWith("UnderSprite")) { + binding.keys = switchOn(h, w); + } else { + continue; + } + changed.push(id); + } + if (changed.length !== validated.changedBindings.length) { + // The topology validator currently checks these. Keep this additional + // fail-closed check should the pinned Rev2D schema ever change. + throw new Error("Eye sprite topology changed; not all opacity bindings were transformed."); + } + return { model, changedBindings: changed, profile: STEPPED_EYE_PROFILE }; +} diff --git a/src/cli/index.ts b/src/cli/index.ts index 06d75cf..5ef5157 100644 --- a/src/cli/index.ts +++ b/src/cli/index.ts @@ -40,7 +40,7 @@ function usage(): never { " puppetctl character approve --reviewed\n" + " puppetctl character variants request [variant-id ...]\n" + " puppetctl character variants status \n" + - " puppetctl character variants import [--experimental-short-fade] --reviewed-art\n" + + " puppetctl character variants import [--experimental-short-fade|--experimental-stepped-eyes] --reviewed-art\n" + " puppetctl character qa compare [--region x,y,w,h]\n" + " puppetctl character qa blink [--region x,y,w,h]\n" + " puppetctl character qa sequence ... [--region x,y,w,h] [--cut-after i,j] [--control-values v1,v2,...]\n" + @@ -178,10 +178,15 @@ async function run(): Promise { } if (third === "import" && flags.length >= 2 && flags[flags.length - 1] === "--reviewed-art") { const requested = flags.slice(0, -1); - const shortFadeIndex = requested.indexOf("--experimental-short-fade"); - if (shortFadeIndex >= 0 && shortFadeIndex !== requested.length - 1) usage(); - const ids = shortFadeIndex >= 0 ? requested.slice(0, -1) : requested; - print(await importDrawnVariants(project, ids, process.cwd(), { experimentalShortFade: shortFadeIndex >= 0 })); + const optionNames = ["--experimental-short-fade", "--experimental-stepped-eyes"]; + const selectedOptions = requested.filter((arg) => optionNames.includes(arg)); + if (selectedOptions.length > 1 || + (selectedOptions.length === 1 && requested.at(-1) !== selectedOptions[0])) usage(); + const ids = selectedOptions.length ? requested.slice(0, -1) : requested; + print(await importDrawnVariants(project, ids, process.cwd(), { + experimentalShortFade: selectedOptions[0] === "--experimental-short-fade", + experimentalSteppedEyes: selectedOptions[0] === "--experimental-stepped-eyes", + })); return; } usage(); diff --git a/tests/drawn-variants.test.ts b/tests/drawn-variants.test.ts index 641f600..31da9d4 100644 --- a/tests/drawn-variants.test.ts +++ b/tests/drawn-variants.test.ts @@ -56,6 +56,16 @@ describe("local drawn avatar variants", () => { } }); + it("rejects mutually exclusive eye transition modes before touching a previously approved avatar", async () => { + const dir = await fixture(); + await expect(importDrawnVariants(dir, ["eyes_closed", "eyes_half"], dir, { + experimentalShortFade: true, + experimentalSteppedEyes: true, + })).rejects.toMatchObject({ code: "EYE_TRANSITION_FLAGS_CONFLICT" }); + const manifest = JSON.parse(await readFile(join(dir, "character.json"), "utf8")); + expect(manifest.poseFamilies[0].approved).toBe(true); + }); + it("refuses stale imported avatar assets instead of laundering changed model bytes", async () => { const dir = await fixture(); const modelFile = join(dir, "test.r2d.json"); diff --git a/tests/eye-stepped.test.ts b/tests/eye-stepped.test.ts new file mode 100644 index 0000000..dc5f582 --- /dev/null +++ b/tests/eye-stepped.test.ts @@ -0,0 +1,94 @@ +import { describe, expect, it } from "vitest"; +import { steppedDrawnEyes, STEPPED_EYE_PROFILE } from "../src/character/eye-stepped.js"; + +type Key = { at: number[]; value: number }; +type Binding = { id: string; target: string; params: string[]; keys: Key[] }; +const key = (x: number, y: number): Key => ({ at: [x], value: y }); + +function sample(keys: Key[], x: number): number { + for (let i = 1; i < keys.length; i++) { + if (x <= keys[i]!.at[0]!) { + const a = keys[i - 1]!; const b = keys[i]!; + const t = (x - a.at[0]!) / (b.at[0]! - a.at[0]!); + return a.value * (1 - t) + b.value * t; + } + } + return keys[keys.length - 1]!.value; +} +function fixture() { + const bindings: Binding[] = []; + for (const [image, param, suffix] of [ + ["imageLeft", "EyeROpen", "eyeR"], + ["imageRight", "EyeLOpen", "eyeL"], + ]) { + for (const name of ["closed", "half"]) { + const part = "sprite_eyes_" + name + "_" + image; + bindings.push({ + id: part + "Show", target: "part:" + part + ".opacity", + params: [param], keys: [key(0, name === "closed" ? 1 : 0), key(1, 0)], + }); + } + for (const layer of ["white", "ball", "lower", "upper", "crease"]) { + const id = suffix + "_" + layer; + bindings.push({ + id: id + "UnderSprite", target: "part:" + id + ".opacity", + params: [param], keys: [key(0, 0), key(0.7, 1), key(1, 1)], + }); + } + } + const mouth = { id: "mouthForm", params: ["MouthForm"], target: "param:MouthForm", + keys: [key(0, 0), key(1, 1)] }; + return { meta: { width: 512, height: 640 }, bindings: [...bindings, mouth] }; +} + +describe("opt-in stepped Rev2D eye sprite experiment", () => { + it("preserves other controls and source model without mutation", () => { + const model = fixture(); + const original = structuredClone(model); + const result = steppedDrawnEyes(model); + expect(model).toEqual(original); + expect(result.changedBindings).toHaveLength(14); + expect((result.model.bindings as Binding[]).at(-1)).toEqual(original.bindings.at(-1)); + expect(result.profile).toEqual(STEPPED_EYE_PROFILE); + }); + + it("has exactly one opaque eye appearance except in the tiny switch interval", () => { + const model = steppedDrawnEyes(fixture()).model as { bindings: Binding[] }; + for (const image of ["imageLeft", "imageRight"]) { + const closed = model.bindings.find(b => b.id === "sprite_eyes_closed_" + image + "Show")!; + const half = model.bindings.find(b => b.id === "sprite_eyes_half_" + image + "Show")!; + const mesh = model.bindings.find(b => b.id === (image === "imageLeft" + ? "eyeR_whiteUnderSprite" : "eyeL_whiteUnderSprite"))!; + for (const x of [0, 0.05, 0.19, 0.20, 0.35, 0.5, 0.68, 0.70, 0.82, 1]) { + const states = [closed, half, mesh].map(b => sample(b.keys, x)); + expect(states.filter(value => Math.abs(value - 1) < 1e-9)).toHaveLength(1); + expect(states.reduce((sum, value) => sum + value, 0)).toBeCloseTo(1, 7); + } + expect(sample(closed.keys, 0.19)).toBe(1); + expect(sample(half.keys, 0.19)).toBe(0); + expect(sample(half.keys, 0.2)).toBe(1); + expect(sample(half.keys, 0.68)).toBe(1); + expect(sample(mesh.keys, 0.70)).toBe(1); + expect(sample(half.keys, 0.69)).toBe(0); + } + }); + + it("enforces complementary opacity at the exact narrow switch midpoint", () => { + const model = steppedDrawnEyes(fixture()).model as { bindings: Binding[] }; + const find = (id: string) => model.bindings.find(b => b.id === id)!.keys; + const c = STEPPED_EYE_PROFILE.closedToHalf; + const h = STEPPED_EYE_PROFILE.halfToMesh; + const halfWidth = STEPPED_EYE_PROFILE.stepWidth / 2; + expect(sample(find("sprite_eyes_closed_imageLeftShow"), c - halfWidth)).toBeCloseTo(0.5, 6); + expect(sample(find("sprite_eyes_half_imageLeftShow"), c - halfWidth)).toBeCloseTo(0.5, 6); + expect(sample(find("sprite_eyes_half_imageLeftShow"), h - halfWidth)).toBeCloseTo(0.5, 6); + expect(sample(find("eyeR_whiteUnderSprite"), h - halfWidth)).toBeCloseTo(0.5, 6); + }); + + it("rejects missing/unsupported eye topology rather than altering arbitrary rig", () => { + const withoutRight = fixture(); + withoutRight.bindings = withoutRight.bindings.filter(b => + b.id !== "sprite_eyes_half_imageRightShow"); + expect(() => steppedDrawnEyes(withoutRight)).toThrow(/incompatible|variants/); + }); +});