Babylon.js 8.x 中文文档整理——Scene篇 (上)

由于 Scene 涵盖的内容太庞大，所以将Scene 系列共分为三篇：

– 上篇：API 参考，系统整理 Scene 的构造函数、配置项、实例属性、实例方法以及事件与生命周期；

– 中篇：基础概念，从整体角度介绍 Scene 中涉及的基础概念与相关的基础类，有助于建立完整的 Scene 知识体系；

– 下篇：实践总结，总结 Scene 相关的常用功能实现、开发经验、性能优化思路以及常见问题与踩坑记录；

Part 1 Scene类

1. 概述

Scene 是 Babylon.js 中最核心的场景对象，也是所有三维对象的容器。一个 Scene 包含了摄像机Camera、光源Light、模型Mesh、材质Material、纹理Texture、粒子系统ParticleSystem、动画Animation等几乎所有运行时对象。简单来说，Engine 负责渲染，而 Scene 负责组织整个三维世界。

Engine
│
└── Scene
│
├── Camera
├── Light
├── Mesh
├── Material
├── Texture
├── Animation
├── Environment
└── Particle

2. 构造函数

new Scene(
engine: AbstractEngine, //必填，engine实例
options?: SceneOptions //配置项参数，在part 2详细说明
)

3. 注意事项

Scene 一般必须存在 activeCamera，否则什么也看不到；
Scene 不建议频繁创建；
多个Scene可以共用一个Engine，避免频繁创建和销毁底层图形上下文；

Part 2 Scene配置项

参数名称参数值类型/默认值说明

useGeometryUniqueIdsMap	boolean【false】	是否为 Geometry 建立唯一 ID 索引映射
useMaterialMeshMap	boolean【false】	是否维护 Material 与 Mesh 的关联映射
useClonedMeshMap	boolean【false】	是否维护 Mesh Clone 的映射关系
virtual	boolean【false】	是否创建 Virtual Scene

Part 3 Scene实例属性

1. 场景基础相关

属性名称属性值类型说明

engine	AbstractEngine	当前 Scene 所属 Engine（只读）
uid	string	Scene 唯一标识
metadata	any	用户自定义数据
reservedDataStore	any	Babylon 内部保留数据
isDisposed	boolean	是否已释放
activeCamera	Camera \| null	当前激活摄像机
activeCameras	Camera[]	多摄像机渲染列表
cameraToUseForPointers	Camera	Pointer Picking 使用的 Camera

2. 场景对象集合

这是 Scene 最重要的一组成员，几乎所有资源都会注册到这里。

属性名称属性值类型说明

rootNodes	Node[]	当前Scene 根节点集合
meshes	AbstractMesh[]	当前Scene中所有 Mesh
transformNodes	TransformNode[]	当前Scene中所有 TransformNode
lights	Light[]	当前Scene中所有 Light
cameras	Camera[]	当前Scene中所有 Camera
materials	Material[]	当前Scene中所有 Material
multiMaterials	MultiMaterial[]	当前Scene中所有 MultiMaterial
textures	BaseTexture[]	当前Scene中所有 Texture
actionManagers	AbstractActionManager[]	当前Scene中 ActionManager 集合
effectLayers	EffectLayer[]	当前Scene中 EffectLayer 集合
layers	Layer[]	当前Scene中 Layer 集合
sounds	Sound[]	当前Scene中 Sound 集合
lensFlareSystems	LensFlareSystem[]	当前Scene中 LensFlareSystem 集合
proceduralTextures	ProceduralTexture[]	当前Scene中 ProceduralTexture 集合
frameGraphs	FrameGraph[]	当前Scene中 FrameGraph 集合
geometries	Geometry[]	当前Scene中所有 Geometry
morphTargetManagers	MorphTargetManager[]	当前Scene中MorphTargetManager集合
skeletons	Skeleton[]	当前Scene中Skeleton集合
animations	Animation[]	当前Scene中Animation集合
animationGroups	AnimationGroup[]	当前Scene中AnimationGroup集合
particleSystems	IParticleSystem[]	当前Scene中ParticleSystem粒子系统集合
spriteManagers	SpriteManager[]	当前Scene中SpriteManager集合
reflectionProbes	ReflectionProbe[]	当前Scene中ReflectionProbe集合
postProcesses	PostProcess[]	当前Scene中PostProcess集合
importedMeshesFiles	string[]	已导入 Mesh 文件列表

