import { BlockCustomComponent, ItemCustomComponent, Entity, StartupEvent, Player, ScriptEventCommandMessageAfterEvent, Vector3 as Vector3$1 } from '@minecraft/server';

declare const isOptional: unique symbol;
declare class Optional<T = any> {
    private value;
    static none<T>(): Optional<T>;
    static some<T>(value?: T): Optional<T>;
    constructor(value: T);
    private [isOptional];
    unwrap(): T;
    isEmpty(): boolean;
    orElse(other: T): T;
    use<R = any>(fn: (v: T) => R, self?: any): R extends Optional ? R : Optional<R>;
}

interface Component<Actor> {
    onTick(dt: number): void;
    detach(): void;
    getManager(): ComponentManager<Actor>;
    getEntity(): Optional<Actor>;
}
interface BasicComponent<Actor> extends Component<Actor> {
    onAttach(manager: ComponentManager<Actor>): boolean | void | Promise<boolean | void>;
    onDetach(manager: ComponentManager<Actor>): void | Promise<void>;
}
declare const REFLECT_MANAGER: unique symbol;
declare const REFLECT_ENTITY: unique symbol;
declare class CustomComponent<Actor> implements Component<Actor> {
    [REFLECT_MANAGER]?: ComponentManager<Actor>;
    [REFLECT_ENTITY]: Optional<Actor>;
    onTick(dt: number): void;
    detach(): boolean;
    getManager(): ComponentManager<Actor>;
    getEntity(): Optional<Actor>;
    lazyGet<T extends ComponentCtor<unknown>>(ctor: T): InstanceType<T>;
}
declare class BaseComponent<Actor> extends CustomComponent<Actor> implements BasicComponent<Actor> {
    onAttach(manager: ComponentManager<Actor>): boolean | void | Promise<boolean | void>;
    onDetach(manager: ComponentManager<Actor>): void | Promise<void>;
}
interface ComponentCtor<Actor, T extends Component<Actor> | BasicComponent<Actor> = Component<Actor>> {
    new (...args: any[]): T;
}
declare class ComponentManager<Actor> {
    #private;
    static profilerEnable: boolean;
    static readonly global: ComponentManager<unknown>;
    getComponentUnsafe<T extends ComponentCtor<Actor>>(ctor: T): InstanceType<T>;
    getComponent<T extends Component<Actor>>(ctor: ComponentCtor<Actor, T>): Optional<T>;
    getComponents(...ctor: ComponentCtor<Actor>[]): (Component<Actor> | undefined)[];
    attachComponent(...component: Component<Actor>[]): Optional<Component<Actor>>[];
    getOrCreate<T extends Component<Actor>>(ctor: ComponentCtor<Actor, T>, ...args: any[]): Promise<Optional<T>>;
    detachComponent(ctor: ComponentCtor<Actor>): boolean;
    clear(): void;
    getComponentKeys(): MapIterator<ComponentCtor<Actor, Component<Actor>>>;
    has(ctor: ComponentCtor<Actor>): boolean;
    afterTick(fn: (en: Optional<Actor>) => void): void;
    beforeTick(fn: (en: Optional<Actor>) => void): void;
    handleTicks(en: Actor, dt: number): void;
    update<T extends Component<Actor>>(ctor: ComponentCtor<Actor, T>, fn: (component: T) => void): boolean;
    profiler(fn: Function, component?: Component<Actor>, name?: string): any;
}
type RequireComponentsParam<Actor> = ComponentCtor<Actor> | [ComponentCtor<Actor>, ...any[]];
declare const REQUIRED_COMPONENTS: unique symbol;
interface RequiredComponent<Actor> extends BasicComponent<Actor> {
    getComponent<T extends Component<Actor>>(ctor: ComponentCtor<Actor>): T;
}
declare function RequireComponents<Actor>(...params: RequireComponentsParam<Actor>[]): {
    new (): {
        getComponent<T extends Component<Actor>>(ctor: ComponentCtor<Actor>): T;
        [REQUIRED_COMPONENTS]: Map<ComponentCtor<Actor, Component<Actor>>, Component<Actor>>;
        onAttach(manager: ComponentManager<Actor>): boolean | void | Promise<boolean | void>;
        onDetach(manager: ComponentManager<Actor>): void | Promise<void>;
        onTick(dt: number): void;
        detach(): boolean;
        getManager(): ComponentManager<Actor>;
        getEntity(): Optional<Actor>;
        lazyGet<T extends ComponentCtor<unknown>>(ctor: T): InstanceType<T>;
        [REFLECT_MANAGER]?: ComponentManager<Actor> | undefined;
        [REFLECT_ENTITY]: Optional<Actor>;
    };
};
/**
 * 使用前请保证组件已存在
 * @param manager
 * @param ctor
 * @returns
 */
