最后同步日期：2026-04-15 | Godot 官方原文 — MeshInstance3D

MeshInstance3D

节点继承关系

继承链：Node → Node3D → [VisualInstance3D] → [GeometryInstance3D] → MeshInstance3D

定义

MeshInstance3D 在 3D 空间中显示一个模型（Mesh）。它是 3D 游戏中最常用的显示节点——角色模型、场景物体、地形，全都靠它渲染出来。你给它一个 3D 模型资源，它就把模型显示在游戏世界中。

一句话理解：如果 3D 世界是一出舞台剧，MeshInstance3D 就是舞台上的每个道具和演员的"身体"。

使用频率：★★★★ 维度专用常用——几乎所有 3D 游戏的核心显示节点。

节点用途

• 显示 3D 模型（角色、建筑、道具、地形）
• 使用内置基本几何体（立方体、球体、圆柱体等）快速原型开发
• 加载外部 3D 模型文件（.glb、.gltf、.fbx）
• 配合材质实现各种视觉效果

使用场景

场景	说明
角色模型	显示从 Blender/Maya 导出的角色模型
场景物体	桌椅、墙壁、地面等静态物体
快速原型	使用内置 Mesh 快速搭建场景
地形显示	显示程序化生成的地形 Mesh

常用节点搭配

搭配节点	搭配方式	用途
StaticBody3D	作为兄弟子节点	给模型加上物理碰撞
RigidBody3D	作为子节点	让模型可以被物理推动
AnimationPlayer	作为兄弟子节点	播放模型上的骨骼动画（Skeletal Animation）
CollisionShape3D	作为兄弟子节点	定义模型的碰撞形状
NavigationRegion3D	配合	让 AI 可以在模型上方寻路
MultiMeshInstance3D	替代关系	需要大量相同模型时用 MultiMesh 提升性能

生效必备素材/资源

资源类型	格式	说明
Mesh	内置 / .glb / .gltf / .obj	3D 模型资源。Godot 推荐使用 .glb 格式
Material（可选）	StandardMaterial3D 等	材质资源，定义模型的外观（颜色、纹理、光照等）

常用内置 Mesh 一览

Mesh 类型	形状	典型用途
BoxMesh	立方体	箱子、墙壁、方块
SphereMesh	球体	球、行星、弹丸
CylinderMesh	圆柱体	柱子、桶、管道
CapsuleMesh	胶囊体	碰撞体预览、胶囊角色
PlaneMesh	平面	地面、水面、天花板
PrismMesh	棱柱	楔形物、斜坡
TorusMesh	甜甜圈形	环形物、管道弯头
ConcavePolygonShape3D	凹多边形	复杂地形碰撞

节点属性与信号

Mesh 属性

属性	类型	默认值	继承自	说明
Mesh	Mesh	null	—	要显示的 3D 模型资源
Skeleton	Skeleton3D	null	—	骨骼引用（用于骨骼动画的模型）

材质覆盖

属性	类型	默认值	继承自	说明
MaterialOverride	Material	null	—	覆盖整个模型的材质
SurfaceMaterialOverride	Material[]	[]	—	按表面索引覆盖材质（多材质模型）
ExtraCullMargin	float	0.0	—	额外剔除边距，防止大型模型被误剔除

继承自 GeometryInstance3D 的常用属性

属性	类型	默认值	继承自	说明
CastShadow	ShadowCastingSetting	On	[GeometryInstance3D]	是否投射阴影
ReceiveShadows	bool	true	[GeometryInstance3D]	是否接收阴影
VisibilityRangeBegin	float	0.0	[GeometryInstance3D]	可见距离起点（LOD 用）
VisibilityRangeEnd	float	0.0	[GeometryInstance3D]	可见距离终点（超出则不渲染）
VisibilityRangeFadeMode	VisibilityRangeFadeMode	Disabled	[GeometryInstance3D]	距离淡入淡出模式
GIMode	GIMode	Static	[GeometryInstance3D]	全局光照模式（静态/动态/禁用）
LayerMask	uint	4294967295	[GeometryInstance3D]	渲染层掩码（控制哪些相机能看到）

