Lumberyard
User Guide (Version 1.16)

Converting Entities with the Legacy Converter

This feature is in preview release and is subject to change.

The Legacy Converter converts your legacy entities (CryEntities) to the new component entity system. Legacy features will eventually be removed from Lumberyard Editor. When you use the Legacy Converter, it tries to convert all legacy entities in your level. You cannot select which entities to convert or skip. Once an entity is converted, it cannot be converted back to a legacy entity.

Converting Your Legacy Entities

If your level has legacy entities, Lumberyard Editor detects them and prompts you to convert them.

To convert your legacy entities

  1. Do any of the following to open the Legacy Converter:

    • If the CryEntity Removal gem is enabled, and you load a level that contains legacy entities, the Legacy Converter opens by default.

    • In Lumberyard Editor, choose File, Upgrade Legacy Entities.

    Note

    The CryEntity Removal gem disables all legacy features in Lumberyard Editor. For more information, see the CryEntity Removal Gem.

  2. The dialog box shows the number of legacy entities in your level. Choose Convert Entities.

    A progress bar appears that shows the number of entities that the Legacy Converter is processing. The conversion takes several seconds to complete.

    
                        The conversion log shows which entities were converted and which
                            were not in Lumberyard.
  3. After the conversion completes, the dialog box shows the number of converted and unconverted entities. See the Status and Message columns for more information. Choose OK.

    
                        The conversion log shows that entities converted and which did not
                            in Lumberyard.

    Note

    If the Legacy Converter can't convert an entity, a Conversion Error dialog box appears that shows the number of entities that were not converted. If the CryEntity Removal gem is enabled, unconverted entities remain in your level but cannot be edited. For more information, choose View Log. You can also choose Export Log to save the conversion log as a .csv file.

List of Legacy Entity Conversions

The Legacy Converter converts each legacy entity to its corresponding component entity. For a list of legacy entities, see the Entity Reference in the Amazon Lumberyard Legacy Reference.

Converted entities keep the same position in the viewport. For more information, see Using the Viewport.

Note

Some legacy entities cannot be converted at this time.

See the following tables for the converted component entity.

Area Box Entity

An area box entity is converted to a component entity that is attached with a Box Shape component.

Settings in Area Box Entity Converted Settings in Box Shape Component

Width

Dimensions : x

Length

Dimensions : y

Height

Dimensions : z

Area Sphere Entity

An area sphere entity is converted to a component entity that is attached with a Sphere Shape component.

Settings in Area Sphere Entity Converted Settings in Sphere Shape Component

Radius

Radius

Brush, Geom, and Simple Entities

The brush, geom, and simple entities are converted to a component entity that is attached with a Mesh component or Skinned Mesh component, depending on the asset type.

Settings in Brush, Geom, and Simple Entities Converted Settings in Mesh or Skinned Mesh Components

Geometry (set to .cdf files)

Character Definition (Skinned Mesh component)

Geometry (set to non .cdf file)

Static asset (Mesh component)

Camera Entity

A camera entity is converted to a component entity that is attached with a Camera component.

Settings in Camera Entity Converted Settings in Camera Component

FOV

Field of View

NearZ

Near Clip Distance

FarZ

Far Clip Distance

Camera Target Entity

The camera target entity is converted to an empty component entity.

Comment Entity

A Comment entity is converted to a component entity that is attached with a component.

Settings in Comment Entity Converted Settings in Comment Component

Text

Comment

Environment Probe Entity

The environment probe entity is converted to a component entity that is attached with an Environment Probe component.

Settings in Environment Probe Entity Converted Settings in Environment Probe Component

EnvironmentProbe Params : cubemap_resolution

Environment Probe Settings : Resolution

EnvironmentProbe Params : Outdoor Only

Options : Indoor only

EnvironmentProbe Params : ViewDistanceMultiplier

Options : View distance multiplier

EnvironmentProbe Properties : Active

On initially

EnvironmentProbe Properties : BoxSizeX

Environment Probe Settings : Area dimensions : X

