Skip to content

Migration Guide

Jump to bottom
zhuxudong edited this page May 28, 2025 · 34 revisions

1.4.0 → 1.5.0

  • We delete intensity property in Light component, you can directly premultiply the intensity into the color.
  • We have reorganized the color management system so that all colors will be treated as linear values, so if you are not upgrading your project through the editor, you will need to manually convert the colors to linear using Color#toLinear

1.3.0 → 1.4.0

  • The parameters carried by the Script.onPointerXXX callback are changed from Pointer to PointerEventData containing more content.
  • The package name of ShaderLab is renamed from @galacean/engine-shader-lab to @galacean/engine-shaderlab.

Spine runtime API Breaking Changes:

  • Deprecated manual creation via addComponent(SpineAnimationRenderer) + set SpineResource. ➔ Use new SpineResource.instantiate() method to create Spine entities directly.
  • Renamed parameter: defaultState → defaultConfig (improved clarity for animation configuration)
  • Removed default scale configuration in Spine animation. ➔ Adjust animation size via Entity's scale property instead.
  • Added premultipliedAlpha parameter ➔ Enable when using pre-multiplied textures exported from Spine Editor.

1.1.0 → 1.2.0

  • The problem of Camera's renderTarget using Y-axis flipping as a texture has been fixed, and the related Shader needs to remove the Y-axis flipping specialization logic

  • glTF models containing draco compression are no longer supported, please use Meshopt compression

