/**
 * Физика — raycast, velocity, импульсы, взрывы.
 * Phase 6.5: добавлены Rapier3D методы setBodyType/applyImpulseV2/setVelocityV2.
 */
declare namespace game.physics {
    /**
     * Phase 6.5: переключить примитив в режим Rapier-физики.
     * @param ref ref примитива.
     * @param bodyType 'dynamic' (катится/падает) | 'static' (не двигается)
     *                 | 'kinematic' (двигается скриптом, столкновения учитываются)
     *                 | 'none' (отключить Rapier).
     * @param opts mass, friction (0..1), restitution (упругость 0..1).
     * @example
     * const ball = game.scene.spawn('primitive:sphere', { x:0, y:10, z:0 });
     * game.physics.setBodyType(ball, 'dynamic', { mass: 2, restitution: 0.7 });
     * // мяч падает и отскакивает от земли
     */
    function setBodyType(
        ref: game.Ref,
        bodyType: 'dynamic' | 'static' | 'kinematic' | 'none',
        opts?: { mass?: number; friction?: number; restitution?: number }
    ): void;

    /**
     * Phase 6.5: настоящий импульс Rapier (для тел в режиме 'dynamic').
     * В отличие от applyImpulse, тело реально двигается под физикой.
     */
    function applyImpulseV2(ref: game.Ref, ix: number, iy: number, iz: number): void;
    function setVelocityV2(ref: game.Ref, vx: number, vy: number, vz: number): void;

    /**
     * Луч от origin в направлении dir. Возвращает первое попадание или null.
     * @example
     * const hit = game.physics.raycast(
     *     game.player.position,
     *     game.player.forward,
     *     { maxDist: 50, ignored: ['ref_self'] }
     * );
     * if (hit) game.log('Попал:', hit.ref, 'на расстоянии', hit.distance);
     */
    function raycast(
        origin: game.Vector3,
        dir: game.Vector3,
        opts?: {
            maxDist?: number;
            ignored?: game.Ref[];
        }
    ): {
        hit: boolean;
        point?: game.Vector3;
        ref?: game.Ref;
        distance?: number;
        normal?: game.Vector3;
    } | null;

    /**
     * Задать скорость объекту (для физически-анимированных тел).
     */
    function setVelocity(ref: game.Ref, vx: number, vy: number, vz: number): void;

    /**
     * Применить мгновенный импульс к объекту.
     */
    function applyImpulse(ref: game.Ref, ix: number, iy: number, iz: number): void;

    /**
     * Взрыв в точке: визуал + урон в радиусе игроку и мобам.
     * @example
     * game.physics.explode(game.player.position, 5, { damage: 50, force: 10 });
     */
    function explode(
        pos: game.Vector3,
        radius: number,
        opts?: { damage?: number; force?: number }
    ): void;

    /**
     * Проходимость объекта/группы (collision groups через теги).
     */
    function passThrough(target: game.Ref | string, enabled: boolean): void;
}
