本文介绍了如何使用Three.js和Vue开发一款名为CubeCity的城建游戏。文章详细阐述了游戏的元数据体系规划、三维场景呈现流程以及交互系统的实现原理。游戏采用17x17的网格地图，通过Pinia管理元数据，并利用City、Tile和Building等类将元数据转换为三维场景。交互系统采用模式驱动和射线拾取相结合的方式，实现了建造、选择、搬迁和拆除等操作模式。文章还探讨了SimObject类在交互系统中的作用，以及射线检测的优化手段。

💡 元数据体系规划：文章核心思想是将“城市事实”与“三维表现”解耦，以Pinia的metadata作为单一事实源，将三维场景视为其投影和可视化。这种设计使得游戏逻辑与表现分离，简化了心智模型，并提高了性能。

🏗️ 三维场景呈现：文章详细介绍了从Pinia读取元数据到City按网格实例化，再到Tile生成地形与挂载建筑，最后由Building初始化模型与状态效果的流程。这种分层设计使得代码结构清晰，易于维护。

🔍 交互系统：文章深入探讨了SimObject在交互系统中的作用，包括mesh材质克隆、选中/聚焦高亮和动画反馈等功能。此外，文章还介绍了射线拾取的原理和优化手段，例如限定射线检测对象为地皮，以提高性能。

原创 何贤 2025-08-30 09:01 重庆

点击关注公众号，技术干货及时达。

（💰金石瓜分计划强势上线，速戳上图了解详情🔍）

0.好久不见各位早上、中午、晚上好！我是鸽子王何贤，距离上次更新已时隔两月，在此深表歉意。除近期本职工作较忙外，还有一些特殊原因导致鸽了这么久：

Blender mcp 的作者联系我说有米奇妙妙小工具，我说这太好了，一来二去可能就耽误了本次发文章的时间，还是很对不起运营小哥的，在这说一声对不起。但请允许我将功补过——在完成Beta版后第一时间与大家分享。

1.Page 预览话说老何长时间被电子 ED 困扰，没什么游戏好玩，又不想干农活，于是就在 Steam 上找起了游戏。鼠标在夏日促销页面上不断翻动，商品琳琅满目但都提不起兴趣。

不知不觉就就找到了一款城建类卡通风游戏《卡牌城镇Cardboard Town》 

老何平时的游戏风格都是战斗爽，从来没玩过城建游戏哇！一下子就给陷进去了。后面两天老何天天就是白天看攻略，晚上通宵当市长。久而久之老何就连白天都想着能不能开一把。但是公司人多眼杂，当众玩游戏只怕游戏10点开的，12点就开始办离职申请了。但是规矩是死的，人是活的。上班玩游戏的胆子没有，但是...借着敲代码的名义开发一个游戏来玩的胆子大大的有。

因此，这个项目就在老板的眼皮底下诞生了。 由此，在老板眼皮底下诞生了基于Three.js+Vue的城建游戏——《CubeCity》。

1.1 粗略概览(平台限制 画质需要压缩)

1.2 大致功能概览1.3 玩法介绍游戏主要围绕四种操作模式展开

「🏗️ 建造模式 (BUILD):」

快捷键 「B」

从左侧面板选择你想要的建筑。

在地图上的可用地皮上点击即可放置建筑，实时预览模型和高亮提示让操作更直观。

「🔍 选择模式 (SELECT):」

快捷键 「S」

点击建筑查看详细信息，如这一级的产出 & 污染，以及下一级的产出 & 污染等。

满足条件时可对建筑进行升级，提升其功能和产出。

「🚚 搬迁模式 (RELOCATE):」

快捷键 「R」

在文章 😲我又写出了被 Three.js 官推转发的项目？！🥳🥳中曾提到过游戏开发三要素