0.9.0 → 1.0.0

  • Transform direction-related API adjusted from method to property:

    • getWorldForward(forward: Vector3) -> get worldForward

    • getWorldRight(right: Vector3) -> get worldRight

    • getWorldUp(up: Vector3) -> get worldUp

  • Time-related adjustments:

    • Redesign Time and unified time unit to second

    • Migrate PhysicsManager maxAllowedTimeStep to Time maximumDeltaTime

  • Parameter adjustment related to physical collision in the script:

    • onCollisionEnter(other: ColliderShape): void-> onCollisionEnter(other: Collision): void

    • onCollisionExit(other: ColliderShape): void-> onCollisionExit(other: Collision): void

    • onCollisionStay(other: ColliderShape): void-> onCollisionStay(other: Collision): void

  • glTF Loader Asset type adjustment, AssetType.Prefab -> AssetType.GLTF

  • The initialization of the engine is adjusted to be asynchronous:

    • Canvas and WebGL graphic device parameter adjustment, before:

      new WebGLEngine("canvas",{alpha:true})

      Now:

      WebGLEngine.create({ canvas: "canvas", graphicDeviceOptions:{alpha:true}})

    • PhyscX backend does not require a separate initialization，before:

      PhysXPhysics.initialize().then(() => {
  const engine = new WebGLEngine("canvas");
  engine.physicsManager.initialize(PhysXPhysics);
  ......
}

      Now:

      WebGLEngine.create({ canvas: "canvas", physics: new PhysXPhysics()}).then(
  (engine) => {
  ......
  }

  • SkyBoxMaterial textureCubeMap -> texture

  • SkyBoxMaterial textureCubeMap -> texture

  • get shader property, before:

     Shader.getPropertyByName('propertyName');

    Now:

    ShaderProperty.getByName('propertyName');

  • create Shader with shadow's method, before:

     Shader.create("custom-shader", vs, fs);

    Now:

      const forwardPassTags = {
    pipelineStage: PipelineStage.Forward
  };

 const shadowCasterPass = Shader.find("pbr").subShaders[0].passes[1];
 Shader.create("custom-shader",[new ShaderPass(vs, fs, forwardPassTags), shadowCasterPass])

  • Built-in shader variables and macro changes:

    Shader variables

    • u_directLightDirection -> scene_DirectLightDirection

    • u_pointLightCullingMask -> scene_PointLightCullingMask

    • u_pointLightPosition -> scene_PointLightPosition

    • u_pointLightDistance -> scene_PointLightDistance

    • u_spotLightCullingMask -> scene_SpotLightCullingMask

    • u_spotLightColor -> scene_SpotLightColor

    • u_spotLightPosition -> scene_SpotLightPosition

    • u_spotLightDirection -> scene_SpotLightDirection

    • u_spotLightDistance -> scene_SpotLightDistance

    • u_spotLightAngleCos -> scene_SpotLightAngleCos

    • u_spotLightPenumbraCos -> scene_SpotLightPenumbraCos

    • u_env_specularSampler -> scene_EnvSpecularSampler

    • u_env_sh -> scene_EnvSH

    • u_envMapLight -> scene_EnvMapLight

    • u_directLightCullingMask -> scene_DirectLightCullingMask

    • u_directLightColor -> scene_DirectLightColor

    • u_shadowInfo -> scene_ShadowInfo

    • u_viewMat -> camera_ViewMat

    • u_projMat -> camera_ProjMat

    • u_VPMat -> camera_VPMat

    • u_viewInvMat -> camera_ViewInvMat

    • u_cameraPos -> camera_Position

    • u_localMat -> renderer_LocalMat

    • u_modelMat -> renderer_ModelMat

    • u_MVMat -> renderer_MVMat

    • u_MVPMat -> renderer_MVPMat

    • u_MVInvMat -> renderer_MVInvMat

    • oasis_RendererLayer -> renderer_Layer

    • u_normalMat -> renderer_NormalMat

    • u_normalTexture -> material_NormalTexture

    • u_normalIntensity -> material_NormalIntensity

    • u_baseColor -> material_BaseColor

    • u_baseTexture -> material_BaseTexture

    • u_tilingOffset -> material_TilingOffset

    • u_metal -> material_Metal

    • u_roughness -> material_Roughness

    • u_PBRSpecularColor -> material_PBRSpecularColor

    • u_glossiness -> material_Glossiness

    • u_alphaCutoff -> material_AlphaCutoff

    • u_roughnessMetallicTexture -> material_RoughnessMetallicTexture

    • u_occlusionTextureCoord -> material_OcclusionTextureCoord

    • u_occlusionTexture -> material_OcclusionTexture

    • u_occlusionIntensity -> material_OcclusionIntensity

    • u_emissiveColor -> material_EmissiveColor

    • u_emissiveTexture -> material_EmissiveTexture

    • u_clearCoatRoughness -> material_ClearCoatRoughness

    • u_clearCoatRoughnessTexture -> material_ClearCoatRoughnessTexture

    • u_clearCoatTexture -> material_ClearCoatTexture

    • u_clearCoat -> material_ClearCoat

    Macros

    • O3_DIRECT_LIGHT_COUNT -> SCENE_DIRECT_LIGHT_COUNT

    • O3_POINT_LIGHT_COUNT -> SCENE_POINT_LIGHT_COUNT

    • O3_SPOT_LIGHT_COUNT -> SCENE_SPOT_LIGHT_COUNT

    • OASIS_CALCULATE_SHADOWS -> SCENE_IS_CALCULATE_SHADOWS

    • O3_USE_SPECULAR_ENV -> SCENE_USE_SPECULAR_ENV

    • O3_USE_SH -> SCENE_USE_SH

    • O3_HAS_NORMAL -> RENDERER_HAS_NORMAL

    • O3_HAS_TANGENT -> RENDERER_HAS_TANGENT

    • O3_HAS_UV -> RENDERER_HAS_UV

    • O3_HAS_UV1 -> RENDERER_HAS_UV1

    • OASIS_RECEIVE_SHADOWS -> RENDERER_IS_RECEIVE_SHADOWS

    • NORMALTEXTURE -> MATERIAL_HAS_NORMALTEXTURE

    • HAS_CLEARCOATNORMALTEXTURE -> MATERIAL_HAS_CLEAR_COAT_NORMAL_TEXTURE

    • BASETEXTURE -> MATERIAL_HAS_BASETEXTURE

    • ALPHA_CUTOFF -> MATERIAL_IS_ALPHA_CUTOFF

    • ROUGHNESSMETALLICTEXTURE -> MATERIAL_HAS_ROUGHNESS_METALLIC_TEXTURE

    • OCCLUSIONTEXTURE -> MATERIAL_HAS_OCCLUSION_TEXTURE

    • EMISSIVETEXTURE -> MATERIAL_HAS_EMISSIVETEXTURE

    • OASIS_TRANSPARENT -> MATERIAL_IS_TRANSPARENT

    • O3_NEED_WORLDPOS -> MATERIAL_NEED_WORLD_POS

    • O3_NEED_TILINGOFFSET -> MATERIAL_NEED_TILING_OFFSET

    • OMIT_NORMAL -> MATERIAL_OMIT_NORMAL

    • O3_SPECULAR_TEXTURE -> MATERIAL_HAS_SPECULAR_TEXTURE

    • HAS_CLEARCOATTEXTURE -> MATERIAL_HAS_CLEAR_COAT_TEXTURE

    • CLEARCOAT -> MATERIAL_ENABLE_CLEAR_COAT

    • HAS_CLEARCOATROUGHNESSTEXTURE -> MATERIAL_HAS_CLEAR_COAT_ROUGHNESS_TEXTURE

    • SPECULARGLOSSINESSTEXTURE -> MATERIAL_HAS_SPECULAR_GLOSSINESS_TEXTURE

0.9.0 Beta → 0.9.0

  • The Oasis brand name has been changed to Galacean, and the corresponding npm package has also been changed from oasis-engine to @galacean/engine. Upgrade steps:

    • Change npm package from oasis-engine to @galacean/engine
    • Adjust all imports to @galacean/engine, for example: import { Entity } from "@galacean/engine;"

0.8.0 → 0.9.0 Beta

  • InputManager support get multi pointer detailed data ability, InputManager.pointerMovingDelta can use InputManager.pointers[x].deltaPosition instead, InputManager.pointerPosition use InputManager.pointers[x].position instead https://github.com/ant-galaxy/oasis-engine/pull/1005

0.7.0 → 0.8.0

0.6.0 → 0.7.0

  • The physics param of WebGLEngine and Engine's constructor is removed, Please use PhysicsManager.initialize() to set the backend physics engine.
  • Rename TextureCubeMap to TextureMap.
  • RenderColorTexture and RenderDepthTexture are removed, the colorTextures and depthTexture of the RenderTarget need to adjust from RenderColorTexture and RenderDepthTexture to Texture.

# Want to contribute to this Galacean?

Fork it and send a pull request.

Project Management

Architecture design

中文指引

Clone this wiki locally