Migrate a Decentraland SDK6 Scene to SDK7

This is a porting skill, not a scaffolding skill. It assumes an existing SDK6 project on disk. For a brand-new SDK7 scene, use [[create-scene]].

RULE: Verify it really is SDK6 before doing anything

Inspect these files in this order. ALL of the SDK6 signals must be present before treating the project as SDK6 — partial matches usually mean a half-migrated project that needs a different approach.

Check	SDK6 signal	SDK7 signal
`package.json` dependencies	`decentraland-ecs`	`@dcl/sdk`
`package.json` scripts	`build-ecs` , `dcl start`	`sdk-commands start` , `sdk-commands build`
`scene.json`	No `runtimeVersion` , or `ecs7` missing	`"runtimeVersion": "7"` and/or `"ecs7": true`
Source code imports	No explicit `@dcl/sdk/ecs` import — symbols ( `Entity` , `Transform` , `Vector3` , `engine` ) are globals	Most things imported from `@dcl/sdk/ecs` and `@dcl/sdk/math`
Source code patterns	`new Entity()` , `entity.addComponent(...)` , `@Component('name')` , `class X implements ISystem` , `OnPointerDown` , `GLTFShape` , `Input.instance`	`engine.addEntity()` , `Transform.create(entity, ...)` , `engine.defineComponent(...)` , `pointerEventsSystem.onPointerDown` , `GltfContainer`

RULE: Do NOT change

scene.json

main

field

Keep the

main

value the SDK6 project already had (typically

"bin/game.js"

). The SDK7 default for new scenes is

bin/index.js

, but

sdk-commands build

writes the bundle to whatever path

scene.json

main

names (verified:

sdk-commands

bundle.ts

sets the output file from

sceneJson.main

) — so an existing

bin/game.js

keeps working with no changes. Do NOT rename it to
bin/index.js
unless the user explicitly asks.

You SHOULD add

"runtimeVersion": "7"

scene.json

(and remove anything ECS6-specific). See [[create-scene]] for the full scene.json schema.

RULE: The composite-first rule applies to migrations too

After migration, all static scenery (models, lights, primitives, text placed at scene load) belongs in

assets/scene/main.composite

, NOT in TypeScript. SDK6 scenes have no composite — every entity is created in code. Migrating those into a composite is a separate, optional pass; the minimum-viable migration leaves them as

engine.addEntity()

in TypeScript so the scene runs first.

Order of operations:

Get the SDK7 TypeScript port running (entities still created in code).
THEN, optionally, move static entities into
```
assets/scene/main.composite
```
. See [[create-scene]] for the composite-first rule and [[composites]] for the format.

The Conceptual Shift — read this before writing any code

SDK6 modeled entities as objects with components attached to them. SDK7 is a true ECS where entities are just opaque IDs and components are pure data.

Concept	SDK6	SDK7
Entity creation	`const e = new Entity()` then `engine.addEntity(e)`	`const e = engine.addEntity()` (returns the ID)
Entity type	`IEntity` / `Entity` class with methods ( `addComponent` , `getComponent` , `setParent` , `alive` )	`Entity` = opaque integer ID, NO methods
Adding a component	`entity.addComponent(new Transform({...}))` — entry point is the entity	`Transform.create(entity, {...})` — entry point is the component type
Defining a component	`@Component('name') class GemData { val: number; constructor(...) {...} }`	`export const GemData = engine.defineComponent('gemData', { val: Schemas.Number }, { val: 2 })` — schema + defaults, NO methods
Component methods ( `reset()` , etc.)	Allowed (class methods)	Forbidden — components are data only. Move methods into free functions or systems
Reading component data	`entity.getComponent(GemData).val` (always mutable)	`GemData.get(entity).val` (immutable, fast) OR `GemData.getMutable(entity).val = X` (only when writing)
Modifying component data	Mutate the returned reference	MUST use `getMutable()` — `.get()` returns a read-only reference. Using `.get()` and mutating it silently fails
Parenting	`child.setParent(parent)`	Set `parent` field of child's Transform: `Transform.create(child, { parent: parentEntity })` or `Transform.getMutable(child).parent = parentEntity`
Defining a system	`class MoveGems implements ISystem { update(dt) {...} }` then `engine.addSystem(new MoveGems())`	`export function moveGemsSystem(dt: number) { ... }` then `engine.addSystem(moveGemsSystem)`
Querying entities	`const group = engine.getComponentGroup(Transform, GemData)` then `group.entities`	`for (const [entity, gemData, transform] of engine.getEntitiesWith(GemData, Transform)) { ... }`
Removing an entity	`engine.removeEntity(entity)`	`engine.removeEntity(entity)` (same API)
Event callbacks on components	`entity.addComponent(new OnPointerDown((e) => {...}))`	`pointerEventsSystem.onPointerDown({entity, opts}, () => {...})` — separated from the component
Static "scene-level" objects	`Camera.instance` , `Input.instance` (singletons)	`engine.PlayerEntity` , `engine.CameraEntity` , `engine.RootEntity` + component reads ( `Transform.get(engine.PlayerEntity)` )

