@edv4h/usketch-plugin-character 0.2.0

package/dist/character-sync.js

@@ -0,0 +1,117 @@
+// Multiplayer via Yjs awareness (same model as the avatar plugin): each client
+// publishes its own character under the `character` field; everyone reads the
+// others' fields. Awareness is ephemeral — a client's character disappears when it
+// disconnects — which is exactly the "coexisting live characters" semantics.
+// Typed structurally so the plugin doesn't depend on @edv4h/usketch-sync.
+import { wrapDeg } from "@edv4h/usketch-shared";
+export const AWARENESS_FIELD = "character";
+/** Validate an untrusted awareness payload (other clients can send anything). */
+export function parseWireState(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    const o = v;
+    const num = (k) => typeof o[k] === "number" && Number.isFinite(o[k]) ? o[k] : null;
+    const x = num("x");
+    const y = num("y");
+    const heading = num("heading");
+    if (x === null || y === null || heading === null)
+        return null;
+    const appearance = o.appearance && typeof o.appearance === "object" && !Array.isArray(o.appearance)
+        ? o.appearance
+        : {};
+    return {
+        x,
+        y,
+        heading: wrapDeg(heading),
+        speed: num("speed") ?? 0,
+        moving: o.moving === true,
+        appearance,
+        name: typeof o.name === "string" ? o.name : undefined,
+    };
+}
+/** Minimum interval between broadcasts (≈20 Hz) — remote views interpolate between. */
+export const BROADCAST_INTERVAL_MS = 50;
+export function createCharacterSync(awareness, store, onTargetsChanged, now = () => Date.now()) {
+    let lastSent = Number.NEGATIVE_INFINITY;
+    let lastPayload = null;
+    let targets = new Map();
+    const publish = (force = false) => {
+        const s = store.getState();
+        const t = now();
+        if (!force && t - lastSent < BROADCAST_INTERVAL_MS)
+            return;
+        const wire = s.enabled
+            ? {
+                x: s.pose.x,
+                y: s.pose.y,
+                heading: s.pose.heading,
+                speed: s.pose.speed,
+                moving: s.pose.moving,
+                appearance: s.appearance,
+                name: s.name,
+            }
+            : null;
+        const payload = JSON.stringify(wire);
+        if (payload === lastPayload)
+            return; // idle: don't spam awareness
+        lastPayload = payload;
+        lastSent = t;
+        awareness.setLocalStateField(AWARENESS_FIELD, wire);
+    };
+    const read = () => {
+        const next = new Map();
+        for (const [clientId, st] of awareness.getStates()) {
+            if (clientId === awareness.clientID)
+                continue;
+            const w = parseWireState(st?.[AWARENESS_FIELD]);
+            if (!w)
+                continue;
+            const id = String(clientId);
+            next.set(id, { id, ...w });
+        }
+        targets = next;
+        onTargetsChanged();
+    };
+    awareness.on("change", read);
+    read();
+    return {
+        publish,
+        targets: () => targets,
+        dispose() {
+            awareness.off("change", read);
+            // Withdraw our character so it vanishes for others right away.
+            awareness.setLocalStateField(AWARENESS_FIELD, null);
+        },
+    };
+}
+/**
+ * Ease displayed remote poses toward their latest targets (hides the ~20 Hz
+ * update steps). Returns the next display map and whether anything is still moving.
+ */
+export function easeRemotes(display, targets, alpha) {
+    const next = new Map();
+    let settling = false;
+    for (const [id, t] of targets) {
+        const d = display.get(id);
+        if (!d) {
+            next.set(id, t);
+            continue;
+        }
+        const dx = t.x - d.x;
+        const dy = t.y - d.y;
+        const dh = wrapDeg(t.heading - d.heading);
+        if (Math.abs(dx) < 0.05 && Math.abs(dy) < 0.05 && Math.abs(dh) < 0.05) {
+            next.set(id, t);
+            continue;
+        }
+        settling = true;
+        next.set(id, {
+            ...t,
+            x: d.x + dx * alpha,
+            y: d.y + dy * alpha,
+            heading: wrapDeg(d.heading + dh * alpha),
+        });
+    }
+    return { next, settling };
+}
+//# sourceMappingURL=character-sync.js.map

