hzengine-core 0.1.2-dev

package/types/platform/index.d.ts

@@ -0,0 +1,134 @@
+export interface Platform<WidgetFactory = any> {
+    name: string;
+    getScreenSize(): [width: number, height: number];
+    createUILayer({ z_index }: {
+        z_index: number;
+    }): WidgetFactory;
+    deleteUILayer(widgetFactory: WidgetFactory): void;
+    isFileSync({ path }: {
+        path: string;
+    }): boolean;
+    readdirSync(option: Platform.readdirSync.Option): Platform.readdirSync.Result;
+    statSync(option: Platform.statSync.Option): Platform.statSync.Result;
+    readFileSync(option: Platform.readFileSync.Option): Platform.readFileSync.Result;
+    writeFileSync(option: Platform.writeFileSync.Option): void;
+    getImageInfo(img_path: string): {
+        width: number;
+        height: number;
+    };
+    getTime(): number;
+    createAudioPlayer(): Platform.AudioPlayer;
+    releaseAudioPlayer(audio_player: Platform.AudioPlayer): void;
+    setFrameInterval(callback: () => void): void;
+}
+export declare namespace Platform {
+    interface AudioPlayer {
+        onPrepared?: (success: boolean) => void | undefined;
+        onCompleted?: () => void | undefined;
+        prepare(): void;
+        start(): void;
+        stop(): void;
+        release(): void;
+        getMediaInfo(): MediaInfo;
+        setSource({ path }: {
+            path: string;
+        }): void;
+    }
+    interface MediaInfo {
+        title: string | undefined;
+        artist: string | undefined;
+        duration: number;
+    }
+    namespace readdirSync {
+        interface Option {
+            /**
+             * @zh 目录路径
+             * @en Directory path
+             */
+            path: string;
+        }
+        /**
+         * @zh 如果返回 `undefined` 则目录不存在，否则返回文件名数组
+         * @en If `undefined` is returned, the directory does not exist, otherwise an array of filenames is returned
+         */
+        type Result = Array<string> | undefined;
+    }
+    namespace statSync {
+        interface Option {
+            /**
+             * @zh 路径
+             * @en path
+             */
+            path: string;
+        }
+        /**
+         * @zh 如果返回 `undefined` 则目标文件不存在，否则返回文件信息对象
+         * @en If `undefined` is returned, the target file does not exist, otherwise the file information object is returned
+         */
+        type Result = FSStat | undefined;
+        /**
+         * @output
+         */
+        interface FSStat {
+            /**
+             * @zh 文件大小（单位为字节）
+             * @en The size of the file in bytes
+             */
+            size: number;
+        }
+    }
+    namespace readFileSync {
+        interface Option {
+            /**
+             * @zh 文件路径
+             * @en path
+             */
+            path: string;
+            /**
+             * @zh 其他选项
+             * @en Other Options
+             */
+            options?: Options;
+        }
+        interface Options {
+            /**
+             * @zh 当指定了编码方式之后，API 返回结果为 `string`
+             * @en When the encoding method is specified, the API returns `string` as the result
+             */
+            encoding?: string;
+        }
+        /**
+         * @zh 文件内容。如果返回 `undefined`，则表明读取文件失败
+         * @en File content. If `undefined` is returned, the file failed to be read
+         */
+        type Result = ArrayBuffer | string | undefined;
+    }
+    namespace writeFileSync {
+        interface Option {
+            /**
+             * @zh 文件路径或者文件句柄
+             * @en File path or file descriptor
+             */
+            path: string | number;
+            /**
+             * @zh 写入目标文件的数据
+             * @en Data to be written to the target file
+             */
+            data: ArrayBuffer | string | DataView;
+            /**
+             * @zh 其他选项
+             * @en Other Options
+             */
+            options?: Options;
+        }
+        interface Options {
+            /**
+             * @zh 如果数据格式为 `string`，需要指定编码方式
+             * @en If the `data` format is `string`, you need to specify the encoding method
+             * @defaultValue utf8
+             */
+            encoding?: string;
+        }
+    }
+}
+export default Platform;

package/types/plugins/basic_command/$.d.ts

