@nilvn/core 0.17.0 → 0.17.1

package/dist/chunk-build.js

@@ -113,7 +113,7 @@ export function buildChunkedExport(project, opts) {
         for (const sceneId of chunk.scenes) {
             const scene = byId.get(sceneId);
             for (const n of scene.nodes) {
-                if (n.kind === 'jump')
+                if (n.kind === 'jump' || n.kind === 'call')
                     addEdge(targetSceneId(n.target, sceneIds));
                 else if (n.kind === 'choice')
                     for (const o of n.options)

package/dist/commands.js

@@ -3,7 +3,11 @@
 //
 // Excluded on purpose:
 //  - use / alias / actor  -> project setup (Project.plugins / alias / actors), not nodes
-//  - jump / if / set      -> first-class node kinds (JumpNode / JumpNode+condition / SetNode)
+//  - jump / if / set / call / return -> first-class node kinds (JumpNode / JumpNode+condition / SetNode / CallNode / ReturnNode)
+//  - choices / persist    -> fields of ChoiceNode / VariableDef (serialize.ts emits them)
+/** The scene transitions `[trans]` and `[bg trans=]` know (the engine's TransitionKind). */
+const TRANSITION_OPTIONS = ['fade', 'crossfade', 'wipe', 'slide', 'circle', 'blinds', 'rule'].map((value) => ({ value, label: `cmd.trans.kind.${value}` }));
+const DIR_OPTIONS = ['left', 'right', 'up', 'down'].map((value) => ({ value, label: `cmd.trans.dir.${value}` }));
 export const BUILTIN_COMMANDS = [
     {
         name: 'bg',
@@ -15,6 +19,93 @@ export const BUILTIN_COMMANDS = [
             { key: 'bg', label: 'cmd.bg.bg', type: 'asset:bg', positional: 0 },
             { key: 'color', label: 'cmd.bg.color', type: 'color' },
             { key: 'fade', label: 'cmd.bg.fade', type: 'number', default: 0 },
+            // `trans=` swaps through a scene transition instead of a cross-fade.
+            { key: 'trans', label: 'cmd.bg.trans', type: 'enum', options: TRANSITION_OPTIONS, advanced: true },
+            { key: 'dir', label: 'cmd.trans.dir', type: 'enum', options: DIR_OPTIONS, advanced: true },
+            { key: 'duration', label: 'cmd.trans.duration', type: 'number', advanced: true },
+            { key: 'mask', label: 'cmd.trans.mask', type: 'asset:bg', advanced: true },
+        ],
+    },
+    {
+        name: 'trans',
+        label: 'cmd.trans.label',
+        category: 'fx',
+        icon: '🎞',
+        hint: 'cmd.trans.hint',
+        params: [
+            { key: 'kind', label: 'cmd.trans.kind', type: 'enum', required: true, positional: 0, default: 'fade', options: [...TRANSITION_OPTIONS, { value: 'end', label: 'cmd.trans.kind.end' }] },
+            { key: 'duration', label: 'cmd.trans.duration', type: 'number', default: 0.6 },
+            { key: 'dir', label: 'cmd.trans.dir', type: 'enum', options: DIR_OPTIONS },
+            { key: 'color', label: 'cmd.trans.color', type: 'color', advanced: true },
+            { key: 'mask', label: 'cmd.trans.mask', type: 'asset:bg', advanced: true },
+            { key: 'softness', label: 'cmd.trans.softness', type: 'number', default: 0.1, advanced: true },
+        ],
+    },
+    {
+        name: 'preload',
+        label: 'cmd.preload.label',
+        category: 'stage',
+        icon: '⏳',
+        hint: 'cmd.preload.hint',
+        params: [
+            { key: 'assets', label: 'cmd.preload.assets', type: 'string', required: true, positional: 0, list: true },
+            { key: 'wait', label: 'cmd.preload.wait', type: 'boolean', default: false },
+        ],
+    },
+    {
+        name: 'ui',
+        label: 'cmd.ui.label',
+        category: 'stage',
+        icon: '🪟',
+        hint: 'cmd.ui.hint',
+        params: [
+            {
+                key: 'op',
+                label: 'cmd.ui.op',
+                type: 'enum',
+                required: true,
+                positional: 0,
+                default: 'show',
+                options: [
+                    { value: 'show', label: 'cmd.ui.op.show' },
+                    { value: 'hide', label: 'cmd.ui.op.hide' },
+                    { value: 'toggle', label: 'cmd.ui.op.toggle' },
+                ],
+            },
+            { key: 'id', label: 'cmd.ui.id', type: 'panel', required: true, positional: 1 },
+        ],
+    },
+    {
+        name: 'hotspot',
+        label: 'cmd.hotspot.label',
+        category: 'stage',
+        icon: '🎯',
+        hint: 'cmd.hotspot.hint',
+        params: [
+            // `[hotspot clear]` / `[hotspot remove <id>]` reuse the id slot with a keyword.
+            { key: 'id', label: 'cmd.hotspot.id', type: 'string', required: true, positional: 0 },
+            { key: 'target', label: 'cmd.hotspot.target', type: 'string', positional: 1, advanced: true },
+            { key: 'x', label: 'cmd.hotspot.x', type: 'number', default: 0 },
+            { key: 'y', label: 'cmd.hotspot.y', type: 'number', default: 0 },
+            { key: 'w', label: 'cmd.hotspot.w', type: 'number', default: 10 },
+            { key: 'h', label: 'cmd.hotspot.h', type: 'number', default: 10 },
+            { key: 'onclick', label: 'cmd.hotspot.onclick', type: 'script' },
+            { key: 'if', label: 'cmd.hotspot.if', type: 'expr' },
+        ],
+    },
+    {
+        name: 'input',
+        label: 'cmd.input.label',
+        category: 'flow',
+        icon: '⌨️',
+        hint: 'cmd.input.hint',
+        params: [
+            { key: 'var', label: 'cmd.input.var', type: 'variable', required: true, positional: 0 },
+            { key: 'prompt', label: 'cmd.input.prompt', type: 'key' },
+            { key: 'default', label: 'cmd.input.default', type: 'string' },
+            { key: 'persist', label: 'cmd.input.persist', type: 'boolean', default: false },
+            { key: 'maxlength', label: 'cmd.input.maxlength', type: 'number', advanced: true },
+            { key: 'pattern', label: 'cmd.input.pattern', type: 'string', advanced: true },
         ],
     },
     {

package/dist/ir.d.ts

@@ -91,8 +91,13 @@ export interface ReplaySegment {
  *      migration maps bundled short names (`textfx` → `app.nilvn.textfx`) and keeps
  *      unknown names verbatim (the editor reports them, nothing is dropped).
  *  v12: `Project.config` — the work's engine configuration (the JSON form of
- *      nilvn.config.toml), exported as the package's `config`. Pure addition. */
-export declare const CURRENT_SCHEMA_VERSION = 12;
+ *      nilvn.config.toml), exported as the package's `config`. Pure addition.
+ *  v13: layered sprites and the actor's plugin fields — `Actor.textColor` /
+ *      `canvas` / `layers` / `ext` (pure additions) and `Actor.voice` moved under
+ *      `ext['app.nilvn.voicefx']` (migrated); `ChoiceNode.timer` / `timerDefault`,
+ *      `ChoiceOption.disabled`, `VariableDef.persist`, `CallNode` / `ReturnNode`
+ *      (pure additions). */
+export declare const CURRENT_SCHEMA_VERSION = 13;
 /** Bring a loaded project up to CURRENT_SCHEMA_VERSION in place (then return it).
  *  Call once on load, after reading from disk. Runs every table step the project
  *  predates, in order, then stamps the current version. */
@@ -129,18 +134,41 @@ export interface SceneMapChapter {
     sceneIds: string[];
     collapsed?: boolean;
 }
+/** One layer of a layered sprite. `src` is a path template with `{<layer>}`
+ *  for the value (`char/yuki/body-{body}.webp`); `values` is the editor's
+ *  picker list — the `face` layer's values are the actor's `faces`. */
+export interface ActorLayer {
+    src: string;
+    /** The value shown until a command sets one. */
+    default?: string;
+    /** Where a cropped layer image sits on the canvas, in canvas pixels. */
+    offset?: [number, number];
+    /** May be unset (`none` clears it). */
+    optional?: boolean;
+    values?: string[];
+}
 export interface Actor {
     id: string;
     /** Display name is localizable, hence a catalog key. */
     nameKey: string;
+    /** Name-tag BACKGROUND colour. */
     color?: string;
+    /** Name-tag TEXT colour (the theme's `name-color` when absent). */
+    textColor?: string;
     /** Sprite URL template; `{face}` is replaced by the current face. */
     sprites: string;
     /** Available faces, for the editor's expression picker. */
     faces: string[];
     defaultFace?: string;
-    /** Base pitch (Hz) for the voicefx plugin. */
-    voice?: number;
+    /** Layered sprite: the shared canvas in image pixels the layers align on. */
+    canvas?: [number, number];
+    /** Layered sprite: named layers composed bottom to top in declaration order.
+     *  `face` is the layer `say.face` / `[char id face]` drive; the others change
+     *  through `[char id body=casual]`. Wins over `sprites` when present. */
+    layers?: Record<string, ActorLayer>;
+    /** Plugin-declared fields by plugin id (`contributes.actorFields`) — the
+     *  voicefx pitch lives at `ext['app.nilvn.voicefx'].voice` (v13; was `voice`). */
+    ext?: Record<string, Record<string, unknown>>;
     /** The character's reproducible recipe (provenance):
      *  typically `source:'face-creator'`, carrying the whole def so any pose can be
      *  re-rendered at conversion time (the expression-set "registration template" a
@@ -154,6 +182,10 @@ export interface VariableDef {
     default: number | boolean | string;
     /** Display name in the editor. */
     label?: string;
+    /** Kept across saves, restarts and runs (the engine's `[persist]` table: the
+     *  stored value wins, `default` seeds the first run). Exported into the
+     *  package config's `persist` section, never as a script command. */
+    persist?: boolean;
 }
 export interface ResourceRegistry {
     backgrounds: AssetRef[];
@@ -234,7 +266,7 @@ export interface Scene {
     titleKey: string;
     nodes: SceneNode[];
 }
-export type SceneNode = SayNode | NarrateNode | CommandNode | ChoiceNode | SetNode | JumpNode | LabelNode | RecallNode | AnimNode | EventFrameNode | LoopStartNode | LoopStopNode;
+export type SceneNode = SayNode | NarrateNode | CommandNode | ChoiceNode | SetNode | JumpNode | CallNode | ReturnNode | LabelNode | RecallNode | AnimNode | EventFrameNode | LoopStartNode | LoopStopNode;
 export type NodeKind = SceneNode['kind'];
 interface NodeBase {
     /** Stable id generated by the editor; jumps/references point at it. */
@@ -268,12 +300,19 @@ export interface CommandNode extends NodeBase {
 export interface ChoiceNode extends NodeBase {
     kind: 'choice';
     options: ChoiceOption[];
+    /** Seconds the prompt waits before picking `timerDefault` by itself (the
+     *  engine's `[choices timer=]`); absent = what the `[choices]` config says. */
+    timer?: number;
+    /** The option a timeout picks, counted from 1 among the shown options. */
+    timerDefault?: number;
 }
 export interface ChoiceOption {
     labelKey: string;
     target: JumpTarget;
     /** Shown only when truthy. */
     condition?: string;
+    /** Shown greyed and unpickable when truthy (`disabled=`). */
+    disabled?: string;
 }
 export interface SetNode extends NodeBase {
     kind: 'set';
@@ -284,6 +323,15 @@ export interface JumpNode extends NodeBase {
     kind: 'jump';
     target: JumpTarget;
 }
+/** `[call label]`: jump there and come back at the next `[return]` (calls nest). */
+export interface CallNode extends NodeBase {
+    kind: 'call';
+    target: JumpTarget;
+}
+/** `[return]`: back to the line after the last `[call]`. */
+export interface ReturnNode extends NodeBase {
+    kind: 'return';
+}
 export interface LabelNode extends NodeBase {
     kind: 'label';
     name: string;

package/dist/ir.js

@@ -42,8 +42,13 @@ import { resolvePluginId } from './plugins.js';
  *      migration maps bundled short names (`textfx` → `app.nilvn.textfx`) and keeps
  *      unknown names verbatim (the editor reports them, nothing is dropped).
  *  v12: `Project.config` — the work's engine configuration (the JSON form of
- *      nilvn.config.toml), exported as the package's `config`. Pure addition. */
-export const CURRENT_SCHEMA_VERSION = 12;
+ *      nilvn.config.toml), exported as the package's `config`. Pure addition.
+ *  v13: layered sprites and the actor's plugin fields — `Actor.textColor` /
+ *      `canvas` / `layers` / `ext` (pure additions) and `Actor.voice` moved under
+ *      `ext['app.nilvn.voicefx']` (migrated); `ChoiceNode.timer` / `timerDefault`,
+ *      `ChoiceOption.disabled`, `VariableDef.persist`, `CallNode` / `ReturnNode`
+ *      (pure additions). */
+export const CURRENT_SCHEMA_VERSION = 13;
 /** The stable id a ref (of either shape) points at. */
 function refId(r) {
     const raw = r.id ?? r.name;
@@ -156,6 +161,21 @@ const MIGRATIONS = [
     },
     // v11 -> v12: `Project.config` (the work's engine configuration). Pure addition
     // — a project without one plays with the engine's defaults.
+    // v12 -> v13: the voicefx pitch (`Actor.voice`) moves under `ext['app.nilvn.voicefx']`
+    // like every plugin actor field; the layered-sprite fields are pure additions.
+    {
+        to: 13,
+        run: (p) => {
+            for (const a of Object.values(p.actors)) {
+                const legacy = a;
+                if (legacy.voice === undefined)
+                    continue;
+                const ext = (a.ext ??= {});
+                ext['app.nilvn.voicefx'] = { ...ext['app.nilvn.voicefx'], voice: legacy.voice };
+                delete legacy.voice;
+            }
+        },
+    },
 ];
 /** Bring a loaded project up to CURRENT_SCHEMA_VERSION in place (then return it).
  *  Call once on load, after reading from disk. Runs every table step the project

package/dist/package.d.ts

@@ -1,4 +1,4 @@
-import type { Project, WorkConfig } from './ir.js';
+import type { Actor, Project, WorkConfig } from './ir.js';
 import { type ChunkManifest, type ManifestAsset } from './chunk.js';
 import { type BuildChunkedOptions, type ChunkFile } from './chunk-build.js';
 /** Script-package format version. Bumped only when nilvn.json's shape changes
@@ -12,13 +12,32 @@ export declare const PACKAGE_MANIFEST_FILE = "nilvn.json";
 export interface PackageActor {
     name?: string;
     nameKey?: string;
+    /** Name-tag background colour. */
     color?: string;
+    /** Name-tag text colour. */
+    textColor?: string;
     /** Sprite URL template; `{face}` is replaced by the current face. */
     sprites?: string;
     defaultFace?: string;
-    /** Base pitch (Hz) for the voice blip. */
+    /** Layered sprite: the shared canvas in image pixels (`[600, 1100]`). */
+    canvas?: [number, number];
+    /** Layered sprite: named layers composed bottom to top (`face` follows the
+     *  face; the others change through `[char id body=casual]`). Wins over `sprites`. */
+    layers?: Record<string, PackageActorLayer>;
+    /** Plugin actor fields by plugin id (`contributes.actorFields`), e.g.
+     *  `ext['app.nilvn.voicefx'].voice`. */
+    ext?: Record<string, Record<string, unknown>>;
+    /** @deprecated — the voicefx pitch; the engine moves it under `ext`. */
     voice?: number;
 }
+/** One layer of a layered sprite in the package (the engine's `ActorLayerDef`). */
+export interface PackageActorLayer {
+    /** Path template; `{<layer>}` is replaced by the layer's value. */
+    src: string;
+    default?: string;
+    offset?: [number, number];
+    optional?: boolean;
+}
 /** One enabled plugin, by its reverse-DNS id (`app.nilvn.textfx`; the engine
  *  also accepts the short names older packages carry).
  *  `entry` = a plugin carried inside the package (its `plugin.json`, relative to
@@ -98,6 +117,8 @@ export interface ScriptPackagePlan {
 /** Languages the finished work can switch between: the default plus every
  *  declared language that ships a non-empty catalog. The default comes first. */
 export declare function packageLanguages(project: Project): string[];
+/** The layer table minus the editor's picker lists. */
+export declare function packageLayers(layers: NonNullable<Actor['layers']>): Record<string, PackageActorLayer>;
 /** The runtime actor table straight from the IR (`name` = the default-language
  *  display name, falling back to the id). */
 export declare function packageActors(project: Project): Record<string, PackageActor>;

package/dist/package.js

@@ -43,13 +43,31 @@ export function packageLanguages(project) {
     const extra = declared.filter((l) => l !== def && Object.keys(project.catalogs[l] ?? {}).length > 0);
     return [def, ...extra];
 }
+/** The layer table minus the editor's picker lists. */
+export function packageLayers(layers) {
+    const out = {};
+    for (const [name, l] of Object.entries(layers)) {
+        out[name] = { src: l.src, ...(l.default ? { default: l.default } : {}), ...(l.offset ? { offset: l.offset } : {}), ...(l.optional ? { optional: true } : {}) };
+    }
+    return out;
+}
 /** The runtime actor table straight from the IR (`name` = the default-language
  *  display name, falling back to the id). */
 export function packageActors(project) {
     const cat = project.catalogs[project.meta.defaultLang] ?? {};
     const out = {};
     for (const [id, a] of Object.entries(project.actors)) {
-        out[id] = { name: cat[a.nameKey] ?? id, nameKey: a.nameKey, color: a.color, sprites: a.sprites, defaultFace: a.defaultFace, voice: a.voice };
+        out[id] = {
+            name: cat[a.nameKey] ?? id,
+            nameKey: a.nameKey,
+            color: a.color,
+            sprites: a.sprites,
+            defaultFace: a.defaultFace,
+            ...(a.textColor ? { textColor: a.textColor } : {}),
+            ...(a.canvas ? { canvas: a.canvas } : {}),
+            ...(a.layers ? { layers: packageLayers(a.layers) } : {}),
+            ...(a.ext && Object.keys(a.ext).length ? { ext: a.ext } : {}),
+        };
     }
     return out;
 }

package/dist/schema.d.ts

@@ -1,4 +1,4 @@
-export type ParamType = 'string' | 'number' | 'boolean' | 'enum' | 'asset:bg' | 'asset:bgm' | 'asset:se' | 'asset:sprite' | 'actor' | 'face' | 'color' | 'expr';
+export type ParamType = 'string' | 'number' | 'boolean' | 'enum' | 'asset:bg' | 'asset:bgm' | 'asset:se' | 'asset:sprite' | 'actor' | 'face' | 'color' | 'expr' | 'variable' | 'panel' | 'key' | 'script';
 export interface ParamOption {
     value: string;
     label: string;
@@ -18,6 +18,9 @@ export interface ParamSchema {
     positional?: number;
     /** Tuck behind an "advanced" disclosure in the editor. */
     advanced?: boolean;
+    /** A positional that holds several values: the value is whitespace-separated
+     *  and serializes as that many positional tokens (`[preload a.png b.wav]`). */
+    list?: boolean;
 }
 export type CommandCategory = 'stage' | 'audio' | 'fx' | 'flow' | 'text';
 export interface CommandSchema {

package/dist/serialize.js

@@ -169,13 +169,28 @@ function serializeNode(node, text, commands, scope = null) {
         }
         case 'narrate':
             return `|${text(node.textKey)}`;
-        case 'choice':
-            return node.options
-                .map((o) => {
-                const cond = o.condition ? ` if=${token(o.condition)}` : '';
-                return `[choice ${token(text(o.labelKey))} -> ${dest(o.target, scope)}${cond}]`;
-            })
-                .join('\n');
+        case 'choice': {
+            // `if=` / `disabled=` are read to the tag's end and unquoted by the engine
+            // (they carry spaces), so they go last and raw. A timer rides a `[choices]`
+            // line right before the prompt.
+            const lines = node.options.map((o) => {
+                const guards = [o.condition ? `if=${o.condition}` : '', o.disabled ? `disabled=${o.disabled}` : ''].filter(Boolean);
+                return `[choice ${token(text(o.labelKey))} -> ${dest(o.target, scope)}${guards.length ? ' ' + guards.join(' ') : ''}]`;
+            });
+            if (node.timer !== undefined || node.timerDefault !== undefined) {
+                const parts = ['choices'];
+                if (node.timer !== undefined)
+                    parts.push(`timer=${node.timer}`);
+                if (node.timerDefault !== undefined)
+                    parts.push(`default=${node.timerDefault}`);
+                lines.unshift(`[${parts.join(' ')}]`);
+            }
+            return lines.join('\n');
+        }
+        case 'call':
+            return `[call ${dest(node.target, scope)}]`;
+        case 'return':
+            return '[return]';
         case 'jump':
             // v1 DSL expresses a conditional jump as [if cond -> label].
             return node.condition
@@ -188,7 +203,7 @@ function serializeNode(node, text, commands, scope = null) {
             // gallery is built from the IR directly, not from the runtime script.
             return `; recall ${node.recallId}`;
         case 'command':
-            return serializeCommand(node, commands[node.cmd]);
+            return serializeCommand(node, commands[node.cmd], text);
         case 'anim':
             return serializeAnim(node);
         case 'eventframe':
@@ -203,10 +218,18 @@ function serializeNode(node, text, commands, scope = null) {
         }
     }
 }
-function serializeCommand(node, schema) {
+function serializeCommand(node, schema, text) {
     const parts = [node.cmd];
     const params = node.params;
     const used = new Set();
+    // A `key` param holds a catalog `@key`; under keepKeys the engine resolves it,
+    // otherwise the literal text goes out like a dialogue line's.
+    const value = (p, v) => {
+        if (p.type === 'key' && text && typeof v === 'string' && v.startsWith('@'))
+            return text(v.slice(1));
+        return v;
+    };
+    const raw = [];
     if (schema) {
         const positionals = schema.params
             .filter((p) => p.positional !== undefined)
@@ -221,7 +244,12 @@ function serializeCommand(node, schema) {
         for (let i = 0; i <= last; i++) {
             const p = positionals[i];
             used.add(p.key);
-            parts.push(token(params[p.key] ?? p.default ?? ''));
+            const v = value(p, params[p.key] ?? p.default ?? '');
+            if (p.list)
+                for (const item of String(v).split(/\s+/).filter(Boolean))
+                    parts.push(token(item));
+            else
+                parts.push(token(v));
         }
         for (const p of schema.params) {
             if (p.positional !== undefined)
@@ -232,7 +260,11 @@ function serializeCommand(node, schema) {
                 continue;
             if (p.default !== undefined && val === p.default)
                 continue;
-            parts.push(`${p.key}=${token(val)}`);
+            // A condition is read to the tag's end unquoted: it goes last, raw.
+            if (p.type === 'expr')
+                raw.push(`${p.key}=${String(val)}`);
+            else
+                parts.push(`${p.key}=${token(value(p, val))}`);
         }
     }
     // Params not described by the schema (e.g. unknown plugin command) -> key=value.
@@ -241,7 +273,7 @@ function serializeCommand(node, schema) {
             continue;
         parts.push(`${k}=${token(v)}`);
     }
-    return `[${parts.join(' ')}]`;
+    return `[${[...parts, ...raw].join(' ')}]`;
 }
 // A recorded keyframe animation (AnimNode) serializes to an `[anim …]` command the
 // engine's built-in `anim` handler plays. The whole track rides one compact `kf`

package/dist/versions.d.ts

@@ -1,7 +1,7 @@
 export declare const FORMAT_VERSIONS: Readonly<{
     /** Project / IR document (`ProjectMeta.schemaVersion`) — `migrateProject` brings
      *  older projects forward, one table step per bump. */
-    irSchema: 12;
+    irSchema: 13;
     /** Chunked-streaming manifest (`ChunkManifest.format`) — the loaders gate on it. */
     chunkManifest: 1;
     /** Script package (`nilvn.json` `format`) — `checkPackageManifest` gates on it. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nilvn/core",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "type": "module",
   "description": "NilVN shared core — the project document model (IR), command / plugin-manifest schemas, script-package format and serializers",
   "license": "MIT",