fl-web-component 2.2.2 → 2.2.4

package/packages/components/com-graphics/index.vue

@@ -22,11 +22,91 @@
         <div class="loading-text">{{ modelLoadingState.text }}</div>
       </div>
     </div>
+    <el-dialog
+      class="roaming-settings-dialog"
+      title="漫游设置"
+      width="520px"
+      :visible.sync="roamingSettingsVisible"
+      :append-to-body="true"
+      :close-on-click-modal="false"
+      @close="handleRoamingSettingsDialogClose"
+    >
+      <el-form
+        v-if="roamingSettingsDraft"
+        ref="roamingSettingsForm"
+        :model="roamingSettingsDraft"
+        label-width="100px"
+        size="small"
+        class="roaming-settings-form"
+      >
+        <div class="roaming-settings-section-title">视角</div>
+        <el-form-item label="视角">
+          <el-radio-group
+            v-model="roamingSettingsDraft.perspective"
+            class="roaming-settings-perspective"
+          >
+            <el-radio label="first-person">第一人称</el-radio>
+            <el-radio label="third-person">第三人称</el-radio>
+          </el-radio-group>
+        </el-form-item>
+
+        <div class="roaming-settings-section-title">人物属性</div>
+        <el-form-item label="人物身高">
+          <el-input
+            v-model.number="roamingSettingsDraft.height"
+            type="number"
+            :min="roamingSettingsLimits.height.min"
+            :max="roamingSettingsLimits.height.max"
+            :step="1"
+            class="roaming-settings-height"
+          >
+            <span slot="append">cm</span>
+          </el-input>
+        </el-form-item>
+        <el-form-item label="设置障碍">
+          <el-select
+            v-model="roamingSettingsDraft.collisionEnabled"
+            class="roaming-settings-control"
+          >
+            <el-option label="开启" :value="true"></el-option>
+            <el-option label="关闭" :value="false"></el-option>
+          </el-select>
+        </el-form-item>
+        <el-form-item label="移动速度">
+          <el-slider
+            v-model="roamingSettingsDraft.moveSpeed"
+            :min="roamingSettingsLimits.moveSpeed.min"
+            :max="roamingSettingsLimits.moveSpeed.max"
+            :step="roamingSettingsLimits.moveSpeed.step"
+          ></el-slider>
+        </el-form-item>
+        <el-form-item label="鼠标速度">
+          <el-slider
+            v-model="roamingSettingsDraft.mouseSpeed"
+            :min="roamingSettingsLimits.mouseSpeed.min"
+            :max="roamingSettingsLimits.mouseSpeed.max"
+            :step="roamingSettingsLimits.mouseSpeed.step"
+          ></el-slider>
+        </el-form-item>
+      </el-form>
+      <div slot="footer" class="roaming-settings-footer">
+        <el-button size="small" @click="cancelRoamingSettings">取消</el-button>
+        <el-button size="small" type="primary" @click="confirmRoamingSettings">确定</el-button>
+      </div>
+    </el-dialog>
   </div>
 </template>
 <script>
 var singleFrameTime = 1 / 30;
 var dragThreshold = 5; // 拖拽阈值，像素单位
+const ORIENTATION_AXIS_VIEWPORT_SIZE = 120;
+const ORIENTATION_AXIS_VIEWPORT_MARGIN = 16;
+const ORIENTATION_AXIS_LENGTH = 0.68;
+const ORIENTATION_AXIS_HEAD_LENGTH = 0.21;
+const ORIENTATION_AXIS_HEAD_RADIUS = 0.12;
+const ORIENTATION_AXIS_SHAFT_RADIUS = 0.045;
+const ORIENTATION_AXIS_LABEL_OFFSET = 0.12;
+const ORIENTATION_AXIS_LABEL_SIZE = 0.3;
 
 // camera-controls 相机限位参数，见 setCameraConfig / applyCameraBoundary
 // minDistance 是相机到目标点的最小距离，取场景最大边长的千分之一，并夹在上下限之间。
@@ -38,7 +118,7 @@ var orbitMinDistanceCeiling = 50;
 // 相机离目标点的最远距离，按场景包围盒对角线倍数给
 var orbitMaxDistanceRatio = 3;
 // 目标点可活动范围相对场景包围盒的外扩倍数（1 表示不超出包围盒）
-var orbitBoundaryRatio = 1.5;
+var orbitBoundaryRatio = 3;
 // 左键切换旋转中心时，命中点与当前目标点的最小位移（占场景最大边长比例），小于该值视为重复点击
 var orbitPointMoveRatio = 1e-4;
 
@@ -154,6 +234,14 @@ var clippingMesh = [],
 
 const FIRST_PERSON_GROUND_HEIGHT = 1680;
 const FIRST_PERSON_POINTER_SPEED = 0.3;
+const THIRD_PERSON_MODEL_NAME = '__third_person_roaming_avatar__';
+const THIRD_PERSON_CAMERA_DISTANCE = 12500;
+const THIRD_PERSON_CAMERA_MIN_DISTANCE_RATIO = 1;
+const THIRD_PERSON_CAMERA_MAX_DISTANCE_MULTIPLIER = 10;
+const THIRD_PERSON_CAMERA_HEIGHT_RATIO = 0.65;
+const THIRD_PERSON_COLLISION_RADIUS_RATIO = 0.16;
+const THIRD_PERSON_GRAVITY = 9800;
+const THIRD_PERSON_GROUND_SNAP_DISTANCE = 12;
 
 var removeSpeed = 1000,
   upSpeed = 200; //控制器移动速度 , //控制跳起时的速度
@@ -162,6 +250,40 @@ var roamConfig = {
   speed: 0, // 最大值为3
   name: '',
 };
