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 within the existing scene. If you're teleporting outside the scene, you can only do it with their consent (they must accept the prompt). Design around misbehaving players with game mechanics, not eviction. If the scene has admin players, admins are able to ban other players from the scene manually.
• 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

Most limits scale with parcel count n (triangles, entities, bodies linear; materials, textures logarithmic). Height is a flat 330 m for every scene; content above ~200 m may suffer multiplayer sync issues. Key rule of thumb: 10,000 triangles and 200 entities per parcel.

For the full limits table across all parcel counts, see the optimize-scene skill.

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

Use the AssetLoad component to pre-load assets that aren't needed at scene startup so they display instantly when needed (e.g. things that appear later or on player interaction); don't use it for startup assets.

For the implementation pattern, see the optimize-scene skill.

First impression: time the intro to the loading screen

Anything the scene does on startup — an intro cinematic, a welcome sound, a title UI, an opening tween — happens behind the Explorer's loading screen and the player never sees it. EngineInfo.sceneHidden is true while that screen is up and flips to false the frame it fades out; that flip is the only reliable cue for "the player is now looking at the scene". Gate the opening beat on it instead of on a timer or a frame count. See the scene-runtime skill for the pattern.

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.

Disable Landscape Terrain (Worlds)

For single-scene Worlds, set landscapeTerrain: false in scene.json to remove the auto-generated grassland/trees/sea around the scene. Two payoffs: it frees rendering budget, and it lets you commit to a self-contained aesthetic (open water, space, void). Ignored in Genesis City. See the create-scene skill.

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. It is avatar distance (default 10), not camera distance, so it reads the way a player experiences reach. Keep proximity interactions inside ~3m: the explorer's proximity broad phase is a hard-coded 3m sphere that clamps larger values. See add-interactivity > "Distance rules".
• 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.
• Never open with a wall of text: a rules pop-up with long paragraphs, or a rulebook painted on an in-world plane, is a known bad pattern — players skip it and then play confused. See section 13, "Rules: show, don't tell".
• Place screen UI where the client is not: never anchor a HUD to the top-left corner (minimap, chat, mobile joystick live there). Anchor right or center, or use the interactable inset; keep mobile HUDs clear of the bottom-right action buttons, or hide those buttons while a full-screen UI is open. Rules and code in the build-ui skill.
• 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 defined: One sentence describing what the player does.
• First action obvious: A new player knows what to do within 30 seconds.
• Feedback present: Every interaction produces visible and/or audible feedback.
• Win/progress condition clear: The player understands when they are succeeding.
• Lose/fail condition fair: If there is failure, the player understands why and can retry quickly.
• Replay value exists: There is a reason to play again (score improvement, new content, social competition).
• Multiplayer compatible: Works correctly with 1 player and with 5+ simultaneous players.
• Within scene limits: Triangle count, entity count, texture count, and file size all within budget for the target parcel count.
• Performance acceptable: Maintains 30+ FPS during gameplay with target entity/triangle counts.
• Mobile compatible: Core interactions work without a keyboard (pointer-only inputs). Use TouchScreenControls (see advanced-input) to customize on-screen buttons and UiInputBinding (see build-ui) for custom touch-action buttons. Detect platform with isMobile() from @dcl/sdk/platform to branch UI/controls. Note: borderRadius is unsupported on mobile UI; LightSource (dynamic lights) ships on mobile v1.13.0 (Sept 2026). Smart Items are not officially supported on mobile.

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

10. Game Loop Archetypes

Exploration

• Core loop: Discover locations, find hidden items, unlock areas.
• DCL fit: Excellent. The 3D world and spatial navigation are strengths.
• Design tips: Use landmarks for wayfinding. Reward curiosity with hidden content. Use lighting and sound to guide attention.

Collection

• Core loop: Gather items, complete sets, earn rewards.
• DCL fit: Strong. Combines well with exploration and daily engagement.
• Design tips: Use entity pooling for collectibles. Scatter items spatially. Tie collections to visual progress (display cases, counters).

Puzzle

• Core loop: Solve spatial or logic challenges to progress.
• DCL fit: Good. Spatial puzzles (move objects, find paths, activate sequences) work well.
• Design tips: Provide clear feedback on progress. Avoid puzzles that require typing (input is limited). Use 3D interactions (click, proximity triggers) as puzzle inputs.

Social

• Core loop: Interact with other players, attend events, roleplay.
• DCL fit: Excellent. This is the platform's native strength.
• Design tips: Create gathering spaces (seating, stages, open areas). Provide conversation starters (interactive objects, games). Design for groups of 5-20.

Competitive

• Core loop: Race, fight, or outscore other players.
• DCL fit: Moderate. Latency and input limitations constrain fast-paced action.
• Design tips: Prefer turn-based or timing-based competition over twitch reflexes. Use server-authoritative state to prevent cheating. Keep rounds short (2-5 minutes).
• Anti-cheat architecture: whenever scores or prizes are at stake, make the scene server-authoritative (see [[authoritative-server]]). Clients send intent messages only (e.g. claimPoint) — never a score; the server validates (proximity to the objective, permissions) and is the only writer of game state. The official leaderboard test scene is a complete end-to-end template of this design: https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/90,-9-authoritative-server-leaderboard

