dcl-regenesislabs/game-design

Decentraland Game Design & Scene Optimization

1. DCL Game Design Philosophy

Decentraland is a continuous, shared 3D world. Design around these constraints:

• No startup screen: The scene is always live. Players walk in from adjacent parcels — there is no splash screen, no "press start." Your scene must be meaningful the instant a player arrives.
• No forced endings: You cannot force a "game over" state. Players can leave at any time by walking away or teleporting. Design loops that accommodate drop-in / drop-out naturally.
• Cannot remove players: There is no API to eject a player from a scene. You can teleport a player, but only with their consent (they must accept the prompt). Design around misbehaving players with game mechanics, not eviction.
• Boundary awareness: Players standing outside your parcel can see into it. Your scene is always on display. Neighboring scenes are visible too — consider visual harmony.
• Shared space: Multiple players are always potentially present. Even a "single-player" puzzle is witnessed by others. Embrace or account for this.

2. Scene Limitation Formulas

All limits scale with parcel count n. Except for hard MB file-size limits on deploy, all other limits CAN be exceeded — scenes won't crash, but performance degrades and the scene may be unusable on low-end devices. Treat the table as guidelines, not enforcement.

| Resource | Formula | 1 parcel | 2 parcels | 4 parcels | 9 parcels | 16 parcels | |---|---|---|---|---|---|---| | Triangles | n x 10,000 | 10,000 | 20,000 | 40,000 | 90,000 | 160,000 | | Entities | n x 200 | 200 | 400 | 800 | 1,800 | 3,200 | | Physics bodies | n x 300 | 300 | 600 | 1,200 | 2,700 | 4,800 | | Materials | log2(n+1) x 20 | 20 | 31 | 46 | 66 | 81 | | Textures | log2(n+1) x 10 | 10 | 15 | 23 | 33 | 40 | | Height limit | log2(n+1) x 20m | 20m | 31m | 46m | 66m | 81m | | Draw calls | n x 300 (target) | 300 | 600 | 1,200 | 2,700 | 4,800 |

File limits: 15 MB per parcel, 300 MB max total, 200 files per parcel, 50 MB max per individual file.

3. Texture Requirements

• Dimensions must be power-of-two: 256, 512, 1024, 2048
• Recommended sizes: 1024x1024 for scene objects, 512x512 for wearables
• Use texture atlases to combine multiple small textures into one, reducing draw calls and material count
• Prefer compressed formats (WebP) over raw PNG where possible
• Share texture references across materials — do not duplicate texture files

4. Asset Preloading (AssetLoad Component)

For large assets that would cause visible pop-in, use AssetLoad to pre-download before rendering:

import { engine, AssetLoad, LoadingState, GltfContainer, Transform } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

const preloadEntity = engine.addEntity()
AssetLoad.create(preloadEntity, { src: 'models/large-model.glb' })

function assetLoadingSystem(dt: number) {
  for (const [entity] of engine.getEntitiesWith(AssetLoad)) {
    const state = AssetLoad.get(entity)
    if (state.loadingState === LoadingState.FINISHED) {
      GltfContainer.create(entity, { src: 'models/large-model.glb' })
      Transform.create(entity, { position: Vector3.create(8, 0, 8) })
      AssetLoad.deleteFrom(entity)
    }
  }
}
engine.addSystem(assetLoadingSystem)

Use this pattern for any model over ~1 MB or for assets that should be ready before a game phase begins.

5. Performance Patterns

Object Pooling

Reuse entities instead of creating and destroying them:

const pool: Entity[] = []

function getFromPool(): Entity {
  const existing = pool.pop()
  if (existing) return existing
  return engine.addEntity()
}

function returnToPool(entity: Entity) {
  Transform.getMutable(entity).position = Vector3.create(0, -100, 0)
  pool.push(entity)
}

LOD (Level of Detail)

Swap models or hide entities based on distance from the player:

function lodSystem() {
  const playerPos = Transform.get(engine.PlayerEntity).position
  for (const [entity, transform] of engine.getEntitiesWith(Transform, GltfContainer)) {
    const distance = Vector3.distance(playerPos, transform.position)
    VisibilityComponent.createOrReplace(entity, { visible: distance <= 30 })
  }
}
engine.addSystem(lodSystem)

Draw Call Reduction

• Merge meshes in Blender before export
• Use texture atlases (one material for many objects)
• Limit unique materials — reuse them across entities
• Avoid transparency when possible (transparent objects cost extra draw calls)

System Optimization

• Do NOT run heavy logic every frame. Use timers:

  let timer = 0
  function heavySystem(dt: number) {
    timer += dt
    if (timer < 0.5) return // Run every 500ms, not every frame
    timer = 0
    // ... expensive work here
  }
  