+const ROAMING_SETTINGS_DEFAULTS = Object.freeze({
+  perspective: 'first-person',
+  height: 168,
+  collisionEnabled: true,
+  moveSpeed: 1,
+  mouseSpeed: 1,
+});
+const ROAMING_SETTINGS_LIMITS = Object.freeze({
+  height: { min: 0.1, max: 250 },
+  moveSpeed: { min: 0.01, max: 5, step: 0.01 },
+  mouseSpeed: { min: 0.01, max: 5, step: 0.01 },
+});
+
+function createRoamingSettings(config) {
+  const source = config && typeof config === 'object' ? config : {};
+  const settings = { ...ROAMING_SETTINGS_DEFAULTS };
+  if (source.perspective === 'first-person' || source.perspective === 'third-person') {
+    settings.perspective = source.perspective;
+  }
+  if (typeof source.collisionEnabled === 'boolean') {
+    settings.collisionEnabled = source.collisionEnabled;
+  }
+  ['height', 'moveSpeed', 'mouseSpeed'].forEach(key => {
+    const value = Number(source[key]);
+    if (Number.isFinite(value)) {
+      settings[key] = value;
+    }
+  });
+  return settings;
+}
+
+function copyRoamingSettings(config) {
+  return { ...createRoamingSettings(config) };
+}
 var guiParams = {
   x轴: 0,
   y轴: 0,
@@ -281,6 +403,8 @@ import { OutlinePass } from 'three/examples/jsm/postprocessing/OutlinePass.js';
 import { OutputPass } from 'three/examples/jsm/postprocessing/OutputPass.js';
 import Stats from 'three/examples/jsm/libs/stats.module.js';
 import { OBB } from 'three/examples/jsm/math/OBB.js';
+import { MeshLineGeometry, MeshLineMaterial } from 'meshline';
+import workerModelUrl from './assets/worker.glb';
 // import boxJson from './box.json';
 import {
   StreamLoader,
@@ -293,8 +417,8 @@ import { EDITOR_EVENT, SCENE_NODE_TYPE, TRANSFORM_MODE } from '@/utils/threejs/e
 import { isCustomRoot, isTransformAttachableObject } from '@/utils/threejs/editor/scene-helpers.js';
 import { onContextHandle } from './component/context';
 
-const isDebug = process.env.NODE_ENV !== 'production' || process.env.VUE_APP_IS_WATCH === true;
-// const isDebug = false;
+let isDebug = process.env.NODE_ENV !== 'production' || process.env.VUE_APP_IS_WATCH === true;
+// isDebug = false;
 const COLLISION_CONTACT_EPSILON = 0.1;
 const COLLISION_OBB_AXIS_EPSILON = 1e-8;
 const COLLISION_CONNECTION_DISTANCE_TOLERANCE = 1;
@@ -380,6 +504,11 @@ export default {
         visible: false,
         text: '加载中',
       },
+      roamingSettingsVisible: false,
+      roamingSettingsDraft: null,
+      roamingSettings: createRoamingSettings(),
+      roamingSettingsCloseReason: '',
+      roamingSettingsLimits: ROAMING_SETTINGS_LIMITS,
       isolateMode: false,
       // collisionObbDebugEnabled: isDebug,
       sceneBoundingBoxDebugEnabled: isDebug,
@@ -428,6 +557,9 @@ export default {
       'velocity',
       'direction',
       'clock',
+      'firstPersonMouseSpeed',
+      'firstPersonCollisionEnabled',
+      'firstPersonActorHeight',
       'pointControls',
       'threeMeasure',
       'modelGroup',
@@ -443,7 +575,14 @@ export default {
       'centeringDebounceTimer',
       'sceneBoundingBox',
       'sceneBoundingBoxHelper',
+      'globalClippingBoundsHelper',
       'collisionObbDebugGroup',
+      '_thirdPersonState',
+      '_thirdPersonMixer',
+      '_thirdPersonPointerLockHandler',
+      '_thirdPersonMouseMoveHandler',
+      '_thirdPersonWheelHandler',
+      '_thirdPersonPointerErrorHandler',
       'occlusionBoundsDebugGroup',
     ];
     arr.forEach(item => {
@@ -653,6 +792,9 @@ export default {
     this.initSceneCommandService();
     this.initCamera();
     this.initControl();
+    if (this._orientationAxisEnabled !== false) {
+      this.initOrientationAxis();
+    }
     this.initTransformControls();
     this.initPostProcessing();
     // 初始化统一的相机事件监听
@@ -673,6 +815,187 @@ export default {
     this.destroyScene();
   },
   methods: {
+    setOrientationAxisEnabled(enabled = true) {
+      this._orientationAxisEnabled = enabled !== false;
+      if (!this._orientationAxisEnabled) {
+        this.disposeOrientationAxis();
+        return;
+      }
+
+      if (!this._orientationAxisState && this.THREE) {
+        this.initOrientationAxis();
+      }
+    },
+    initOrientationAxis() {
+      const THREE = this.THREE;
+      const state = {
+        scene: new THREE.Scene(),
+        camera: new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 10),
+        group: new THREE.Group(),
+        inverseCameraQuaternion: new THREE.Quaternion(),
+        renderSize: new THREE.Vector2(),
+        previousViewport: new THREE.Vector4(),
+        previousScissor: new THREE.Vector4(),
+        resources: {
+          geometries: [],
+          materials: [],
+          textures: [],
+        },
+      };
+      this._orientationAxisState = state;
+
+      state.camera.position.set(0, 0, 3);
+      state.camera.lookAt(0, 0, 0);
+
+      const axes = [
+        { label: 'X', color: 0xff453a, direction: new THREE.Vector3(1, 0, 0) },
+        { label: 'Y', color: 0x30d158, direction: new THREE.Vector3(0, 1, 0) },
+        { label: 'Z', color: 0x0a84ff, direction: new THREE.Vector3(0, 0, 1) },
+      ];
+      const up = new THREE.Vector3(0, 1, 0);
+      const shaftLength = ORIENTATION_AXIS_LENGTH - ORIENTATION_AXIS_HEAD_LENGTH;
+
+      axes.forEach(axis => {
+        const material = new THREE.MeshBasicMaterial({
+          color: axis.color,
+          depthTest: true,
+          depthWrite: true,
+          toneMapped: false,
+        });
+        const shaftGeometry = new THREE.CylinderGeometry(
+          ORIENTATION_AXIS_SHAFT_RADIUS,
+          ORIENTATION_AXIS_SHAFT_RADIUS,
+          shaftLength,
+          8
+        );
+        const headGeometry = new THREE.ConeGeometry(
+          ORIENTATION_AXIS_HEAD_RADIUS,
+          ORIENTATION_AXIS_HEAD_LENGTH,
+          10
+        );
+        const orientation = new THREE.Quaternion().setFromUnitVectors(up, axis.direction);
+        const shaft = new THREE.Mesh(shaftGeometry, material);
+        const head = new THREE.Mesh(headGeometry, material);
+
+        shaft.position.copy(axis.direction).multiplyScalar(shaftLength / 2);
+        head.position
+          .copy(axis.direction)
+          .multiplyScalar(ORIENTATION_AXIS_LENGTH - ORIENTATION_AXIS_HEAD_LENGTH / 2);
+        shaft.quaternion.copy(orientation);
+        head.quaternion.copy(orientation);
+        state.group.add(shaft, head);
+
+        state.resources.geometries.push(shaftGeometry, headGeometry);
+        state.resources.materials.push(material);
+
+        const texture = this.createOrientationAxisLabelTexture(axis.label);
+        if (texture) {
+          const labelMaterial = new THREE.SpriteMaterial({
+            map: texture,
+            transparent: true,
+            depthTest: true,
+            depthWrite: false,
+            toneMapped: false,
+          });
+          const label = new THREE.Sprite(labelMaterial);
+          label.position
+            .copy(axis.direction)
+            .multiplyScalar(ORIENTATION_AXIS_LENGTH + ORIENTATION_AXIS_LABEL_OFFSET);
+          label.scale.set(ORIENTATION_AXIS_LABEL_SIZE, ORIENTATION_AXIS_LABEL_SIZE, 1);
+          label.renderOrder = 2;
+          state.group.add(label);
+          state.resources.materials.push(labelMaterial);
+          state.resources.textures.push(texture);
+        }
+      });
+
+      state.scene.add(state.group);
+    },
+    createOrientationAxisLabelTexture(text) {
+      const canvas = document.createElement('canvas');
+      canvas.width = 128;
+      canvas.height = 128;
+      const context = canvas.getContext('2d');
+      if (!context) return null;
+
+      context.font = '700 88px Arial, sans-serif';
+      context.textAlign = 'center';
+      context.textBaseline = 'middle';
+      context.lineJoin = 'round';
+      context.lineWidth = 9;
+      context.strokeStyle = 'rgba(255, 255, 255, 0.9)';
+      context.strokeText(text, 64, 68);
+      context.fillStyle = '#17202a';
+      context.fillText(text, 64, 68);
+
+      const texture = new this.THREE.CanvasTexture(canvas);
+      texture.colorSpace = this.THREE.SRGBColorSpace;
+      texture.generateMipmaps = false;
+      texture.minFilter = this.THREE.LinearFilter;
+      texture.magFilter = this.THREE.LinearFilter;
+      texture.needsUpdate = true;
+      return texture;
+    },
+    syncOrientationAxis() {
+      const state = this._orientationAxisState;
+      if (!state || !this.camera) return;
+
+      this.camera.getWorldQuaternion(state.inverseCameraQuaternion);
+      state.group.quaternion.copy(state.inverseCameraQuaternion).invert();
+    },
+    renderOrientationAxis() {
+      const renderer = this.renderer;
+      const state = this._orientationAxisState;
+      if (this._orientationAxisEnabled === false || !renderer || !state) return;
+
+      renderer.getSize(state.renderSize);
+      const viewportSize = Math.min(
+        ORIENTATION_AXIS_VIEWPORT_SIZE,
+        state.renderSize.x,
+        state.renderSize.y
+      );
+      if (!viewportSize) return;
+
+      const x = Math.max(
+        0,
+        Math.min(ORIENTATION_AXIS_VIEWPORT_MARGIN, state.renderSize.x - viewportSize)
+      );
+      const y = Math.max(
+        0,
+        Math.min(ORIENTATION_AXIS_VIEWPORT_MARGIN, state.renderSize.y - viewportSize)
+      );
+      const previousRenderTarget = renderer.getRenderTarget();
+      const previousScissorTest = renderer.getScissorTest();
+      const previousAutoClear = renderer.autoClear;
+      renderer.getViewport(state.previousViewport);
+      renderer.getScissor(state.previousScissor);
+
+      try {
+        renderer.setRenderTarget(null);
+        renderer.setViewport(x, y, viewportSize, viewportSize);
+        renderer.setScissor(x, y, viewportSize, viewportSize);
+        renderer.setScissorTest(true);
+        renderer.autoClear = false;
+        renderer.clearDepth();
+        renderer.render(state.scene, state.camera);
+      } finally {
+        renderer.autoClear = previousAutoClear;
+        renderer.setRenderTarget(previousRenderTarget);
+        renderer.setViewport(state.previousViewport);
+        renderer.setScissor(state.previousScissor);
+        renderer.setScissorTest(previousScissorTest);
+      }
+    },
+    disposeOrientationAxis() {
+      const state = this._orientationAxisState;
+      if (!state) return;
+
+      state.resources.geometries.forEach(geometry => geometry.dispose());
+      state.resources.materials.forEach(material => material.dispose());
+      state.resources.textures.forEach(texture => texture.dispose());
+      state.scene.clear();
+      this._orientationAxisState = null;
+    },
     bindScenePointerEvents() {
       if (!this.renderer || !this.renderer.domElement) return;
       this.renderer.domElement.addEventListener('pointerup', this.mouseClick, true);
@@ -3725,6 +4048,8 @@ export default {
         }
       }
       cam.far = newFar;
+      // cam.far = 200;
+      // cam.near = 0.1;
       cam.updateProjectionMatrix();
     },
     /**
@@ -5301,14 +5626,17 @@ export default {
      * @param {Function} [config.boxLoadingText] - 自定义进度文案函数
      * @param {Function} [config.onBoxProgress] - 包围盒下载进度回调
      * @param {boolean} [config.showModelLoading=true] - 是否显示模型加载（裁剪 → 请求 → 分批上屏）进度提示
+     * @param {boolean} [config.showOrientationAxis=true] - 是否显示左下角 XYZ 坐标轴
      * @param {string} [config.modelLoadingText="加载中"] - 自定义模型加载进度文案
      * @param {Function} [config.onStreamProgress] - 几何流式加载阶段回调（透传 StreamLoader 事件）
      */
     init(config = {}) {
       console.log('init');
+      const { showOrientationAxis, ...streamLoaderConfig } = config;
+      this.setOrientationAxisEnabled(showOrientationAxis !== false);
       this.setCameraControlMoveObserverConfig(config);
       this.setProgressiveRenderingConfig(config);
-      this.initStreamLoader(config.modelApi, config);
+      this.initStreamLoader(config.modelApi, streamLoaderConfig);
     },
 
     /**
@@ -6920,7 +7248,7 @@ export default {
         source => {
           // 漫游、第一人称移动、普通视角拖拽/缩放中，使用节流策略避免持续运动被防抖吞掉。
           // 避免在持续运动中因防抖重置定时器而无法触发
-          if (source === 'roam' || source === 'firstPersonMove') {
+          if (source === 'roam' || source === 'firstPersonMove' || source === 'thirdPersonMove') {
             return { type: 'throttle', limit: 1000 };
           }
           if (source === 'controlMove') {
@@ -7077,13 +7405,13 @@ export default {
     drawModel(data, color = '', meshNameConfig = {}, options = {}) {
       // 只打印规模摘要：直接打印 data 会让 DevTools 控制台长期持有整批数据（含全量材质字典）的引用，
       // 分批加载期间这些引用在控制台清空前无法回收，会抬高内存高水位。
+      // data = require('./mock.json');
       console.log('drawModel', {
         material: data.material || [],
         mergeMaterial: data.mergeMaterial || [],
         primitive: data.primitive || [],
         mesh: data.mesh || [],
       });
-      // data = require('./mock.json');
       // 使用新的分帧加载方法，提供进度回调
       return this.drawModelWithBatchLoading(
         data,
@@ -7520,6 +7848,7 @@ export default {
           this.outlinePass.setSize(width, height);
         }
         this.labelRenderer.setSize(width, height);
+        this.updateGlobalClippingBoundsResolution(width, height);
         // this.timeRender()
         // 这里也要更新测量
         if (this.threeMeasure) {
@@ -7755,6 +8084,31 @@ export default {
         }
       }
     },
+    captureBusinessVisibilityState() {
+      const modelState = this.noObserver
+        ? this.noObserver.modelStateManager
+        : this.modelStateManager;
+      return {
+        defaultBusinessVisible: modelState.defaultBusinessVisible,
+        businessVisibilityOverrides: new Map(modelState.businessVisibilityOverrides),
+      };
+    },
+    restoreBusinessVisibilityState(state) {
+      if (!state) return;
+      const modelState = this.noObserver
+        ? this.noObserver.modelStateManager
+        : this.modelStateManager;
+      modelState.defaultBusinessVisible = state.defaultBusinessVisible;
+      modelState.businessVisibilityOverrides = new Map(state.businessVisibilityOverrides || []);
+      this.syncBusinessVisibilityByIds(
+        Array.from(new Set([
+          ...Array.from((this._boxIndex && this._boxIndex.keys()) || []),
+          ...Array.from(modelState.businessVisibilityOverrides.keys()),
+        ]))
+      );
+      this.notifyCameraChange();
+      if (this._boxIndex) this.buildOctreeFromBoxIndex();
+    },
     setAllModelVisible(visible) {
       const isVisible = Boolean(visible);
       const modelState = this.noObserver
@@ -8513,7 +8867,9 @@ export default {
     },
     // 销毁场景 释放内存
     destroyScene() {
+      this.endThirdPersonRoaming();
       cancelAnimationFrame(this.animateId);
+      this.disposeOrientationAxis();
       this.disposeTransformControls();
 
       if (this.sceneCommandEventDisposers.length > 0) {
@@ -8589,6 +8945,7 @@ export default {
       this.resetBusinessVisibilityState();
       this.hideCollisionObbDebug();
       this.hideOcclusionBoundsDebug();
+      this.removeGlobalClippingBoundsHelper();
 
       if (this.scene) {
         this.removeTraverse();
@@ -8733,6 +9090,565 @@ export default {
         this.clock = new this.THREE.Clock();
       }
     },
+    openRoamingSettings(config) {
+      const currentConfig = config ? { ...this.roamingSettings, ...config } : this.roamingSettings;
+      this.roamingSettingsDraft = copyRoamingSettings(currentConfig);
+      this.roamingSettingsCloseReason = '';
+      this.roamingSettingsVisible = true;
+      return this.getRoamingConfig();
+    },
+    getRoamingConfig() {
+      return copyRoamingSettings(this.roamingSettings);
+    },
+    closeRoamingSettings() {
+      if (!this.roamingSettingsVisible) return;
+      this.roamingSettingsCloseReason = 'api';
+      this.roamingSettingsVisible = false;
+    },
+    cancelRoamingSettings() {
+      if (!this.roamingSettingsVisible) return;
+      this.roamingSettingsCloseReason = 'cancel';
+      this.roamingSettingsVisible = false;
+    },
+    handleRoamingSettingsDialogClose() {
+      if (!this.roamingSettingsCloseReason) {
+        this.roamingSettingsCloseReason = 'cancel';
+      }
+      if (this.roamingSettingsCloseReason !== 'confirm') {
+        this.$emit('roaming-settings-cancel');
+      }
+      this.roamingSettingsDraft = null;
+      this.roamingSettingsCloseReason = '';
+    },
+    showRoamingSettingsError(message) {
+      this.$emit('roaming-settings-error', { message });
+      if (this.$message && typeof this.$message.warning === 'function') {
+        this.$message.warning(message);
+      }
+    },
+    validateRoamingSettings() {
+      const draft = this.roamingSettingsDraft;
+      if (!draft) return null;
+
+      const height = Number(draft.height);
+      const moveSpeed = Number(draft.moveSpeed);
+      const mouseSpeed = Number(draft.mouseSpeed);
+      const {
+        height: heightLimit,
+        moveSpeed: moveSpeedLimit,
+        mouseSpeed: mouseSpeedLimit,
+      } = ROAMING_SETTINGS_LIMITS;
+
+      if (draft.height === '' || draft.height === null || !Number.isFinite(height)) {
+        this.showRoamingSettingsError('请输入人物身高');
+        return null;
+      }
+      if (height < heightLimit.min || height > heightLimit.max) {
+        this.showRoamingSettingsError(
+          `人物身高需在 ${heightLimit.min}-${heightLimit.max} cm 范围内`
+        );
+        return null;
+      }
+      if (draft.moveSpeed === '' || draft.moveSpeed === null || !Number.isFinite(moveSpeed)) {
+        this.showRoamingSettingsError('请输入移动速度');
+        return null;
+      }
+      if (moveSpeed < moveSpeedLimit.min || moveSpeed > moveSpeedLimit.max) {
+        this.showRoamingSettingsError(
+          `移动速度需在 ${moveSpeedLimit.min}-${moveSpeedLimit.max} 范围内`
+        );
+        return null;
+      }
+      if (draft.mouseSpeed === '' || draft.mouseSpeed === null || !Number.isFinite(mouseSpeed)) {
+        this.showRoamingSettingsError('请输入鼠标速度');
+        return null;
+      }
+      if (mouseSpeed < mouseSpeedLimit.min || mouseSpeed > mouseSpeedLimit.max) {
+        this.showRoamingSettingsError(
+          `鼠标速度需在 ${mouseSpeedLimit.min}-${mouseSpeedLimit.max} 范围内`
+        );
+        return null;
+      }
+      if (draft.perspective !== 'first-person' && draft.perspective !== 'third-person') {
+        this.showRoamingSettingsError('请选择漫游视角');
+        return null;
+      }
+      if (typeof draft.collisionEnabled !== 'boolean') {
+        this.showRoamingSettingsError('请选择是否设置障碍');
+        return null;
+      }
+
+      return {
+        perspective: draft.perspective,
+        height,
+        collisionEnabled: draft.collisionEnabled,
+        moveSpeed,
+        mouseSpeed,
+      };
+    },
+    confirmRoamingSettings() {
+      const settings = this.validateRoamingSettings();
+      if (!settings) return;
+
+      this.roamingSettings = settings;
+      this.roamingSettingsCloseReason = 'confirm';
+      this.roamingSettingsVisible = false;
+      this.$emit('roaming-settings-confirm', this.getRoamingConfig());
+    },
+    startRoaming() {
+      const settings = this.getRoamingConfig();
+      if (settings.perspective === 'third-person') {
+        return this.startThirdPersonRoaming(settings);
+      }
+      this.endThirdPersonRoaming();
+      this.startFirstPer({
+        moveSpeed: 8000 * settings.moveSpeed,
+        jumpSpeed: 500,
+        mouseSpeed: settings.mouseSpeed,
+        height: settings.height,
+        collisionEnabled: settings.collisionEnabled,
+      });
+      this.$emit('roaming-start', settings);
+      return true;
+    },
+    isRoamingActive() {
+      return !!(this.firstPerSign || this._thirdPersonState);
+    },
+    startThirdPersonRoaming(settings) {
+      if (!this.scene || !this.camera || !this.cameraControls || !this.renderer) {
+        this.showRoamingSettingsError('模型场景尚未准备完成，暂时无法开始第三人称漫游');
+        return false;
+      }
+      this.endThirdPersonRoaming();
+      if (this.pointControls && this.pointControls.isLocked) {
+        this.pointControls.unlock();
+      }
+
+      const config = copyRoamingSettings(settings || this.roamingSettings);
+      const sceneBox = this.sceneBoundingBox;
+      if (!sceneBox || sceneBox.isEmpty()) {
+        this.showRoamingSettingsError('模型空间范围尚未就绪，暂时无法开始第三人称漫游');
+        return false;
+      }
+
+      const target = new this.THREE.Vector3();
+      if (typeof this.cameraControls.getTarget === 'function') {
+        this.cameraControls.getTarget(target);
+      } else if (this.cameraControls._target) {
+        target.copy(this.cameraControls._target);
+      } else {
+        this.camera.getWorldDirection(target);
+        target.multiplyScalar(800).add(this.camera.position);
+      }
+      const direction = this.camera.getWorldDirection(new this.THREE.Vector3());
+      const yaw = Math.atan2(-direction.x, -direction.z);
+      const actorHeight = config.height * 10;
+      const actorPosition = new this.THREE.Vector3(
+        target.x,
+        this.getThirdPersonSpawnHeight(target.x, target.z, sceneBox),
+        target.z
+      );
+
+      this._thirdPersonState = {
+        config,
+        moveSpeed: this.getFirstPersonMoveSpeed(8000 * config.moveSpeed),
+        actorPosition,
+        actorHeight,
+        verticalVelocity: 0,
+        yaw,
+        // worker.glb 的默认正面朝向与相机方向一致，进入第三人称时旋转 180 度背对镜头。
+        avatarYaw: yaw + Math.PI,
+        pitch: 0.22,
+        cameraDistance: (THIRD_PERSON_CAMERA_DISTANCE * config.height) / 168,
+        cameraPosition: this.camera.position.clone(),
+        cameraTarget: target.clone(),
+        avatar: null,
+        walkAction: null,
+        walking: false,
+        loading: true,
+        pointerLocked: false,
+      };
+      this.cameraControls.enabled = false;
+      const initialDistance = this._thirdPersonState.cameraDistance;
+      const initialPitch = this._thirdPersonState.pitch;
+      const initialPosition = new this.THREE.Vector3(
+        target.x + Math.sin(yaw) * Math.cos(initialPitch) * initialDistance,
+        target.y + Math.sin(initialPitch) * initialDistance + actorHeight * 0.15,
+        target.z + Math.cos(yaw) * Math.cos(initialPitch) * initialDistance
+      );
+      this._thirdPersonState.cameraPosition.copy(initialPosition);
+      this.camera.position.copy(initialPosition);
+      this.camera.lookAt(target);
+      this.camera.updateMatrixWorld();
+      this.detachTransformControls();
+      this.unbindScenePointerEvents();
+      document.addEventListener('keydown', this.onThirdPersonKeyDown, false);
+      document.addEventListener('keyup', this.onThirdPersonKeyUp, false);
+      this._thirdPersonMouseMoveHandler = event => this.onThirdPersonMouseMove(event);
+      this._thirdPersonWheelHandler = event => this.onThirdPersonWheel(event);
+      this._thirdPersonPointerLockHandler = () => this.handleThirdPersonPointerLockChange();
+      this._thirdPersonPointerErrorHandler = () => {
+        this.showRoamingSettingsError('浏览器未能锁定鼠标，请点击模型视口后重试');
+        this.endThirdPersonRoaming();
+      };
+      document.addEventListener('mousemove', this._thirdPersonMouseMoveHandler, false);
+      if (this.renderer.domElement) {
+        this.renderer.domElement.addEventListener('wheel', this._thirdPersonWheelHandler, {
+          capture: true,
+          passive: false,
+        });
+      }
+      document.addEventListener('pointerlockchange', this._thirdPersonPointerLockHandler, false);
+      document.addEventListener('pointerlockerror', this._thirdPersonPointerErrorHandler, false);
+      if (this.renderer.domElement && this.renderer.domElement.requestPointerLock) {
+        try {
+          this.renderer.domElement.requestPointerLock();
+        } catch (error) {
+          // 部分浏览器会拒绝自动锁定，仍可通过键盘移动并在视口内点击后获得鼠标控制。
+        }
+      }
+
+      const loader = new GLTFLoader();
+      loader.load(
+        workerModelUrl,
+        gltf => {
+          const state = this._thirdPersonState;
+          if (!state || !this.scene) return;
+          const avatar = gltf.scene;
+          avatar.name = THIRD_PERSON_MODEL_NAME;
+          avatar.updateMatrixWorld(true);
+          const originalBox = new this.THREE.Box3().setFromObject(avatar);
+          const originalHeight = Math.max(originalBox.max.y - originalBox.min.y, 1e-6);
+          const scale = state.actorHeight / originalHeight;
+          avatar.scale.setScalar(scale);
+          state.avatarYOffset = -originalBox.min.y * scale;
+          avatar.position.y = state.avatarYOffset + state.actorPosition.y;
+          avatar.position.x = state.actorPosition.x;
+          avatar.position.z = state.actorPosition.z;
+          avatar.rotation.y = state.avatarYaw;
+          avatar.traverse(object => {
+            if (object.isMesh) {
+              object.frustumCulled = false;
+              object.userData.cull = false;
+            }
+          });
+          state.avatar = avatar;
+          state.loading = false;
+          this.scene.add(avatar);
+          if (gltf.animations && gltf.animations.length) {
+            this._thirdPersonMixer = new this.THREE.AnimationMixer(avatar);
+            state.walkAction = this._thirdPersonMixer.clipAction(gltf.animations[0]);
+            state.walkAction.clampWhenFinished = false;
+            state.walkAction.enabled = true;
+            state.walkAction.stop();
+          }
+          this.$emit('roaming-start', this.getRoamingConfig());
+        },
+        undefined,
+        error => {
+          console.error('第三人称人物模型加载失败', error);
+          this.showRoamingSettingsError('第三人称人物模型加载失败，请检查内置资源');
+          this.endThirdPersonRoaming();
+        }
+      );
+      return true;
+    },
+    endRoaming() {
+      if (this._thirdPersonState) {
+        this.endThirdPersonRoaming();
+        return;
+      }
+      const wasFirstPersonActive = this.firstPerSign;
+      const wasPointerLocked = !!(this.pointControls && this.pointControls.isLocked);
+      if (this.pointControls) {
+        if (this.pointControls.isLocked) this.pointControls.unlock();
+        if (this.pointControls.object && this.pointControls.object.parent === this.scene) {
+          this.scene.remove(this.pointControls.object);
+        }
+      }
+      window.removeEventListener('keydown', this.onKeyDown);
+      window.removeEventListener('keyup', this.onKeyUp);
+      this.pointControls = null;
+      if (this.cameraControls) this.cameraControls.enabled = true;
+      if (this.renderer && this.renderer.domElement) this.bindScenePointerEvents();
+      this.firstPerSign = false;
+      if (!wasFirstPersonActive || !wasPointerLocked) this.$emit('roaming-end');
+    },
+    endThirdPersonRoaming() {
+      const state = this._thirdPersonState;
+      if (!state) return;
+      document.removeEventListener('keydown', this.onThirdPersonKeyDown, false);
+      document.removeEventListener('keyup', this.onThirdPersonKeyUp, false);
+      if (this._thirdPersonMouseMoveHandler) {
+        document.removeEventListener('mousemove', this._thirdPersonMouseMoveHandler, false);
+      }
+      if (this._thirdPersonWheelHandler && this.renderer && this.renderer.domElement) {
+        this.renderer.domElement.removeEventListener('wheel', this._thirdPersonWheelHandler, true);
+      }
+      if (this._thirdPersonPointerLockHandler) {
+        document.removeEventListener(
+          'pointerlockchange',
+          this._thirdPersonPointerLockHandler,
+          false
+        );
+      }
+      if (this._thirdPersonPointerErrorHandler) {
+        document.removeEventListener(
+          'pointerlockerror',
+          this._thirdPersonPointerErrorHandler,
+          false
+        );
+      }
+      const avatar = state.avatar;
+      if (avatar && avatar.parent) avatar.parent.remove(avatar);
+      if (avatar) {
+        avatar.traverse(object => {
+          if (!object.isMesh) return;
+          object.geometry && object.geometry.dispose();
+          const materials = Array.isArray(object.material) ? object.material : [object.material];
+          materials.forEach(material => material && material.dispose());
+        });
+      }
+      if (this._thirdPersonMixer && avatar) this._thirdPersonMixer.uncacheRoot(avatar);
+      this._thirdPersonMixer = null;
+      this._thirdPersonMouseMoveHandler = null;
+      this._thirdPersonWheelHandler = null;
+      this._thirdPersonPointerLockHandler = null;
+      this._thirdPersonPointerErrorHandler = null;
+      if (this.cameraControls && this.camera && state.cameraTarget) {
+        this.cameraControls.setLookAt(
+          this.camera.position.x,
+          this.camera.position.y,
+          this.camera.position.z,
+          state.cameraTarget.x,
+          state.cameraTarget.y,
+          state.cameraTarget.z,
+          false
+        );
+      }
+      this._thirdPersonState = null;
+      if (this.cameraControls) this.cameraControls.enabled = true;
+      if (
+        this.renderer &&
+        this.renderer.domElement &&
+        document.pointerLockElement === this.renderer.domElement
+      ) {
+        document.exitPointerLock && document.exitPointerLock();
+      }
+      if (this.renderer && this.renderer.domElement) this.bindScenePointerEvents();
+      if (this.scene) this.ensureTransformSelectionValid();
+      this.$emit('roaming-end');
+    },
+    onThirdPersonKeyDown(event) {
+      if (!this._thirdPersonState || !event) return;
+      if (![37, 38, 39, 40, 65, 68, 83, 87].includes(event.keyCode)) return;
+      event.preventDefault();
+      if (event.keyCode === 38 || event.keyCode === 87) this.moveForward = true;
+      if (event.keyCode === 40 || event.keyCode === 83) this.moveBackward = true;
+      if (event.keyCode === 37 || event.keyCode === 65) this.moveLeft = true;
+      if (event.keyCode === 39 || event.keyCode === 68) this.moveRight = true;
+    },
+    onThirdPersonKeyUp(event) {
+      if (!this._thirdPersonState || !event) return;
+      this.onKeyUp(event);
+    },
+    onThirdPersonMouseMove(event) {
+      const state = this._thirdPersonState;
+      if (!state || document.pointerLockElement !== this.renderer.domElement) return;
+      const sensitivity = state.config.mouseSpeed * 0.0018;
+      state.yaw -= (event.movementX || 0) * sensitivity;
+      state.pitch = Math.max(
+        -0.2,
+        Math.min(0.8, state.pitch + (event.movementY || 0) * sensitivity)
+      );
+    },
+    onThirdPersonWheel(event) {
+      const state = this._thirdPersonState;
+      if (!state || !event) return;
+      event.preventDefault();
+      event.stopPropagation();
+      if (typeof event.stopImmediatePropagation === 'function') event.stopImmediatePropagation();
+      const baseDistance = (THIRD_PERSON_CAMERA_DISTANCE * state.config.height) / 168;
+      const minDistance = Math.max(state.actorHeight * THIRD_PERSON_CAMERA_MIN_DISTANCE_RATIO, 20);
+      const maxDistance = baseDistance * THIRD_PERSON_CAMERA_MAX_DISTANCE_MULTIPLIER;
+      const delta = Math.max(-240, Math.min(240, event.deltaY || 0));
+      state.cameraDistance = Math.max(
+        minDistance,
+        Math.min(maxDistance, state.cameraDistance + delta * Math.max(baseDistance * 0.001, 0.5))
+      );
+    },
+    handleThirdPersonPointerLockChange() {
+      const state = this._thirdPersonState;
+      if (!state || !this.renderer || !this.renderer.domElement) return;
+      if (document.pointerLockElement === this.renderer.domElement) {
+        state.pointerLocked = true;
+      } else if (state.pointerLocked) this.endThirdPersonRoaming();
+    },
+    canMoveThirdPersonTo(position) {
+      const state = this._thirdPersonState;
+      if (!state || !state.config.collisionEnabled) return true;
+      if (!this._octree && this._boxIndex && this._boxIndex.size) this.buildOctreeFromBoxIndex();
+      const radius = state.actorHeight * THIRD_PERSON_COLLISION_RADIUS_RATIO;
+      const bodyBox = new this.THREE.Box3(
+        new this.THREE.Vector3(
+          position.x - radius,
+          position.y + state.actorHeight * 0.12,
+          position.z - radius
+        ),
+        new this.THREE.Vector3(
+          position.x + radius,
+          position.y + state.actorHeight * 0.9,
+          position.z + radius
+        )
+      );
+      const candidates = this._queryOctreeByBox(bodyBox);
+      return !candidates.some(
+        item => item && item.box && item.box.userData && item.box.userData.visible !== false
+      );
+    },
+    getThirdPersonSpawnHeight(x, z, sceneBox) {
+      if (!sceneBox || sceneBox.isEmpty() || !this.scene) return 0;
+      const origin = new this.THREE.Vector3(x, sceneBox.max.y + 1, z);
+      const raycaster = new this.THREE.Raycaster(
+        origin,
+        new this.THREE.Vector3(0, -1, 0),
+        0,
+        Math.max(sceneBox.max.y - sceneBox.min.y + 2, 1)
+      );
+      const intersections = raycaster.intersectObjects(this.scene.children, true);
+      return intersections.length ? intersections[0].point.y : sceneBox.min.y;
+    },
+    getThirdPersonCameraDistance(state, target, desiredPosition) {
+      if (!this._octree && this._boxIndex && this._boxIndex.size) this.buildOctreeFromBoxIndex();
+      const segmentBox = new this.THREE.Box3().setFromPoints([target, desiredPosition]);
+      const radius = Math.max(state.actorHeight * 0.035, 10);
+      segmentBox.expandByScalar(radius);
+      const ray = new this.THREE.Ray(target, desiredPosition.clone().sub(target).normalize());
+      const desiredDistance = target.distanceTo(desiredPosition);
+      let nearestDistance = desiredDistance;
+      this._queryOctreeByBox(segmentBox).forEach(item => {
+        if (!item || !item.box || (item.box.userData && item.box.userData.visible === false))
+          return;
+        const expandedBox = item.box.clone().expandByScalar(radius);
+        const hit = ray.intersectBox(expandedBox, new this.THREE.Vector3());
+        if (hit) {
+          const distance = target.distanceTo(hit);
+          if (distance > radius && distance < nearestDistance) nearestDistance = distance;
+        }
+      });
+      return Math.max(state.actorHeight * 0.65, nearestDistance - radius);
+    },
+    updateThirdPersonGrounding(state, delta) {
+      if (!state || !state.actorPosition || !this.scene || !this.sceneBoundingBox) return;
+      const position = state.actorPosition;
+      const sceneBox = this.sceneBoundingBox;
+      const rayOriginY = position.y + THIRD_PERSON_GROUND_SNAP_DISTANCE;
+      const rayDistance = Math.max(rayOriginY - sceneBox.min.y, THIRD_PERSON_GROUND_SNAP_DISTANCE);
+      const raycaster = new this.THREE.Raycaster(
+        new this.THREE.Vector3(position.x, rayOriginY, position.z),
+        new this.THREE.Vector3(0, -1, 0),
+        0,
+        rayDistance
+      );
+      const groundObjects = this.scene.children.filter(
+        object => object && object.name !== THIRD_PERSON_MODEL_NAME
+      );
+      const intersections = raycaster.intersectObjects(groundObjects, true);
+      const groundHit = intersections[0];
+      const groundHeight = groundHit ? groundHit.point.y : sceneBox.min.y;
+      const distanceToGround = position.y - groundHeight;
+      const snapDistance = Math.max(THIRD_PERSON_GROUND_SNAP_DISTANCE, state.actorHeight * 0.015);
+
+      if (distanceToGround <= snapDistance && state.verticalVelocity <= 0) {
+        position.y = groundHeight;
+        state.verticalVelocity = 0;
+        return;
+      }
+
+      state.verticalVelocity = Math.max(
+        state.verticalVelocity - THIRD_PERSON_GRAVITY * delta,
+        -THIRD_PERSON_GRAVITY
+      );
+      const nextY = position.y + state.verticalVelocity * delta;
+      if (nextY <= groundHeight) {
+        position.y = groundHeight;
+        state.verticalVelocity = 0;
+      } else {
+        position.y = nextY;
+      }
+    },
+    updateThirdPersonRoaming(delta) {
+      const state = this._thirdPersonState;
+      if (!state || !state.avatar || state.loading) return;
+      const elapsed = Math.min(Math.max(delta || 0, 0), 0.05);
+      const forward = Number(this.moveForward) - Number(this.moveBackward);
+      const lateral = Number(this.moveRight) - Number(this.moveLeft);
+      const moving = forward !== 0 || lateral !== 0;
+      if (state.walkAction) {
+        if (moving && !state.walking) {
+          state.walkAction.reset().play();
+          state.walking = true;
+        } else if (!moving && state.walking) {
+          state.walkAction.stop();
+          state.walking = false;
+        }
+      }
+      const length = Math.hypot(forward, lateral) || 1;
+      const speed = state.moveSpeed;
+      const step = speed * elapsed;
+      const moveX =
+        ((-Math.sin(state.yaw) * forward + Math.cos(state.yaw) * lateral) / length) * step;
+      const moveZ =
+        ((-Math.cos(state.yaw) * forward - Math.sin(state.yaw) * lateral) / length) * step;
+      const nextX = state.actorPosition.clone();
+      nextX.x += moveX;
+      if (this.canMoveThirdPersonTo(nextX)) state.actorPosition.x = nextX.x;
+      const nextZ = state.actorPosition.clone();
+      nextZ.z += moveZ;
+      if (this.canMoveThirdPersonTo(nextZ)) state.actorPosition.z = nextZ.z;
+      this.updateThirdPersonGrounding(state, elapsed);
+
+      const avatar = state.avatar;
+      avatar.position.set(
+        state.actorPosition.x,
+        state.actorPosition.y + (state.avatarYOffset || 0),
+        state.actorPosition.z
+      );
+      if (forward !== 0 || lateral !== 0) {
+        // 模型正面沿 +Z，人物朝向实际的相机相对移动方向。
+        state.avatarYaw = Math.atan2(moveX, moveZ);
+      }
+      avatar.rotation.y = state.avatarYaw;
+      if (this._thirdPersonMixer) this._thirdPersonMixer.update(elapsed);
+
+      const target = new this.THREE.Vector3(
+        state.actorPosition.x,
+        state.actorPosition.y + state.actorHeight * THIRD_PERSON_CAMERA_HEIGHT_RATIO,
+        state.actorPosition.z
+      );
+      const horizontalDistance = state.cameraDistance;
+      const pitch = state.pitch;
+      const desiredPosition = new this.THREE.Vector3(
+        target.x + Math.sin(state.yaw) * Math.cos(pitch) * horizontalDistance,
+        target.y + Math.sin(pitch) * horizontalDistance + state.actorHeight * 0.15,
+        target.z + Math.cos(state.yaw) * Math.cos(pitch) * horizontalDistance
+      );
+      const safeDistance = this.getThirdPersonCameraDistance(state, target, desiredPosition);
+      const desiredOffset = desiredPosition
+        .clone()
+        .sub(target)
+        .normalize()
+        .multiplyScalar(safeDistance);
+      desiredPosition.copy(target).add(desiredOffset);
+      const smoothing = 1 - Math.exp(-50 * elapsed);
+      state.cameraPosition.lerp(desiredPosition, smoothing);
+      state.cameraTarget.lerp(target, smoothing);
+      this.camera.position.copy(state.cameraPosition);
+      this.camera.lookAt(state.cameraTarget);
+      this.camera.updateMatrixWorld();
+      if (typeof this._cameraChangeObserver === 'function')
+        this._cameraChangeObserver('thirdPersonMove');
+    },
     //
     // 开启漫游
     /*
@@ -8861,6 +9777,7 @@ export default {
       if (userData.transformControlHelper === true) return true;
       if (userData.collisionObbDebugHelper === true) return true;
       if (userData.occlusionBoundsDebugHelper === true) return true;
+      if (userData.globalClippingBoundsHelper === true) return true;
       if (object.isCamera || object.isLight) return true;
       if (typeof object.type === 'string' && /Helper$/i.test(object.type)) return true;
       return object.type === 'CSS2DObject' || object.type === 'TransformControlsRoot';
@@ -8882,6 +9799,138 @@ export default {
       });
       return box3.isEmpty() ? null : box3;
     },
+    getGlobalClippingBoundsSegments(bounds) {
+      const min = bounds.min;
+      const max = bounds.max;
+      return [
+        [
+          min.x,
+          min.y,
+          min.z,
+          max.x,
+          min.y,
+          min.z,
+          max.x,
+          max.y,
+          min.z,
+          min.x,
+          max.y,
+          min.z,
+          min.x,
+          min.y,
+          min.z,
+        ],
+        [
+          min.x,
+          min.y,
+          max.z,
+          max.x,
+          min.y,
+          max.z,
+          max.x,
+          max.y,
+          max.z,
+          min.x,
+          max.y,
+          max.z,
+          min.x,
+          min.y,
+          max.z,
+        ],
+        [min.x, min.y, min.z, min.x, min.y, max.z],
+        [max.x, min.y, min.z, max.x, min.y, max.z],
+        [max.x, max.y, min.z, max.x, max.y, max.z],
+        [min.x, max.y, min.z, min.x, max.y, max.z],
+      ];
+    },
+    updateGlobalClippingBoundsResolution(width, height) {
+      const helper = this.globalClippingBoundsHelper;
+      const firstLine = helper && helper.children && helper.children[0];
+      const resolution = firstLine && firstLine.material && firstLine.material.resolution;
+      if (!resolution) return;
+      if ((!width || !height) && this.renderer && this.renderer.domElement) {
+        const rect = this.renderer.domElement.getBoundingClientRect();
+        width = rect.width;
+        height = rect.height;
+      }
+      if (width > 0 && height > 0) resolution.set(width, height);
+    },
+    removeGlobalClippingBoundsHelper() {
+      const helper = this.globalClippingBoundsHelper;
+      if (!helper) return;
+      if (this.scene) this.scene.remove(helper);
+      helper.children.forEach(line => {
+        line.geometry && line.geometry.dispose && line.geometry.dispose();
+      });
+      const material = helper.children[0] && helper.children[0].material;
+      material && material.dispose && material.dispose();
+      this.globalClippingBoundsHelper = null;
+    },
+    updateGlobalClippingBoundsHelper() {
+      const planes = this.renderer && this.renderer.clippingPlanes;
+      if (!this.scene || !planes || planes.length < 6) {
+        this.removeGlobalClippingBoundsHelper();
+        return false;
+      }
+
+      const constants = planes.slice(0, 6).map(plane => plane && plane.constant);
+      if (constants.some(value => !Number.isFinite(value))) {
+        this.removeGlobalClippingBoundsHelper();
+        return false;
+      }
+
+      const bounds = new this.THREE.Box3(
+        new this.THREE.Vector3(-constants[3], -constants[4], -constants[5]),
+        new this.THREE.Vector3(constants[0], constants[1], constants[2])
+      );
+      if (bounds.isEmpty()) {
+        this.removeGlobalClippingBoundsHelper();
+        return false;
+      }
+
+      const segments = this.getGlobalClippingBoundsSegments(bounds);
+      let helper = this.globalClippingBoundsHelper;
+      if (!helper) {
+        const material = new MeshLineMaterial({
+          color: 0x999999,
+          lineWidth: 15,
+          sizeAttenuation: 0,
+          transparent: true,
+          opacity: 1,
+          depthTest: false,
+          depthWrite: false,
+          depthFunc: this.THREE.LessEqualDepth,
+          // polygonOffset: true,
+          // polygonOffsetFactor: -1,
+          // polygonOffsetUnits: -1,
+          side: this.THREE.DoubleSide,
+          toneMapped: false,
+          resolution: new this.THREE.Vector2(1, 1),
+        });
+        helper = new this.THREE.Group();
+        helper.name = 'globalClippingBoundsHelper';
+        helper.userData.globalClippingBoundsHelper = true;
+        segments.forEach(points => {
+          const geometry = new MeshLineGeometry();
+          geometry.setPoints(points);
+          const line = new this.THREE.Mesh(geometry, material);
+          line.renderOrder = 1001;
+          line.frustumCulled = false;
+          line.raycast = function () {};
+          helper.add(line);
+        });
+        this.scene.add(helper);
+        this.globalClippingBoundsHelper = helper;
+      } else {
+        helper.children.forEach((line, index) => {
+          line.geometry.setPoints(segments[index]);
+        });
+        if (helper.parent !== this.scene) this.scene.add(helper);
+      }
+      this.updateGlobalClippingBoundsResolution();
+      helper.visible = !this.guiParams || this.guiParams['显示剖切线框'] !== false;
+      return true;
+    },
     // 设置全局整体剖切
     /*
         先开启模型全局剖切模式, 会返回剖切值的最大最小值
@@ -8890,6 +9939,7 @@ export default {
     setGlobalClipping(flag = true) {
       const box3 = this.getGlobalClippingBox();
       if (!box3) {
+        this.removeGlobalClippingBoundsHelper();
         return {
           min: null,
           max: null,
@@ -8952,6 +10002,7 @@ export default {
           clippingPlanes
         );
       }
+      this.updateGlobalClippingBoundsHelper();
       return {
         min: min,
         max: max,
@@ -8971,6 +10022,7 @@ export default {
       for (const key in params) {
         this.renderer.clippingPlanes[axis[key]].constant = params[key];
       }
+      this.updateGlobalClippingBoundsHelper();
       // this.timeRender()
     },
     // 取消全局剖切
@@ -8985,6 +10037,7 @@ export default {
       };
       this.clippingPlanesConstants = null;
       this.renderer.clippingPlanes = Object.freeze([]);
+      this.removeGlobalClippingBoundsHelper();
       if (this.gui) {
         this.gui.destroy();
         this.gui = null;
@@ -9116,6 +10169,9 @@ export default {
         '-y轴': yRange.min,
         '-z轴': zRange.min,
       };
+      if (title === '全局剖切') {
+        this.guiParams['显示剖切线框'] = true;
+      }
 
       const initialConstants = [
         xRange.max,
@@ -9147,7 +10203,22 @@ export default {
           this.closeGlobalClipping();
         });
         this.gui.domElement.querySelector('.title').appendChild(closeButton);
+        const wireframeToggle = this.gui
+          .add(this.guiParams, '显示剖切线框')
+          .name('显示剖切线框')
+          .listen();
+        wireframeToggle.domElement.classList.add('global-clipping-wireframe-toggle');
+        const wireframeToggleWidget = wireframeToggle.domElement.querySelector('.widget');
+        if (wireframeToggleWidget) wireframeToggleWidget.classList.remove('widget');
+        wireframeToggle.onChange(visible => {
+          if (this.globalClippingBoundsHelper) {
+            this.globalClippingBoundsHelper.visible = visible;
+          }
+        });
       }
+      const updateGlobalClippingBounds = () => {
+        if (title === '全局剖切') this.updateGlobalClippingBoundsHelper();
+      };
       this.gui
         .add(this.guiParams, 'x轴')
         .step(0.001)
@@ -9156,6 +10227,7 @@ export default {
         .onChange(d => {
           objClipp1[0].constant = d;
           objClipp2 && (objClipp2[0].constant = d);
+          updateGlobalClippingBounds();
         });
       this.gui
         .add(this.guiParams, '-x轴')
@@ -9165,6 +10237,7 @@ export default {
         .onChange(d => {
           objClipp1[3].constant = -d;
           objClipp2 && (objClipp2[3].constant = -d);
+          updateGlobalClippingBounds();
         });
       this.gui
         .add(this.guiParams, 'y轴')
@@ -9174,6 +10247,7 @@ export default {
         .onChange(d => {
           objClipp1[2].constant = d;
           objClipp2 && (objClipp2[2].constant = d);
+          updateGlobalClippingBounds();
         });
       this.gui
         .add(this.guiParams, '-y轴')
@@ -9183,6 +10257,7 @@ export default {
         .onChange(d => {
           objClipp1[5].constant = -d;
           objClipp2 && (objClipp2[5].constant = -d);
+          updateGlobalClippingBounds();
         });
       this.gui
         .add(this.guiParams, 'z轴')
@@ -9192,6 +10267,7 @@ export default {
         .onChange(d => {
           objClipp1[1].constant = d;
           objClipp2 && (objClipp2[1].constant = d);
+          updateGlobalClippingBounds();
         });
       this.gui
         .add(this.guiParams, '-z轴')
@@ -9201,6 +10277,7 @@ export default {
         .onChange(d => {
           objClipp1[4].constant = -d;
           objClipp2 && (objClipp2[4].constant = -d);
+          updateGlobalClippingBounds();
         });
     },
     getFirstPersonMoveSpeed(customMoveSpeed) {
@@ -9265,9 +10342,17 @@ export default {
     },
     // 开启第一视角
     startFirstPer(options) {
-      let { moveSpeed = 200, jumpSpeed = 200 } = options || {};
-      this.removeSpeed = 3500;
-      // this.removeSpeed = this.getFirstPersonMoveSpeed(moveSpeed);
+      let {
+        moveSpeed = 200,
+        jumpSpeed = 200,
+        mouseSpeed = 1,
+        collisionEnabled = true,
+        height = 168,
+      } = options || {};
+      this.firstPersonMouseSpeed = mouseSpeed;
+      this.firstPersonCollisionEnabled = collisionEnabled;
+      this.firstPersonActorHeight = height * 10;
+      this.removeSpeed = this.getFirstPersonMoveSpeed(moveSpeed);
       const jumpConfig = this.getFirstPersonJumpConfig(jumpSpeed);
       this.upSpeed = jumpConfig.jumpSpeed;
       this.firstPersonGravity = jumpConfig.gravity;
@@ -9293,7 +10378,8 @@ export default {
         this.camera.rotation.z = 0;
 
         this.pointControls = new PointerLockControls(this.camera, this.renderer.domElement);
-        this.pointControls.pointerSpeed = FIRST_PERSON_POINTER_SPEED;
+        this.pointControls.pointerSpeed =
+          FIRST_PERSON_POINTER_SPEED * (this.firstPersonMouseSpeed || 1);
         this.pointControls.lock();
         if (!this._onFirstPersonChange) {
           this._onFirstPersonChange = () => {
@@ -9320,6 +10406,7 @@ export default {
         });
         // 解锁
         this.pointControls.addEventListener('unlock', () => {
+          const wasFirstPersonActive = this.firstPerSign;
           this.firstPerSign = false;
           if (this.cameraControls) {
             this.cameraControls.enabled = true;
@@ -9350,6 +10437,7 @@ export default {
           if (typeof this._cameraChangeObserver === 'function') {
             this._cameraChangeObserver('firstPersonUnlock');
           }
+          if (wasFirstPersonActive) this.$emit('roaming-end');
         });
         if (this.scene) this.scene.add(this.pointControls.object);
       }, 10);
@@ -9391,9 +10479,24 @@ export default {
           this.velocity.y = Math.max(0, this.velocity.y);
           this.canJump = true;
         }
-        // 根据速度值移动控制器
-        this.pointControls.moveRight(-this.velocity.x * delta);
-        this.pointControls.moveForward(-this.velocity.z * delta);
+        // 分轴应用移动，避免合并位移的碰撞结果阻断可通行的另一个方向。
+        const yaw = control.rotation.y;
+        const rightDistance = -this.velocity.x * delta;
+        const forwardDistance = -this.velocity.z * delta;
+        const nextRightPosition = control.position.clone();
+        nextRightPosition.x += Math.cos(yaw) * rightDistance;
+        nextRightPosition.z += -Math.sin(yaw) * rightDistance;
+        if (this.canMoveFirstPersonTo(nextRightPosition, control.position)) {
+          this.pointControls.moveRight(rightDistance);
+        } else this.velocity.x = 0;
+
+        const nextForwardPosition = control.position.clone();
+        // moveForward 的正距离沿相机前方移动，预判位置必须与实际位移方向一致。
+        nextForwardPosition.x -= Math.sin(yaw) * forwardDistance;
+        nextForwardPosition.z -= Math.cos(yaw) * forwardDistance;
+        if (this.canMoveFirstPersonTo(nextForwardPosition, control.position)) {
+          this.pointControls.moveForward(forwardDistance);
+        } else this.velocity.z = 0;
         control.position.y += this.velocity.y * delta;
         // 保证控制器的y轴在平面上
         if (control.position.y < FIRST_PERSON_GROUND_HEIGHT) {
@@ -9418,6 +10521,59 @@ export default {
         }
       }
     },
+    canMoveFirstPersonTo(position, currentPosition) {
+      if (!this.firstPersonCollisionEnabled) return true;
+      if (!this._octree && this._boxIndex && this._boxIndex.size) this.buildOctreeFromBoxIndex();
+      if (!this._octree) return true;
+      const radius = Math.max((this.firstPersonActorHeight || 1700) * 0.16, 20);
+      const clearance = Math.max((this.firstPersonActorHeight || 1700) * 0.015, 4);
+      const height = this.firstPersonActorHeight || 1700;
+      const collisionRadius = radius + clearance;
+      const makeActorBox = actorPosition =>
+        new this.THREE.Box3(
+          new this.THREE.Vector3(
+            actorPosition.x - collisionRadius,
+            actorPosition.y - height * 0.9,
+            actorPosition.z - collisionRadius
+          ),
+          new this.THREE.Vector3(
+            actorPosition.x + collisionRadius,
+            actorPosition.y - height * 0.1,
+            actorPosition.z + collisionRadius
+          )
+        );
+      const start = currentPosition || position;
+      const startActorBox = makeActorBox(start);
+      const startActorObb = new OBB().fromBox3(startActorBox);
+      const distance = Math.hypot(position.x - start.x, position.z - start.z);
+      const sampleStep = Math.max(radius * 0.35, 5);
+      const sampleCount = Math.max(1, Math.ceil(distance / sampleStep));
+
+      for (let sample = 1; sample <= sampleCount; sample++) {
+        const progress = sample / sampleCount;
+        const samplePosition = new this.THREE.Vector3(
+          start.x + (position.x - start.x) * progress,
+          position.y,
+          start.z + (position.z - start.z) * progress
+        );
+        const actorBox = makeActorBox(samplePosition);
+        const candidates = this._queryOctreeByBox(actorBox);
+        const actorObb = new OBB().fromBox3(actorBox);
+        const blocked = candidates.some(item => {
+          const obstacleBox = item && item.box;
+          if (!this._isCollisionBoxAvailable(obstacleBox)) return false;
+          if (!obstacleBox.intersectsBox(actorBox)) return false;
+          return this._getCollisionObbs(obstacleBox).some(obstacleObb => {
+            const penetration = this._getObbMinPenetration(actorObb, obstacleObb);
+            const initialPenetration = this._getObbMinPenetration(startActorObb, obstacleObb);
+            if (initialPenetration <= 0) return penetration > 0;
+            return penetration > initialPenetration + 0.1;
+          });
+        });
+        if (blocked) return false;
+      }
+      return true;
+    },
     // 键盘监听事件
     onKeyDown(event) {
       if (!event.keyCode) return;
@@ -9918,6 +11074,8 @@ export default {
         // 计算相机近裁面到包围盒当前面的距离
         this.cameraTrack();
         this.firstPerspective();
+        this.updateThirdPersonRoaming(delta);
+        this.syncOrientationAxis();
         // 相机姿态（含漫游/第一人称写入）确定后，再刷新远裁剪面
         this.syncCameraProjection();
         if (this.scenePass) {
@@ -9966,6 +11124,7 @@ export default {
           //   interactionFrameCount = 0;
           // }
         }
+        this.renderOrientationAxis();
 
         // 3. 按频率输出（避免每帧都log）
         // if (frameCounter++ % LOG_INTERVAL === 0) {
@@ -10897,6 +12056,98 @@ export default {
   position: relative;
   cursor: pointer;
 }
+
+::v-deep .roaming-settings-dialog .el-dialog__header {
+  padding: 22px 32px 16px;
+  border-bottom: 1px solid #ebeef5;
+}
+
+::v-deep .roaming-settings-dialog .el-dialog__title {
+  color: #303133;
+  font-size: 18px;
+  font-weight: 600;
+}
+
+::v-deep .roaming-settings-dialog .el-dialog__body {
+  padding: 28px 32px 8px;
+}
+
+::v-deep .roaming-settings-dialog .el-dialog__footer {
+  padding: 14px 32px 24px;
+  border-top: 1px solid #ebeef5;
+}
+
+.roaming-settings-form {
+  ::v-deep .el-form-item__label {
+    color: #303133;
+    font-size: 14px;
+    font-weight: 400;
+  }
+
+  .roaming-settings-perspective {
+    display: flex;
+    align-items: center;
+    min-height: 32px;
+    gap: 72px;
+
+    ::v-deep .el-radio {
+      margin-right: 0;
+      color: #303133;
+      font-size: 14px;
+    }
+
+    ::v-deep .el-radio__label {
+      padding-left: 8px;
+      font-size: 14px;
+    }
+  }
+
+  .roaming-settings-section-title {
+    margin: 8px 0 20px;
+    color: #303133;
+    font-size: 15px;
+    font-weight: 600;
+  }
+
+  .roaming-settings-height,
+  .roaming-settings-control {
+    width: 280px;
+  }
+
+  .el-slider {
+    width: 330px;
+    padding: 0 8px 0 0;
+  }
+
+  .el-form-item {
+    margin-bottom: 22px;
+  }
+}
+
+::v-deep .roaming-settings-dialog {
+  max-width: calc(100vw - 32px);
+}
+
+::v-deep .roaming-settings-dialog .el-dialog__close {
+  font-size: 18px;
+}
+
+::v-deep .roaming-settings-dialog .el-dialog__body {
+  padding: 10px 20px;
+}
+
+.roaming-settings-footer {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+
+  ::v-deep .el-button {
+    min-width: 76px;
+    height: 34px;
+    font-size: 14px;
+  }
+}
+
 ::v-deep .tips-label {
   width: 60px;
   color: #000;
@@ -11086,9 +12337,16 @@ export default {
   }
 }
 </style>
+
+<style lang="scss">
+/* el-dialog 开启 append-to-body 后挂载到 body，使用非 scoped 选择器确保样式生效。 */
+.roaming-settings-dialog .el-dialog__body {
+  padding: 10px 20px;
+}
+</style>
 <style>
 /* 自定义lil-gui样式 - 浅色主题 */
-.lil-this.gui {
+.lil-gui {
   background: rgba(255, 255, 255, 0.95) !important;
   border: 1px solid #e0e0e0 !important;
   border-radius: 8px !important;
@@ -11097,7 +12355,7 @@ export default {
   font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif !important;
 }
 
-.lil-this.gui .title {
+.lil-gui .title {
   background: linear-gradient(135deg, #f8f9fa 0%, #e9ecef 100%) !important;
   color: #495057 !important;
   border-bottom: 1px solid #dee2e6 !important;
@@ -11106,50 +12364,70 @@ export default {
   border-radius: 8px 8px 0 0 !important;
 }
 
-.lil-this.gui .controller {
+.lil-gui .controller {
   border-bottom: 1px solid #f1f3f4 !important;
   background: transparent !important;
 }
 
-.lil-this.gui .controller:last-child {
+.lil-gui .controller:last-child {
   border-bottom: none !important;
 }
 
-.lil-this.gui .controller .name {
+.lil-gui .controller .name {
   color: #495057 !important;
   font-weight: 500 !important;
   font-size: 12px !important;
 }
 
-.lil-this.gui .controller .widget {
+.lil-gui .controller .widget {
   background: #f8f9fa !important;
   border: 1px solid #ced4da !important;
   border-radius: 4px !important;
   color: #495057 !important;
 }
 
-.lil-this.gui .controller .widget:hover {
+.lil-gui .controller .widget:hover {
   border-color: #80bdff !important;
   box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25) !important;
 }
 
-.lil-this.gui .controller .widget:focus {
+.lil-gui .controller .widget:focus {
   border-color: #80bdff !important;
   box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25) !important;
   outline: none !important;
 }
 
-.lil-this.gui .controller input[type='range'] {
+.lil-gui .global-clipping-wireframe-toggle label {
+  display: flex !important;
+  align-items: center !important;
+  justify-content: flex-start !important;
+  background: transparent !important;
+  border: 0 !important;
+  box-shadow: none !important;
+}
+
+.lil-gui .global-clipping-wireframe-toggle input[type='checkbox'] {
+  width: 16px !important;
+  height: 16px !important;
+  margin: 0 8px 0 0 !important;
+  padding: 0 !important;
+  color: #495057 !important;
+  border: 1px solid !important;
+  accent-color: #1684d8;
+  cursor: pointer;
+}
+
+.lil-gui .controller input[type='range'] {
   background: #e9ecef !important;
   height: 4px !important;
   -webkit-appearance: none !important;
   appearance: none !important;
   border-radius: 2px !important;
 }
-.lil-this.gui .controller.number .fill {
+.lil-gui .controller.number .fill {
   border-right: solid #008de9;
 }
-.lil-this.gui .controller input[type='range']::-webkit-slider-thumb {
+.lil-gui .controller input[type='range']::-webkit-slider-thumb {
   background: #007bff !important;
   border: 2px solid #ffffff !important;
   box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2) !important;
@@ -11161,7 +12439,7 @@ export default {
   cursor: pointer !important;
 }
 
-.lil-this.gui .controller input[type='range']::-moz-range-thumb {
+.lil-gui .controller input[type='range']::-moz-range-thumb {
   background: #007bff !important;
   border: 2px solid #ffffff !important;
   box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2) !important;
@@ -11171,23 +12449,23 @@ export default {
   cursor: pointer !important;
 }
 
-.lil-this.gui .controller .option {
+.lil-gui .controller .option {
   background: #ffffff !important;
   color: #495057 !important;
   border-bottom: 1px solid #f1f3f4 !important;
 }
 
-.lil-this.gui .controller .option:hover {
+.lil-gui .controller .option:hover {
   background: #f8f9fa !important;
 }
 
-.lil-this.gui .controller .option:last-child {
+.lil-gui .controller .option:last-child {
   border-bottom: none !important;
 }
-.lil-this.gui input:active {
+.lil-gui input:active {
   background: #e6eff4;
 }
-.lil-this.gui .controller button {
+.lil-gui .controller button {
   background: linear-gradient(135deg, #007bff 0%, #0056b3 100%) !important;
   color: #ffffff !important;
   border: none !important;
@@ -11196,51 +12474,51 @@ export default {
   transition: all 0.2s ease !important;
 }
 
-.lil-this.gui .controller button:hover {
+.lil-gui .controller button:hover {
   background: linear-gradient(135deg, #0056b3 0%, #004085 100%) !important;
   transform: translateY(-1px) !important;
   box-shadow: 0 4px 8px rgba(0, 123, 255, 0.3) !important;
 }
 
-.lil-this.gui .controller .color {
+.lil-gui .controller .color {
   border: 2px solid #ffffff !important;
   border-radius: 4px !important;
   box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1) !important;
 }
-.lil-this.gui .controller.number .slider {
+.lil-gui .controller.number .slider {
   background-color: #e6eff4;
 }
-.lil-this.gui .controller.number .slider:hover {
+.lil-gui .controller.number .slider:hover {
   background-color: #e6eff4;
 }
-.lil-this.gui input:hover {
+.lil-gui input:hover {
   background: #e6eff4;
 }
-.lil-this.gui input[type='number']:focus,
-.lil-this.gui input[type='text']:focus,
-.lil-this.gui input {
+.lil-gui input[type='number']:focus,
+.lil-gui input[type='text']:focus,
+.lil-gui input {
   background: #e6eff4;
 }
-.lil-this.gui .controller > .name {
+.lil-gui .controller > .name {
   min-width: 25px;
 }
-.lil-this.gui .controller.number input {
+.lil-gui .controller.number input {
   color: #2e3136;
 }
-.lil-this.gui .controller.number .slider:active {
+.lil-gui .controller.number .slider:active {
   background-color: #e6eff4;
 }
-.lil-this.gui .folder > .title {
+.lil-gui .folder > .title {
   background: linear-gradient(135deg, #f1f3f4 0%, #e9ecef 100%) !important;
   color: #495057 !important;
   border-bottom: 1px solid #dee2e6 !important;
 }
 
-.lil-this.gui .folder > .title:before {
+.lil-gui .folder > .title:before {
   color: #6c757d !important;
 }
 
-/* .lil-this.gui .folder.closed > .children {
+/* .lil-gui .folder.closed > .children {
   display: none !important;
 } */
 .lil-gui button {