/explorer

🌎 Explore Decentraland from a web browser

Primary LanguageTypeScriptApache License 2.0Apache-2.0

Decentraland Explorer

This is the decentraland explorer official repository.

Before you start

  1. Contribution Guidelines
  2. Coding Guidelines
  3. Code Review Standards

Running the Explorer

Main Dependencies

This repo requires git lfs to track images and other binary files. https://git-lfs.github.com/ . So, before anything make sure you have it installed by typing:

git lfs install
git lfs pull

Debug using Unity only

Why you should care

Take this path if you intend to contribute on features without the need of modifying Kernel. This is the recommended path for artists.

Steps

  1. Download and install Unity 2019.4.19f1
  2. Open the scene named InitialScene
  3. Within the scene, select the WSSController GameObject.
  4. On WSSController inspector, make sure that Base url mode is set to Custom and Base url custom is set to https://play.decentraland.zone/?
  5. Run the Initial Scene in the Unity editor
  6. A browser tab with explorer should open automatically and steal your focus, don't close it!. Login with your wallet, go back to Unity and explorer should start running on the Game View.
  7. As you can see, WSSController has other special options like the starting position, etc. You are welcome to use them as you see fit, but you'll have to close the tab and restart the scene for them to make effect.

Troubleshooting

Missing git lfs extension

If while trying to compile the Unity project you get an error regarding some libraries that can not be added (for instance Newtonsoft Json.NET or Google Protobuf), please execute the following command in the root folder:

git lfs install
git lfs pull

Then, on the Unity editor, click on Assets > Reimport All

Debug using Kernel only

Why you should care

Kernel mostly takes care of scene code execution and sandboxing, communication with catalysts, external services, comms, etc. If you want to delve into any of this, you may want to follow these steps and don't bother with the Unity installation.

Steps

Make sure you have the following dependencies:

  • Latest version of GNU make, install it using brew install make
  • If you are using Windows 10, you must enable the Linux subsystem and install a Linux distro from Windows Store like Ubuntu. Then install all tools and dependecies like nodejs, npm, typescript, make, et cetera.
  • Node v10 or compatible installed via sudo apt install nodejs or nvm

IMPORTANT: If your path has spaces the build process will fail. Make sure to clone this repo in a properly named path.

When all the dependencies are in place, you can start building the project.

First off, we need the npm packages for website and kernel. In most of the cases this should be done only once:

cd website
npm install
cd kernel
npm install

By now, you can run and watch a server with the kernel build by typing:

make watch

The make process will take a while. When its finished, you can start debugging the browser's explorer by going to http://localhost:3000/

Note that the Unity version used by this approach will be the latest version deployed to master branch. If you need a local Unity build, check out the advanced debugging scenarios.

Update local renderer build version

The unity build used when accessing through localhost can be changed with several commands:

  • make update-renderer downloads the renderer build for the master branch and installs it, overwriting the previous build.

Keep in mind that a make watch should be run and keep the server up before updating the local build, otherwise it will be replaced by the make watch command.

Run kernel tests

To see test logs/errors directly in the browser, run:

make watch

Now, navigate to http://localhost:8080/test

Troubleshooting

Missing xcrun (macOS)

If you get the "missing xcrun" error when trying to run the make watch command, you should download the latest command line tools for macOS, either by downloading them from https://developer.apple.com/download/more/?=command%20line%20tools or by re-installing XCode

Testing your branch using automated builds

When any commit is pushed to a branch on the server, a build is generated and deployed to:

https://play.decentraland.zone/branch/<branch-name>/index.html

If the CI succeeds, you can browse to the generated link and test your changes. Bear in mind that any push will kick the CI, and there's no need to create a pull request.

Advanced debugging scenarios

Debug with Unity Editor + local Kernel

Why you should care

You may want to use this approach for any features that need both Kernel and Unity modifications, and you need to watch Unity code changes fast without the need of injecting a wasm targeted build in the browser.

When the steps are followed, you will be able to test your changes with just pressing the "Play" button within Unity. This will open a tab running the local Kernel build and Unity will connect to it using websocket.

This is the most useful debugging scenario for advanced feature implementation.

Steps

  • Make sure you have the proper Unity version up and running
  • Make sure you are running kernel through make watch command.
  • Back in unity editor, open the WSSController component inspector of InitialScene
  • Make sure that is setup correctly

Debug with browsers + local Unity build

See https://github.com/decentraland/unity-renderer/ for instructions regarding Unity testing.

Technical how-to guides and explainers

For more advanced topics, don't forget to check out our Architecture Decisions Records (ADR) repository.

Copyright info

This repository is protected with a standard Apache 2 license. See the terms and conditions in the LICENSE file.