@nilvn/core 0.16.3 → 0.17.1

package/dist/chunk-build.d.ts

@@ -28,6 +28,16 @@ export interface BuildChunkedOptions {
     /** Command schema registry for serialization (`commandRegistry(manifests)`);
      *  built-ins only when omitted — see SerializeOptions.commands. */
     commands?: Record<string, CommandSchema>;
+    /** A scoped build (the studio's preview of one scene): only these scene ids, in
+     *  project order, go into the package — as ONE chunk, which is also the entry —
+     *  and a jump or choice that leaves the scope routes to the unset landing
+     *  (serialize's non-`crossChunk` mode) instead of naming a label the package
+     *  does not carry. `groups` is ignored when set. Omitted = the whole project. */
+    scenes?: string[];
+    /** Emit `[label anchorLabel]` right before this node (play-from-here). */
+    anchorNodeId?: string;
+    /** The label to inject at `anchorNodeId`; defaults to `__nilvn_here__`. */
+    anchorLabel?: string;
 }
 /** Catalog keys a scene's runtime body references (say/narrate text + choice
  *  option labels) — i.e. the text that belongs in this scene's locale slice.

package/dist/chunk-build.js

@@ -57,10 +57,12 @@ export function sceneTextKeys(nodes, into) {
     }
 }
 export function buildChunkedExport(project, opts) {
-    const sceneOrder = project.scenes.map((s) => s.id);
+    const scoped = opts.scenes ? project.scenes.filter((s) => opts.scenes.includes(s.id)) : project.scenes;
+    const sceneOrder = scoped.map((s) => s.id);
     const sceneIds = new Set(sceneOrder);
-    const byId = new Map(project.scenes.map((s) => [s.id, s]));
-    const groups = opts.groups ?? sceneOrder.map((id) => [id]);
+    const byId = new Map(scoped.map((s) => [s.id, s]));
+    const groups = opts.scenes ? [sceneOrder] : (opts.groups ?? sceneOrder.map((id) => [id]));
+    const anchor = opts.anchorNodeId ? { anchorNodeId: opts.anchorNodeId, ...(opts.anchorLabel ? { anchorLabel: opts.anchorLabel } : {}) } : {};
     // Each group → one chunk. Chunk id = its first scene id (stable, unique).
     const chunks = [];
     const files = [];
@@ -76,7 +78,7 @@ export function buildChunkedExport(project, opts) {
         if (!ids.length)
             continue;
         const chunkId = ids[0];
-        const { body, labels, assetRefs } = serializeChunk(project, { scenes: ids, keepKeys: true, crossChunk: true, ...(opts.commands ? { commands: opts.commands } : {}) });
+        const { body, labels, assetRefs } = serializeChunk(project, { scenes: ids, keepKeys: true, crossChunk: !opts.scenes, ...anchor, ...(opts.commands ? { commands: opts.commands } : {}) });
         const scriptChunk = { id: chunkId, body, labels };
         const text = JSON.stringify(scriptChunk);
         const bytes = utf8Len(text);
@@ -111,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

@@ -1,6 +1,18 @@
 export type Lang = string;
 /** textKey -> localized string. Values may carry inline markup ({wave:..}, {w:0.5}, {br}). */
 export type TextCatalog = Record<string, string>;