Mutability is a performance contract, not just style. Always prefer

.get()

(read) over

.getMutable()

(write). Using

.getMutable()

when you only read causes a CRDT delta to be sent every frame.

API Mapping — quick reference

See

{baseDir}/references/api-mapping.md

for the full table. The most common conversions:

SDK6	SDK7
`import { ... } from 'decentraland-ecs'` (often implicit)	`import { engine, Transform, GltfContainer, Vector3, Quaternion, Color4 } from '@dcl/sdk/ecs'` + `'@dcl/sdk/math'`
`new Entity()` + `engine.addEntity(entity)`	`const entity = engine.addEntity()`
`entity.addComponent(new Transform({position, rotation, scale}))`	`Transform.create(entity, { position, rotation, scale })`
`entity.getComponent(Transform)` (read/write)	`Transform.get(entity)` (read) / `Transform.getMutable(entity)` (write)
`entity.getComponentOrCreate(Transform)`	`Transform.getOrCreateMutable(entity)`
`entity.addComponentOrReplace(...)`	`Component.createOrReplace(entity, {...})`
`entity.hasComponent(Transform)`	`Transform.has(entity)`
`entity.removeComponent(Transform)`	`Transform.deleteFrom(entity)`
`child.setParent(parent)`	`Transform.getMutable(child).parent = parent` (or pass `parent` in `create` )
`new GLTFShape('models/x.glb')` + `entity.addComponent(shape)`	`GltfContainer.create(entity, { src: 'models/x.glb' })`
`new BoxShape()` / `new PlaneShape()` / `new SphereShape()` / `new CylinderShape()`	`MeshRenderer.setBox(entity)` / `setPlane(entity)` / `setSphere(entity)` / `setCylinder(entity)` (add `MeshCollider.setBox(entity)` etc. for collision)
`new Material()` + `m.albedoColor = Color3.Blue()` + `entity.addComponent(m)`	`Material.setPbrMaterial(entity, { albedoColor: Color4.Blue() })` (note: Color4 in SDK7)
`new BasicMaterial()` + `m.texture = new Texture(...)`	`Material.setBasicMaterial(entity, { texture: Material.Texture.Common({ src }) })`
`new TextShape(text)` + `t.fontSize = 1`	`TextShape.create(entity, { text, fontSize: 1 })`
`new Animator()` + `new AnimationState('Clip')` + `animator.addClip(state)`	`Animator.create(entity, { states: [{ clip: 'Clip', playing: false, loop: false }] })` ; play with `Animator.playSingleAnimation(entity, 'Clip')` ; stop with `Animator.stopAllAnimations(entity)`
`new OnPointerDown(handler, { button, hoverText })` on the entity	`pointerEventsSystem.onPointerDown({ entity, opts: { button: InputAction.IA_POINTER, hoverText } }, handler)`
`Input.instance.subscribe('BUTTON_DOWN', ActionButton.POINTER, false, handler)`	`inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_DOWN)` inside a system, or `pointerEventsSystem.onPointerDown` for entity-specific
`ActionButton.POINTER` / `.PRIMARY` / `.SECONDARY`	`InputAction.IA_POINTER` / `.IA_PRIMARY` / `.IA_SECONDARY`
`Camera.instance.position` / `.rotation`	`Transform.get(engine.CameraEntity).position` / `.rotation`
`new Vector3(x, y, z)`	`Vector3.create(x, y, z)`
`Quaternion.Euler(x, y, z)`	`Quaternion.fromEulerDegrees(x, y, z)`
`Color3.Blue()`	`Color4.Blue()` (most SDK7 component fields use Color4)
`Vector3.Lerp(a, b, t)`	`Vector3.lerp(a, b, t)` (lowercase l)
`Scalar.Lerp(a, b, t)`	`Scalar.lerp(a, b, t)`
`vector.setAll(0.5)`	`Vector3.create(0.5, 0.5, 0.5)` (no mutating helper — Vector3 is treated as plain data)
`class X implements ISystem { update(dt) {...} }` + `engine.addSystem(new X())`	`function xSystem(dt: number) { ... }` + `engine.addSystem(xSystem)`
`engine.getComponentGroup(A, B)` returning `.entities`	`engine.getEntitiesWith(A, B)` returning iterable of `[entity, a, b]` tuples
`log(...)`	`console.log(...)`
`entity.addComponent(new utils.Delay(ms, cb))` (from `decentraland-ecs-utils` / `@dcl-sdk/utils` )	`timers.setTimeout(cb, ms)` ( `import { timers } from '@dcl/sdk/ecs'` , argument order is `(callback, ms)` )
`entity.addComponent(new utils.Interval(ms, cb))`	`timers.setInterval(cb, ms)` ( `import { timers } from '@dcl/sdk/ecs'` )
Custom per-frame `timerSystem` accumulating `dt`	Delete it — use `timers.setTimeout` / `timers.setInterval` instead