package/dist/character-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"character-sync.js","sourceRoot":"","sources":["../src/character-sync.ts"],"names":[],"mappings":"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"}

package/dist/character-types.d.ts

@@ -0,0 +1,52 @@
+import type { ReactNode } from "react";
+/** JSON-serializable look data, broadcast so other clients can draw you the same way. */
+export type CharacterAppearance = Record<string, unknown>;
+/** Everything a renderer needs to draw one character at its (already placed) spot. */
+export interface CharacterRenderProps {
+    /** `"self"` for the local character, otherwise the remote client's id. */
+    id: string;
+    isSelf: boolean;
+    /** Facing in the world, degrees (0 = up / -y, clockwise). */
+    heading: number;
+    /**
+     * Apparent facing ON SCREEN = `heading + viewport.rotation`. Rotate a top-down
+     * sprite by this (`transform: rotate(${screenHeading}deg)`); a side-view sprite
+     * might instead flip on its sign.
+     */
+    screenHeading: number;
+    /** Whether the character is moving right now (drive walk cycles etc.). */
+    moving: boolean;
+    /** Signed speed along the heading, world units / s. */
+    speed: number;
+    /** Current viewport zoom (scale the sprite with the world, or not). */
+    zoom: number;
+    /** The owner's broadcast appearance. */
+    appearance: CharacterAppearance;
+    /** The owner's display name, if any. */
+    name?: string;
+}
+/**
+ * Draws one character. The plugin places the returned node centered on the
+ * character's screen position (a zero-size, pointer-transparent wrapper).
+ */
+export type CharacterRenderer = (props: CharacterRenderProps) => ReactNode;
+/** A remote client's character as last received (plus the smoothed display pose). */
+export interface RemoteCharacter {
+    id: string;
+    x: number;
+    y: number;
+    heading: number;
+    speed: number;
+    moving: boolean;
+    appearance: CharacterAppearance;
+    name?: string;
+}
+/** Customizable key bindings: `KeyboardEvent.code` values per direction. */
+export interface CharacterKeys {
+    up: string[];
+    down: string[];
+    left: string[];
+    right: string[];
+}
+export declare const DEFAULT_KEYS: CharacterKeys;
+//# sourceMappingURL=character-types.d.ts.map

package/dist/character-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"character-types.d.ts","sourceRoot":"","sources":["../src/character-types.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,yFAAyF;AACzF,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1D,sFAAsF;AACtF,MAAM,WAAW,oBAAoB;IACpC,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,OAAO,CAAC;IAChB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;IAChB,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,UAAU,EAAE,mBAAmB,CAAC;IAChC,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,oBAAoB,KAAK,SAAS,CAAC;AAE3E,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,mBAAmB,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,eAAO,MAAM,YAAY,EAAE,aAK1B,CAAC"}

package/dist/character-types.js

@@ -0,0 +1,7 @@
+export const DEFAULT_KEYS = {
+    up: ["KeyW"],
+    down: ["KeyS"],
+    left: ["KeyA"],
+    right: ["KeyD"],
+};
+//# sourceMappingURL=character-types.js.map

