@datamoc/mw_games 0.43.0 → 0.44.2

package/dist/mwl/package-document.d.ts

@@ -0,0 +1,217 @@
+import { type MwlPreprocessOptions } from './grammar.ts';
+/** plain JSON, the form a sound-effect definition or a script action keeps */
+export type PackageValue = null | boolean | number | string | PackageValue[] | {
+    [key: string]: PackageValue;
+};
+export type PackageAssetKind = 'image' | 'audio' | 'music' | 'font' | 'data' | 'synth-patch';
+/**
+ * The `kind` values an `asset` tag accepts.
+ *
+ * @example
+ * ```ts
+ * import { PACKAGE_ASSET_KINDS } from '@datamoc/mw_games/mwl';
+ *
+ * console.log(PACKAGE_ASSET_KINDS.includes('synth-patch')); // true
+ * ```
+ */
+export declare const PACKAGE_ASSET_KINDS: readonly PackageAssetKind[];
+/**
+ * Kinds that are somebody's creative work: `license` and `source` are mandatory for these.
+ *
+ * @example
+ * ```ts
+ * import { PACKAGE_MEDIA_KINDS } from '@datamoc/mw_games/mwl';
+ *
+ * console.log(PACKAGE_MEDIA_KINDS.includes('data')); // false
+ * ```
+ */
+export declare const PACKAGE_MEDIA_KINDS: readonly PackageAssetKind[];
+/**
+ * The MWL tags a package document may hold, and the only ones. Standard game tags (`unit_type`,
+ * `event`, ...) are refused in a package: a character expands into them, and keeping the two
+ * apart means nothing in a shared file can reach the rules of the game it is dropped into.
+ *
+ * @example
+ * ```ts
+ * import { PACKAGE_TAGS } from '@datamoc/mw_games/mwl';
+ *
+ * console.log(PACKAGE_TAGS.includes('character')); // true
+ * ```
+ */
+export declare const PACKAGE_TAGS: readonly ['package', 'asset', 'character', 'animation', 'sound_effect', 'music', 'script', 'import'];
+/**
+ * The event vocabulary a package script may `do`. It is the data-only subset of the MWL event
+ * actions plus `play` and `give`; `hook` (game-author code), `endlevel`, `win`, `lose`,
+ * `spawn`, `kill` and anything else that decides the outcome of a scenario are not on it.
+ *
+ * @example
+ * ```ts
+ * import { PACKAGE_SCRIPT_ACTIONS } from '@datamoc/mw_games/mwl';
+ *
+ * console.log(PACKAGE_SCRIPT_ACTIONS.includes('hook')); // false
+ * ```
+ */
+export declare const PACKAGE_SCRIPT_ACTIONS: readonly string[];
+/**
+ * The capabilities mwg itself knows how to grant; a package may name others, a policy decides.
+ *
+ * @example
+ * ```ts
+ * import { KNOWN_PACKAGE_CAPABILITIES } from '@datamoc/mw_games/mwl';
+ *
+ * console.log(KNOWN_PACKAGE_CAPABILITIES); // ['audio', 'script']
+ * ```
+ */
+export declare const KNOWN_PACKAGE_CAPABILITIES: readonly string[];
+export interface PackageRequires {
+    /** semver range of the mwg version, e.g. `>=0.42` */
+    readonly mwg?: string;
+    /** semver range of `@datamoc/mwg-retro-audio` */
+    readonly retroAudio?: string;
+    readonly capabilities: readonly string[];
+}
+export interface PackageMeta {
+    readonly id: string;
+    readonly version: string;
+    readonly author?: string;
+    readonly license?: string;
+    readonly requires: PackageRequires;
+}
+export interface PackageAsset {
+    readonly id: string;
+    readonly kind: PackageAssetKind;
+    readonly path: string;
+    readonly mime?: string;
+    readonly sha256?: string;
+    readonly license?: string;
+    readonly source?: string;
+}
+export interface PackageAnimation {
+    readonly id: string;
+    readonly frames: readonly number[];
+    readonly fps?: number;
+    readonly loop?: boolean;
+    /** frame number to the sound effect it triggers */
+    readonly events: Readonly<Record<string, {
+        readonly sound: string;
+    }>>;
+}
+export interface PackageSoundEffect {
+    readonly id: string;
+    /** everything but the id: chip, priority, retrigger, voices... read by the audio engine */
+    readonly definition: Readonly<Record<string, PackageValue>>;
+}
+export interface PackageMusic {
+    readonly id: string;
+    /** an asset id */
+    readonly src: string;
+    readonly loop?: boolean;
+    readonly region?: readonly [number, number];
+    /** an asset id of a streamed file for platforms without the engine */
+    readonly fallback?: string;
+}
+export interface PackageAction {
+    readonly tag: string;
+    readonly attributes: Readonly<Record<string, string | number | boolean>>;
+}
+export interface PackageScript {
+    readonly id: string;
+    readonly on: string;
+    /** a pure condition from the MWL condition language */
+    readonly when?: string;
+    readonly do: readonly PackageAction[];
+    /** real code; needs the `script` capability, which a game is free to refuse */
+    readonly code?: string;
+}
+export interface PackageImport {
+    /** another MWL document inside this package, merged under the same package id */
+    readonly src?: string;
+    /** another package this one builds on, which must be merged first */
+    readonly package?: string;
+    readonly version?: string;
+    /** prefix, joined with a dot, for the ids of an imported file */
+    readonly as?: string;
+}
+export interface PackageCharacter {
+    readonly id: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly portrait?: string;
+    readonly sprite?: {
+        readonly image: string;
+        readonly frame?: readonly [number, number];
+    };
+    readonly theme?: string;
+    /** name to animation id */
+    readonly animations: Readonly<Record<string, string>>;
+    /** name to sound-effect id */
+    readonly sounds: Readonly<Record<string, string>>;
+    readonly scripts: readonly string[];
+    /** hitpoints, movement, attack, defense...: the numbers of the unit */
+    readonly stats: Readonly<Record<string, string | number | boolean>>;
+}
+export interface PackageDocument {
+    readonly meta: PackageMeta;
+    readonly assets: readonly PackageAsset[];
+    readonly characters: readonly PackageCharacter[];
+    readonly animations: readonly PackageAnimation[];
+    readonly soundEffects: readonly PackageSoundEffect[];
+    readonly music: readonly PackageMusic[];
+    readonly scripts: readonly PackageScript[];
+    readonly imports: readonly PackageImport[];
+    /** the `_("...")` strings, sorted, for the i18n catalog */
+    readonly messages: readonly string[];
+}
+/**
+ * Reads a package document: the MWL tags `package`, `asset`, `character`, `animation`,
+ * `sound_effect`, `music`, `script` and `import`, into plain typed data. Macros and
+ * `#include`s are expanded first, as for any MWL file. Nothing is executed: a script's `when` is
+ * only checked for syntax and its `do` only for membership of the safe vocabulary.
+ *
+ * `character` is a macro, not a compiled type of its own: it stays one record here and expands
+ * into a `unit_type` (plus the animations, effects and scripts it names) when merged. A new
+ * compiled table would need its own schema, validator and loader beside the one `unit_type`
+ * already has; the macro reuses all of them, and the fields only a renderer or a player of
+ * sound reads (portrait, sprite, theme) have no consumer in the rules core anyway.
+ *
+ * @example
+ * ```ts
+ * import { parsePackageDocument } from '@datamoc/mw_games/mwl';
+ *
+ * const document = parsePackageDocument(
+ *   "[{ tag: 'package', id: 'marta', version: '1.0.0' }, { tag: 'character', id: 'marta', hitpoints: 28 }]",
+ * );
+ * console.log(document.characters[0]?.stats.hitpoints); // 28
+ * ```
+ */
+export declare function parsePackageDocument(source: string, options?: MwlPreprocessOptions & {
+    readonly files?: Readonly<Record<string, string>>;
+}): PackageDocument;
+/**
+ * Checks a version against a small semver range: `>=`, `>`, `<=`, `<`, `^`, `~`, an exact
+ * version or a partial one (`0.42` is `0.42.x`), several separated by spaces (all must hold) and
+ * alternatives separated by `||`. A pre-release or build suffix on the version is ignored.
+ * A malformed range throws a `PackageFormatError`.
+ *
+ * @example
+ * ```ts
+ * import { satisfiesVersionRange } from '@datamoc/mw_games/mwl';
+ *
+ * console.log(satisfiesVersionRange('0.43.0', '>=0.42 <1')); // true
+ * console.log(satisfiesVersionRange('0.43.0', '^0.42.0')); // false
+ * ```
+ */
+export declare function satisfiesVersionRange(version: string, range: string): boolean;
+/**
+ * Orders two `x.y.z` versions: negative when `a` is older, positive when newer. It decides which
+ * of two coexisting versions of a package owns the plain `packageId:id` name.
+ *
+ * @example
+ * ```ts
+ * import { compareVersions } from '@datamoc/mw_games/mwl';
+ *
+ * console.log(compareVersions('1.2.0', '1.10.0') < 0); // true
+ * ```
+ */
+export declare function compareVersions(a: string, b: string): number;
+//# sourceMappingURL=package-document.d.ts.map

package/dist/mwl/package-document.d.ts.map

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