/**
 * UI и HUD: текст поверх viewport (счёт, таймер, метки),
 * 2D-интерфейс из элементов (frame/text/button/image/textbox/scroll).
 */
declare namespace game {
    interface UiApi {
        /** Счётчик в правом верхнем углу. null убирает. */
        score: number | string | null;

        /** Таймер (секунды) в правом верхнем углу. null убирает. */
        timer: number | null;

        /**
         * Большой текст по центру экрана на N секунд.
         * @example game.ui.showText('Победа!', 3);
         */
        showText(text: string | number, seconds?: number): void;

        /**
         * Произвольная именованная метка на HUD.
         * @example
         * game.ui.set('hp_label', `HP: ${game.player.hp}`,
         *             { x: 10, y: 10, color: '#fff', size: 20 });
         */
        set(id: string, text: string | number | null, opts?: {
            x?: number; y?: number;
            color?: game.Color; size?: number;
        }): void;

        /** Убрать метку по id. */
        remove(id: string): void;

        /** Стереть весь HUD. */
        clear(): void;
    }
    const ui: UiApi;

    /** Показ/скрытие стандартного HUD (HP-бар, hotbar, миникарта). */
    namespace hud {
        function setVisible(visible: boolean): void;
        function reset(): void;
    }

    interface GuiProps {
        id?: string;
        type?: game.GuiType;
        name?: string;
        parentId?: string | null;
        x?: number; y?: number; w?: number; h?: number;
        anchor?: game.GuiAnchor;
        /**
         * Phase 6.3.1: AnchorPoint -- точка ВНУТРИ элемента, относительно которой
         * считается x/y. {x:0,y:0} = левый верх, {x:0.5,y:0.5} = центр (по умолч.),
         * {x:1,y:1} = правый низ. Удобно для центрирования всплывающих окон.
         */
        anchorPoint?: { x: number; y: number };
        visible?: boolean;
        bgColor?: game.Color; bgOpacity?: number;
        borderColor?: game.Color; borderWidth?: number; borderRadius?: number;
        text?: string;
        textColor?: game.Color; textSize?: number;
        textAlign?: 'left' | 'center' | 'right';
        fontWeight?: number;
        imageUrl?: string;
        placeholder?: string;
        shadow?: boolean;
        /**
         * Phase 6.3.2: авто-раскладка детей контейнера (только для frame/scroll).
         *   'none' -- дети по своим x/y
         *   'vertical' -- в столбик
         *   'horizontal' -- в строку
         *   'grid' -- сетка (требует layoutCellW/H/Cols)
         */
        layout?: 'none' | 'vertical' | 'horizontal' | 'grid';
        /** Отступ между детьми (в % от размера контейнера). */
        layoutGap?: number;
        /** Внутреннее поле (в % от размера контейнера). */
        layoutPad?: number;
        /** Phase 6.3.2: размер ячейки в grid-layout (%). */
        layoutCellW?: number;
        layoutCellH?: number;
        /** Phase 6.3.2: число колонок в grid (0 = авто). */
        layoutCols?: number;
    }

    namespace gui {
        function find(name: string): string | null;
        function all(): string[];
        function get(id: string): game.GuiProps | null;
        function update(id: string, patch: Partial<game.GuiProps>): void;
        function show(id: string): void;
        function hide(id: string): void;
        /**
         * Создать новый GUI-элемент. Возвращает id.
         * @example
         * const lbl = game.gui.create('text', {
         *     x: 50, y: 10, text: 'Привет!', textColor: '#fff',
         * });
         */
        function create(type: game.GuiType, opts?: Partial<game.GuiProps>): string;
        function remove(id: string): void;
        /** Клик по кнопке. id или имя. */
        function onClick(idOrName: string, fn: (event: { id: string }) => void): void;
        /** Изменение текста в TextBox. */
        function onChange(idOrName: string, fn: (event: { id: string; text: string }) => void): void;
        /** Submit в TextBox (Enter). */
        function onSubmit(idOrName: string, fn: (event: { id: string; text: string }) => void): void;
    }
}