EnvironmentProbe Properties : BoxSizeY Environment Probe Settings : Area dimensions : Y
EnvironmentProbe Properties : BoxSizeZ Environment Probe Settings : Area dimensions : Z

Color : Diffuse

General Settings : Color

Color : DiffuseMultiplier General Settings : Diffuse multiplier
Color : SpecularMultiplier General Settings : Specular multiplier

Options : AffectVolumetricFogOnly

Options : Volumetric fog only

Options : AttenuatioinFallofMax

Environment Probe Settings : Attenuation fall off

Options : IgnoresVisAreas

Options : Ignore vis areas

Options : Sort Priority

Environment Probe Settings : Sort priority

Options : VolumetricFog

Options : Volumetric fog

OptionsAdvanced : deferred_cubemap

Cubemap generation: Cubemap asset

Projection : BoxHeight

Environment Probe Settings : Box height

Projection : BoxLength

Environment Probe Settings : Box length
Projection : BoxProject Environment Probe Settings : Box projected
Projection : BoxWidth Environment Probe Settings : Box width

Decal Entity

A decal entity is converted to a component entity that is attached with a Decal component.

Settings in Decal Entity Converted Settings in Decal Component

Entity : Mtl

Decal Settings : Material

Entity : MinSpec

Decal Settings : Minimum spec

Entity Params : ProjectType

Decal Settings : Projection type

Entity Params : Deferred

Decal Settings : Deferred

Entity Params : View Distance Multiplier

Options : View distance multiplier

Entity Params : SortPriority

Decal Settings : View distance multiplier

Entity Params : Projection Depth (Deferred)

Decal Settings : Depth

Designer Objects

The Legacy Converter converts designer objects to a component entity that is attached with the following components:

The Legacy Converter converts the original shape of designer objects into .cgf files and then saves them to your game project directory.

Settings in Designer Object Converted Settings in Mesh Component

Geometry

Mesh asset (.cgf file)

Example

  1. You have a legacy designer object named Designer1 shaped as a sphere.

    
                                Legacy designer object before conversion.
  2. With the Legacy Converter, you convert the object into a entity with the Mesh, Static Physics, and Mesh Collider components attached.

    
                                The log shows that converted legacy designer
                                    object.
  3. The Legacy Converter creates a .cgf file and saves it to the lumberyard_version\dev\game-project\Objects\DesignerConversion\level-name\ directory.

    
                                The converted designer object is a mesh asset file.
  4. In the Mesh component, the Mesh asset property specifies this Designer1.cgf file. The entity has the same shape as the original designer object.

    
                                The converted designer object is a mesh asset file.

Note

You cannot edit a designer object after it is converted into a component entity. You can use the legacy Designer Tool to create your object and convert it again. For more information, see Using the Designer Tool in the Amazon Lumberyard Legacy Reference.

Groups and Layers

Groups and layers are converted to empty component entities with the same names.

Legacy entities that are nested under legacy groups or layers appear nested under the newly created component entities, which keep the same hierarchy.

If a legacy entity belongs to a layer and a group, the converted component entity appears under the converted group component entity. It also appears as a child of the converted layer component entity.

Example

  1. You have the following legacy entities in your level:

    • LegacyEntityA, LegacyEntityB and LegacyEntityC are grouped under LegacyGroupA, so the hierarchy appears as: LegacyGroupA [LegacyEntityA, LegacyEntityB, LegacyEntityC]

    • LegacyEntityA belongs to LegacyLayerA, so the hierarchy appears as: LegacyLayerA [LegacyEntityA]

  2. You use the Legacy Converter to convert your entities.

  3. The converted entities have the following hierarchy:

    ComponentEntityLayerA [ComponentEntityGroupA[ComponentEntityA, ComponentEntityB, ComponentEntityC]]

Light Entity

A light entity with the Planar Light setting specified is converted to a component entity that is attached with a Area Light component.

A light entity with the Projector setting specified to Texture is converted to a component entity attached with a Projector Light component.

A light entity with neither the Planar Light or Projector setting specified to Texture is converted to a component entity attached with a Point Light component