export const useGameState = defineStore('gameState', {
  state: () => ({
    metadata: Array.from({ length: 17 }, _ =>
      Array.from({ length: 17 }, _ => ({
        type: 'grass',
        building: null,
        direction: 0,
      }))),
    currentMode: 'build', //当前玩家选择的模式
    selectedBuilding: null, //当前玩家选择的地皮
  }),

{
  "type": "ground",            // 地形：grass/ground/road ...
  "building": "factory",       // 建筑类型 如 民宿、工厂、商店
  "direction": 0,              // 朝向：0/1/2/3（右/下/左/上）
  "level": 1,                  // 建筑等级
  "detail": {                  // 后续会提到具体各项 props
    "coinOutput": 70,
    "powerUsage": 40,
    "pollution": 22,
    "population": 20,
    "category": "industrial"// 建筑类别 主要分三大类 住房 工业 商业
  },
  "outputFactor": 1            // 产出系数（相互作用或全局事件影响）
}

export const useGameState = defineStore('gameState', {
  // ....

  // 更新 metadata 地皮的 action
  action: {
    setTile(x, y, patch) {
      Object.assign(this.metadata[x][y], patch)
    },
    updateTile(x, y, patch) {
      Object.assign(this.metadata[x][y], patch)
    },
    getTile(x, y) {
      return this.metadata?.[x]?.[y] || null
    },
  }
})

export const useGameState = defineStore('gameState', {
  state: () => ({
    // 核心游戏状态
    metadata: Array.from({ length: 17 }, _ =>
      Array.from({ length: 17 }, _ => ({
        type: 'grass',
        building: null,
        direction: 0,
      }))),
    currentMode: 'build',
    selectedBuilding: null,
    // 游戏时间和经济
    gameDay: 1,
    credits: 3000,
    // ... 其余同上
  }),
  getters: {
    /**
     * 计算每日总收入（直接使用metadata中的detail，大幅提升性能）
     * @param {object} state - 游戏状态
     * @returns {number} 总收入
     */
    dailyIncome: (state) => {
      let totalIncome = 0
      state.metadata.forEach((row, x) => {
        row.forEach((tile, y) => {
//遍历有建筑的地皮进行汇总计算
          if (tile.building && tile.detail) {
            // 使用高效函数：自动判断是否需要相互作用计算(后面会讲到)
            const income = getEffectiveBuildingValue(state, x, y, 'coinOutput')
            totalIncome += income
          }
        })
      })

      return totalIncome
    },
    // ... 其余同上
  }

export const useGameState = defineStore('gameState', {
  // 省略...
  getters: {
    /**
     * 计算每日总收入（直接使用metadata中的detail，大幅提升性能）
     * @param {object} state - 游戏状态
     * @returns {number} 总收入
     */
    dailyIncome: (state) => {
      let totalIncome = 0
      state.metadata.forEach((row, x) => {
        row.forEach((tile, y) => {
//遍历有建筑的地皮进行汇总计算
          if (tile.building && tile.detail) {
            // 使用高效函数：自动判断是否需要相互作用计算(后面会讲到)
            const income = getEffectiveBuildingValue(state, x, y, 'coinOutput')
            totalIncome += income
          }
        })
      })

      return totalIncome
    },
    // ... 其余同上
  },
  action: {
    /**
     * 进入下一天，更新金币和稳定度
     */
    nextDay() {
      // 经济系统更新
      this.credits += this.dailyIncome
      this.gameDay++
    // ... 其余同上
    },
  }

import Experience from './experience.js' 

export default class Your3DComponent {
  constructor() {
    // 获取 Experience 单例实例
    this.experience = new Experience()

    // 通过 experience 实例访问核心组件和工具 
    this.scene = this.experience.scene             // THREE.Scene 实例
    this.resources = this.experience.resources     // 资源加载器实例 (Resources)
    this.camera = this.experience.camera.instance  // THREE.Camera 实例 (透视或正交)
    this.renderer = this.experience.renderer.instance // THREE.WebGLRenderer 实例
    this.time = this.experience.time               // 时间控制器实例 (Time)
    this.sizes = this.experience.sizes             // 尺寸管理器实例 (Sizes)
    this.iMouse = this.experience.iMouse           // 鼠标跟踪器实例 (IMouse)
    this.debug = this.experience.debug             // 调试 UI 实例 (Debug)
    this.physics = this.experience.physics         // 物理世界实例 (PhysicsWorld)
    this.stats = this.experience.stats             //性能监控实例 (Stats)
    this.canvas = this.experience.canvas           // HTML Canvas 元素
    // ... 其他可能需要的实例
  }

    update() {
// 如果需要逐帧更新，从 this.experience.time 取时间对象
   }

    resize() {
// 如果需要响应尺寸变化
  }
}

export default class World {
  constructor() {
    this.experience = new Experience() //
    this.scene = this.experience.scene
    this.resources = this.experience.resources

    this.resources.on('ready', () => {
      // 实例化城市地皮
      this.city = new City()
    })
  }

  update() {
    // 若 city 有 update 行为可调用
    if (this.city && this.city.update) {
      this.city.update()
    }
  }
}

import { useGameState } from '@/stores/useGameState.js'

export default class City {
  constructor() {
    this.experience = new Experience()
    this.scene = this.experience.scene
    this.resources = this.experience.resources

    // 初始化地皮
    this.initTiles()

    // 调试面板
    if (this.debug.active) {
      this.debugInit()
    }
  }
//初始化 17x17 地皮，分布在 XOZ 平面 -8~+8
  initTiles() {
    const gameState = useGameState()
    const { metadata } = storeToRefs(gameState)
    const meta = metadata.value
    for (let x = 0; x < this.size; x++) {
      const row = []
      for (let y = 0; y < this.size; y++) {
        const tileMeta = meta[x]?.[y] || { type: 'grass', building: null }
        const tile = new Tile(x, y, {
          type: tileMeta.type,
          building: tileMeta.building,
          direction: tileMeta.direction !== undefined ? tileMeta.direction : 0,
          level: tileMeta.level !== undefined ? tileMeta.level : 0,
        })
        row.push(tile)
        this.root.add(tile)
      }
      this.meshes.push(row)
    }
  }

// Tile 类，代表单个地皮格子，继承 SimObject (具体 SimObject作用在后面会说，现在只需要把他等同于 Object3D 类即可)
export default class Tile extends SimObject {
     constructor(x, y, { type = 'grass', building = null, direction = 0, level = 0 } = {}) {
        this.experience = new Experience()
        this.scene = this.experience.scene
        this.resources = this.experience.resources

        //...some code

        //加载草地资源
        this.grassMesh = grassResource
          ? grassMesh
          : new THREE.Mesh(
            new THREE.BoxGeometry(0.98, 0.2, 0.98),
            new THREE.MeshStandardMaterial({ color: '#579649' }),
          )
        this.grassMesh.position.set(0, 0, 0)
        this.grassMesh.scale.set(0.98, 1, 0.98)
        this.grassMesh.userData = this
        this.grassMesh.name = `${this.name}-grass`

        //加载平地资源
        const groundResource = resources.items.ground ? resources.items.ground : null
        this.groundMesh = groundResource
          ? this.initMeshFromResource(groundResource)
          : new THREE.Mesh(
            new THREE.BoxGeometry(1, 0.2, 1),
            new THREE.MeshStandardMaterial({ color: '#a89984' }),
          )
        this.groundMesh.position.set(0, 0.01, 0) // 稍微高于 grass，避免 z-fighting
        this.groundMesh.scale.set(0.98, 1, 0.98)
        this.groundMesh.userData = this
        this.groundMesh.name = `${this.name}-ground`
        this.groundMesh.visible = (type === 'ground') // 初始是否显示

        this.grassMesh.add(this.groundMesh)
        this.add(this.grassMesh) //层级为 Tile--> grassMesh（groundMesh） --> building
        // 如果有建筑，加载建筑实例
        if (building) {
          this.setBuilding(building, level, direction)
        }
          // 切换地皮类型（实际上是控制 ground mesh 的显示与隐藏）
          setType(type) {
            this.type = type
            this.groundMesh.visible = (type === 'ground')
          }

          // 创建并添加建筑实例
          setBuilding(type, level = 1, direction = 0) {
            this.removeBuilding()
            const buildingData = BUILDING_DATA[type]
            const levelData = buildingData.levels[level]
            const options = { buildingData, levelData, position: { x: this.x, y: this.y } }
            const buildingInstance = createBuilding(type, level, direction, options)
            if (buildingInstance) {
              this.buildingInstance = buildingInstance
              this.grassMesh.add(buildingInstance)
            }
          }
     }

const BUILDING_CLASS_MAP = {
  house: House,
  house2: House2,
  factory: Factory,
  shop: Shop,
  office: Office,
  park: Park,
  police: Police,
  hospital: Hospital,
  road: Road,
  chemistry_factory: ChemistryFactory,
  nuke_factory: NukeFactory,
  fire_station: FireStation,
  sun_power: SunPower,
  water_tower: WaterTower,
  wind_power: WindPower,
  garbage_station: GarbageStation,
  hero_park: HeroPark,
  // 其他建筑类型可在此扩展
}

export function createBuilding(type, level = 1, direction = 0, options = {}) {
  const Cls = BUILDING_CLASS_MAP[type]
  if (Cls) {
    return new Cls(type, level, direction, options)
  }
  return null
}

// SimObject 互动基类，所有可交互对象继承自此类
export default class SimObject extends THREE.Object3D {
  /** @type {THREE.Mesh?} */
  #mesh = null
  /** @type {THREE.Vector3} */
  #worldPos = new THREE.Vector3()

  /**
   * @param {number} x 对象的 x 坐标
   * @param {number} y 对象的 y 坐标
   * @param {object} resource 可选，threejs 资源对象（如 gltf 加载结果）
   */
  constructor(x = 0, y = 0, resource = null) {
    super()
    this.name = 'SimObject'
    this.position.x = x
    this.position.z = y
    // 如果传入资源，自动初始化 mesh
    if (resource) {
      const mesh = this.initMeshFromResource(resource)
      if (mesh) {
        this.setMesh(mesh)
      }
    }
  }

  /**
   * 从 threejs 资源对象（如 gltf 加载结果）初始化 mesh，并克隆材质
   * @param {object} resource - threejs 资源对象，需包含 scene 属性
   * @returns {THREE.Object3D|null}
   */
  initMeshFromResource(resource) {
    if (!resource || !resource.scene)
      return null
    // 克隆模型
    const mesh = resource.scene.clone()
    // 遍历所有子节点，克隆材质并设置透明，userData 指向自身
    mesh.traverse((child) => {
      child.userData = this
      if (child instanceof THREE.Mesh && child.material) {
        child.receiveShadow = true
        child.castShadow = true
        child.material = child.material.clone()
        child.material.transparent = true
      }
    })
    return mesh
  }
}

  // 设置 mesh 的发光色
  #setMeshEmission(color) {
    if (!this.mesh)
      return
    this.mesh.traverse(obj => obj.material?.emissive?.setHex(color))
  }

  // 设置 mesh 的透明度
  #setMeshOpacity(opacity) {
    if (!this.mesh)
      return
    this.mesh.traverse(obj => obj.material && (obj.material.opacity = opacity))
  }

  /**
   * 设置聚焦高亮，根据当前操作模式调整颜色和透明度
   * @param {boolean} value 是否聚焦
   * @param {string} mode 操作模式，可选：'select' | 'build' | 'relocate' | 'demolish'，默认为 'select'
   */
  setFocused(value, mode = 'select') {
    // mode 到颜色和透明度的映射
    let emissionColor = HIGHLIGHTED_COLOR
    let opacity = SIMOBJECT_SELECTED_OPACITY
    switch (mode) {
      case 'select':
        emissionColor = SELECTED_COLOR
        opacity = SELECTED_COLOR_OPACITY
        break
      case 'build':
        emissionColor = BUILD_COLOR
        opacity = BUILD_COLOR_OPACITY
        break
      case 'build-invalid':
        emissionColor = BUILD_INVALID_COLOR
        opacity = BUILD_INVALID_COLOR_OPACITY
        break
      case 'relocate':
        emissionColor = RELOCATE_COLOR
        opacity = RELOCATE_COLOR_OPACITY
        break
      case 'demolish':
        emissionColor = DEMOLISH_COLOR
        opacity = DEMOLISH_COLOR_OPACITY
        break
      default:
        emissionColor = HIGHLIGHTED_COLOR
        opacity = SIMOBJECT_SELECTED_OPACITY
    }
    if (value) {
      this.#setMeshEmission(emissionColor)
      this.#setMeshOpacity(opacity)
      // 使用gsap实现y轴yoyo动画
      if (this.mesh) {
        // 先停止可能已有动画
        gsap.killTweensOf(this.mesh.position)
        gsap.to(this.mesh.position, {
          y: 0.13,
          duration: 0.41,
          yoyo: true,
          repeat: -1,
          ease: 'sine.inOut',
        })
      }
    }
    else {
      // 取消聚焦，恢复默认
      this.#setMeshEmission(0)
      this.#setMeshOpacity(SIMOBJECT_DEFAULT_OPACITY)
      if (this.mesh) {
        // 停止动画并复位y轴
        gsap.killTweensOf(this.mesh.position)
        // 直接回到初始y（假设聚焦只加了0.1）
        gsap.to(this.mesh.position, { y: 0, duration: 0.2, overwrite: true })
      }
    }
  }

    for (let x = 0; x < this.size; x++) {
      const row = []
      for (let y = 0; y < this.size; y++) {
        // 读取元数据
        const tileMeta = meta[x]?.[y] || { type: 'grass', building: null }
        const tile = new Tile(x, y, {
          type: tileMeta.type,
          building: tileMeta.building,
          direction: tileMeta.direction !== undefined ? tileMeta.direction : 0, // 传递建筑朝向
          level: tileMeta.level !== undefined ? tileMeta.level : 0, // 传递建筑等级
        })
        row.push(tile)
        this.root.add(tile) //统一塞入一个单独的 Three.Group
      }
      // 随后让 group 居中
      this.meshes.push(row)
    }

export default class Building extends SimObject {

  // 初始化建筑模型
  initModel() {
    const modelName = `${this.type}_level${this.level}`
    const modelResource = this.resources.items[modelName]
    if (modelResource && modelResource.scene) {
      const mesh = this.initMeshFromResource(modelResource)
      mesh.position.set(0, 0, 0)
      mesh.scale.set(0.8, 0.8, 0.8)
      // 设置朝向
      const angle = (this.direction % 4) * 90
      mesh.rotation.y = THREE.MathUtils.degToRad(angle)
      // 禁止建筑被选中
    mesh.raycast = () => {}
      this.setMesh(mesh)
    }
    //...
  }

function selectBuilding({ type, name, level = 1 }) {
  // 仅在 BUILD 模式下允许选中
  if (currentMode.value !== 'build')
    return
  if (selectedBuilding.value?.type === type && selectedBuilding.value?.level === level)
    return
  gameState.setSelectedBuilding({ type, level })
  gameState.addToast(`${t('selectedIndicator.selected')}: ${name[language.value]}`, 'info')
}

_onClick() {
  if (!this.focused)
    return

  const mode = this.gameState.currentMode

  // 在特定模式下，单击即选中
  if (PERSISTENT_HIGHLIGHT_MODES.includes(mode))
    this._setSelected(this.focused)

  // 根据模式委托给对应的处理器
  switch (mode) {
    case MODES.SELECT:
      handleSelectMode(this, this.selected)
      break
    case MODES.BUILD:
      handleBuildMode(this, this.focused)
      break
    case MODES.DEMOLISH:
      handleDemolishMode(this, this.selected)
      break
    case MODES.RELOCATE:
      handleRelocateMode(this, this.selected)
      break
    default:
      handleDefaultMode(this, this.focused)
      break
  }
}

export function canPlaceBuilding(x, y, buildingType, metadata) {
  if (!metadata?.[x]?.[y])
    return false
  // 部分特殊建筑可随意建造
  if (FREE_BUILDING_TYPES.includes(buildingType))
    return true

  // 其他建筑需相邻道路
  const dirs = [[0, 1], [1, 0], [0, -1], [-1, 0]]
  for (const [dx, dy] of dirs) {
    const nx = x + dx
    const ny = y + dy
    if (metadata[nx]?.[ny]?.type === 'ground' && metadata[nx]?.[ny]?.building === 'road')
      return true
  }
  return false
}

export function handleBuildMode(ctx, tile) {
  const buildingTypeToBuild = ctx.gameState.selectedBuilding?.type
  const buildingLevelToBuild = 1
  if (!tile)
    return
  const { x, y } = tile
  const metadata = ctx.gameState.metadata
  const canBuild = canPlaceBuilding(x, y, buildingTypeToBuild, metadata)
  if (!buildingTypeToBuild || !canBuild || tile.buildingInstance) {
    showToast('error', '无法在此处建造，请选择合规地块。')
    return
  }
  // 通过 Pinia 修改 metadata
  ctx.gameState.setTile(x, y, {
    type: 'ground',
    building: buildingTypeToBuild,
    direction: 0, // 可根据实际情况
    level: buildingLevelToBuild,
    // 新增建筑详情
    detail: BUILDING_DATA[buildingTypeToBuild]?.levels[buildingLevelToBuild],
    // 产出因子 可能因为某些因素而影响产出，比如人口、科技等
    outputFactor: 1,
  })
  if (ctx.gameState.credits < BUILDING_DATA[buildingTypeToBuild]?.levels[buildingLevelToBuild]?.cost) {
    showToast('error', 'Insufficient funds, unable to build.')
    return
  }
  ctx.gameState.updateCredits(-BUILDING_DATA[buildingTypeToBuild]?.levels[buildingLevelToBuild]?.cost)
  // ...后续同步 Three.js 层刷新
  tile.setBuilding(buildingTypeToBuild, buildingLevelToBuild, 0)
  tile.setType('ground')
  updateAdjacentRoads(tile, ctx.experience.world.city)
  showBuildingPlacedToast(buildingTypeToBuild, tile, buildingLevelToBuild, ctx.gameState)
}

export function handleDemolishMode(ctx, tile) {
  if (!tile)
    return

  if (tile.buildingInstance) {
    eventBus.emit('ui:confirm-action', {
      action: 'demolish',
      tileId: tile.id,
      tileName: tile.name || '',
      buildingType: tile.buildingInstance.type,
      buildingLevel: tile.buildingInstance.level,
    })
    ctx.gameState.setSelectedBuilding({ type: tile.buildingInstance.type, level: tile.buildingInstance.level || 1 })
    ctx.gameState.setSelectedPosition(tile.position)
  }
  else {
    tile.setType('grass')
    ctx._clearSelection()
  }
}

export function confirmDemolish(ctx) {
  const tile = ctx.selected
  const building = tile.buildingInstance
  if (tile && building) {
    ctx.gameState.setTile(tile.x, tile.y, {
      type: 'ground',
      building: null,
      direction: 0,
      level: 0,
    })
    tile.removeBuilding()
    showBuildingRemovedToast(building.type, tile, building.level, ctx.gameState)
    updateAdjacentRoads(tile, ctx.experience.world.city)
  }
}

AI编程资讯AI Coding专区指南：https://aicoding.juejin.cn/aicoding

点击"阅读原文"了解详情~

阅读原文

跳转微信打开

Fish AI Reader

Fish AI Reader

AI辅助创作，多种专业模板，深度分析，高质量内容生成。从观点提取到深度思考，FishAI为您提供全方位的创作支持。新版本引入自定义参数，让您的创作更加个性化和精准。

FishAI

鱼阅，AI 时代的下一个智能信息助手，助你摆脱信息焦虑

联系邮箱 441953276@qq.com