信号

MeshInstance3D 本身没有自定义信号，继承自 [GeometryInstance3D] 和 Node3D。

常用方法

方法	返回值	说明
GetMesh()	Mesh	获取当前 Mesh
SetMesh(mesh)	void	设置 Mesh
CreateTrimeshCollision()	void	根据 Mesh 自动创建三角形碰撞形状
GetSurfaceOverrideMaterialCount()	int	获取表面材质数量
GetSurfaceOverrideMaterial(surfaceIdx)	Material	获取指定表面的覆盖材质

代码示例

基础用法：创建一个红色立方体

C

// 创建一个红色立方体
var meshInst = new MeshInstance3D();
meshInst.Mesh = new BoxMesh { Size = new Vector3(2, 2, 2) };

var mat = new StandardMaterial3D
{
    AlbedoColor = Colors.Red
};
meshInst.MaterialOverride = mat;
AddChild(meshInst);

GDScript

# 创建一个红色立方体
var mesh_inst = MeshInstance3D.new()
mesh_inst.mesh = BoxMesh.new()
mesh_inst.mesh.size = Vector3(2, 2, 2)

var mat = StandardMaterial3D.new()
mat.albedo_color = Color.RED
mesh_inst.material_override = mat
add_child(mesh_inst)

加载外部模型

C

// 加载外部模型文件
var model = new MeshInstance3D();
model.Mesh = GD.Load<Mesh>("res://models/character.glb");

// 设置位置和缩放
model.Position = new Vector3(0, 0, 5);
model.Scale = new Vector3(1, 1, 1);
AddChild(model);

// 自动生成碰撞体
model.CreateTrimeshCollision();

GDScript

# 加载外部模型文件
var model = MeshInstance3D.new()
model.mesh = load("res://models/character.glb")

# 设置位置和缩放
model.position = Vector3(0, 0, 5)
model.scale = Vector3(1, 1, 1)
add_child(model)

# 自动生成碰撞体
model.create_trimesh_collision()

使用内置基本几何体搭建场景

C

// 地面
var ground = new MeshInstance3D();
ground.Mesh = new BoxMesh { Size = new Vector3(20, 0.5f, 20) };
ground.Position = new Vector3(0, -0.25f, 0);
var groundMat = new StandardMaterial3D { AlbedoColor = new Color("8B7355") };
ground.MaterialOverride = groundMat;
AddChild(ground);

// 柱子
var pillar = new MeshInstance3D();
pillar.Mesh = new CylinderMesh
{
    TopRadius = 0.3f,
    BottomRadius = 0.3f,
    Height = 5
};
pillar.Position = new Vector3(3, 2.5f, 3);
AddChild(pillar);

// 球体
var ball = new MeshInstance3D();
ball.Mesh = new SphereMesh { Radius = 0.5f, Height = 1.0f };
ball.Position = new Vector3(-2, 0.5f, 0);
ball.CastShadow = GeometryInstance3D.ShadowCastingSetting.On;
AddChild(ball);

GDScript

# 地面
var ground = MeshInstance3D.new()
ground.mesh = BoxMesh.new()
ground.mesh.size = Vector3(20, 0.5, 20)
ground.position = Vector3(0, -0.25, 0)
var ground_mat = StandardMaterial3D.new()
ground_mat.albedo_color = Color("8B7355")
ground.material_override = ground_mat
add_child(ground)

# 柱子
var pillar = MeshInstance3D.new()
pillar.mesh = CylinderMesh.new()
pillar.mesh.top_radius = 0.3
pillar.mesh.bottom_radius = 0.3
pillar.mesh.height = 5
pillar.position = Vector3(3, 2.5, 3)
add_child(pillar)

# 球体
var ball = MeshInstance3D.new()
ball.mesh = SphereMesh.new()
ball.mesh.radius = 0.5
ball.mesh.height = 1.0
ball.position = Vector3(-2, 0.5, 0)
ball.cast_shadow = GeometryInstance3D.SHADOW_CASTING_SETTING_ON
add_child(ball)