declare function lazyGet<T extends ComponentCtor<unknown>>(component: Component<unknown>, ctor: T): InstanceType<T>;

/**
 * 注册方块自定义组件（自动保证 `system.beforeEvents.startup` 时机）。
 * 在方块 JSON 里仍须用 `BlockComponent.setCustomComponents(['<id>'])` 声明同名组件。
 */
declare function registerBlockComponent(id: string, handlers: BlockCustomComponent): void;
/**
 * 注册物品自定义组件（自动保证 `system.beforeEvents.startup` 时机）。
 * ⚠️ 物品要能触发 `onUse`，还必须在物品上声明 `minecraft:interact_button`（见 AGENTS.md）。
 */
declare function registerItemComponent(id: string, handlers: ItemCustomComponent): void;
/**
 * 注册**框架内置的兜底**方块自定义组件：只有当项目**没有**自己注册同一 id 时才真正注册。
 *
 * 语义（判定发生在 `system.beforeEvents.startup`，见文件头注释）：
 * - 项目没注册该 id → 内置实现生效；
 * - 项目注册了该 id → **项目实现生效**，内置实现被跳过，并打一条 warn（不是错误）；
 * - 重复登记同一个内置 id（`registerBuiltinComponents()` 被调两次）→ **幂等**，只算一次。
 *
 * ⚠️ 与 `registerBlockComponent` 的差别只有「撞 id 时的方向」：
 * 前者是「项目说了算」，后者是「项目之间重复 = 编程错误 → 抛」。
 * 框架内置组件必须用本函数，否则每一个在历史上手工注册过该 id 的项目升级后都会开不了机。
 *
 * @param id 组件 id，必须与方块 JSON 里写的那个键完全相同
 * @param handlers 处理器对象（与 `registerBlockComponent` 同一套事件名）
 */
declare function registerFallbackBlockComponent(id: string, handlers: BlockCustomComponent): void;
/** 物品侧的兜底注册（与 `registerFallbackBlockComponent` 语义完全一致，见其注释） */
declare function registerFallbackItemComponent(id: string, handlers: ItemCustomComponent): void;
/** 已排队但尚未注册的组件数（启动前 > 0 属正常；不含框架兜底组件） */
declare function pendingComponentCount(): number;
/** 已成功注册的组件列表（形如 `block:fz:machine`），用于运行期自检 */
declare function registeredComponents(): string[];
/**
 * 因「项目已注册同 id」而被跳过的**内置兜底**组件列表（形如 `block:sapdon:block_with_entity`）。
 *
 * 用途：运行期自检时区分「内置实现生效」与「项目实现生效」
 * （两者都正常，但排查「方块行为不对」时第一个要看的就是它）。
 */
declare function skippedFallbackComponents(): string[];

type AxisValue = number | [number, number] | [number, number, number];
interface IKeyState {
    pressing: boolean;
    times: number;
    consume(): void;
}
interface InputKeyMapping {
    Jump: boolean;
    Sneak: boolean;
    Attack: boolean;
    Interact: boolean;
    Sprint: boolean;
}
interface InputAxisMapping {
    Movement: [number, number];
}
declare class PlayerInputComponent<Actor> extends BaseComponent<Actor> {
    readonly keyStateMapping: Map<string, IKeyState>;
    readonly axisMapping: Map<string, AxisValue>;
    inputKey(key: keyof InputKeyMapping, pressing: boolean): void;
    inputAxis(key: keyof InputAxisMapping, value: AxisValue): void;
    getKeyState(key: keyof InputKeyMapping): IKeyState | undefined;
    getAxis(key: keyof InputAxisMapping): AxisValue | undefined;
    getKeyPressing(key: keyof InputKeyMapping): boolean;
    getKeyPressTimes(key: keyof InputKeyMapping): number;
    exhaust(key: keyof InputKeyMapping): void;
    combineAxis(axis1: AxisValue, axis2: AxisValue): number[];
    splitAxis(axis: Exclude<AxisValue, number>, nDim1: number, nDim2?: number): number[][];
}