3. Environment/Rendering相关

属性名称属性值类型说明

clearColor	Color4	Scene的背景色
ambientColor	Color3	Scene的环境光颜色
environmentTexture	BaseTexture	Scene的环境贴图
environmentBRDFTexture	BaseTexture	Scene的 BRDF LUT 纹理
environmentIntensity	number	Scene的环境光强度
iblIntensity	number	Scene的 IBL 光照强度
clipPlane ~ clipPlane6	Plane \| null	全局裁剪面 1 ~ 6
defaultMaterial	Material	Scene的默认材质
imageProcessingConfiguration	ImageProcessingConfiguration	Scene图像后处理配置
performancePriority	ScenePerformancePriority	性能策略
autoClear	boolean	是否自动清除颜色缓冲
autoClearDepthAndStencil	boolean	是否自动清除深度/模板缓冲
useRightHandedSystem	boolean	是否是否使用右手坐标系
postProcessManager	PostProcessManager	后处理管理器
dumpNextRenderTargets	boolean	下一帧导出 RenderTarget
customRenderTargets	RenderTargetTexture[]	自定义 RenderTarget

4. 功能开关相关

属性名称属性值类型说明

lightsEnabled	boolean	光照开关
texturesEnabled	boolean	纹理开关
particlesEnabled	boolean	粒子开关
spritesEnabled	boolean	Sprite 开关
shadowsEnabled	boolean	阴影开关
fogEnabled	boolean	雾开关
collisionsEnabled	boolean	碰撞检测开关
physicsEnabled	boolean	物理系统开关
probesEnabled	boolean	Reflection Probe 开关
audioEnabled	boolean	音频开关
skeletonsEnabled	boolean	骨骼动画开关
postProcessesEnabled	boolean	后处理开关
renderTargetsEnabled	boolean	RenderTarget 开关

5. 雾效果相关

属性名称属性值类型说明

fogMode	number	雾模式
fogColor	Color3	雾颜色
fogDensity	number	雾密度
fogStart	number	Linear Fog 起点
fogEnd	number	Linear Fog 终点

6. Picking相关

属性名称属性值类型说明

pointerX	number	当前Pointer X（屏幕坐标）
pointerY	number	当前Pointer Y（屏幕坐标）
unTranslatedPointer	Vector2	原始 Pointer 坐标
meshUnderPointer	AbstractMesh	当前 Pointer 下 Mesh
defaultCursor	string	默认鼠标样式
hoverCursor	string	Hover Cursor类型
doNotHandleCursors	boolean	是否禁用 Cursor 管理
constantlyUpdateMeshUnderPointer	boolean	是否持续更新 Hover Mesh
skipPointerMovePicking	boolean	是否跳过 Move Picking
pointerMoveFastCheck	boolean	是否开启Move Fast Check
pointerDownFastCheck	boolean	是否开启Down Fast Check
pointerUpFastCheck	boolean	是否开启Up Fast Check
pointerDoubleTapFastCheck	boolean	是否开启DoubleTap Fast Check
preventDefaultOnPointerDown	boolean	PointerDown 是否阻止默认事件
preventDefaultOnPointerUp	boolean	PointerUp 是否阻止默认事件
pointerMoveTrianglePredicate	TrianglePickingPredicate	Move Picking 三角面过滤
pointerDownTrianglePredicate	TrianglePickingPredicate	Down Picking 三角面过滤
pointerUpTrianglePredicate	TrianglePickingPredicate	Up Picking 三角面过滤
unTranslatedPointer	Vector2	未经过 viewport 转换的 Pointer 坐标
DragMovementThreshold	number	拖拽阈值
LongPressDelay	number	长按判定时间
DoubleClickDelay	number	双击判定时间
ExclusiveDoubleClickMode	boolean	独占双击模式

7. Debug/Cache/Performance相关

属性名称属性值类型说明