package/dist/character-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"character-types.js","sourceRoot":"","sources":["../src/character-types.ts"],"names":[],"mappings":"AA0DA,MAAM,CAAC,MAAM,YAAY,GAAkB;IAC1C,EAAE,EAAE,CAAC,MAAM,CAAC;IACZ,IAAI,EAAE,CAAC,MAAM,CAAC;IACd,IAAI,EAAE,CAAC,MAAM,CAAC;IACd,KAAK,EAAE,CAAC,MAAM,CAAC;CACf,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { anchorPx, type CameraFocus, type CameraMode, easeFocus, followViewport, smoothingAlpha, targetRotation, } from "./character-camera.js";
+export { type CharacterPose, type ControlScheme, DEFAULT_MOTION, headingVector, type MotionParams, type MoveInput, stepCharacter, turnToward, vectorHeading, } from "./character-physics.js";
+export { CHARACTER_LAYER_ID, CHARACTER_VIEWPORT_PRIORITY } from "./character-runtime.js";
+export { type CharacterApi, characterService, getCharacterApi, } from "./character-service.js";
+export { AWARENESS_FIELD, type CharacterAwareness, type CharacterWireState, parseWireState, } from "./character-sync.js";
+export { type CharacterAppearance, type CharacterKeys, type CharacterRenderer, type CharacterRenderProps, DEFAULT_KEYS, type RemoteCharacter, } from "./character-types.js";
+export { type CharacterPluginOptions, createCharacterPlugin } from "./plugin.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,QAAQ,EACR,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,SAAS,EACT,cAAc,EACd,cAAc,EACd,cAAc,GACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACN,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,cAAc,EACd,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,aAAa,EACb,UAAU,EACV,aAAa,GACb,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AACzF,OAAO,EACN,KAAK,YAAY,EACjB,gBAAgB,EAChB,eAAe,GACf,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACN,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,cAAc,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,YAAY,EACZ,KAAK,eAAe,GACpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export { anchorPx, easeFocus, followViewport, smoothingAlpha, targetRotation, } from "./character-camera.js";
+export { DEFAULT_MOTION, headingVector, stepCharacter, turnToward, vectorHeading, } from "./character-physics.js";
+export { CHARACTER_LAYER_ID, CHARACTER_VIEWPORT_PRIORITY } from "./character-runtime.js";
+export { characterService, getCharacterApi, } from "./character-service.js";
+export { AWARENESS_FIELD, parseWireState, } from "./character-sync.js";
+export { DEFAULT_KEYS, } from "./character-types.js";
+export { createCharacterPlugin } from "./plugin.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,QAAQ,EAGR,SAAS,EACT,cAAc,EACd,cAAc,EACd,cAAc,GACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAGN,cAAc,EACd,aAAa,EAGb,aAAa,EACb,UAAU,EACV,aAAa,GACb,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AACzF,OAAO,EAEN,gBAAgB,EAChB,eAAe,GACf,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACN,eAAe,EAGf,cAAc,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAKN,YAAY,GAEZ,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAA+B,qBAAqB,EAAE,MAAM,aAAa,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,36 @@
+import type { UsketchPlugin } from "@edv4h/usketch-shared";
+import type { CameraMode } from "./character-camera.js";
+import type { ControlScheme, MotionParams } from "./character-physics.js";
+import type { CharacterAwareness } from "./character-sync.js";
+import { type CharacterAppearance, type CharacterKeys, type CharacterRenderer } from "./character-types.js";
+export interface CharacterPluginOptions {
+    /** Draws a character (self and others). Omitted = headless (nothing drawn). */
+    renderCharacter?: CharacterRenderer;
+    /** Broadcast look data for your character (e.g. `{ color: "#e44" }`). */
+    appearance?: CharacterAppearance;
+    /** Multiplayer: share characters through this provider's awareness. Omitted = solo. */
+    wsProvider?: {
+        awareness: CharacterAwareness;
+    };
+    /** Display name sent with your character. */
+    userName?: string;
+    /** Movement keys as `KeyboardEvent.code` lists (default WASD). */
+    keys?: Partial<CharacterKeys>;
+    /** Start with the character on (default `false`). */
+    enabledInitially?: boolean;
+    /** Default `"fixed"`. */
+    cameraMode?: CameraMode;
+    /** Default `"directional"`. */
+    controlScheme?: ControlScheme;
+    /** Speed / turning / vehicle tuning. */
+    motion?: Partial<MotionParams>;
+    /** Where the character sits on screen, as canvas fractions (default center). */
+    screenAnchor?: {
+        x?: number;
+        y?: number;
+    };
+    /** Follow-camera lag: 0 = rigid (default) … 0.99 = heavy. */
+    followSmoothing?: number;
+}
+export declare function createCharacterPlugin(options?: CharacterPluginOptions): UsketchPlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAiB,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAI1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EAEtB,MAAM,sBAAsB,CAAC;AAG9B,MAAM,WAAW,sBAAsB;IACtC,+EAA+E;IAC/E,eAAe,CAAC,EAAE,iBAAiB,CAAC;IACpC,yEAAyE;IACzE,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,uFAAuF;IACvF,UAAU,CAAC,EAAE;QAAE,SAAS,EAAE,kBAAkB,CAAA;KAAE,CAAC;IAC/C,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAC9B,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,yBAAyB;IACzB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,+BAA+B;IAC/B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,wCAAwC;IACxC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/B,gFAAgF;IAChF,YAAY,CAAC,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,sBAA2B,GAAG,aAAa,CAgCzF"}