Migration Workflow

Do this in order. Skipping steps leads to a broken scene that's hard to debug.

1. Audit the SDK6 project

Read every source file. Build a list of:

Every custom
```
@Component
```
class — these become
```
engine.defineComponent(...)
```
with a flat schema. Class methods (
```
reset()
```
, etc.) must be lifted out into free functions or systems.

Every

class X implements ISystem

— these become free functions

(dt: number) => void

Every

OnPointerDown

OnPointerUp

Input.instance.subscribe

— these become

pointerEventsSystem

calls or

inputSystem.isTriggered()

in a system.

Every
```
GLTFShape
```
,
```
BoxShape
```
, etc. — see mapping table.
Every
```
Camera.instance
```
,
```
Input.instance
```
— these become static engine entities + component reads.
All
```
setParent
```
calls — these become
```
Transform.parent
```
field assignments.

This list is the completion checklist for steps 5–10 — each of those steps is done only when every item in its category has been ported and its SDK6 symbols no longer appear in the source.

2. Replace

package.json

tsconfig.json

, and update

scene.json

Replace
```
decentraland-ecs
```
with
```
@dcl/sdk
```
(latest).

Replace

build-ecs

dcl start

scripts with

sdk-commands start

sdk-commands build

Replace the old

tsconfig.json