debugLayer	DebugLayer	DebugLayer 管理器
instrumentation	SceneInstrumentation	场景性能统计
loadingPluginName	string	当前资源加载插件名称
disableOfflineSupportExceptionRules	RegExp[]	离线缓存例外规则
totalVerticesPerfCounter	PerfCounter	当前 Scene 中顶点统计
blockMaterialDirtyMechanism	boolean	禁止 Material Dirty 更新
dispatchAllSubMeshesOfActiveMeshes	boolean	ActiveMesh 调度策略
forceShowBoundingBoxes	boolean	是否强制显示 BoundingBox
forceWireframe	boolean	是否强制线框模式
forcePointsCloud	boolean	是否强制点云模式
skipFrustumClipping	boolean	是否跳过视锥裁剪
skipPointerMovePicking	boolean	是否跳过 Move Picking
useDelayedTextureLoading	boolean	是否延迟纹理加载
deltaTime	number	当前帧耗时
animationTimeScale	number	动画时间倍率
useConstantAnimationDeltaTime	boolean	是否固定动画时间步长
activeMeshes	SmartArray<AbstractMesh>	当前 Active Mesh
activeParticles	number	当前活跃粒子数
activeBones	number	当前活跃骨骼数
database	Database	离线数据库
offlineProvider	IOfflineProvider	离线缓存提供者
getCachedMaterial	Material	当前缓存 Material
getCachedEffect	Effect	当前缓存 Effect
getCachedVisibility	number	当前缓存 Visibility
isCachedMaterialInvalid	boolean	Material Cache 是否失效

8. Physics相关

属性名称属性值类型说明

gravity

Vector3

当前 Scene重力方向

Part 4 Scene实例方法

1. 场景基础相关

方法返回值类型说明

render(updateCameras?: boolean, ignoreAnimations?: boolean)	void	触发一次完整渲染流程，同时会触发各阶段 Observable
dispose()	void	销毁当前 Scene
incrementRenderId()	void	更新当前 RenderId
resetCachedMaterial()	void	重置当前材质缓存
attachControl(attachUp?: boolean, attachDown?: boolean, attachMove?: boolean)	void	绑定 Pointer 输入控制
detachControl()	void	解除 Pointer 输入控制

2. Camera管理相关

方法返回值类型说明

addCamera(newCamera: Camera)	Camera	添加 Camera至Scene
removeCamera(toRemove: Camera)	boolean	从Scene中移除 Camera
switchActiveCamera(newCamera: Camera, attachControl?: boolean)	boolean	切换当前激活 Camera
setActiveCameraById(id: string)	Camera \| null	根据 ID 设置当前 Camera
setActiveCameraByName(name: string)	Camera \|null	根据名称设置当前 Camera
getCameraById(id: string)	Camera \|null	根据 ID 查询 Camera
getCameraByUniqueId(uniqueId: number)	Camera \|null	根据 UniqueId 查询 Camera
getCameraByName(name: string)	Camera \|null	根据名称查询 Camera

3. Mesh管理相关

方法返回值类型说明

addMesh(newMesh: AbstractMesh, recursive?: boolean)	AbstractMesh	添加 Mesh至Scene
removeMesh(toRemove: AbstractMesh, recursive?: boolean)	boolean	从Scene中移除Mesh
getMeshById(id: string)	AbstractMesh \| null	根据 ID 查询 Mesh
getMeshByUniqueId(uniqueId: number)	AbstractMesh \| null	根据 UniqueId 查询 Mesh
getMeshByName(name: string)	AbstractMesh \|null	根据 Name 查询 Mesh
getMeshesById(id: string)	AbstractMesh[]	查询所有匹配 ID 的 Mesh
getLastMeshById(id: string)	AbstractMesh \| null	获取最后一个匹配 ID 的 Mesh
getLastMeshByName(name: string)	AbstractMesh \| null	获取最后一个匹配Name的 Mesh

4. TransformNode管理相关

方法返回值类型说明

addTransformNode(node: TransformNode)	TransformNode	添加 TransformNode至Scene
removeTransformNode(node: TransformNode)	boolean	从Scene中移除TransformNode
getTransformNodeById(id: string)	TransformNode \| null	根据 ID 查询 TransformNode
getTransformNodeByUniqueId(uniqueId: number)	TransformNode \| null	根据 UniqueId 查询 TransformNode
getTransformNodeByName(name: string)	TransformNode \| null	根据 Name 查询 TransformNode

5. Light管理相关

方法返回值类型说明

