dsh-pet-live2d-viola 1.0.0

package/lib/index.js

@@ -0,0 +1,591 @@
+/**
+ * dsh-pet-live2d-viola — a Live2D desktop pet for the DSH web GUI.
+ *
+ * Host half. Owns everything that must outlive one browser tab: the persisted
+ * layout, the session-activity bridge that drives the pet's reactions, and the
+ * HTTP surfaces (model assets + a small JSON API) the browser polls.
+ *
+ * The client half is `lib/client.js`, served by the client-module loader as the
+ * package's `./client` export. The Live2D runtime itself is
+ * `lib/client.live2d.js`, a package-local chunk the client requests with
+ * `require.async("./client.live2d.js")`; the loader serves it from
+ * `/plugins/dsh-pet-live2d-viola/` so no host route is needed for it.
+ *
+ * @module dsh-pet-live2d-viola
+ */
+
+import z from "schemastery";
+import { Service } from "@deepseek-ai/cordis";
+import { mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { PetMachine, PHASES } from "./machine.js";
+import {
+	CHARACTERS_DIR,
+	CROP_PRESETS,
+	DEFAULT_CROP,
+	DEFAULT_MODEL,
+	DEFAULT_PET_NAME,
+	LAYOUT_LIMITS,
+	emptyPersist,
+	loadPersist,
+	normalizeLayout,
+	petHomeDir,
+	savePersist
+} from "./persist.js";
+import { makePetRoutes } from "./routes.js";
+
+export { PHASES, PetMachine } from "./machine.js";
+export {
+	CHARACTERS_DIR,
+	CROP_PRESETS,
+	DEFAULT_CROP,
+	DEFAULT_LAYOUT,
+	DEFAULT_MODEL,
+	DEFAULT_PET_NAME,
+	LAYOUT_LIMITS,
+	normalizeLayout
+} from "./persist.js";
+export { PET_API_PREFIX, PET_ASSET_PREFIX } from "./routes.js";
+
+/** Display name of the character shown on a fresh install. */
+export const DEFAULT_MODEL_NAME = DEFAULT_MODEL;
+/**
+ * Directory (relative to the package root) holding one subdirectory per character.
+ *
+ * The plugin ships two models and switches between them from the menu, so they live in a tree keyed by
+ * character id rather than in one fixed directory.
+ */
+export const MODELS_DIR = CHARACTERS_DIR;
+/**
+ * Directory (relative to the package root) holding the bundled voice clips.
+ *
+ * Kept OUT of the model directory on purpose: the model is addressed as
+ * `/pet-live2d-viola/assets/<settingsFile>`, so the asset root has to be the model directory itself.
+ */
+export const VOICE_DIR = join("assets", "voice");
+/**
+ * The click sound's directory.
+ *
+ * Its own tree rather than a file inside the voice directory: the voice clips are the character's spoken
+ * lines and are addressed one-per-phase, while this is a UI sound in a different format (`.mp3`). Keeping
+ * them apart means "the voice directory" keeps meaning one thing.
+ */
+export const CLICK_DIR = join("assets", "click");
+/** Extensions that make up one Cubism model tree, for asset allow-listing. */
+export const MODEL_FILE_PATTERN = /\.(model3\.json|moc3|physics3\.json|pose3\.json|cdi3\.json|motion3\.json|exp3\.json|userdata3\.json|png|webp|jpe?g|mp3|wav|ogg|txt)$/i;
+
+/**
+ * Motion pools per character, by phase name.
+ *
+ * A pool is the set of motions a phase may drift through at random. It is per character because the entries
+ * name motion groups that exist in one model and not the other: 都子's idle pool is her everyday motions plus
+ * all six plush poses, while 薇欧拉 has no plush and no drift chosen for her yet.
+ *
+ * An EMPTY pool is a supported state — the drift becomes a no-op — which is what lets a character be added
+ * with its model and its menu before its choreography is decided.
+ */
+export const CHARACTER_PHASES = {
+	miyako: {
+		idle: {
+			idleMotions: [
+				"mtn_idle01_C",
+				"mtn_idle02_C",
+				"mtn_look01_C",
+				"mtn_look02_C",
+				"mtn_mal_smile01_C",
+				"mtn_mal_happy01_C",
+				"mtn_mal_angry01_C",
+				"mtn_mal_cry01_C",
+				"mtn_mal_bye01_C",
+				"mtn_mal_rampage01_C"
+			]
+		},
+		working: {
+			randomMotions: ["mtn_serious01_C", "mtn_nod01_C", "mtn_smile01_C"],
+			idleMotions: ["mtn_serious01_C", "mtn_nod01_C", "mtn_smile01_C"]
+		}
+	},
+	viola: {
+		idle: {
+			idleMotions: ["mtn_idle01_C", "mtn_look01_C", "mtn_smile01_C"]
+		},
+		working: { randomMotions: [], idleMotions: [] }
+	},
+	/*
+	 * 薇欧拉's school uniform: a different MODEL with the same content, so it needs the same pools.
+	 *
+	 * Written out rather than shared by reference with the entry above. The two are separate models, and this is
+	 * the place their choreography would diverge if it ever should.
+	 */
+	viola_school: {
+		idle: {
+			idleMotions: ["mtn_idle01_C", "mtn_look01_C", "mtn_smile01_C"]
+		},
+		working: { randomMotions: [], idleMotions: [] }
+	}
+};
+
+/*
+ * There is deliberately no label derivation here.
+ *
+ * An earlier version tried to recover a character name from the settings file name, and it produced
+ * `sub_viola_casual_spring` for 薇欧拉's casual outfit — the game's file names put the variant in the middle of the
+ * identifier, so the short name cannot be recovered from them. The browser's own table names every model this
+ * build ships, and it falls back to the id for one it does not; a second, worse source of the same information is
+ * what made the menu show a file name.
+ */
+
+/** Absolute package root, resolved from this module's own location (lib/). */
+export function petPackageRoot(importMetaUrl) {
+	return fileURLToPath(new URL("../", importMetaUrl));
+}
+
+/**
+ * Read the model's own manifest and report what it can play, so the browser
+ * never has to guess motion or expression names.
+ * @param modelDir - absolute directory of one model tree.
+ * @returns motion groups, expressions and the settings file name.
+ */
+export function readModelManifest(modelDir) {
+	const entries = readdirSync(modelDir);
+	const settingsFile = entries.find((name) => name.endsWith(".model3.json"));
+	if (settingsFile === undefined) throw new Error(`no .model3.json in ${modelDir}`);
+	const settings = JSON.parse(readFileSync(join(modelDir, settingsFile), "utf8"));
+	const motions = Object.keys(settings.FileReferences?.Motions ?? {});
+	const expressions = (settings.FileReferences?.Expressions ?? [])
+		.map((entry) => entry?.Name)
+		.filter((name) => typeof name === "string" && name !== "");
+	const groups = (settings.Groups ?? [])
+		.filter((group) => group?.Target === "Parameter" && Array.isArray(group.Ids))
+		.map((group) => ({ name: group.Name, ids: group.Ids }));
+	return { settingsFile, motions, expressions, groups };
+}
+
+/**
+ * Discover the characters this package ships.
+ *
+ * One subdirectory per character, identified by its folder name, and only those that actually contain a
+ * `.model3.json` count — a stray directory (a leftover extraction, an empty folder) is skipped rather than
+ * offered in the menu as an entry that cannot load.
+ *
+ * The display labels live in the browser, next to the rest of the user-facing copy, so this stays about
+ * what exists on disk.
+ *
+ * @param dir - absolute path of the characters directory.
+ * @returns `[{ id }]`, sorted by id so the menu order is stable across platforms.
+ */
+export function discoverCharacters(dir) {
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const found = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		try {
+			if (readdirSync(join(dir, entry.name)).some((name) => name.endsWith(".model3.json"))) {
+				found.push({ id: entry.name });
+			}
+		} catch {
+			// An unreadable directory is not a character.
+		}
+	}
+	return found.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * The pet service: persisted layout + the session-driven state machine.
+ *
+ * Events only ever touch in-memory state; the file is written when the user
+ * moves/renames the pet or the plugin config changes.
+ */
+export class PetLive2DService extends Service {
+	/** Hard dependency: the browser HTTP carrier that serves assets and the API. */
+	static inject = ["webServer"];
+
+	constructor(ctx, config = {}) {
+		/*
+		 * The service name is namespaced, and that is load-bearing rather than tidiness.
+		 *
+		 * cordis refuses a service name that is already registered, and the standalone 都子 plugin registers
+		 * `petLive2d`. While both packages were installed, this plugin therefore FAILED TO LOAD — the whole pet,
+		 * not just a feature — and the symptom was simply that the character never appeared, with nothing on
+		 * screen pointing at the cause.
+		 */
+		super(ctx, "petLive2dViola");
+		this.packageRoot = config.packageRoot ?? petPackageRoot(import.meta.url);
+		this.charactersDir = join(this.packageRoot, MODELS_DIR);
+		/*
+		 * Every character the package ships, discovered from disk rather than listed in code: adding a model
+		 * is then a directory copy, and a character whose tree is missing simply does not appear in the menu
+		 * instead of becoming a broken entry.
+		 */
+		this.characters = discoverCharacters(this.charactersDir);
+		this.manifests = new Map();
+		this.voiceDir = join(this.packageRoot, VOICE_DIR);
+		this.clickDir = join(this.packageRoot, CLICK_DIR);
+		this.stateDir = config.stateDir ?? petHomeDir(process.env, homedir());
+		this.stateFile = join(this.stateDir, "pet-live2d-viola.json");
+		this.disabled = config.enabled === false;
+		this.affinity = config.affinity === true;
+
+		const loaded = loadPersist(readFileSync, this.stateFile);
+		this.record = loaded ?? emptyPersist();
+		/*
+		 * The stored character is validated HERE, against what is actually on disk. `loadPersist` carries the
+		 * id through as a plain string because it must stay filesystem-free, so a character that has since
+		 * been removed would otherwise leave the pet pointing at a missing model.
+		 */
+		const wanted = config.character ?? this.record.character ?? DEFAULT_MODEL;
+		this.modelName = this.characters.some((c) => c.id === wanted)
+			? wanted
+			: (this.characters.find((c) => c.id === DEFAULT_MODEL)?.id ?? this.characters[0]?.id ?? DEFAULT_MODEL);
+		this.record.character = this.modelName;
+		this.modelDir = join(this.charactersDir, this.modelName);
+		this.manifest = config.manifest ?? this.manifestFor(this.modelName);
+
+		this.machine = new PetMachine(config.timing ?? {});
+		this.applyConfig(config);
+		this.syncActivity();
+	}
+
+	/**
+	 * The model manifest for one character, read once and kept.
+	 *
+	 * Cached because the menu asks for every character's motions and expressions, and re-reading and
+	 * re-parsing each `model3.json` on every state poll would be wasted work for a file that cannot change
+	 * while the process runs.
+	 */
+	manifestFor(id) {
+		const cached = this.manifests.get(id);
+		if (cached !== undefined) return cached;
+		const manifest = readModelManifest(join(this.charactersDir, id));
+		this.manifests.set(id, manifest);
+		return manifest;
+	}
+
+	/**
+	 * Switch to another character.
+	 *
+	 * Re-points the asset tree as well as the manifest: the model and its textures, motions and expressions are
+	 * addressed relative to `/pet-live2d-viola/assets/`, so that route has to be re-registered against the new
+	 * directory or the browser would keep loading the previous model's files.
+	 *
+	 * @returns true when the active character changed.
+	 */
+	setCharacter(id) {
+		if (typeof id !== "string" || !this.characters.some((c) => c.id === id)) return false;
+		if (id === this.modelName) return false;
+		this.modelName = id;
+		this.record.character = id;
+		this.modelDir = join(this.charactersDir, id);
+		this.manifest = this.manifestFor(id);
+		this.syncRoutes();
+		this.flush();
+		return true;
+	}
+
+	/** The characters the menu may offer, with the active one marked. */
+	charactersView() {
+		return {
+			active: this.modelName,
+			available: this.characters.map((character) => ({
+				id: character.id,
+				// The asset sub-path the browser adds to PET_ASSET_PREFIX to reach this model.
+				path: character.id,
+				motions: this.manifestFor(character.id).motions,
+				expressions: this.manifestFor(character.id).expressions
+				/*
+				 * No display label: the browser has a localized name for every model this build knows, and a
+				 * derived one cannot compete — the game's file names do not contain the character name in a form
+				 * that can be recovered, so `sub_viola`'s variants came out as `sub_viola_casual_spring`. The id
+				 * is the browser's fallback for a model it has no translation for, which is the honest outcome.
+				 */
+			}))
+		};
+	}
+
+	/** The model tree the browser should load. */
+	manifestView() {
+		return {
+			name: this.modelName,
+			settings: this.manifest.settingsFile,
+			motions: this.manifest.motions,
+			expressions: this.manifest.expressions,
+			groups: this.manifest.groups
+		};
+	}
+
+	/** Current layout (defensive copy). */
+	layout() {
+		return { ...this.record.layout };
+	}
+
+	/** Current pet name. */
+	petName() {
+		return this.record.name;
+	}
+
+	/**
+	 * The full snapshot the browser polls: machine state, layout, the model
+	 * manifest it needs to load the model, and the animation binding table.
+	 */
+	view() {
+		const state = this.machine.view();
+		const definition = PHASES[state.phase] ?? PHASES.idle;
+		const pool = CHARACTER_PHASES[this.modelName]?.[state.phase] ?? {};
+		return {
+			ok: true,
+			enabled: !this.disabled,
+			name: this.record.name,
+			model: this.manifestView(),
+			/**
+			 * Every character the menu can switch to, plus which one is active.
+			 *
+			 * Sent in the same snapshot as the active model's manifest so the client can build the whole menu
+			 * — including the labels for characters that are not loaded — without a second request.
+			 */
+			characters: this.charactersView(),
+			layout: { ...this.record.layout },
+			phase: state.phase,
+			revision: state.revision,
+			bubble: state.bubble,
+			holding: state.holding,
+			sessions: state.sessions,
+			/**
+			 * What to play on entering a phase, and the motions it drifts through at random
+			 * while the phase lasts. The client mirrors this table. No expression: her face
+			 * changes only when one is picked from the menu.
+			 *
+			 * `randomMotions`, when present, is a set the client picks ONE entry motion from instead
+			 * of always playing `motion`. It exists because a transient phase can be shorter than the
+			 * drift interval, which left the drift set unreachable and made every completion identical.
+			 */
+			animation: {
+				motion: definition.motion,
+				randomMotions: pool.randomMotions ?? definition.randomMotions,
+				idleMotions: pool.idleMotions ?? definition.idleMotions
+			}
+		};
+	}
+
+	/**
+	 * The whole phase -> animation table, for diagnostics and for the harness that verifies
+	 * every phase's clips actually play. `view()` only exposes the current phase, which is all
+	 * the browser needs but not enough to check the other five.
+	 */
+	phaseTable(character = this.modelName) {
+		const out = {};
+		for (const [name, definition] of Object.entries(PHASES)) {
+			// The shared table supplies the entry motion and the bubble; this character's pools override the
+			// drift sets, which are the part that names motions the other model may not have.
+			const override = CHARACTER_PHASES[character]?.[name] ?? {};
+			out[name] = {
+				motion: definition.motion,
+				// Mirrors view(): the set the client picks one entry motion from, when there is one.
+				randomMotions: override.randomMotions ?? definition.randomMotions,
+				idleMotions: override.idleMotions ?? definition.idleMotions,
+				bubble: definition.bubble
+			};
+		}
+		return out;
+	}
+
+	/**
+	 * Replace the layout with a validated patch.
+	 *
+	 * A `character` key in the SAME patch switches the active model. It rides on this route rather than
+	 * getting its own because the menu treats "which character" as one more piece of the pet's appearance,
+	 * and the browser already posts here for every other change of that kind — so a switch costs one request
+	 * and the reply carries the new manifest.
+	 */
+	setLayout(patch) {
+		const changed = patch !== null && typeof patch === "object" && typeof patch.character === "string"
+			? this.setCharacter(patch.character)
+			: false;
+		this.record = { ...this.record, layout: normalizeLayout(patch, this.record.layout) };
+		if (!changed) this.flush();
+		return {
+			ok: true,
+			characterChanged: changed,
+			character: this.modelName,
+			model: this.manifestView(),
+			characters: this.charactersView(),
+			layout: this.layout()
+		};
+	}
+
+	/** Rename the pet (trimmed, 1–24 characters). */
+	setName(name) {
+		const trimmed = typeof name === "string" ? name.trim() : "";
+		if (trimmed === "") return { ok: false, error: "name-empty" };
+		if (trimmed.length > 24) return { ok: false, error: "name-too-long" };
+		this.record = { ...this.record, name: trimmed };
+		this.flush();
+		return { ok: true, name: trimmed };
+	}
+
+	/**
+	 * Accept a client-side interaction report. `revision` lets the browser hand
+	 * back the state it acted on, so a stale report cannot rewind a newer phase.
+	 */
+	reportClientEvent(body) {
+		const kind = body?.kind;
+		if (kind !== "pat" && kind !== "poke") return { ok: false, error: "invalid-kind" };
+		this.machine.enter(kind === "pat" ? "listening" : "done", Date.now(), { holdMs: 1200, force: true });
+		return { ok: true };
+	}
+
+	/**
+	 * Apply the plugin Config. Only fields the config actually sets are applied,
+	 * so an unset field keeps whatever the pet's own UI last stored.
+	 */
+	applyConfig(config) {
+		if (typeof config.name === "string" && config.name.trim() !== "") {
+			this.record = { ...this.record, name: config.name.trim().slice(0, 24) };
+		}
+		this.record = { ...this.record, layout: normalizeLayout(config, this.record.layout) };
+		if (typeof config.enabled === "boolean") {
+			this.disabled = !config.enabled;
+			this.syncActivity();
+		}
+		this.flush();
+	}
+
+	/** Start or stop the session listeners and the asset/API routes. */
+	setEnabled(enabled) {
+		this.disabled = !enabled;
+		this.syncActivity();
+		this.syncRoutes();
+	}
+
+	/**
+	 * (Re)bind the session-activity listeners. One listener reduces every host
+	 * session event to a phase transition; `activity/status` is kept as a
+	 * compatibility path for the original working-activity protocol.
+	 */
+	syncActivity() {
+		this.disposeActivity?.();
+		this.disposeActivity = undefined;
+		if (this.disabled) return;
+		const disposers = [
+			this.ctx.on("session/event", (session, event) => {
+				this.machine.onSessionActive(session?.id);
+				this.machine.onSessionEvent(event);
+			}),
+			this.ctx.on("session/disposed", (session) => {
+				this.machine.onSessionDisposed(session?.id);
+			}),
+			this.ctx.on("app-boot/config-reload", () => {
+				// A config edit replaces this service; drop the stale timer.
+				this.machine.clearSettle();
+			})
+		];
+		this.disposeActivity = () => {
+			for (const dispose of disposers) dispose();
+		};
+	}
+
+	/**
+	 * Register the asset + API routes (idempotent).
+	 *
+	 * The asset root is the CHARACTERS DIRECTORY, not the active character's folder, and the browser addresses a
+	 * model as `<prefix>/<character>/<settings file>`. That keeps every character's textures on distinct URLs,
+	 * which is required: both models name their textures identically, PIXI caches textures globally by URL, and
+	 * a flat path made the second model reuse the first one's atlas — it drew as a patchwork figure.
+	 *
+	 * Re-registering on every switch is therefore no longer necessary for correctness, but the call is kept so
+	 * the route is rebuilt after a config change.
+	 */
+	syncRoutes() {
+		this.disposeRoutes?.();
+		this.disposeRoutes = undefined;
+		if (this.disabled) return;
+		const routes = makePetRoutes({ pet: this, assetRoot: this.charactersDir, voiceRoot: this.voiceDir, clickRoot: this.clickDir });
+		const disposers = routes.map((route) => this.ctx.webServer.register(route));
+		this.disposeRoutes = () => {
+			for (const dispose of disposers) dispose();
+		};
+	}
+
+	/**
+	 * Write the record to disk, tolerating a read-only home.
+	 *
+	 * `mkdirSync` is wrapped rather than passed directly, because it takes its options as the SECOND argument while the
+	 * persistence port calls `mkdir(dir, { recursive })`. Passing the raw function meant the option was dropped, the
+	 * create failed with ENOENT on a fresh install, `savePersist` swallowed the error and returned false, and — since
+	 * no caller checks the return value — the pet's settings were never written at all.
+	 */
+	flush() {
+		const mkdir = (dir) => mkdirSync(dir, { recursive: true });
+		savePersist({ mkdir, writeFile: writeFileSync, rename: renameSync }, this.stateFile, this.stateDir, this.record);
+	}
+
+	/** Release timers and routes. */
+	dispose() {
+		this.disposeActivity?.();
+		this.disposeRoutes?.();
+		this.machine.dispose();
+	}
+}
+
+/** Stable cordis plugin name (matches the cordis.patch.yml insert id). */
+export const name = "pet-live2d-viola";
+
+/** Services required before the pet can mount its surfaces. */
+export const inject = ["webServer"];
+
+/**
+ * Plugin config: dsh renders this schema as the plugin's settings form. Every
+ * layout field is optional on purpose — an unset field leaves whatever the
+ * pet's own UI last stored, so editing one field never resets the others.
+ */
+export const Config = z.object({
+	enabled: z.boolean().default(true).description("挂载桌宠。关闭后不注册路由与界面。"),
+	model: z.string().default(DEFAULT_MODEL).description("默认角色（assets/characters/ 下的目录名）。菜单里可以随时切换。"),
+	visible: z.boolean().description("上线 / 下线。"),
+	height: z.number().step(1).min(LAYOUT_LIMITS.height.min).max(LAYOUT_LIMITS.height.max).description("桌宠高度（px）。"),
+	right: z.number().step(1).min(LAYOUT_LIMITS.inset.min).max(LAYOUT_LIMITS.inset.max).description("距视口右边缘（px）。"),
+	bottom: z.number().step(1).min(LAYOUT_LIMITS.inset.min).max(LAYOUT_LIMITS.inset.max).description("距视口下边缘（px）。"),
+	locked: z.boolean().description("锁定位置与缩放。"),
+	scale: z.number().step(0.05).min(LAYOUT_LIMITS.scale.min).max(LAYOUT_LIMITS.scale.max).description("模型缩放倍率。"),
+	opacity: z.number().step(0.05).min(LAYOUT_LIMITS.opacity.min).max(LAYOUT_LIMITS.opacity.max).description("不透明度。"),
+	crop: z.union([
+		z.const("full").description("全身（默认，不会切到人物）"),
+		z.const("threeQuarter").description("四分之三身（含手持玩偶）"),
+		z.const("bust").description("半身特写（头肩）")
+	]).description("取景范围：显示人物的多少。"),
+	showFrame: z.boolean().description("显示取景框边界（虚线，仅作视觉参考，不影响拖动与缩放）。"),
+	blink: z.boolean().description("自动眨眼。"),
+	gaze: z.boolean().description("视线与头部追随鼠标。"),
+	voiceVolume: z.number().step(0.1).min(LAYOUT_LIMITS.voiceVolume.min).max(LAYOUT_LIMITS.voiceVolume.max)
+		.description("语音音量，0 为静音（也可在桌宠菜单的「设置 → 语音音量」里调整）。"),
+	name: z.string().min(1).max(24).description("桌宠显示名。")
+});
+
+/**
+ * Mount the pet: build the service, then register its routes. The service owns
+ * the route lifetime so `enabled: false` really removes them.
+ *
+ * A failure here is reported rather than left to propagate silently. When this plugin failed to mount because
+ * its service name clashed with another pet's, the only symptom was that no character appeared — no message, no
+ * broken panel, nothing to search for. Logging the reason is what turns that into a one-line diagnosis.
+ */
+export function apply(ctx, config = {}) {
+	try {
+		const service = new PetLive2DService(ctx, config);
+		service.syncRoutes();
+		ctx.effect(() => () => service.dispose(), "pet-live2d-viola: service");
+		return service;
+	} catch (error) {
+		if (typeof console !== "undefined" && typeof console.error === "function") {
+			console.error("[pet-live2d-viola] failed to mount:", error);
+		}
+		throw error;
+	}
+}