11. Spatial Design

Landmarks

• Place a tall, visible landmark at the center or entrance of your scene. Players use it to orient themselves.
• Every distinct area should have a unique visual identity (color, shape, lighting).

Pathfinding

• Guide players with visible paths (floor patterns, lighting, railings).
• Avoid dead ends that require backtracking — use loops.
• Place interactive elements along paths to maintain engagement during traversal.

Sightlines

• Use open sightlines to draw players toward objectives.
• Block sightlines strategically to create mystery and discovery.
• Ensure the scene looks inviting from the parcel boundary (this is your "shop window").

Parcel Transitions

• If your scene spans multiple parcels, ensure smooth visual transitions.
• Do not place critical interactive elements right at parcel boundaries (loading edge cases).

Vertical Traversal with Gliding

• While a player glides, continuous scene forces are 1.5× stronger and their upward component can lift the glider (the falling-speed cap only limits descent). This enables traversal mechanics like thermal updrafts, wind corridors, and floating-island hops. One-shot impulses (launch pads, knockback) are unaffected by gliding. See the player-physics skill ("Forces while gliding").
• Use open space at parcel edges as buffer zones.

12. Engagement and Monetization

Engagement Patterns

• Daily rewards: Offer small rewards for daily visits. Track visits via external server — DCL has no built-in daily tracking. Display streak counters in-scene.
• Progression systems: Levels or unlockable content tied to cumulative play. Store progress on a server or use NFT-based progression. Show progression visually (leaderboards, badges, evolving scene elements). For persistent leaderboards and per-player progress, the built-in Multiplayer Server's Storage persists across redeploys and server sleep, with a server-owned synced component all clients render — see [[authoritative-server]] for the full pattern and reference scene.
• Achievements: Define clear milestones (first win, 100 collectibles, visited all rooms). Announce with sound and visual effects. Display achievement history in-scene (trophy room, wall of fame).

Monetization Approaches

• In-scene purchases: Sell virtual items or abilities via MANA transactions. Use signedFetch for secure server-verified purchases. Always provide free gameplay alongside paid upgrades.
• Wearable sales: Create and sell wearables that complement your scene's theme. Display wearables on mannequins in-scene as advertisements.
• Entry fees/token gating: Charge MANA to enter a premium area, or require ownership of a specific NFT. Always have a free area that showcases what the paid area offers.

Social Mechanics

• Cooperative tasks: Design objectives requiring multiple players (two switches pressed simultaneously, etc.). Reward cooperation with shared benefits.
• Shared spaces: Create common areas where players naturally congregate. Add ambient interactive objects that encourage casual interaction.
• Events: Design scenes that can host scheduled events (concerts, competitions). Include a stage area with good sightlines. Provide event host controls (start/stop game, reset scene, broadcast messages). Gate host/admin actions server-side with an admin allow-list checked against the server-verified sender ([[authoritative-server]] Pattern 4) — never trust a client-reported role.

13. Tutorial and Onboarding

In-World Signs

• Place TextShape entities with short instructions at key locations.
• Use arrows, glowing outlines, or animated indicators to point to interactive objects.
• Keep text under 10 words per sign.

NPC Guides

• Use an animated NPC at the scene entrance to greet and instruct.
• Deliver instructions through a dialog system (one message at a time, player advances).
• NPC dialog should be skippable for returning players.

Progressive Complexity

• Introduce one mechanic at a time. The first interaction should be obvious (a big, glowing button).
• After the player succeeds at the simple task, introduce the next layer.
• Gate advanced mechanics behind early accomplishments.

Rules: show, don't tell

Two anti-patterns show up constantly in generated games. Both lose players before the first interaction.

• The rules pop-up. An intro modal with several dense paragraphs explaining every mechanic, scoring rule and control. Players dismiss it unread. Fix: the pop-up (if any) is one screen, 3–5 lines, ≤ 8 words each, ideally one goal line plus one control line plus one picture/diagram. Everything else is learned by playing.
• The in-world rulebook. The same paragraphs on a stylized plane or board in the scene. It looks like design, but the text is too small and too long to read in-world, and players will not stand still and squint. Fix: a sign says one thing (≤ 10 words, large fontSize); one sign per idea; put the rest into the level design.

Show instead of tell:

• Make the first target unmistakable: a glowing, animated, or oversized object placed in the player's opening sightline. A pulsing outline teaches "click me" better than a sentence does.
• Teach one mechanic by letting the player do it once safely (tutorial gate, practice target) before the real game starts.
• Use hoverText on interactive entities as the just-in-time instruction — it appears exactly when it is relevant and costs no reading up-front.
• Use an image/diagram (a uiBackground texture or an in-world plane) for spatial or sequence rules; a picture of "red gems = 1, blue = 5" replaces a paragraph.
• Deliver anything longer through an NPC or a dialog one message at a time, skippable, or as Timed Announcement-style hints at the moment they matter.