addLight(newLight: Light)	Light	添加 Light至Scene
removeLight(toRemove: Light)	boolean	从Scene中移除Light
getLightById(id: string)	Light \| null	根据 ID 查询 Light
getLightByUniqueId(uniqueId: number)	Light \| null	根据 UniqueId 查询 Light
getLightByName(name: string)	Light \| null	根据 Name 查询 Light

6. Material管理相关

方法返回值类型说明

addMaterial(material: Material)	Material	添加 Material至Scene
removeMaterial(material: Material)	boolean	从Scene中移除Material
getMaterialById(id: string)	Material \| null	根据 ID 查询 Material
getMaterialByUniqueId(uniqueId: number)	Material \| null	根据 UniqueId 查询 Material
getMaterialByName(name: string)	Material \| null	根据 Name 查询 Material
getLastMaterialById(id: string)	Material \|null	获取最后一个匹配 ID 的 Material

7. Texture管理相关

方法返回值类型说明

addTexture(texture: BaseTexture)	void	添加 Texture至Scene
removeTexture(texture: BaseTexture)	void	从Scene中移除Texture
getTextureByUniqueId(uniqueId: number)	BaseTexture \| null	根据 UniqueId 查询 Texture

8. Geometry管理相关

方法返回值类型说明

pushGeometry(geometry: Geometry, force?: boolean)	boolean	添加 Geometry至Scene
removeGeometry(geometry: Geometry)	boolean	从Scene中移除Geometry
getGeometryById(id: string)	Geometry \| null	根据 ID 查询 Geometry
getGeometryByUniqueId(uniqueId: number)	Geometry \|null	根据 UniqueId 查询 Geometry

9. Animation管理相关

方法返回值类型说明

beginAnimation(target: any, from: number, to: number, loop?: boolean, speedRatio?: number, onAnimationEnd?: Nullable<() => void>, animatable?: Animatable, stopCurrent?: boolean, targetMask?: (target: any) => boolean)	Animatable	播放动画
beginDirectAnimation(target: any, animations: Animation[], from: number, to: number, loop?: boolean, speedRatio?: number, onAnimationEnd?: Nullable<() => void>, animatable?: Animatable)	Animatable	播放直接动画
beginWeightedAnimation(target: any, from: number, to: number, weight: number, loop?: boolean, speedRatio?: number)	Animatable	播放权重动画
stopAnimation(target: any, animationName?: string, targetMask?: (target: any) => boolean)	void	停止指定动画
stopAllAnimations()	void	停止所有动画
getAnimatableByTarget(target: any)	Animatable \| null	获取目标动画控制器

10. Picking相关

方法返回值类型说明

pick(x: number, y: number, predicate?: MeshPredicate, fastCheck?: boolean, camera?: Camera, trianglePredicate?: TrianglePickingPredicate)	PickingInfo	屏幕坐标拾取
pickWithBoundingInfo(x: number, y: number, predicate?: MeshPredicate, fastCheck?: boolean, camera?: Camera)	PickingInfo	使用 BoundingInfo 进行快速拾取
pickWithRay(ray: Ray, predicate?: MeshPredicate, fastCheck?: boolean, trianglePredicate?: TrianglePickingPredicate)	PickingInfo	Ray 拾取
multiPick(x: number, y: number, predicate?: MeshPredicate, camera?: Camera, trianglePredicate?: TrianglePickingPredicate)	PickingInfo[] \| null	多对象拾取
multiPickWithRay(ray: Ray, predicate?: MeshPredicate, trianglePredicate?: TrianglePickingPredicate)	PickingInfo[] \|null	Ray 多对象拾取
createPickingRay(x: number, y: number, world?: Matrix, camera?: Camera, cameraViewSpace?: boolean)	Ray	创建 Picking Ray
createPickingRayToRef(x: number, y: number, world: Matrix, result: Ray, camera?: Camera, cameraViewSpace?: boolean)	Scene	创建 Picking Ray（ToRef）
createPickingRayInCameraSpace(x: number, y: number, camera?: Camera)	Ray	创建 Camera 空间 Picking Ray
createPickingRayInCameraSpaceToRef(x: number, y: number, result: Ray, camera?: Camera)	Scene	创建 Camera 空间 Picking Ray（ToRef）
getPointerOverMesh()	AbstractMesh \| null	获取当前 Pointer 下的 Mesh
setPointerOverMesh(mesh: Nullable<AbstractMesh>, pointerId?: number, pickResult?: PickingInfo)	void	设置 Pointer 当前悬停的 Mesh
simulatePointerMove(pickResult: PickingInfo, pointerEventInit?: PointerEventInit)	void	模拟 PointerMove 事件
simulatePointerDown(pickResult: PickingInfo, pointerEventInit?: PointerEventInit)	void	模拟 PointerDown 事件
simulatePointerUp(pickResult: PickingInfo, pointerEventInit?: PointerEventInit)	void	模拟 PointerUp 事件
isPointerCaptured(pointerId?: number)	boolean	判断 Pointer 是否已被当前 Scene 捕获