@@ -0,0 +1,2 @@
+import { HZEngineCore } from "../../index.js";
+export declare function $_command(core: HZEngineCore): void;

package/types/plugins/basic_command/audio.d.ts

@@ -0,0 +1,2 @@
+import { HZEngineCore } from "../../index.js";
+export declare function audio_command(core: HZEngineCore): void;

package/types/plugins/basic_command/basic.d.ts

@@ -0,0 +1,3 @@
+import { HZEngineCore } from "../../index.js";
+export declare function basic_commands(core: HZEngineCore): void;
+export declare function sayAction(core: HZEngineCore, who: string, what: string, wait: boolean): void;

package/types/plugins/basic_command/character.d.ts

@@ -0,0 +1,2 @@
+import { HZEngineCore } from "../../index.js";
+export declare function character_command(core: HZEngineCore): void;

package/types/plugins/basic_command/conditional.d.ts

@@ -0,0 +1,2 @@
+import { HZEngineCore } from "../../index.js";
+export declare function conditional(core: HZEngineCore): void;

package/types/plugins/basic_command/config.d.ts

@@ -0,0 +1,2 @@
+import { HZEngineCore } from "../../index.js";
+export declare function config_command(core: HZEngineCore): void;

package/types/plugins/basic_command/decorator.d.ts

@@ -0,0 +1,2 @@
+import { HZEngineCore } from "../../index.js";
+export declare function decorator_module(core: HZEngineCore): void;

package/types/plugins/basic_command/eval.d.ts

@@ -0,0 +1,2 @@
+import { HZEngineCore } from "../../index.js";
+export declare function eval_module(core: HZEngineCore): void;

package/types/plugins/basic_command/img.d.ts

@@ -0,0 +1,2 @@
+import { HZEngineCore } from "../../index.js";
+export declare function img(core: HZEngineCore): void;

package/types/plugins/basic_command/index.d.ts

@@ -0,0 +1,2 @@
+import { HZEngineCore } from "../../index.js";
+export declare function basic_command(core: HZEngineCore): void;

package/types/plugins/basic_command/menu.d.ts

@@ -0,0 +1,2 @@
+import { HZEngineCore } from "../../index.js";
+export declare function menu_statement(core: HZEngineCore): void;

package/types/plugins/global_gesture/index.d.ts

@@ -0,0 +1,2 @@
+import { HZEngineCore } from "../../index.js";
+export declare function global_gesture(core: HZEngineCore): void;

package/types/plugins/transform/animation.d.ts