package/dist/plugin.js

@@ -0,0 +1,38 @@
+import { setupCharacterRuntime } from "./character-runtime.js";
+import { characterService, createCharacterApi } from "./character-service.js";
+import { createCharacterStore } from "./character-store.js";
+import { DEFAULT_KEYS, } from "./character-types.js";
+import { registerCharacterHud } from "./register-character-hud.js";
+export function createCharacterPlugin(options = {}) {
+    return {
+        id: "usketch-plugin-character",
+        name: "キャラクター",
+        setup(ctx) {
+            const store = createCharacterStore({
+                enabled: options.enabledInitially,
+                cameraMode: options.cameraMode,
+                controlScheme: options.controlScheme,
+                motion: options.motion,
+                anchor: options.screenAnchor,
+                followSmoothing: options.followSmoothing,
+                appearance: options.appearance,
+                name: options.userName,
+                renderer: options.renderCharacter,
+            });
+            const runtime = setupCharacterRuntime(ctx, store, {
+                keys: { ...DEFAULT_KEYS, ...options.keys },
+                awareness: options.wsProvider?.awareness,
+            });
+            const api = createCharacterApi(store, runtime);
+            const stopHud = registerCharacterHud(ctx, api);
+            // Provide the service LAST so a failed earlier step can't leak it.
+            const unprovide = characterService.provide(ctx.services, api);
+            return () => {
+                unprovide();
+                stopHud();
+                runtime.dispose();
+            };
+        },
+    };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,EAIN,YAAY,GACZ,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AA2BnE,MAAM,UAAU,qBAAqB,CAAC,OAAO,GAA2B,EAAE;IACzE,OAAO;QACN,EAAE,EAAE,0BAA0B;QAC9B,IAAI,EAAE,QAAQ;QACd,KAAK,CAAC,GAAkB;YACvB,MAAM,KAAK,GAAG,oBAAoB,CAAC;gBAClC,OAAO,EAAE,OAAO,CAAC,gBAAgB;gBACjC,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,aAAa,EAAE,OAAO,CAAC,aAAa;gBACpC,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,MAAM,EAAE,OAAO,CAAC,YAAY;gBAC5B,eAAe,EAAE,OAAO,CAAC,eAAe;gBACxC,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,IAAI,EAAE,OAAO,CAAC,QAAQ;gBACtB,QAAQ,EAAE,OAAO,CAAC,eAAe;aACjC,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,qBAAqB,CAAC,GAAG,EAAE,KAAK,EAAE;gBACjD,IAAI,EAAE,EAAE,GAAG,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE;gBAC1C,SAAS,EAAE,OAAO,CAAC,UAAU,EAAE,SAAS;aACxC,CAAC,CAAC;YACH,MAAM,GAAG,GAAG,kBAAkB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAC/C,MAAM,OAAO,GAAG,oBAAoB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YAC/C,mEAAmE;YACnE,MAAM,SAAS,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;YAE9D,OAAO,GAAG,EAAE;gBACX,SAAS,EAAE,CAAC;gBACZ,OAAO,EAAE,CAAC;gBACV,OAAO,CAAC,OAAO,EAAE,CAAC;YACnB,CAAC,CAAC;QACH,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/register-character-hud.d.ts

@@ -0,0 +1,4 @@
+import type { PluginContext } from "@edv4h/usketch-shared";
+import type { CharacterApi } from "./character-service.js";
+export declare function registerCharacterHud(ctx: PluginContext, api: CharacterApi): () => void;
+//# sourceMappingURL=register-character-hud.d.ts.map

package/dist/register-character-hud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-character-hud.d.ts","sourceRoot":"","sources":["../src/register-character-hud.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAO3D,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,YAAY,GAAG,MAAM,IAAI,CAmHtF"}

package/dist/register-character-hud.js

@@ -0,0 +1,122 @@
+const CAMERA_MODES = ["fixed", "rotate", "free"];
+const SCHEMES = ["directional", "vehicle"];
+const truthy = (v) => v === true || v === "true";
+export function registerCharacterHud(ctx, api) {
+    const offSettings = ctx.hud.registerSettings({
+        id: "usketch-plugin-character:settings",
+        label: "キャラクター",
+        order: 15,
+        fields: [
+            { name: "enabled", label: "操作キャラ", type: "boolean" },
+            {
+                name: "cameraMode",
+                label: "カメラ",
+                type: "enum",
+                options: [
+                    { value: "fixed", label: "追従（固定）" },
+                    { value: "rotate", label: "追従（向きで回転）" },
+                    { value: "free", label: "追従しない" },
+                ],
+            },
+            {
+                name: "controlScheme",
+                label: "操作方式",
+                type: "enum",
+                options: [
+                    { value: "directional", label: "方向移動" },
+                    { value: "vehicle", label: "車（前進＋旋回）" },
+                ],
+            },
+            { name: "moveSpeed", label: "速度", type: "number", min: 50, max: 3000, step: 50 },
+            { name: "turnRate", label: "旋回(°/秒)", type: "number", min: 30, max: 1080, step: 30 },
+            { name: "anchorX", label: "画面位置 横(%)", type: "number", min: 0, max: 100, step: 5 },
+            { name: "anchorY", label: "画面位置 縦(%)", type: "number", min: 0, max: 100, step: 5 },
+            { name: "smoothing", label: "カメラ遅れ(%)", type: "number", min: 0, max: 95, step: 5 },
+        ],
+        get(name) {
+            const motion = api.getMotion();
+            const anchor = api.getAnchor();
+            switch (name) {
+                case "enabled":
+                    return api.isEnabled();
+                case "cameraMode":
+                    return api.getCameraMode();
+                case "controlScheme":
+                    return api.getControlScheme();
+                case "moveSpeed":
+                    return motion.moveSpeed;
+                case "turnRate":
+                    return motion.turnRate;
+                case "anchorX":
+                    return Math.round(anchor.x * 100);
+                case "anchorY":
+                    return Math.round(anchor.y * 100);
+                case "smoothing":
+                    return Math.round(api.getFollowSmoothing() * 100);
+                default:
+                    return undefined;
+            }
+        },
+        set(name, value) {
+            switch (name) {
+                case "enabled":
+                    if (truthy(value))
+                        api.enable();
+                    else
+                        api.disable();
+                    return;
+                case "cameraMode":
+                    if (CAMERA_MODES.includes(value))
+                        api.setCameraMode(value);
+                    return;
+                case "controlScheme":
+                    if (SCHEMES.includes(value))
+                        api.setControlScheme(value);
+                    return;
+            }
+            const n = Number(value);
+            if (!Number.isFinite(n))
+                return;
+            switch (name) {
+                case "moveSpeed":
+                    api.setMotion({ moveSpeed: n });
+                    break;
+                case "turnRate":
+                    api.setMotion({ turnRate: n });
+                    break;
+                case "anchorX":
+                    api.setAnchor({ x: n / 100 });
+                    break;
+                case "anchorY":
+                    api.setAnchor({ y: n / 100 });
+                    break;
+                case "smoothing":
+                    api.setFollowSmoothing(n / 100);
+                    break;
+            }
+        },
+        subscribe: (listener) => api.onChange(listener),
+    });
+    const offToggle = ctx.actions.register({
+        id: "character:toggle",
+        label: "操作キャラ ON/OFF",
+        group: "キャラクター",
+        order: 1,
+        run: () => api.toggle(),
+        isActive: () => api.isEnabled(),
+    });
+    const offPlace = ctx.actions.register({
+        id: "character:place-at-anchor",
+        label: "キャラを画面位置に配置",
+        group: "キャラクター",
+        order: 2,
+        run: () => api.placeAtAnchor(),
+        isEnabled: () => api.isEnabled(),
+    });
+    return () => {
+        offPlace();
+        offToggle();
+        offSettings();
+    };
+}
+//# sourceMappingURL=register-character-hud.js.map

package/dist/register-character-hud.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-character-hud.js","sourceRoot":"","sources":["../src/register-character-hud.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@edv4h/usketch-plugin-character",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@edv4h/usketch-shared": "4.14.0"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EdV4H/usketch.git",
+    "directory": "plugins/usketch-plugin-character"
+  },
+  "homepage": "https://github.com/EdV4H/usketch#readme",
+  "bugs": {
+    "url": "https://github.com/EdV4H/usketch/issues"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.18",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist"
+  }
+}