11. Environment/Rendering相关

方法返回值类型说明

createDefaultEnvironment(options?: IEnvironmentHelperOptions)	EnvironmentHelper \| null	创建默认环境
createDefaultSkybox(environmentTexture: BaseTexture, pbr?: boolean, scale?: number, blur?: number, setGlobalEnvTexture?: boolean)	Mesh \| null	创建默认天空盒
createDefaultCamera(createArcRotateCamera?: boolean,replace?: boolean,attachCameraControls?: boolean)	void	创建默认相机
createDefaultLight(replace?: boolean)	void	创建默认灯光
createDefaultCameraOrLight(createArcRotateCamera?: boolean,replace?: boolean,attachCameraControls?: boolean,)	void	创建默认相机与灯光
setRenderingOrder(renderingGroupId: number, opaqueSortCompareFn?: Nullable<(a: SubMesh, b: SubMesh) => number>, alphaTestSortCompareFn?: Nullable<(a: SubMesh, b: SubMesh) => number>, transparentSortCompareFn?: Nullable<(a: SubMesh, b: SubMesh) => number>)	void	设置指定 RenderingGroup 的渲染顺序
setRenderingAutoClearDepthStencil(renderingGroupId: number, autoClearDepthStencil: boolean, depth?: boolean, stencil?: boolean)	void	设置 RenderingGroup 是否自动清除 Depth / Stencil
markAllMaterialsAsDirty(flag: number, predicate?: (mat: Material) => boolean)	void	将符合条件的材质标记为 Dirty，触发重新编译或更新

12. Node管理相关

方法返回值类型说明

getNodeById(id: string)	Node \| null	根据 ID 查询 Node
getNodeByUniqueId(uniqueId: number)	Node \| null	根据 UniqueId 查询 Node
getNodeByName(name: string)	Node \| null	根据 Name 查询 Node
getLastEntryById(id: string)	Node \| null	获取最后一个匹配 ID 的对象
getLastEntryByName(name: string)	Node \|null	获取最后一个匹配 Name 的对象

13. Skeleton管理相关

方法返回值类型说明

addSkeleton(newSkeleton: Skeleton)	Skeleton \| null	添加 Skeleton至Scene
removeSkeleton(toRemove: Skeleton)	boolean	从Scene中移除Skeleton
getSkeletonByUniqueId(uniqueId: number)	Skeleton \| null	根据 UniqueId 查询 Skeleton
getBoneById(id: string)	Bone \| null	根据 ID 查询 Bone
getBoneByName(name: string)	Bone \|null	根据 Name 查询 Bone
getLastSkeletonById(id: string)	Skeleton \| null	获取最后一个匹配 Skeleton

14. EffectLayer管理相关

方法返回值类型说明

addEffectLayer(effectLayer: EffectLayer)	void	添加 EffectLayer至Scene
removeEffectLayer(effectLayer: EffectLayer)	void	从Scene中移除EffectLayer

15. ParticleSystem管理相关

方法返回值类型说明

addParticleSystem(ps: IParticleSystem)	void	添加 ParticleSystem至Scene
removeParticleSystem(ps: IParticleSystem)	void	从Scene中移除ParticleSystem

16. ActionManager管理相关

方法返回值类型说明

removeActionManager(actionManager: AbstractActionManager)

void

从Scene中移除ActionManager

17. PostProcess管理相关

方法返回值类型说明

removePostProcess(postProcess: PostProcess)

void

从Scene中移除PostProcess