@@ -0,0 +1,131 @@
+/**
+ * animation.js
+ * @description A library for providing multi-track animations for HZEngine. 一个用于在HZEngine中提供简单动画的库
+ * @date 2024/10/2
+ * @author CuberQAQ
+ */
+export declare class Animation<P extends Profile.PropsType = unknown> {
+    normalizedProfile: Profile.Track<P>;
+    initProps: Partial<P>;
+    activeRootTrack: ActiveTrackNode<P> | null;
+    lastTime: number;
+    onFrame: ((props: Partial<P>) => void) | null;
+    onEnd: (() => void) | null;
+    customWrappers: Record<string, Wrapper>;
+    constructor(profile: Profile<P>, options?: Animation.Options<P>);
+    onStop: ((animation: Animation<P>) => void) | null;
+    serialize(): Animation.Serialized;
+    static unserialize(serialized: Animation.Serialized, wrappers?: Record<string, Wrapper>): Animation<unknown>;
+    timerCb(): void;
+    init(): void;
+    goto(time: number): void;
+    step(delta_time: number): void;
+    calcProps(): Partial<P>;
+    reverse(): void;
+    stop(): void;
+    _accessProfile(accessKeys: string[]): unknown;
+    _getWrapper(wrapper: string | Wrapper | undefined): Wrapper;
+    _calcWrappedProps<P extends Profile.PropsType>(former_props: Partial<P>, props: Partial<P>, wrapper: Wrapper | string | undefined, progress: number): Partial<P>;
+}
+export declare namespace Animation {
+    interface Options<P extends Profile.PropsType> {
+        initProps?: Partial<P>;
+        wrappers?: Record<string, Wrapper>;
+    }
+    interface Serialized {
+        normalizedProfile: Profile.Serialized;
+        initProps?: Partial<unknown>;
+        activeRootTrack?: ActiveTrackNode.Serialized;
+        lastTime: number;
+    }
+}
+export type Profile<P extends Profile.PropsType = unknown> = Profile.Section<P> | Profile.Track<P> | Profile.TrackList<P>;
+export declare namespace Profile {
+    type Serialized = Profile;
+    type TrackList<P extends PropsType> = Track<P>[];
+    type Track<P extends PropsType> = Section<P>[];
+    type Section<P extends PropsType> = {
+        time?: number;
+        repeat?: number;
+        wrapper?: keyof typeof buildInWrappers | string | Wrapper;
+        frame?: Partial<P>;
+        syncs?: Profile<P>[];
+        asyncs?: Profile<P>[];
+    };
+    type FrameItem = number | boolean | string;
+    type PropsType = Record<string, FrameItem> | unknown;
+    function normalize<P extends PropsType>(profile: Profile<P>): Track<P>;
+}
+export interface Timer<TimerIdType> {
+    init(animation: Animation): void;
+    setTimeout(timeout?: number): TimerIdType;
+    clearTimeout(timerId: TimerIdType): void;
+    setInterval(interval?: number): TimerIdType;
+    clearInterval(timerId: TimerIdType): void;
+    getTime(): number;
+    setOption?(option: Timer.Options): void;
+}
+export declare namespace Timer {
+    interface Options {
+        fps?: number;
+    }
+}
+export declare class ActiveTrackNode<P extends Profile.PropsType> {
+    #private;
+    animation: Animation;
+    accessKeys: string[];
+    currentIndex: number | null;
+    repeated: number;
+    status: ActiveTrackNode.Status;
+    now_time: number;
+    get currentSection(): Profile.Section<P>;
+    get currentTrack(): Profile.Track<P> | null;
+    lastProps: Partial<P>;
+    nowProps: Partial<P>;
+    constructor(animation: Animation, { accessKeys, index, initProps, }: {
+        accessKeys: string[];
+        index: number | null;
+        initProps: Partial<P>;
+    });
+    serialize(): ActiveTrackNode.Serialized;
+    static unserialize<P>(animation: Animation, serialized: ActiveTrackNode.Serialized): ActiveTrackNode<P>;
+    /**
+     *
+     * @param delta_time
+     * @returns 剩餘的時間
+     */
+    step(delta_time: number): number;
+    calcProps(): Partial<P>;
+    _switchNextSection(): boolean;
+    activeSyncs: ActiveTrackNode<P>[];
+    initSyncs(): void;
+    stepSyncs(delta_time: number): number;
+    checkSyncsFinished(): boolean;
+    getSyncsProps(): Partial<P>;
+}
+export declare namespace ActiveTrackNode {
+    enum Status {
+        Playing = 0,
+        WaitingSyncs = 1,
+        Pause = 2
+    }
+    interface Serialized {
+        accessKeys: string[];
+        currentIndex: number | null;
+        repeated: number;
+        status: ActiveTrackNode.Status;
+        now_time: number;
+        lastProps: Partial<unknown>;
+        nowProps: Partial<unknown>;
+        activeSyncs: ActiveTrackNode.Serialized[];
+    }
+}
+export type Wrapper = (x: number) => number;
+declare const buildInWrappers: {
+    none: (x: number) => 0 | 1;
+    linear: (x: number) => number;
+    easeout: (x: number) => number;
+    easein: (x: number) => number;
+    easeinout: (x: number) => number;
+};
+export {};

package/types/plugins/transform/commands.d.ts

@@ -0,0 +1,7 @@
+import { HZEngineCore } from "../../index.js";
+export declare function registerHzscriptCommands(core: HZEngineCore): void;
+export declare function getTransitionMap(core: HZEngineCore): Record<string, TransitionData>;
+export type TransitionData = {
+    inTransforms: string[];
+    outTransforms: string[];
+};

package/types/plugins/transform/example_profiles.d.ts

@@ -0,0 +1,2 @@
+import { Profile } from "./animation.js";
+export declare const ExampleProfile1: Profile;

package/types/plugins/transform/hz_anime.d.ts