Settings in Light Entity Converted Settings Common in Area Light, Projector Light, and Point Light Components

Entity Params : Outdoor Only

Options : Indoor Only

Entity Params : ViewDistanceMultiplier

Options : View distance multiplier

Entity Params : HiddenInGame

Visible

Entity Properties : Active

On initially

Entity Properties : Color : Diffuse

General Settings : Color

Entity Properties : Color : DiffuseMultiplier General Settings : Diffuse multiplier
Entity Properties : Color : SpecularMultiplier General Settings : Specular multiplier
Entity Properties : Options : AffectsThisAreaOnly

Options : Affects this area only

Entity Properties : Options : AffectsVolumetricFogOnly Options : Volumetric fog only
Entity Properties : Options : Ambient General Settings : Ambient
Entity Properties : Options : IgnoresVisArea Options : Ignore vis areas
Entity Properties : Options : VolumetricFog Options : Volumetric fog
Entity Properties : Style : LightStyle

Animation : Style

Entity Properties : Style : AnimationSpeed

Animation : Speed

Entity Properties : Style : AnimationPhase

Animation : Phase

Entity Properties : Shadows : CastShadows (spec)

Options : Cast shadow spec

The following settings appear only in the Entity Inspector when the setting Cast shadow spec has any value, expect Never.
Entity Properties : Shadows : ShadowBias

Shadow Settings : Shadow bias

Entity Properties : Shadows : ShadowResolutionScale Shadow Settings : Shadow resolution scale
Entity Properties : Shadows : ShadowSlopeBias Shadow Settings : Shadow slope bias
Entity Properties : Shadows : ShadowUpdateMinRadius Shadow Settings : Shadow update radius
Entity Properties : Shadows : ShadowUpdateRatio Shadow Settings : Shadow update ratio

Settings in Light Entity Converted Settings in Projector Light Component

AttenuationBulbSize

Projector Light Settings : Attenuation bulb size

Projector : ProjectNearPlane Projector Light Settings : Near plane

Projector : ProjectorFov

Projector Light Settings : FOV

Projector : Texture

Projector Light Settings : Texture

Radius

Projector Light Settings : Max distance

Settings in Light Entity Converted Settings in Area Light Component

Radius

Area Light Settings : Max distance

Shape : SourceDiameter

Area Light Settings : Area height

Shape : SourceWidth

Area Light Settings : Area width

Settings in Light Entity Converted Settings in Point Light Component

AttenuatioinBulbSize

Point Light Settings : Attenuation bulb size

Radius

Point Light Settings : Max distance

Light Entity with Lens Flare

A light entity with a lens flare is converted to a component entity that is attached with a Lens Flare component and a light component.

The lens flare asset that is specified for a light entity is converted to the Lens Flare component settings: Library and Lens flare.

Settings in Light Entity Converted Settings in Point Light Component

Entity Properties : Style : FlareFOV

Flare Settings : FOV

Particle Effect Entity

The particle effect entity is converted to a component entity that is attached with a Particle component.

Settings in Particle Effect Entity Settings in Particle Component

ParticleEntity Properties : Prime

Spawn Settings : Pre-Roll

ParticleEntity Properties : CountScale

Spawn Settings : Count scale

ParticleEntity Properties : TimeScale

Spawn Settings : Time scale

ParticleEntity Properties : PulsePeriod

Spawn Settings : Pulse period

ParticleEntity Properties : Scale

Spawn Settings : Speed scale

ParticleEntity Properties : Strength

Spawn Settings : Strength curve time

Audio : EnableAudio

Audio Settings : Enable audio

Audio : Rtpc

Audio Settings : Audio RTPC

Proximity Trigger Entity

A proximity trigger entity is converted to a component entity attached with a Box Shape component, and a Trigger Area component.

Settings in Proximity Trigger Entity Converted Settings in Box Shape Component

Entity Properties : DimX

Dimensions : x

Entity Properties : DimY

Dimensions : y

Entity Properties : DimZ

Dimensions : z

Tag Point Entity

A tag point entity is converted to an empty component entity.