interface Scheduler<Actor> {
    get currentTick(): number;
    start(table: Map<string, ComponentManager<Actor>>): void;
    stop(): void;
    timeDilation: number;
}
declare abstract class Level<T> {
    readonly table: Map<string, ComponentManager<any>>;
    addEntity(entityId: string): ComponentManager<unknown>;
    removeEntity(entityId: string): void;
    getManager(entityId: string): ComponentManager<any>;
    abstract getScheduler(): Scheduler<T>;
    start(): void;
    stop(): void;
}

type ConstructorOf<T, Args extends unknown[] = []> = new (...args: Args) => T;

declare function initialize(gameInstanceCls: ConstructorOf<GameInstance>, conf?: any): void;
declare function finalize(gameInstance: GameInstance): void;
interface GameInstance<A = any> {
    onStart(conf: any): void;
    shutdown(): void;
    setLevel(lvl: Level<A>): Level<A>;
    getLevel(): Level<A>;
}
declare const GameInstance: (target: Function) => void;
declare function getGameInstanceClass(): ConstructorOf<GameInstance<any>> | undefined;
declare function getGameInstance(): GameInstance<any> | undefined;

declare class ArrayEx extends Array {
    constructor(init?: number[]);
    set(arr: Iterable<number>): void;
}

interface Vector3 {
    x: number;
    y: number;
    z: number;
}
declare class Vec3 extends ArrayEx implements Vector3 {
    x: number;
    y: number;
    z: number;
    constructor(init: number[]);
    static fromXYZ(x: number, y: number, z: number): Vec3;
    static fromVec3(vec3: Vector3): Vec3;
    static m(vec3: Vector3): number;
    m(): number;
    static isZero(vec: Vector3): boolean;
    isZero(): boolean;
    static normalize(vec: Vector3): false | undefined;
    n(): false | undefined;
    static add(vec1: Vector3, vec2: Vector3): Vec3;
    add(vec: Vector3): Vec3;
    static sub(vec1: Vector3, vec2: Vector3): Vec3;
    sub(vec: Vector3): Vec3;
    static mul(vec: Vector3, scalar: number): Vec3;
    mul(scalar: number): Vec3;
    static div(vec: Vector3, scalar: number): Vec3;
    div(scalar: number): Vec3;
    static dot(vec1: Vector3, vec2: Vector3): number;
    dot(vec: Vector3): number;
    static cross(vec1: Vector3, vec2: Vector3): Vec3;
    cross(vec: Vector3): Vec3;
    valueOf(): ArrayEx;
    toString(): string;
}

declare class Matrix extends ArrayEx {
    constructor();
    get m11(): any;
    get m12(): any;
    get m13(): any;
    get m14(): any;
    get m21(): any;
    get m22(): any;
    get m23(): any;
    get m24(): any;
    get m31(): any;
    get m32(): any;
    get m33(): any;
    get m34(): any;
    get m41(): any;
    get m42(): any;
    get m43(): any;
    get m44(): any;
    set m11(v: any);
    set m12(v: any);
    set m13(v: any);
    set m14(v: any);
    set m21(v: any);
    set m22(v: any);
    set m23(v: any);
    set m24(v: any);
    set m31(v: any);
    set m32(v: any);
    set m33(v: any);
    set m34(v: any);
    set m41(v: any);
    set m42(v: any);
    set m43(v: any);
    set m44(v: any);
    get a(): any;
    get b(): any;
    get c(): any;
    get d(): any;
    get e(): any;
    get f(): any;
    set a(v: any);
    set b(v: any);
    set c(v: any);
    set d(v: any);
    set e(v: any);
    set f(v: any);
    static init(init: Iterable<number>, mapfn: (v: number, k: number) => number, thisArg?: any): Matrix;
    clone(): Matrix;
    setIdentity(): this;
    static identity(): Matrix;
    static add(m1: Matrix, m2: Matrix): Matrix;
    add(m: Matrix): Matrix;
    static sub(m1: Matrix, m2: Matrix): Matrix;
    sub(m: Matrix): Matrix;
    setTranslation(x: number, y: number, z: number): this;
    setRotation(angle: number, axis: Vec3): this;
    setScale(x: number, y: number, z: number): this;
    setRotationX(angle: number): this;
    setRotationY(angle: number): this;
    setRotationZ(angle: number): this;
    setRotationXYZ(yaw: number, pitch: number, roll: number): this;
    static translate(mat: Matrix, vec: Vector3): Matrix;
    translate(vec: Vector3): Matrix;
    static transpose(mat: Matrix): any[];
    transpose(): any[];
    static multiply(mat1: Matrix, t: Matrix | Vector4): number[] | Vec4;
    multiply(t: Matrix | Vector4): number[] | Vec4;
    valueOf(): ArrayEx;
    toString(): string;
    static perspective(fov: number, aspect: number, near: number, far: number): number[];
    static orthographic(right: number, top: number, near: number, far: number): number[];
    static lookAt(eye: Vector3, target: Vector3, up: Vector3): number[];
}