@@ -0,0 +1,51 @@
+import { HZEngineCore, Storage, UI } from "../../index.js";
+import { Animation, Profile, Wrapper } from "./animation.js";
+export declare class AnimationPlugin {
+    _core: HZEngineCore;
+    constructor(_core: HZEngineCore);
+    private accessor _nextAnimationId;
+    private accessor _animationMap;
+    private _lastCbUtc;
+    applyAnimation<P extends Profile.PropsType>({ profile, targetView, options, }: {
+        profile: Profile<P>;
+        targetView: UI.View<Storage.Saveable<unknown>>;
+        options?: AnimationPlugin.Options;
+    }): number;
+    stopAnimation(id: number): void;
+    private _nextTempAnimationId;
+    _tempAnimationMap: Record<string, Animation>;
+    createTempAnimation<P extends Profile.PropsType = unknown>({ profile, onFrame, onEnd, initProps, wrappers, }: {
+        profile: Profile<P>;
+        onFrame?: (props: Partial<P>) => void;
+        onEnd?: () => void;
+        initProps?: Partial<P>;
+        wrappers?: Record<string, Wrapper>;
+    }): number;
+    clearTempAnimation(id: number): void;
+    private _timerCb;
+    private _frameCb;
+    private _linkAnimationCb;
+    private _endCb;
+}
+declare namespace AnimationPlugin {
+    interface Options {
+        destroyOnEnd?: boolean;
+        isSave?: boolean;
+        customWrappers?: Record<string, Wrapper>;
+    }
+    interface AnimationItem {
+        destroyOnEnd: boolean;
+        isSave: boolean;
+        targetViewId: number;
+        instance: Animation;
+    }
+    namespace AnimationItem {
+        interface Serialized {
+            destroyOnEnd: boolean;
+            isSave: boolean;
+            targetViewId: number;
+            serializedInstance: Animation.Serialized;
+        }
+    }
+}
+export {};

package/types/plugins/transform/index.d.ts

@@ -0,0 +1,13 @@
+import { HZEngineCore, Storage, UI } from "../../index.js";
+import { AnimationPlugin } from "./hz_anime.js";
+import { Animation, Profile } from "./animation.js";
+import { TransitionData } from "./commands.js";
+export declare function registerPlugin(core: HZEngineCore): InstanceType;
+export interface InstanceType {
+    applyTransform(names: string[], target: UI.View<Storage.Saveable<unknown>>, isSave?: boolean, destroyOnEnd?: boolean): void;
+    getProfile(name: string): Profile | null;
+    createStrategy(outTransforms: string[] | null, inTransforms: string[] | null): UI.Router.RouteStrategy;
+    animationPlugin: AnimationPlugin;
+    getTransition(name: string): TransitionData | null;
+}
+export { Animation, Profile, AnimationPlugin };

package/types/script/index.d.ts

