README.md

Unity Explorer

Welcome to the official documentation for Unity Explorer — the Decentraland client built on Unity. This wiki covers architecture, development standards, feature guides, and tooling.

---

Getting Started

• Setup — SSH, GPG, LODs, and environment setup
• Getting Started — Scene loaders and Unity project entry points
• Working with Explorer Packages — Managing private UPM packages

Contributing

• Branch & PR Standards — Branches, PRs, commits, and merge policy
• Code Style Guidelines — Naming, formatting, and ordering conventions
• Standards — Memory, GC, performance, tests, and error handling

Architecture

• Architecture Overview — ECS concepts, dependency management, containers, and abstractions
• Directories & Assemblies — Project folder structure and assembly rules
• Systems — ECS system lifecycle, streamables, and scene bounds
• Scene Runtime — SDK7 scene execution, CRDT bridge, JS modules, scene lifecycle states, and threading model
• Cross-World ECS Access — Global world from scene systems, injection chain, propagation systems, bridge components
• MVC — UI architecture: controllers, views, and the MVC manager
• Third-Party Libraries — ArchECS, ClearScript, and Sentry

Development Guides

• Development Guide — ECS system/component design patterns, queries, cleanup, and singletons
• Async Programming — Detached flows, cancellation, and exception-free async
• Implement SDK Components — Step-by-step guide for new SDK7 components
• Feature Flags — Fetching and checking feature flags at runtime
• Features Registry — Centralized feature state registry
• App Arguments — Command-line flags and launch parameters

Core Systems

• Asset Promises — Asynchronous asset loading with ECS promises
• Disk Cache — Persistent asset cache: architecture, atomic writes, corruption self-healing, and eviction
• Asset Bundles Conversion — GLTF to Asset Bundle conversion pipeline
• Web Requests Framework — Allocation-free web requests with retry policies
• Memory & Resource Unloading — Memory budgeting and cache unloading strategies
• Multiplayer — Transport-agnostic multiplayer hub: shared interfaces, movement pipeline, entity/profile tables, SDK propagation, dual-transport wiring
• LiveKit Networking — LiveKit transport: dual-room architecture, messaging pipes, Archipelago/GateKeeper, voice and chat rooms
• Pulse — Pulse transport: ENet peer transport, peer identity, protocol, feature-flag gating
• Diagnostics — ReportHub logging system and Sentry integration
• Performance Analytics — performance_report telemetry: hiccup/frame-time metrics, measurement window, and target-relative threshold

Avatar System

• Avatar Rendering — GPU skinning, compute shaders, and cel-shading
• Emotes — Emote loading, animation controllers, and pooling
• Skeleton Loading Animation — Bone animations for loading states
• Avatar Animation for Demos — Using Unity Timeline for demo recordings
• Unreleased Wearables & Emotes Preview — Builder API signing, GLTF-based loading, and self-preview collection flow

Chat & Social

• Chat — Chat system architecture, state machine, and MVP structure
• Chat Emojis — Emoji atlas creation and TextMesh Pro integration
• Chat History Storage — Local encrypted chat history persistence

Features & UI

• Locomotion — Character movement, jumping, sprinting, and IK
• Landscape — Procedural terrain generation
• Notifications — Remote notification polling and display
• Generic Context Menu — Dynamic context menu components
• Quality Settings — Graphics quality levels and renderer configuration
• Settings Panel — Modular settings panel architecture
• Shared Space Manager — Coordinated UI panel visibility management
• Visibility Component Propagation — SDK visibility component inheritance rules

Authentication & Web3

• Web3 & Authentication — Wallet signing, ephemeral addresses, and auth chains
• IPFS Realms — Publishing entities to IPFS catalysts

Testing & Debugging

• Debug Container & Widgets — Runtime debug panel architecture, widget builder API, bindings, and integration patterns
• Testing Guide — UnitySystemTestBase, ECS test utilities, mocking, EditMode/PlayMode, async test patterns
• Automation Testing — AltTester SDK setup, writing UI automation tests, running against instrumented builds and in-Editor, triggering visual regression on PRs via /visual-tests
• MCP Automation — Embedded MCP server for coding agents: screenshots, player/scene state, scene logs, and player control via --mcp
• Connect to Local Scene — Running and connecting to local SDK7 scenes
• Master of Bots — Simulating multiple bot users for load testing
• Override Debug Log Matrix — Runtime log severity overrides
• Performance Benchmark — Generating PDF benchmark reports

Build & CI

• Build & CI — GitHub workflows, Python build handler, and Unity Cloud
• Unity Upgrades — Handling Unity version upgrades and CI images
• Troubleshooting Missing Docker Images — Fixing missing UnityCI Docker images

Operations

• Incident Response — Severity levels, #qa-team flow, crash escalation, hotfix rules, and SEV-1 postmortems
• Issue Triage Categories — Primary vs secondary feature categories used to assign severity labels and decide SEV-2 hotfixes