18. ExternalData管理相关

方法返回值类型说明

addExternalData<T>(key: string, data: T)	void	添加外部数据
getExternalData<T>(key: string)	T \| null	获取外部数据
removeExternalData(key: string)	boolean	移除外部数据
getOrAddExternalDataWithFactory<T>(key: string, factory: (k: string) => T)	T	获取指定 Key 的外部数据，不存在时通过 Factory 创建并保存

19. Debug/Cache/Performance相关

方法返回值类型说明

getTotalVertices()	number	获取总顶点数
getActiveIndices()	number	获取当前渲染 Indices
getActiveParticles()	number	获取当前活跃粒子数
getActiveBones()	number	获取当前活跃骨骼数
getActiveMeshes()	SmartArray<AbstractMesh>	获取 Active Mesh
getAnimationRatio()	number	获取动画倍率
getRenderId()	number	当前 RenderId
getFrameId()	number	当前 FrameId
freeProcessedMaterials()	void	释放已处理材质缓存
freeActiveMeshes()	void	清空 ActiveMesh 缓存
freeRenderingGroups()	void	释放 RenderingGroup
freezeMaterials()	void	冻结全部材质
unfreezeMaterials()	void	解冻全部材质
freezeActiveMeshes(skipEvaluateActiveMeshes?: boolean, onSuccess?: () => void, onError?: (message: string) => void)	void	冻结 ActiveMesh
unfreezeActiveMeshes()	void	解冻 ActiveMesh
clearCachedVertexData()	void	清理顶点缓存
cleanCachedTextureBuffer()	void	清理纹理缓存
resetDrawCache(passId?: number)	void	重置 Draw Cache
getSceneUniformBuffer()	UniformBuffer	获取场景 UniformBuffer
createSceneUniformBuffer(name?: string)	UniformBuffer	创建 Scene UniformBuffer
setSceneUniformBuffer(buffer: UniformBuffer)	void	设置 Scene UniformBuffer

20. Matrix相关

方法返回值类型说明

getWorldExtends(filterPredicate?: (mesh: AbstractMesh) => boolean)	{ min: Vector3; max: Vector3 }	获取 Scene 世界包围盒范围
getViewMatrix()	Matrix	获取 View Matrix
getProjectionMatrix()	Matrix	获取 Projection Matrix
getTransformMatrix()	Matrix	获取 VP Matrix
setTransformMatrix(view: Matrix, projection: Matrix)	void	设置 View / Projection Matrix
updateTransformMatrix(force?: boolean)	void	更新 Transform Matrix

21. Tags查询相关

方法返回值类型说明

getMeshesByTags(tagsQuery: string)	AbstractMesh[]	根据 Tag 查询 Mesh
getCamerasByTags(tagsQuery: string)	Camera[]	根据 Tag 查询 Camera
getLightsByTags(tagsQuery: string)	Light[]	根据 Tag 查询 Light
getMaterialByTags(tagsQuery: string)	Material[]	根据 Tag 查询 Material
getTransformNodesByTags(tagsQuery: string)	TransformNode[]	根据 Tag 查询 TransformNode

22. MorphTarget管理相关

方法返回值类型说明

addMorphTargetManager(manager: MorphTargetManager)	MorphTargetManager	添加 MorphTargetManager至Scene
removeMorphTargetManager(manager: MorphTargetManager)	boolean	从Scene中移除MorphTargetManager
getMorphTargetManagerById(id: string)	MorphTargetManager \| null	根据 ID 查询 MorphTargetManager
getMorphTargetManagerByName(name: string)	MorphTargetManager \| null	根据 Name 查询 MorphTargetManager
getMorphTargetManagerByUniqueId(uniqueId: number)	MorphTargetManager \| null	根据 UniqueId 查询 MorphTargetManager

Part 5 Scene事件与生命周期

1. Callback方式

属性/方法名称属性值/返回值类型说明