@@ -0,0 +1,123 @@
+import { HZEngineCore } from "../index.js";
+import { Storage } from "../storage/index.js";
+import { mergeObjs2Str as joinObjs2Str, splitStr2Objs } from "./strtools.js";
+export declare class Script {
+    _core: HZEngineCore;
+    constructor(_core: HZEngineCore);
+    /**
+     * 调用栈
+     * 在call时保存当前执行位置和语句栈，在return时恢复执行位置和语句栈
+     */
+    private accessor _callStack;
+    /**
+     * 语句栈
+     * 比如while, if，会在语句开始时入栈，语句结束时出栈
+     */
+    private accessor _statementStack;
+    /**
+     * 下一次执行的脚本位置
+     * 注意：存储该值的时候应总是拷贝赋值而非直接引用赋值
+     */
+    private accessor _nextRunPosition;
+    /**
+     * 执行_nextRunPosition，并返回下一行_nextRunPosition是否不为null
+     */
+    runSingleLine(): boolean;
+    /**
+     * 跳转到目标标签
+     * @param targetLabel
+     */
+    jumpLabel(targetLabel: string): void;
+    jump(path: string, index: number, clearStatementStack?: boolean): void;
+    /**
+     * 调用目标标签
+     * 保存当前执行位置至调用栈，跳转到目标位置，直到return返回
+     * @param targetLabel
+     */
+    callLabel(targetLabel: string): void;
+    hasLabel(targetLabel: string): boolean;
+    return(): void;
+    clear(): void;
+    private _locateLabel;
+    incrementNextPosition(): void;
+    private _middlewares;
+    use(middleware: Script.Middleware, add_front?: boolean): void;
+    private _processCmd;
+    private _processUnsolvedCmd;
+    private _buildContext;
+    private _statementAnalyseStack;
+    private _analyseStatementMiddlewares;
+    private _buildAnalyseStatementContext;
+    useAnalyseStatement(middleware: Script.MiddlewareForAnalyseStatement, add_front?: boolean): void;
+    /**
+     * 分析statement
+     *
+     * Analyze the statement syntax and record the script point location and related information in advance.
+     * When the script executes a statement, the regular middleware corresponding to that statement will load
+     * the information saved by analyseStatement before the statement, and if there is no analysis, it will call
+     * analyseStatement to analyze, and the corresponding analysis middleware will process and save the information.
+     * After analysis is complete, reset _nextRunPosition to the location before the call, switch back to the normal mode,
+     * and continue executing.
+     */
+    analyseStatement(ctx: Script.Context): void;
+    evalScope(code: string): any;
+    evalExpression(code: string): any;
+    parseString(str: string): string;
+}
+export declare namespace Script {
+    type Middleware = (ctx: Context, next: () => void) => void;
+    class Context {
+        protected _core: HZEngineCore;
+        private _rawtext;
+        readonly currentPath: string;
+        readonly currentLineIndex: number;
+        private _statementStack;
+        constructor(_core: HZEngineCore, _rawtext: string, currentPath: string, currentLineIndex: number, _statementStack: StatementStack);
+        get rawtext(): string;
+        set rawtext(rawtext: string);
+        private _rawtextChanged;
+        private _slicedArgs;
+        get slicedArgs(): Context.SlicedArg[];
+        set slicedArgs(slicedArgs: Context.SlicedArg[]);
+        /**
+         * 開始一個新的Statement，返回該Statement的數據
+         * Start a new statement and return the data of the new statement
+         * @param identifier the identifier of the statement
+         * @returns the data of the new statement
+         */
+        startStatement(identifier: string, data?: Storage.Saveable<unknown>): StatementData;
+        endStatement(identifier: string): NonNullable<Storage.Saveable<unknown>>;
+        get statementStack(): StatementStack;
+        getStatementData(): NonNullable<Storage.Saveable<unknown>>;
+        setStatementData(statement_data: NonNullable<Storage.Saveable<unknown>>, start_position: [path: string, index: number]): void;
+    }
+    namespace Utils {
+        export const joinSlicedArgs: typeof joinObjs2Str;
+        export const splitRawtext: typeof splitStr2Objs;
+        export function splitCommas(rawtext: string): string[];
+        export function parseTuple(rawtext: string): TupleOrArr;
+        export function parseArray(rawtext: string): TupleOrArr;
+        export function parseHzsArgs(rawtext: string): TupleOrArr;
+        type TupleOrArr = (string | TupleOrArr)[];
+        export {};
+    }
+    type MiddlewareForAnalyseStatement = (ctx: ContextForAnalyseStatement, next: () => void) => void;
+    class ContextForAnalyseStatement extends Context {
+        startStatement(identifier: string, data?: Storage.Saveable<unknown>): StatementData;
+        endStatement(identifier: string): NonNullable<Storage.Saveable<unknown>>;
+    }
+    namespace Context {
+        interface SlicedArg {
+            str: string;
+            isQuoted?: boolean;
+            isSquared?: boolean;
+        }
+    }
+    type StatementStackItem = [
+        identifier: string,
+        start_position: [path: string, index: number],
+        statement_data: Storage.JSONValue
+    ];
+    type StatementStack = StatementStackItem[];
+    type StatementData = NonNullable<Storage.JSONValue>;
+}

package/types/script/readscript.d.ts

@@ -0,0 +1,2 @@
+import { HZEngineCore } from "../index.js";
+export declare function readline(_core: HZEngineCore, path: string, line_index: number): string | undefined;