+/** The work's engine configuration — the JSON form of `nilvn.config.toml`,
+ *  section by section (`title`, `ending`, `theme`, `window`, `menu`, `settings`,
+ *  `keys`, `saves`, `choices`, `input`, `preload`, `ui`, `persist`, `strings`,
+ *  `plugins.<id>` …). Core keeps it opaque on purpose: the engine is the one
+ *  source of its meaning (its `CONFIG_SCHEMA` / `checkConfig` validate it and the
+ *  studio's settings forms are generated from that schema), so nothing here
+ *  duplicates the engine's types. Sections the package model carries elsewhere
+ *  (`game.entry` / `game.scripts` / `path` / `actors` / `plugins.use`) do not
+ *  belong in it — the engine drops them with a diagnostic. */
+export interface WorkConfig {
+    [section: string]: unknown;
+}
 export interface Project {
     meta: ProjectMeta;
     actors: Record<string, Actor>;
@@ -18,6 +30,10 @@ export interface Project {
      *  the engine unlocks a segment when normal play passes its end. Optional: older
      *  projects simply have none. */
     replays?: ReplaySegment[];
+    /** The work's engine configuration (see {@link WorkConfig}); travels into the
+     *  script package as `nilvn.json` `config`. Optional: a project without one
+     *  plays with the engine's defaults. Added at schema v12. */
+    config?: WorkConfig;
 }
 /** A node position id: which scene, which node — the timeline's stable locator
  *  (`NodeBase.id` is minted once and survives edits around it). */
@@ -73,8 +89,15 @@ export interface ReplaySegment {
  *  v11: plugin platform v2 — `PluginRef`
  *      is `{ id, version?, config? }` keyed by the plugin's reverse-DNS id; the
  *      migration maps bundled short names (`textfx` → `app.nilvn.textfx`) and keeps
- *      unknown names verbatim (the editor reports them, nothing is dropped). */
-export declare const CURRENT_SCHEMA_VERSION = 11;
+ *      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.
+ *  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. */
@@ -111,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
@@ -136,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[];
@@ -216,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. */
@@ -250,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';
@@ -266,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

@@ -40,8 +40,15 @@ import { resolvePluginId } from './plugins.js';
  *  v11: plugin platform v2 — `PluginRef`
  *      is `{ id, version?, config? }` keyed by the plugin's reverse-DNS id; the
  *      migration maps bundled short names (`textfx` → `app.nilvn.textfx`) and keeps
- *      unknown names verbatim (the editor reports them, nothing is dropped). */
-export const CURRENT_SCHEMA_VERSION = 11;
+ *      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.
+ *  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;
@@ -152,6 +159,23 @@ const MIGRATIONS = [
             p.plugins = next;
         },
     },
+    // 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 } 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
@@ -49,6 +68,14 @@ export interface PackageManifest {
     textSpeed: number;
     /** Per-work id the runtime namespaces saves / settings by. */
     saveKey: string;
+    /** The work's engine configuration — the JSON form of `nilvn.config.toml`
+     *  (`Project.config`). The engine applies it once the package is open, after
+     *  the asset table is filled, so a skin, logo or background in it resolves by
+     *  ref like any other asset. Optional (a package without one plays with the
+     *  engine's defaults); the sections `nilvn.json` carries itself (`game.entry`
+     *  / `game.scripts` / `path` / `actors` / `plugins.use`) are dropped with a
+     *  diagnostic. Engines before 0.17 ignore the field. */
+    config?: WorkConfig;
     /** The chunk manifest (chunk.ts), embedded as-is: chunk / locale-slice / asset
      *  index + entry label. Wire files (`chunks/**`, `assets/**`) are unchanged. */
     chunks: ChunkManifest;
@@ -74,6 +101,8 @@ export interface BuildPackageOptions extends BuildChunkedOptions {
     textSpeed?: number;
     /** Defaults to the project id, else the title. */
     saveKey?: string;
+    /** Defaults to `project.config`; left out of the manifest when empty. */
+    config?: WorkConfig;
 }
 export interface ScriptPackagePlan {
     /** nilvn.json, with `chunks.assets` still EMPTY — the producer resolves the
@@ -88,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>;
@@ -96,5 +127,12 @@ export declare function packageActors(project: Project): Record<string, PackageA
  *  single-file / asset-ZIP shape) plus the manifest fields the shells used to bake
  *  into their bootstraps. Pure, zero-I/O. */
 export declare function buildScriptPackage(project: Project, opts: BuildPackageOptions): ScriptPackagePlan;
+/** Asset refs a work configuration names — a skin, logo, background, music,
+ *  HUD icon or preload entry — found by walking every string in it with the
+ *  same predicate the scene walk uses (`isAssetRef`), so a producer resolves
+ *  them into the package's by-ref table alongside the scenes' assets. Strings
+ *  holding a `{placeholder}` (a layered actor's `src` template) are templates,
+ *  not refs, and are left to the actor table. */
+export declare function configAssetRefs(config: WorkConfig | undefined): string[];
 /** Fill the by-ref asset table (`chunks.assets`). Returns a new manifest. */
 export declare function fillPackageAssets(manifest: PackageManifest, assets: Record<string, ManifestAsset>): PackageManifest;

package/dist/package.js

@@ -8,6 +8,7 @@
 // Pure types + a builder over buildChunkedExport, zero-dep. The editor's four
 // exports (single-file HTML / asset ZIP / chunked ZIP / .nvpk) are this package
 // plus a shell; the engine's `load()` is its one consumer.
+import { isAssetRef } from './serialize.js';
 import { isChunkManifest } from './chunk.js';
 import { buildChunkedExport } from './chunk-build.js';
 /** Script-package format version. Bumped only when nilvn.json's shape changes
@@ -42,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;
 }
@@ -57,12 +76,14 @@ export function packageActors(project) {
  *  single-file / asset-ZIP shape) plus the manifest fields the shells used to bake
  *  into their bootstraps. Pure, zero-I/O. */
 export function buildScriptPackage(project, opts) {
-    // Forward the command registry: without it the chunks serialize plugin commands
-    // against the built-ins alone, and a positional argument (`[move yuki …]`)
-    // degrades to `id=yuki`, which the plugin never reads.
-    const plan = buildChunkedExport(project, { engine: opts.engine, groups: opts.groups, ...(opts.commands ? { commands: opts.commands } : {}) });
+    // The chunk options ride through whole (registry, grouping, a preview's scene
+    // scope and anchor): without the command registry the chunks serialize plugin
+    // commands against the built-ins alone, and a positional argument
+    // (`[move yuki …]`) degrades to `id=yuki`, which the plugin never reads.
+    const plan = buildChunkedExport(project, opts);
     const title = opts.title ?? (project.meta.title || 'NilVN');
     const lang = (opts.lang ?? project.meta.defaultLang);
+    const config = opts.config ?? project.config;
     const manifest = {
         format: PACKAGE_FORMAT,
         title,
@@ -73,10 +94,36 @@ export function buildScriptPackage(project, opts) {
         plugins: opts.plugins ?? project.plugins.map((p) => ({ id: p.id })),
         textSpeed: opts.textSpeed ?? (Number(project.meta.textSpeed) || 40),
         saveKey: opts.saveKey ?? (project.meta.id || project.meta.title || 'nilvn'),
+        ...(config && Object.keys(config).length ? { config } : {}),
         chunks: plan.manifest,
     };
     return { manifest, files: plan.files, assetRefs: plan.assetRefs };
 }
+/** Asset refs a work configuration names — a skin, logo, background, music,
+ *  HUD icon or preload entry — found by walking every string in it with the
+ *  same predicate the scene walk uses (`isAssetRef`), so a producer resolves
+ *  them into the package's by-ref table alongside the scenes' assets. Strings
+ *  holding a `{placeholder}` (a layered actor's `src` template) are templates,
+ *  not refs, and are left to the actor table. */
+export function configAssetRefs(config) {
+    const out = new Set();
+    const walk = (v) => {
+        if (typeof v === 'string') {
+            if (isAssetRef(v) && !v.includes('{'))
+                out.add(v);
+        }
+        else if (Array.isArray(v)) {
+            for (const x of v)
+                walk(x);
+        }
+        else if (v && typeof v === 'object') {
+            for (const x of Object.values(v))
+                walk(x);
+        }
+    };
+    walk(config);
+    return [...out];
+}
 /** Fill the by-ref asset table (`chunks.assets`). Returns a new manifest. */
 export function fillPackageAssets(manifest, assets) {
     return { ...manifest, chunks: { ...manifest.chunks, assets } };

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: 11;
+    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.16.3",
+  "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",