interface Vector4 extends Vector3 {
    w: number;
}
declare class Vec4 extends ArrayEx implements Vector4 {
    x: number;
    y: number;
    z: number;
    w: number;
    constructor(init: number[]);
    static fromXYZW(x: number, y: number, z: number, w: number): Vec4;
    static fromVec3(vec3: Vector4): Vec4;
    static fromVec4(vec4: Vector4): Vec4;
    static m(vec: Vector4): number;
    m(): number;
    static isZero(vec: Vector4): boolean;
    isZero(): boolean;
    static normalize(vec: Vector4): false | undefined;
    n(): false | undefined;
    static add(vec1: Vector4, vec2: Vector4): Vec4;
    add(vec: Vector4): Vec4;
    static sub(vec1: Vector4, vec2: Vector4): Vec4;
    sub(vec: Vector4): Vec4;
    static mul(vec: Vector4, scalar: number): Vec4;
    mul(scalar: number): Vec4;
    static div(vec: Vector4, scalar: number): Vec4;
    div(scalar: number): Vec4;
    static dot(vec1: Vector4, vec2: Vector4): number;
    dot(vec: Vector4): number;
    static multiply(vec: Vector4, mat: Matrix): number[] | Vec4;
    multiply(mat: Matrix): number[] | Vec4;
    valueOf(): ArrayEx;
    toString(): string;
}

declare namespace MathExt {
    function clamp(val: number, min: number, max: number): number;
    function lerps(a: number, b: number, scalar: number): number;
    function lerpVec3(a: Vec3, b: Vec3, scalar: number): Vec3;
    function lerpVec4(a: Vec4, b: Vec4, scalar: number): Vec4;
    function lerp(a: number, b: number, scalar: number): number;
    function lerp(a: Vec3, b: Vec3, scalar: number): Vec3;
    function lerp(a: Vec4, b: Vec4, scalar: number): Vec4;
}

declare class MinecraftTickingScheduler implements Scheduler<string> {
    private _run;
    private _currentTick;
    private _timeStamp;
    get currentTick(): number;
    _handleTick(table: Map<string, ComponentManager<any>>, dt: number): void;
    executeTick(table: Map<string, ComponentManager<any>>): void;
    start(table: Map<string, ComponentManager<any>>): void;
    stop(): void;
    timeDilation: number;
}
declare class MinecraftLevel extends Level<Entity> {
    readonly scheduler: MinecraftTickingScheduler;
    getScheduler(): Scheduler<Entity>;
}
declare abstract class MinecraftGameInstance implements GameInstance {
    level?: Level<Entity>;
    setLevel(lvl: Level<Entity>): Level<Entity>;
    getLevel(): Level<Entity>;
    /**
     * 在 Startup 阶段完成时运行
     * @param ev
     */
    onStart(ev: StartupEvent): void;
    /**
     * 在 shutdown 阶段运行
     */
    shutdown(): void;
    /**
     * 在 onStart 之后运行，用于绑定监听器等 (onStart时没有权限进行绑定)
     */
    afterStart(): void;
}