with the standard SDK7 one (

target: ES2020

module: ESNext

jsx: react-jsx

strict: true

Add
```
"runtimeVersion": "7"
```
to
```
scene.json
```
. Do NOT modify
main
unless the user asks.

3. Reorganize asset folders under

assets/

SDK6 scenes commonly kept assets in top-level folders at the project root:

models/

images/

audio/

(or

sounds/

textures/

videos/

. SDK7 + Creator Hub expects assets under a top-level assets/
folder so the visual editor can index them. Do this move as a discrete step BEFORE porting any code — that way the path rewrites in later steps can target the final locations directly.

Identify every top-level asset folder in the SDK6 project. Common SDK6 names:
```
models/
```
,
```
images/
```
,
```
audio/
```
,
```
sounds/
```
,
```
textures/
```
,
```
videos/
```
.
Create the new structure under
```
assets/
```
using the capitalized category convention used elsewhere in these skills (see [[create-scene]], [[add-3d-models]], [[audio-video]]):
- ```
models/
```
  →
```
assets/Models/
```
- ```
images/
```
  →
```
assets/Images/
```
- ```
audio/
```
  or
```
sounds/
```
  →
```
assets/Audio/
```
- ```
videos/
```
  →
```
assets/Videos/
```
- ```
textures/
```
  →
```
assets/Images/
```
  (textures are images; consolidate unless the user wants a separate folder)
Move files into the new structure. Do NOT leave duplicate copies — delete the old top-level folders once the move is complete. Dual copies cause Creator Hub to index stale paths and roughly double scene size on deploy (both copies get bundled).

Rewrite every code reference to the moved paths. Grep the entire source tree for the old folder names and update each hit:

GltfContainer.create(e, { src: 'models/chair.glb' })

→

... { src: 'assets/Models/chair.glb' }

AudioSource.create(e, { audioClipUrl: 'sounds/click.mp3' })

→

... 'assets/Audio/click.mp3'

Material.Texture.Common({ src: 'textures/logo.png' })

→

... 'assets/Images/logo.png'

React-ECS

<UiEntity uiBackground={{ texture: { src: 'images/icon.png' } }} />

→

... 'assets/Images/icon.png'

Any string literal mentioning the old folder name anywhere in code, JSON, or
```
.composite
```
files.

Done when: grepping the project for the old folder names returns zero remaining references, and opening the scene in Creator Hub shows the asset tree populated from
```
assets/
```
.

Exception — reuse existing layout if present. If the project already contains

assets/scene/Models/

(the legacy Creator Hub layout) or

assets/asset-packs/

assets/custom/

(Creator Hub adds these for asset-pack items and custom items), reuse those paths instead of creating a parallel

assets/Models/

. The rule is: one canonical location per asset type — don't fragment.

4. Create

src/index.ts

with an exported

main()

SDK7 scenes start from a top-level exported

main()

function. The convention is to put most code in another file (e.g.

src/game.ts

) and have

index.ts

just call into it:

typescript

import { initializeGame } from "./game";
export function main() {
  initializeGame();
}

5. Port components first

Convert each

@Component

class to

engine.defineComponent(name, schema, defaults)

. Flatten nested types —

Schemas

does not support arbitrary classes, but does support

Schemas.Vector3

Schemas.Quaternion

, primitives, arrays, and nested

Schemas.Map(...)

. A

Vector2

field in SDK6 typically becomes two scalar fields (

posX

posY

) in SDK7 — see the 2048 example in

{baseDir}/references/migration-example.md

Done when:

grep -rn "@Component(" src/

returns zero hits and every component on the step-1 audit list has a corresponding

engine.defineComponent

call.

6. Port systems

Each

class X implements ISystem { update(dt) {...} }

becomes a free function. Replace

engine.getComponentGroup(A, B).entities

iteration with

for (const [entity, a, b] of engine.getEntitiesWith(A, B))

. Inside the loop, use

.getMutable(entity)

only when writing.

Done when:

grep -rnE "implements ISystem|getComponentGroup" src/

returns zero hits and every system on the step-1 audit list is registered via

engine.addSystem

7. Port the entity/component setup (the bulk of

game.ts

)

For each

new Entity()

block, replace with

engine.addEntity()

and a series of

Component.create(entity, ...)

calls. Convert

setParent

to a

parent

field on the Transform. Use the new

assets/Models/...

assets/Audio/...

assets/Images/...

paths established in step 3 for every

src

audioClipUrl

texture.src

Done when:

grep -rnE "new Entity\(|\.addComponent\(|\.setParent\(" src/

returns zero hits, and no

src

audioClipUrl

/ texture path still references a pre-step-3 folder.

8. Port input/pointer handlers

Per-entity click handlers (

new OnPointerDown(...)

) →

pointerEventsSystem.onPointerDown({ entity, opts }, handler)

. Add a collider if the entity doesn't already have one (

MeshCollider.setBox(entity)

visibleMeshesCollisionMask: 1

GltfContainer

). See [[add-interactivity]].

Global key subscriptions (

Input.instance.subscribe

) → use

inputSystem.isTriggered(InputAction.IA_X, PointerEventType.PET_DOWN)

inside a system. See [[advanced-input]].

Done when:

grep -rnE "OnPointerDown|OnPointerUp|Input\.instance|ActionButton\." src/

returns zero hits and every handler on the step-1 audit list has a

pointerEventsSystem

inputSystem

counterpart.

9. Port animations

new Animator()

new AnimationState('clip')

animator.addClip(...)

becomes a single

Animator.create(entity, { states: [{ clip, playing, loop }] })

. Play with

Animator.playSingleAnimation(entity, 'clip')

. Stop all with

Animator.stopAllAnimations(entity)

. See [[animations-tweens]].

Done when:

grep -rnE "new Animator|AnimationState|addClip|getClip" src/

returns zero hits, and every clip name that appears in an SDK6

playAnimation

getClip

call is listed in some

states[]

array — clips missing from

states[]

fail silently (see the

playSingleAnimation

pitfall in Common Pitfalls).

10. Port sounds

new AudioClip(url)

entity.addComponent(new AudioSource(clip))

becomes

AudioSource.create(entity, { audioClipUrl: url, playing: false, ... })

. Play by toggling

AudioSource.getMutable(entity).playing = true

. See [[audio-video]].

Done when:

grep -rnE "new AudioClip|new AudioSource\(" src/

returns zero hits.

11. Verify and test

Run

npm install

to fetch the new SDK, then

sdk-commands start

(or

npm start

). The migration is complete only when ALL of these hold:

```
npm run build
```
exits 0.
A final sweep
```
grep -rnE "decentraland-ecs|@Component\(|implements ISystem|Input\.instance|Camera\.instance" src/
```
returns zero hits — per-step greps get missed when work is interrupted and resumed; this is the end-to-end check.
The preview loads with no errors in the console.
The visible layout (positions/rotations) matches the SDK6 scene.

If any check fails, return to the step that owns that symbol category — do NOT report the migration as done.

Common Pitfalls

Mutating a
.get()
result:

Transform.get(entity).position.x = 5

is silently a no-op. Use

Transform.getMutable(entity).position.x = 5

Passing explicit
rotation: undefined
/
scale: undefined
to
Transform.create
crashes the serializer: symptom is

"Cannot read properties of undefined (reading 'x')"

at serialization. Why (verified —

@dcl/ecs/dist/components/manual/Transform.js

Transform.create

runs the value through

TransformSchema.extend

, which spreads

...value

AFTER its defaults, so an explicit

undefined

field overrides the default identity rotation / unit scale and is stored as

undefined

; the binary

serialize

then reads

value.rotation.x

and throws. This bites when a port builds a Transform from a partial object that may carry

undefined

fields (e.g.

Transform.create(e, { position, rotation: maybeRot, scale: maybeScale })

). Fix — omit the field entirely instead of passing
undefined
so the schema applies its default:

typescript

const out: Partial<TransformType> = { position }
if (rotation) out.rotation = rotation
if (scale) out.scale = scale
if (parent !== undefined) out.parent = parent
Transform.create(entity, out)

Forgetting the schema:
```
engine.defineComponent
```
REQUIRES a schema. SDK6 class fields with no type cannot be auto-inferred.
Component methods: SDK6 components frequently had a
```
reset()
```
or constructor logic. These MUST be moved to free functions in SDK7 — components are pure data.
Vector2 fields:
```
Schemas
```
does NOT have
```
Schemas.Vector2
```
. [UNVERIFIED — confirm by reading the Schemas object exports.] Flatten to two
```
Schemas.Number
```
fields, or use
```
Schemas.Map({ x: Schemas.Number, y: Schemas.Number })
```
.
setParent
on the entity object: Entities are integers in SDK7 — there is no method. Set the
```
parent
```
field on the child's
```
Transform
```
.
Color3 vs Color4: Most SDK7 component fields take
```
Color4
```
(with alpha). Replace
```
Color3.X()
```
calls with
```
Color4.X()
```
unless the field is documented as Color3.
Materials are not entities or objects: There is no
```
new Material()
```
instance you keep a reference to.
```
Material.setPbrMaterial(entity, props)
```
is the only way to set it — a material lives on one entity, not as a shared object.
Shape entities (BoxShape, PlaneShape, etc.) need MeshRenderer AND MeshCollider: In SDK6 a single
```
BoxShape
```
did both render and collide (with a flag). In SDK7 these are two separate components — add both if you need clicks/physics on a primitive.
GLTFShape had its visible mesh clickable by default with
withCollisions: true
: In SDK7,
```
GltfContainer
```
by default only has collisions on the invisible _collider mesh. Some models may not be ready for that. If an entity is no longer clickable from a lack of collider, it may need explicit
```
visibleMeshesCollisionMask
```
set to a value including
```
CL_POINTER
```
(1) for clicks, or
```
CL_PHYSICS
```
(2) for player collision, or
```
3
```
for both. See [[add-3d-models]].
OnPointerDown
callbacks no longer fire inside a
forEach
over a component group: In SDK6 they were event-driven; in SDK7 you register the handler once with
```
pointerEventsSystem.onPointerDown(...)
```
— don't put that call inside a system's update loop or you'll register a new handler every frame.
Animator.playSingleAnimation
silently no-ops on clips not in
Animator.states
(porters who built the Animator in code): this applies specifically to the SDK6-port path where you author the
```
Animator
```
yourself in TypeScript and call
```
Animator.playSingleAnimation(entity, clipName)
```
programmatically. In that case,
```
playSingleAnimation
```
returns
```
false
```
and does nothing if
```
clipName
```
isn't already present in the entity's
```
states
```
array (verified —
```
@dcl/ecs/dist-cjs/components/extended/Animator.js
```
lines 35-46). No warning. SDK6 hid this —
```
Animator.getClip(name)
```
auto-created the clip on first use, so SDK6 scenes routinely call
```
playAnimation('Appear')
```
without declaring
```
'Appear'
```
upfront. A naive port that maps
```
entity.getComponent(Animator).getClip(name).play()
```
→
```
Animator.playSingleAnimation(entity, name)
```
ends up calling it against clip names the porter never added to
```
states[]
```
, and those calls silently fail. Fix: walk every
```
playAnimation
```
/
```
getClip
```
call in the SDK6 source, collect the full set of clip names per entity, and list them all in the
```
states
```
array at
```
Animator.create
```
time. For a quick port-friendly shim that restores SDK6's "play any clip, no setup" ergonomics with a lazy
```
states.push
```
, see the wrapper in [[animations-tweens]] (PITFALL section). This rule does not apply to scenes whose Animator was written by the Creator Hub Inspector (which pre-populates
```
states[]
```
with every GLB clip) or by asset packs / smart items (which ship with
```
states
```
populated), nor to models with no
```
Animator
```
at all — those rely on the autoplay path in the next bullet.
Unnecessary serialization overhead when porting
anim.stop(); anim.play()
to a hand-rolled SDK7 helper called every frame: applies when you replace SDK6's
```
anim.stop(); anim.play()
```
with a custom SDK7 helper that directly mutates
```
Animator.states
```
(
```
s.playing
```
,
```
s.shouldReset
```
) AND that helper is invoked from a per-frame caller — a system update, or an input/raycast callback that fires every tick the input is held. The animation will NOT freeze (the CRDT unchanged-mutable suppression layer in
```
@dcl/ecs
```
detects identical writes and silently drops them), but calling
```
getMutableOrNull()
```
every tick incurs unnecessary serialization + byte-comparison overhead each frame. Fix: track the last-applied clip per entity and short-circuit the helper when unchanged; on a
```
noLoop + revertToIdle
```
re-call with the same clip, only refresh the revert timer instead of re-mutating states; clear the tracked clip before re-applying the idle clip from the revert callback. Does NOT apply when the helper is called only on a state transition (one-shot
```
onPointerDown
```
, edge-triggered state machine), nor when you use
```
Animator.playSingleAnimation
```
from a transition rather than a per-frame caller. See the "Short-circuit clip-switch helpers" best practice in [[animations-tweens]] for the full helper pattern.
GltfContainer
autoplays one clip from a multi-animation .glb when no
Animator
is attached: SDK6 models stayed in their bind pose by default; SDK7 picks one clip from the .glb and plays it. This is the same mechanism that lets clip-less Inspector scenes work without registration — it's the complement to the previous bullet, not a contradiction. When the entity has no
```
Animator
```
, the renderer autoplays; when the entity has an
```
Animator
```
and you call
```
playSingleAnimation
```
, the clip must be in
```
states[]
```
. Which clip the renderer autoplays is not stable across models — observed cases include a Halloween scene where small ghosts with no
```
Animator
```
autoplayed
```
die
```
straight from the GLB. Fix when you want a different default: attach an
```
Animator.create(entity, { states: [{ clip: '<intended-default>', playing: true, loop: true }] })
```
to take control. Fix when you also want to switch clips at runtime via
playSingleAnimation
: list every clip you'll switch to in
```
states[]
```
(see previous bullet).
Input.instance.subscribe
with
BUTTON_DOWN
/
BUTTON_UP
: there is no direct callback equivalent. Use
```
inputSystem.isTriggered()
```
inside a system for "just pressed this frame".
@dcl/ecs-scene-utils
trigger areas (the "Utils library") AND hand-rolled per-frame AABB checks: do NOT port the custom per-frame position-checking system, and do NOT recreate it from scratch in SDK7. SDK6 had no native trigger area, so the community Utils library (and many scenes' bespoke code) polled
```
Camera.instance.position
```
against a box/sphere region every frame and fired
```
onCameraEnter
```
/
```
onCameraExit
```
. SDK7 has a native
```
TriggerArea
```
component (
```
@dcl/sdk/ecs
```
) — replace the entire pattern with
```
TriggerArea.setBox(entity)
```
(or
```
.setSphere
```
) +
```
triggerAreaEventsSystem.onTriggerEnter(entity, cb)
```
/
```
.onTriggerExit
```
/
```
.onTriggerStay
```
. Size comes from
```
Transform.scale
```
, position from
```
Transform.position
```
, and the parent chain is respected — so triggers parented to a rotated/offset scene root Just Work without manual coordinate transforms. Behavior parity: the Utils library only ever fired for the local player; native
```
TriggerArea
```
defaults to
```
ColliderLayer.CL_PLAYER
```
, which fires for ANY player on that layer. The correct guard for local-player-only behavior is
```
if (result.trigger?.entity !== engine.PlayerEntity) return
```
(NOT
```
result.triggeredEntity
```
— despite the confusing name,
```
triggeredEntity
```
is the trigger area's own entity, so comparing it to the player is always true and the guard never fires). See the "Trigger areas" section of
```
{baseDir}/references/api-mapping.md
```
and [[add-interactivity]] for the full component reference.
utils.Delay
/
utils.ExpireIn
from
decentraland-ecs-utils
(later
@dcl-sdk/utils
) AND hand-rolled per-frame timer systems: do NOT port the community
```
Delay
```
component, do NOT recreate it in SDK7, and do NOT write a custom
```
setSceneTimeout
```
helper backed by a
```
timerSystem
```
that accumulates
```
dt
```
. Use the timers
named export from
@dcl/sdk/ecs
(
```
import { timers } from '@dcl/sdk/ecs'
```
) — it provides
```
setTimeout
```
/
```
clearTimeout
```
/
```
setInterval
```
/
```
clearInterval
```
bound to the scene engine. Replace
```
entity.addComponent(new utils.Delay(2000, cb))
```
with
```
timers.setTimeout(cb, 2000)
```
and delete the "timer entity" the SDK6 scene created just to host the Delay component. Argument order is
(callback, ms)
, NOT
```
(ms, callback)
```
— the SDK6
```
Delay(ms, cb)
```
order is the opposite of the JS standard, and custom helpers written with the SDK6 order are a known footgun that compounds the original mistake of writing the helper in the first place. Do NOT use the native JS
setTimeout
/
setInterval
globals — although QuickJS exposes them, they are not bound to the scene engine and can introduce subtle problems; always go through
```
timers
```
. See [[scene-runtime]] (Timers section) for the full reference.
SDK6 "intercepting tool" smart-items (keys, magnets, inventory items that act on a clicked target via
```
Input.instance.subscribe('BUTTON_DOWN', ActionButton.POINTER, true, …)
```
+ entity-hierarchy walking) have no direct SDK7 equivalent.
```
pointerEventsSystem.onPointerDown
```
is per-entity only — there is no global hit-result subscriber. The migration pattern is a small registry keyed by target entity name; the target's own
```
pointerEventsSystem.onPointerDown
```
consults the registry before falling back to its default behavior. See
```
{baseDir}/references/api-mapping.md#click-interception-across-entities-keytool-acting-on-a-target
```
.
Vector3.GetAngleBetweenVectors
,
Vector3.Up()
etc.: many SDK6 Vector3 helpers existed as static methods. SDK7 keeps most under
```
@dcl/sdk/math
```
but capitalization changed (e.g.
```
Vector3.Lerp
```
→
```
Vector3.lerp
```
). Grep for
```
Vector3.
```
after migration and verify each call against the math module.
log()
is not exported in SDK7: replace with
```
console.log()
```
.
Attachable.FIRST_PERSON_CAMERA
/
Attachable.AVATAR
on held items (guns, aiming reticles, flashlights, fixed-position tools): SDK6 only offered two coarse follow modes —
```
Attachable.FIRST_PERSON_CAMERA
```
(follow the camera) and
```
Attachable.AVATAR
```
(follow the avatar root). In SDK7 you have a new choice that didn't exist before: bone-level
```
AvatarAttach
```
with
```
anchorPointId
```
(e.g.
```
AAPT_RIGHT_HAND
```
). The bone anchor looks like the natural SDK7 equivalent of "put it in the avatar's hand", but bone anchors inherit avatar animation (idle bob, walk cycle, gestures) — a gun attached to
```
AAPT_RIGHT_HAND
```
jitters every frame and is unaimable. The correct SDK7 mapping for held gameplay items is to parent the entity via
```
Transform.parent
```
, not
```
AvatarAttach
```
. For any aim-sensitive item (gun, reticle, flashlight, anything the player should be able to point by looking around), the right SDK7 default is
Transform.parent = engine.CameraEntity
— this mirrors SDK6's
```
FIRST_PERSON_CAMERA
```
and tracks both yaw AND pitch, so the muzzle aims where the camera looks.
```
Transform.parent = engine.PlayerEntity
```
is a different choice and a common subtle failure mode: it follows the player root (feet position + body yaw only, no pitch and no animation), so a gun parented to
```
PlayerEntity
```
stays flat when the player tilts the camera up to aim — the item ignores the look direction. Use
```
PlayerEntity
```
only for body-fixed items that should NOT track aim (a held shield, a static torch, a non-aimed inventory item carried at hip-level). Reserve
```
AvatarAttach
```
for cosmetic items where riding the animation is desired (hats, halos, backpacks, name plates). Picking by intent —
```
engine.CameraEntity
```
(aim-sensitive, the recommended default for held weapons),
```
engine.PlayerEntity
```
(yaw-only / no pitch, for body-fixed items),
```
AvatarAttach(boneId)
```
(cosmetic only, animates with the bone). See the "Held items vs cosmetic items" section of [[player-avatar]] for the comparison table and a worked gun example.
Billboarded models may appear facing AWAY from the camera after porting: observed in some SDK6 → SDK7 ports — a model that displayed its front face under SDK6's
```
new Billboard(false, true, false)
```
(Y-axis billboard) shows its back to the camera under SDK7's
```
Billboard.create(e, { billboardMode: BillboardMode.BM_Y })
```
with the same parent/child setup. The two SDKs appear to disagree on which model face (+Z vs -Z) the billboard points at the camera. The SDK7
PBBillboard
interface has no
oppositeDirection
flag — the only field is
```
billboardMode
```
(verified against
```
@dcl/ecs
```
```
billboard.gen.d.ts
```
), so the fix is in the model's Transform, not the Billboard component. Rotate the displayed model 180° on Y (
```
Quaternion.fromEulerDegrees(0, 180, 0)
```
). If the entity is a parent (
```
Billboard
```
'd) + a child model, apply the 180° rotation to the child's
```
Transform.rotation
```
— the parent entity's rotation is owned by the Billboard component and overwriting it on the billboarded entity has no effect. [UNVERIFIED whether this was an explicit SDK behavior change with a changelog entry, or a consequence of a separate convention change in the model importer — phrase any user-facing explanation as "the two SDKs disagree on billboard facing direction" rather than claiming a specific version introduced it.] See [[advanced-rendering]] (Billboard) for the SDK7 component reference.
UI pixel sizes do NOT carry over 1:1: SDK6 UI (
```
UICanvas
```
/
```
UIImage
```
/
```
UIText
```
) was authored in raw pixels against a fixed screen size, so positions and sizes like
```
width = 200
```
or
```
positionX = -350
```
were absolute. SDK7 React-ECS UI lays out in raw screen pixels by default, but the actual screen size depends on the user's machine — so an SDK6 layout copied over verbatim will appear at a different relative size on every display. The fix is to set a virtual canvas on
```
ReactEcsRenderer.setUiRenderer
```
, which makes the engine treat your pixel values as coordinates inside that virtual space and scale to the real screen. Before porting UI, check the SDK6 source (the legacy ECS lives at https://github.com/decentraland/ecs) to see what pixel grid the original UI was designed against, and pass that as the virtual size:
ts
```
ReactEcsRenderer.setUiRenderer(uiRoot, { virtualWidth: 1920, virtualHeight: 1080 })
```
```
1920x1080
```
is a reasonable default to show, but the correct virtualWidth/virtualHeight depends on the resolution the SDK6 UI was authored against — if the SDK6 scene assumed a different reference resolution (e.g.
```
1280x720
```
), use those numbers instead so existing pixel coordinates land in the same place. See [[build-ui]] for the full React-ECS rewrite.

What is genuinely hard to migrate

These don't have a clean 1:1 mapping and need redesign:

Components with methods or constructors that do work (e.g.
```
GemData.reset(val, x, y)
```
): split the data into the new component, move the logic into a free function that takes
```
(entity: Entity, val: number, ...)
```
and calls
```
Component.getMutable(entity)
```
.
Component groups that the user holds a reference to and iterates many times: SDK7
```
engine.getEntitiesWith(...)
```
is recomputed each call. For hot loops over the same set, cache it inside the system or accept the cost.
Object pools that rely on
entity.alive
: SDK7 entities don't have an
```
alive
```
flag. Pools must track liveness with a custom component or by checking
```
Component.has(entity)
```
. The Migrated-2048 example simplified this to "always add a new entity" — that's acceptable for low-throughput cases, but a real pool needs explicit state.
UI built with the SDK6
UICanvas
/
UIImage
/
UIText
/
UIClickable
: not API-compatible with SDK7. SDK7 UI is React-ECS (JSX). See [[build-ui]] — this often requires a from-scratch rewrite. When porting, also set a virtual canvas size on
```
ReactEcsRenderer.setUiRenderer
```
so the SDK6 pixel coordinates scale predictably across screens — see the UI pixel sizing pitfall in Common Pitfalls above.
@Component('name')
decorator metadata: SDK7 component IDs are strings supplied to
```
engine.defineComponent('name', ...)
```
. Use the same name as the SDK6 decorator if other tools (composites, multiplayer sync) reference it by name. Otherwise pick a consistent naming scheme.

Cross-References

[[create-scene]] — scene.json schema, composite-first rule, scaffolding a fresh SDK7 project
[[composites]] —
```
.composite
```
file format for the optional second pass that moves static entities out of TypeScript
[[add-3d-models]] —
```
GltfContainer
```
, collider masks for clickability
[[add-interactivity]] —
```
pointerEventsSystem
```
(replaces SDK6
```
OnPointerDown
```
)
[[advanced-input]] —
```
inputSystem
```
polling (replaces SDK6
```
Input.instance.subscribe
```
)

[[scene-runtime]] —

timers.setTimeout

timers.setInterval

from

@dcl/sdk/ecs

(replaces SDK6 community

decentraland-ecs-utils

Delay

Interval

executeTask

fetch

, realm/scene info

[[animations-tweens]] —
```
Animator
```
and
```
Tween
```
(replaces SDK6
```
Animator
```
/
```
AnimationState
```
)
[[audio-video]] —
```
AudioSource
```
and
```
VideoPlayer
```
[[build-ui]] — React-ECS UI (replaces SDK6
```
UICanvas
```
UI system)
[[advanced-rendering]] — PBR materials, TextShape, Billboard
[[multiplayer-sync]] —
```
syncEntity
```
for multiplayer (replaces SDK6
```
MessageBus
```
/ sync libraries)

References

```
{baseDir}/references/api-mapping.md
```
— full table of SDK6 → SDK7 symbol conversions
```
{baseDir}/references/migration-example.md
```
— annotated before/after using the 2048 game scene (entity setup, components, systems, pointer events, animations)

migrate-sdk6-to-sdk7

NPX Install

SKILL.md Content

Migrate a Decentraland SDK6 Scene to SDK7

RULE: Verify it really is SDK6 before doing anything

RULE: Do NOT change
`scene.json`
's
`main`
field

RULE: The composite-first rule applies to migrations too

The Conceptual Shift — read this before writing any code

API Mapping — quick reference

Migration Workflow

1. Audit the SDK6 project

2. Replace
`package.json`
,
`tsconfig.json`
, and update
`scene.json`

3. Reorganize asset folders under
`assets/`

4. Create
`src/index.ts`
with an exported
`main()`

5. Port components first

6. Port systems

7. Port the entity/component setup (the bulk of
`game.ts`
)

8. Port input/pointer handlers

9. Port animations

10. Port sounds

11. Verify and test

Common Pitfalls

What is genuinely hard to migrate

Cross-References

References

migrate-sdk6-to-sdk7

NPX Install

SKILL.md Content

Migrate a Decentraland SDK6 Scene to SDK7

RULE: Verify it really is SDK6 before doing anything

RULE: Do NOT change scene.json's main field

RULE: The composite-first rule applies to migrations too

The Conceptual Shift — read this before writing any code

API Mapping — quick reference

Migration Workflow

1. Audit the SDK6 project

2. Replace package.json, tsconfig.json, and update scene.json

3. Reorganize asset folders under assets/

4. Create src/index.ts with an exported main()

5. Port components first

6. Port systems

7. Port the entity/component setup (the bulk of game.ts)

8. Port input/pointer handlers

9. Port animations

10. Port sounds

11. Verify and test

Common Pitfalls

What is genuinely hard to migrate

Cross-References

References

RULE: Do NOT change
`scene.json`
's
`main`
field

2. Replace
`package.json`
,
`tsconfig.json`
, and update
`scene.json`

3. Reorganize asset folders under
`assets/`

4. Create
`src/index.ts`
with an exported
`main()`

7. Port the entity/component setup (the bulk of
`game.ts`
)