isReady(checkRenderTargets?: boolean): boolean	boolean	判断 Scene 是否已完成初始化，可开始渲染
isLoading	boolean	当前 Scene 是否仍处于资源加载阶段
isDisposed	boolean	当前 Scene 是否已经释放
executeWhenReady(func: () => void, checkRenderTargets?: boolean)	void	Scene Ready 后执行
executeOnceBeforeRender(func: () => void, timeout?: number)	void	下一帧渲染前执行一次
onPointerMove	(evt: PointerEvent, pickInfo: PickingInfo, type: PointerEventTypes) => void	Pointer 移动回调
onPointerDown	(evt: PointerEvent, pickInfo: PickingInfo, type: PointerEventTypes) => void	Pointer 按下回调
onPointerUp	(evt: PointerEvent, pickInfo: PickingInfo, type: PointerEventTypes) => void	Pointer 抬起回调
onPointerPick	(evt: PointerEvent, pickInfo: PickingInfo) => void	Pointer Pick 回调
onActiveCameraChanged	Camera	ActiveCamera 发生变化
onActiveCamerasChanged	Camera[]	ActiveCameras 发生变化
beforeRender(callback: Nullable<() => void>)	void	每帧渲染前回调
afterRender(callback: Nullable<() => void>)	void	每帧渲染后回调
beforeCameraRender(callback: Nullable<(camera: Camera) => void>)	void	Camera 渲染前
afterCameraRender(callback: Nullable<(camera: Camera) => void>)	void	Camera 渲染后
onDispose(callback: Nullable<() => void>)	void	Scene 销毁回调
registerBeforeRender(func: () => void)	void	注册渲染前回调
unregisterBeforeRender(func: () => void)	void	注销渲染前回调
registerAfterRender(func: () => void)	void	注册渲染后回调
unregisterAfterRender(func: () => void)	void	注销渲染后回调
whenReadyAsync(checkRenderTargets?: boolean)	Promise	Promise 方式等待 Scene Ready

2. Observable方式

Observable泛型说明

onReadyObservable	Scene	Scene 初始化完成
onDisposeObservable	Scene	Scene 即将释放
onBeforeRenderObservable	Scene	每帧渲染开始前
onAfterRenderObservable	Scene	每帧渲染结束后
onBeforeAnimationsObservable	Scene	动画更新前
onAfterAnimationsObservable	Scene	动画更新后
onBeforeDrawPhaseObservable	Scene	Draw Phase 开始前
onAfterDrawPhaseObservable	Scene	Draw Phase 结束后
onBeforeActiveMeshesEvaluationObservable	Scene	ActiveMesh 计算前
onAfterActiveMeshesEvaluationObservable	Scene	ActiveMesh 计算后
onBeforeRenderingGroupObservable	RenderingGroupInfo	RenderingGroup 渲染前
onAfterRenderingGroupObservable	RenderingGroupInfo	RenderingGroup 渲染后
onBeforeRenderingMeshObservable	AbstractMesh	Mesh 渲染前
onAfterRenderingMeshObservable	AbstractMesh	Mesh 渲染后
onBeforeParticlesRenderingObservable	Scene	粒子渲染前
onAfterParticlesRenderingObservable	Scene	粒子渲染后
onBeforeSpritesRenderingObservable	Scene	Sprite 渲染前
onAfterSpritesRenderingObservable	Scene	Sprite 渲染后
onDataLoadedObservable	Scene	Scene 数据加载完成
onNewMeshAddedObservable	AbstractMesh	新增 Mesh
onMeshRemovedObservable	AbstractMesh	删除 Mesh
onNewTransformNodeAddedObservable	TransformNode	新增 TransformNode
onTransformNodeRemovedObservable	TransformNode	删除 TransformNode
onNewCameraAddedObservable	Camera	新增 Camera
onCameraRemovedObservable	Camera	删除 Camera
onNewLightAddedObservable	Light	新增 Light
onLightRemovedObservable	Light	删除 Light
onNewMaterialAddedObservable	Material	新增 Material
onMaterialRemovedObservable	Material	删除 Material
onNewTextureAddedObservable	BaseTexture	新增 Texture
onTextureRemovedObservable	BaseTexture	删除 Texture
onNewGeometryAddedObservable	Geometry	新增 Geometry
onGeometryRemovedObservable	Geometry	删除 Geometry
onBeforeAnimationsObservable	Scene	动画更新前
onAfterAnimationsObservable	Scene	动画更新后
onPointerObservable	PointerInfo	Pointer 统一事件入口
onPrePointerObservable	PointerInfoPre	Pointer 分发前
onKeyboardObservable	KeyboardInfo	键盘事件统一入口
onDisposeObservable	Scene	Scene 销毁时触发
onBeforeRenderTargetsRenderObservable	Scene	RenderTarget渲染前
onAfterRenderTargetsRenderObservable	Scene	RenderTarget渲染后