declare function assertInMinecraft(): void;
declare const Minecraft: ClassDecorator;
declare const MinecraftMain: (target: any) => void;
declare const PlayerSpawned: (...deps: ComponentCtor<Player>[]) => (target: any) => void;
declare const EntitySpawned: (...deps: ComponentCtor<Player>[]) => (target: any) => void;
declare const ActorSpawned: (...deps: ComponentCtor<Player>[]) => (target: any) => void;
declare const SpawnFilter: (filter: (entity: Entity) => boolean) => (target: any) => void;

declare class MinecraftPlayerInputComponent extends PlayerInputComponent<Entity> {
    private playerRef;
    onTick(): void;
    syncAxisAndButtons(): void;
}

declare function MinecraftMethod(target: any, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor;
declare class Utils {
    toPlayer(entity: Entity): Optional<Player>;
    start(): void;
}
declare const utils: Utils;

declare abstract class HudComponent<Actor, Hud> extends CustomComponent<Actor> {
    hud?: Hud;
    actor: Optional<Actor>;
    abstract render(): Hud;
    abstract draw(): void;
    onTick(dt: number): void;
}

declare abstract class PlayerHudComponent extends HudComponent<Player, string> {
    abstract render(): string;
    draw(): void;
}

declare const ScriptEvent: {
    on: (evType: string, handler: (ev: ScriptEventCommandMessageAfterEvent) => void) => void;
    off: (evType: string, handler: (ev: ScriptEventCommandMessageAfterEvent) => void) => void;
    (evType: string): MethodDecorator;
};

/**
 * 分块动态属性读写（`world` / `Entity` / `ItemStack` 通用）。
 *
 * ## 为什么框架要内建
 * Bedrock 单个动态属性值长度有上限（约 **32KB** 量级），超限时 `setDynamicProperty` **抛错**。
 * 项目侧手写时一旦把这段包进 `try-catch`，就会变成**静默丢存档**（症状：重进世界后数据回到早期快照）。
 * AGENTS.md 记的 `digitCircuit` 事故与 `lr-framework` 的 `BaseEngine.save` 都是这个坑。
 * 所以这里把「分块 + 清理残留 + 不吞异常」固化成框架接口。
 *
 * ## 存储格式（与既有实现互通）
 * - 小数据（≤ {@link CHUNK_SIZE}）：主 key 直接存**原字符串**。
 * - 大数据：数据块 `"<key>#0" … "<key>#N-1"`，主 key 存 `{"_chunks":N}`。
 *   与 `examples/lr-framework/.../BaseEngine.ts` 的 `save/load`、
 *   `digitCircuit` 的 `CIRCUIT_CHUNK=24000` 方案**完全一致**，可互相读取。
 * - **提交点**：数据块先写、主 key 后写。中途失败时主 key 仍指向上一份完整数据，
 *   不会留下「半新半旧」的可读结果。
 *
 * ## 空值语义（★ 与 `BaseEngine` 的坑不同）
 * `loadChunked` 返回 `undefined` = **从没存过**；返回 `''` = **存过空串**。
 * ⚠️ 判断时请用 `=== undefined`，**不要**用真值判断（`if (!v)` 会把空串当没存过）。
 *
 * ## 异常约定
 * **本模块不吞任何异常**：写入失败、分块缺失、类型不符一律抛出。
 * 调用方若确实要容错，请自行 catch 并**至少打印日志**，不要静默忽略。
 */
/** 单个数据块的字符数上限（与 BaseEngine / digitCircuit 一致，安全低于约 32KB 的引擎上限） */
declare const CHUNK_SIZE = 24000;
/** 分块键后缀：`<key>#<index>` */
declare const CHUNK_SUFFIX = "#";
/**
 * 无 `getDynamicPropertyIds()` 时的兜底扫描上界。
 * 有该 API 时按实际存在的键精确清理，不受此值限制。
 */
declare const MAX_CHUNK_SCAN = 256;
/** `setDynamicProperty` 允许的取值 */
type DynamicPropertyValue = boolean | number | string | Vector3$1;
/**
 * 分块读写所需的最小目标接口。
 * `world`（World）/ `Entity` / `ItemStack` / 容器槽位均满足；单测里可用内存对象顶替。
 */
interface DynamicPropertyTarget {
    getDynamicProperty(identifier: string): DynamicPropertyValue | undefined;
    setDynamicProperty(identifier: string, value?: DynamicPropertyValue): void;
    /** 可选：@minecraft/server 的 World/Entity/ItemStack 均提供，用于精确清理残留分块 */
    getDynamicPropertyIds?(): string[];
}
/** 第 index 个数据块的键名 */
declare function chunkKey(key: string, index: number): string;
/** 主 key 里表示「已分块」的元数据 JSON，如 `{"_chunks":3}` */
declare function chunkMetaJson(count: number): string;
/**
 * 解析主 key 的分块元数据。
 * 只有「恰好是一个仅含整型 `_chunks` 的对象」才算分块，其余一律返回 undefined。
 */
declare function parseChunkCount(raw: unknown): number | undefined;
/**
 * 该字符串是否**长得像**分块元数据。
 * 这类值必须强制分块，否则 `{"_chunks":2}` 这样的原文会被 `loadChunked` 误判成元数据。
 */
declare function looksLikeChunkMeta(value: string): boolean;
/** 按 size 切分字符串（纯函数，可单测） */
declare function splitValue(value: string, size?: number): string[];
/**
 * 分块写入字符串（幂等：同一份数据连存两次结果一致）。
 *
 * @throws 值不是字符串、或底层 `setDynamicProperty` 抛错（如超限）时**原样抛出**
 */
declare function saveChunked(target: DynamicPropertyTarget, key: string, value: string): void;
/**
 * 读取字符串。
 * @returns `undefined` = 从没存过；`''` = 存过空串
 * @throws 分块数据缺失/损坏，或主 key 被非字符串占用时
 */
declare function loadChunked(target: DynamicPropertyTarget, key: string): string | undefined;
/**
 * 彻底清除：主 key + **所有**数据块（含旧存档残留的更高序号块）。
 * 清完 `loadChunked` 返回 `undefined`（回到「从没存过」）。
 */
declare function clearChunked(target: DynamicPropertyTarget, key: string): void;

/**
 * 注册框架内置的自定义组件。
 *
 * ★ `sapdon:block_with_entity` 走的是**兜底**通道（`registerFallbackBlockComponent`）：
 *   `TileBlock` 会给**每个**带实体方块挂上这个组件（`src/core/block/tileBlock.js:184`），
 *   而历史上框架自己从不注册它 —— 忘了手工注册的项目会**整份方块被引擎丢掉**
 *   （`this component was found in the input, but is not present in the Schema`）。
 *   走兜底而不是直接注册，是为了**不打断既有项目**：项目自己注册了同一个 id 时，
 *   **项目实现生效**、内置实现被跳过（并打一条 warn）。
 *   完整理由与三种场景见 `src/oc/components/registry.ts` 的文件头注释。
 */
declare function registerBuiltinComponents(): void;

export { ActorSpawned, BaseComponent, CHUNK_SIZE, CHUNK_SUFFIX, ComponentManager, CustomComponent, EntitySpawned, GameInstance, HudComponent, MAX_CHUNK_SCAN, MathExt, Matrix, Minecraft, MinecraftGameInstance, MinecraftLevel, MinecraftMain, MinecraftMethod, MinecraftPlayerInputComponent, MinecraftTickingScheduler, Optional, PlayerHudComponent, PlayerInputComponent, PlayerSpawned, RequireComponents, ScriptEvent, SpawnFilter, Vec3, Vec4, assertInMinecraft, chunkKey, chunkMetaJson, clearChunked, finalize, getGameInstance, getGameInstanceClass, initialize, lazyGet, loadChunked, looksLikeChunkMeta, parseChunkCount, pendingComponentCount, registerBlockComponent, registerBuiltinComponents, registerFallbackBlockComponent, registerFallbackItemComponent, registerItemComponent, registeredComponents, saveChunked, skippedFallbackComponents, splitValue, utils };
export type { AxisValue, BasicComponent, Component, ComponentCtor, DynamicPropertyTarget, DynamicPropertyValue, IKeyState, InputAxisMapping, InputKeyMapping, RequiredComponent, Vector3, Vector4 };