• Minimize engine.getEntitiesWith() queries — cache results when entity sets are stable
• Avoid allocating new objects (Vector3.create, arrays) inside systems that run every frame

Disable Unused Colliders

Remove collision meshes from decorative objects that players never interact with. This reduces physics body count significantly.

6. Input System Design

| Input | Action | Notes | |---|---|---| | E key | Primary action (IA_PRIMARY) | Main interaction | | F key | Secondary action (IA_SECONDARY) | Alternate interaction | | Pointer click | IA_POINTER | Left mouse click / tap | | Keys 1-4 | IA_ACTION_3 through IA_ACTION_6 | Action bar slots |

Design Considerations

• Mouse wheel is not available as an input
• Always design for both desktop and mobile. Mobile has no keyboard — rely on pointer and on-screen buttons
• Set maxDistance on pointer events (8-10 meters typical) to prevent interactions from across the scene
• Use hoverText to communicate what an interaction does before the player commits

7. State Management Patterns

Module-Level State (Simple Games)

// game-state.ts
export let score = 0
export let gamePhase: 'waiting' | 'playing' | 'ended' = 'waiting'
export function addScore(points: number) { score += points }

Component-Based State (Complex Games)

Use custom components as structured data containers:

import { engine, Schemas } from '@dcl/sdk/ecs'

const EnemyState = engine.defineComponent('EnemyState', {
  health: Schemas.Number,
  speed: Schemas.Number,
  target: Schemas.Entity
})

State Machines

Model game phases as explicit states with clear transitions:

type GameState = 'lobby' | 'countdown' | 'active' | 'cooldown'
let currentState: GameState = 'lobby'

function gameStateSystem(dt: number) {
  switch (currentState) {
    case 'lobby': handleLobby(dt); break
    case 'countdown': handleCountdown(dt); break
    case 'active': handleActive(dt); break
    case 'cooldown': handleCooldown(dt); break
  }
}

8. UX/UI Guidelines

• Keep UI minimal: The metaverse is about 3D presence, not 2D overlays. Avoid large HUDs that obscure the world.
• Prefer spatial UI: Use TextShape on entities and 3D signs over screen-space UI whenever the information is tied to a place or object.
• Clear affordances: Interactive objects should look interactive. Use glow effects, outlines, floating indicators, or subtle animations to signal "you can click this."
• Sound feedback: Every significant player action should produce audio feedback. It confirms the action registered and adds polish.
• Progressive disclosure: Do not dump all information at once. Reveal mechanics and story as the player engages. Start simple, layer complexity.
• Immediate feedback: When a player interacts, respond within the same frame. Use tweens, sounds, or UI popups so the player never wonders "did that work?"
• Accessibility: Use high-contrast text, readable font sizes (fontSize >= 16 for screen UI), and audio cues alongside visual ones.

9. MVP Planning

Start with the Core Loop

Ask: What does the player DO? The answer should be a single sentence:

• "The player explores rooms and finds hidden objects."
• "The player races other players through an obstacle course."
• "The player collects resources and builds structures."

Prototype Fast

• Build in 1-2 parcels first, even if the final scene will be larger
• Use primitive shapes (boxes, spheres) as placeholders — do not wait for final art
• Get the core loop working before adding any secondary features

Test Early

• Deploy to a test world and walk through it yourself
• Invite 2-3 real players and watch them (do not explain the game — see if it is self-explanatory)
• Measure: Do players understand what to do within 30 seconds?

Iterate on Fun

• Polish comes last. If the core loop is not fun with placeholder art, better art will not fix it
• Cut features aggressively. A tight, small experience beats a sprawling, unfinished one
• Replay value matters more than content volume in DCL (players return to scenes they enjoy)

MVP Checklist

• Core loop is playable in under 60 seconds
• Works with 1 player and with 5+ players simultaneously
• Fits within scene limits for target parcel count
• Has clear visual/audio feedback for all interactions
• Player understands the goal without external instructions

Starting from scratch? See the create-scene skill first to scaffold the project before designing the game.

10. Cross-References

| Topic | Skill | When to Use | |---|---|---| | Interactivity, input handling, raycasting | add-interactivity | Implementing click handlers, triggers, input | | Multiplayer sync, server communication | multiplayer-sync | Networked game state, real-time sync | | Screen UI, React-ECS, HUD elements | build-ui | Building menus, scoreboards, dialogs | | Performance optimization, entity/triangle budgets | optimize-scene | Detailed optimization techniques |

This skill focuses on the design decisions and optimization constraints that shape implementations. For detailed code patterns, see the referenced skills.