Text budget as a checklist: intro panel ≤ 5 lines; sign ≤ 10 words; hint ≤ 1 sentence; if a rule needs more than that, redesign the mechanic or show it with visuals.

Zero-Explanation Test

• If a new player cannot figure out the first action within 30 seconds without any text or instructions, the design needs work.
• Watch real players attempt your scene cold. Their confusion is your design feedback.

14. Cross-References

Topic	Skill	When to Use
Follow/chase a moving target (entities tracking the player)	animations-tweens	Tween.setMoveContinuous for smooth following; do NOT re-create setMove tweens per-frame (causes jitter). See the 79,-4-tween-following-cube test scene.
Interactivity, input handling, raycasting	add-interactivity	Implementing click handlers, triggers, input
Multiplayer sync, server communication	multiplayer-sync	Networked game state, real-time sync
Server-authoritative games, leaderboards, anti-cheat	authoritative-server	Competitive scoring, persistent progress, admin-gated host controls. The Gem Rush reference scene (92,-9) is a complete competitive game architecture with server-side proximity anti-cheat and checkpoint-only storage.
FPS-style / mouselook camera controls	camera-control	Mouselook pattern: PrimaryPointerInfo.screenDelta + VirtualCamera + PointerLock + InputModifier. Desktop only.
Spectate / observer / director camera	camera-control	Spectate Mode pattern: free or player-following camera, WASD/E/F/1/2 controls, parcel-bounds clamping, player roster. Combine with an admin check (authoritative-server) to restrict who can enter spectate mode.
Audio-reactive visuals (music visualizers, beat detection)	audio-analysis	AudioAnalysis component on AudioSource or VideoPlayer (progressive only, not HLS). Drive geometry/lights/colors from amplitude and 8 frequency bands.
Screen UI, React-ECS, HUD elements	build-ui	Building menus, scoreboards, dialogs. UiInputBinding prop for binding InputActions to UI elements (on-screen buttons for mobile).
Mobile touch controls	advanced-input	TouchScreenControls component for hiding/showing on-screen buttons, setting main action, hiding joystick/crosshair. Platform detection via getPlatform() / isMobile() from @dcl/sdk/platform.
Open Explorer UI panels from scenes	scene-runtime	openExplorerUi() restricted action to open map, backpack, settings, etc. from a user gesture. Useful for onboarding flows and UX shortcuts.
Deployment timing & post-publish troubleshooting	deploy-scene	Asset bundle conversion takes ~15 min (plan 30-60 min). Publish 2+ hours before live events. /detectabs checks conversion status in-world. Conversion status URLs for monitoring.
Local asset bundle preview	optimize-scene	"Compress Assets" (Creator Hub Play Options > Desktop Client) or the --asset-bundles CLI flag reproduces production asset bundle conversion locally. Catches texture/model issues before publishing.
Pause gameplay when scene is hidden	scene-runtime	EngineInfo.getOrNull(engine.RootEntity)?.sceneHidden is true when a fullscreen Explorer UI (map, backpack, loading screen) covers the scene. Use to pause game loops, audio, and expensive systems so they don't run while the player can't see or interact with the scene.
Entity removal returns boolean	scene-runtime	engine.removeEntity(entity) now returns boolean — false for renderer-reserved (avatar) entities, where components are left untouched. Check the return when despawning entities in game loops to avoid silently failing to remove an entity.
World deployment, storage budget	deploy-worlds	World storage budget (100 MB per NAME, 100 MB per LAND, 100 MB per 2k MANA; ENS = 36 MB fixed). Plan scene file sizes accordingly.
Performance optimization, entity/triangle budgets	optimize-scene	Detailed optimization techniques, local asset bundle preview, gltf reuse-vs-merge benchmark.
Zone-driven gameplay (checkpoints, arenas, ambush rooms, safe zones)	add-interactivity	TriggerArea + triggerAreaEventsSystem. When the scene is open in the Creator Hub, the utils catalog has a single prompt-driven "Trigger Area" Smart Item — the designer places and resizes an invisible volume and describes the reaction to the AI assistant, so a zone mechanic can be prototyped without writing a detector. Script authors: use its @event enter/exit pattern rather than a second triggerAreaEventsSystem callback (script-components).
Dropping in placeholder art, music or video during blockout	creator-hub-mcp	Dragging a file from the editor's Local Assets tab onto the viewport spawns the matching catalog Smart Item already pointed at it (image / ambient sound / video screen) — the fastest way to get real media into a greybox before committing to a layout. See add-3d-models and audio-video.
Handing reference material to the Creator Hub AI assistant	creator-hub-mcp	The composer takes up to 8 attachments per prompt (paperclip, drag-drop, or paste). Attach a mood board, a mockup, or a .glb instead of describing it — files from disk reach the agent as real absolute paths, with no size cap.

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