3. Observable类

Observable 是 Babylon.js 提供的统一事件通知机制。与 Callback 回调方式不同，Observable 提供了更加灵活的事件注册、注销、优先级控制以及事件广播能力。Scene 中所有以 onXXXObservable 命名的成员均为 Observable<T> 类型，因此均支持 add()、addOnce()、remove()、clear() 等通用事件管理方法。

属性/方法名称属性值/返回值类型说明

add(callback?: ((eventData: T, eventState: EventState) => void) \| null, mask?: number, insertFirst?: boolean, scope?: any, unregisterOnFirstCall?: boolean)	Observer<T> \| null	注册监听器
addOnce(callback?: ((eventData: T, eventState: EventState) => void) \| null)	Observer<T> \|null	注册一次性监听器
remove(observer: Nullable<Observer<T>>)	boolean	删除 Observer
removeCallback(callback: (eventData: T, eventState: EventState) => void, scope?: any)	boolean	删除指定回调
makeObserverTopPriority(observer: Observer<T>)	void	提升优先级
makeObserverBottomPriority(observer: Observer<T>)	void	降低优先级
notifyObservers(eventData: T, mask?: number, target?: any, currentTarget?: any, userInfo?: any)	boolean	通知所有 Observer
notifyObserver(observer: Observer<T>, eventData: T, mask?: number)	void	通知指定 Observer
hasObservers()	boolean	是否存在 Observer
clear()	void	清空所有 Observer
cleanLastNotifiedState()	void	清除 Observable 内部保存的最近一次通知状态
clone()	Observable<T>	克隆 Observable
hasSpecificMask(mask?: number)	boolean	是否存在指定 Mask

总结

Scene 是 Babylon.js 中最核心的管理类，也是整个三维场景的组织者。无论是场景配置、资源管理、渲染流程，还是事件系统与生命周期，都围绕 Scene 展开。熟悉 Scene 的 API，不仅能够快速完成日常开发，也能够帮助我们更好地理解 Babylon.js 的整体架构。

本文作为 Scene 上篇（API 参考），主要整理了 Scene 类、构造函数、配置项、实例属性、实例方法以及事件与生命周期等内容，希望能够为大家提供一份较为完整的 Scene API 查询手册。

在接下来的 Scene 中篇中，将不再围绕 API 展开，而是通过通俗易懂的方式，对 Node、TransformNode、Mesh、Camera、Light、Material、Texture、Skeleton、Animation 等核心对象及其相互关系进行梳理，帮助大家建立完整的 Scene 概念体系；Scene 下篇则会结合实际项目，总结常用功能实现、性能优化以及开发过程中遇到的典型问题与踩坑记录，希望能够帮助大家更高效地使用 Babylon.js。

Part 1 Scene类

1. 概述

2. 构造函数

3. 注意事项

Part 2 Scene配置项

Part 3 Scene实例属性

1. 场景基础相关

2. 场景对象集合

3. Environment/Rendering相关

4. 功能开关相关

5. 雾效果相关

6. Picking相关

7. Debug/Cache/Performance相关

8. Physics相关

Part 4 Scene实例方法

1. 场景基础相关

2. Camera管理相关

3. Mesh管理相关

4. TransformNode管理相关

5. Light管理相关

6. Material管理相关

7. Texture管理相关

8. Geometry管理相关

9. Animation管理相关

10. Picking相关

11. Environment/Rendering相关

12. Node管理相关

13. Skeleton管理相关

14. EffectLayer管理相关

15. ParticleSystem管理相关

16. ActionManager管理相关

17. PostProcess管理相关

18. ExternalData管理相关

19. Debug/Cache/Performance相关

20. Matrix相关

21. Tags查询相关

22. MorphTarget管理相关

Part 5 Scene事件与生命周期

1. Callback方式

2. Observable方式

3. Observable类

总结

相关推荐

评论 抢沙发

评论前必须登录！

热门标签

置顶推荐

热门文章

最新文章

评论抢沙发