package/types/script/strtools.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 将一行字符串切割为(str,quoted)[]的形式
+ * @param str
+ * @returns
+ */
+export declare function splitStr2Objs(str: string): {
+    str: string;
+    isQuoted?: boolean;
+    isSquared?: boolean;
+    isRounded?: boolean;
+}[];
+export declare function mergeObjs2Str(objs: {
+    str: string;
+    isQuoted?: boolean;
+    isSquared?: boolean;
+    isRounded?: boolean;
+}[]): string;
+export declare function splitStr2Strs(str: string): string[];
+/**
+ * 转义一遍字符串，使其中\n等变成对应字符（可能报错）
+ * @param str
+ * @returns
+ */
+export declare function transformStr(str: string): any;
+export declare function parseInterpolatedStr(str: string): ParsedInterpolationItem[];
+export declare function removeComment(str: string): string;
+type ParsedInterpolationItem = {
+    str: string;
+    isExpression: boolean;
+};
+export {};

package/types/storage/decorator.d.ts

@@ -0,0 +1,41 @@
+import { HZEngineCore, Platform, Storage } from "../index.js";
+/**
+ * 存档属性装饰器
+ * @param store_key 保存数据到存档数据对象的key
+ * @returns
+ */
+export declare function Save<PlatformType extends Platform, This extends {
+    _core: HZEngineCore;
+}, Value extends Storage.Saveable<Value>>(store_key: string): (target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>) => ClassAccessorDecoratorResult<This, Value>;
+/**
+ * 存档属性装饰器
+ * @param store_key 保存数据到存档数据对象的key
+ * @returns
+ */
+export declare function CustomSave<PlatformType extends Platform, This extends {
+    _core: HZEngineCore;
+}, Value, SerializedValue extends Storage.Saveable<SerializedValue>>(store_key: string, serializer: (this: This, value: Value) => SerializedValue, deserializer: (this: This, value: SerializedValue) => Value): (target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>) => ClassAccessorDecoratorResult<This, Value>;
+export declare function SaveGetter<PlatformType extends Platform, This extends {
+    _core: HZEngineCore<PlatformType>;
+}, Value extends Storage.Saveable<Value>>(store_key: string): (target: ClassGetterDecoratorTarget<PlatformType, This, Value>, context: ClassGetterDecoratorContext<This, Value>) => (this: This) => Value;
+export declare function CustomSaveGetter<PlatformType extends Platform, This extends {
+    _core: HZEngineCore<PlatformType>;
+}, Value, SerializedValue extends Storage.Saveable<SerializedValue>>(store_key: string, serializer: (this: This, value: Value) => SerializedValue): (target: ClassGetterDecoratorTarget<PlatformType, This, Value>, context: ClassGetterDecoratorContext<This, Value>) => (this: This) => Value;
+/**
+ * 存档属性装饰器
+ * @param store_key 保存数据到存档数据对象的key
+ * @returns
+ */
+export declare function SaveSetter<PlatformType extends Platform, This extends {
+    _core: HZEngineCore<PlatformType>;
+}, Value extends Storage.Saveable<Value>>(store_key: string): (target: ClassSetterDecoratorTarget<PlatformType, This, Value>, context: ClassSetterDecoratorContext<This, Value>) => (this: This, value: Value) => void;
+export declare function CustomSaveSetter<PlatformType extends Platform, This extends {
+    _core: HZEngineCore<PlatformType>;
+}, Value, SerializedValue extends Storage.Saveable<SerializedValue>>(store_key: string, deserializer: (this: This, value: SerializedValue) => Value): (target: ClassSetterDecoratorTarget<PlatformType, This, Value>, context: ClassSetterDecoratorContext<This, Value>) => (this: This, value: Value) => void;
+type ClassGetterDecoratorTarget<PlatformType extends Platform, This extends {
+    _core: HZEngineCore<PlatformType>;
+}, Value> = (this: This) => Value;
+type ClassSetterDecoratorTarget<PlatformType extends Platform, This extends {
+    _core: HZEngineCore<PlatformType>;
+}, Value> = (this: This, value: Value) => void;
+export {};

package/types/storage/fs.d.ts

@@ -0,0 +1 @@
+export {};