โHackMDWebaverse - Quick Start Guide
An open source web3 metaverse game engine that anyone can host. Easy to use, runs in the browser and utilizes open tools and standards like three.js and Node.
Webaverse is composed of a number of open-source applications that work in tandem. Most of them can be installed and configured in your local dev environment by easily following a few steps.
Developer documentation is here.
User documentation is here.
All repositories can be found under the Webaverse account at GitHub:
https://github.com/webaverse.
The main ones required to stand up Webaverse can be found here:
Webaverse Repos.
Key Features
- ๐ฎ A full-featured game engine running in your browser
- โพ๏ธ Infinite procedurally generated world
- ๐งโ๐คโ๐ง Multiplayer with voice and chat
- ๐ค AI-powered non-player characters
- ๐ Supports desktop and VR (mobile coming soon)
- ๐ Expressive, vocal and emotive avatars
- ๐ฎ Runtime support for user uploads and custom apps
- ๐ฅ๏ธ Completely self-hostable
Table of Contents
Minimum Requirements
- 10 GB Disk Space
- 8 GB RAM
- 4 Core CPU / vCPUs
- Node version 19.0.0. The recommended way to get node is
nvm: https://github.com/nvm-sh/nvm
Dependencies
-
Download and install Git.
-
Download and install GitHub Desktop.
-
Download and install Visual Studio Code (VS Code).
- This is optional but using an IDE/text editor will be beneficial when you start creating your own local scenes.
-
Download and install Node.js with version 18 (v.18).
- You can manage your Node version by using NVM.
- If you are installing Node.js for the first time, you can check the version by typing
node -vinto your terminal.
Installation
Begin by cloning the Webaverse repository on your device. You can fork this to your account or open this repository with Github Desktop.
After installing the above dependencies, open VS Code in a new folder where you want to clone the webaverse repository.
This can also be done from your Command Prompt, however, your VS Code terminal will allow for opening and running the program as easily as possible.
Now you can follow these commands within your terminal to download and install the program:
# Clone the Webaverse repository.
git clone https://github.com/webaverse-mmo/webaverse.git
# Go into the repository folder that you cloned.
cd webaverse
# Install the required dependencies.
npm install
# Run the "dev" version of the program.
npm run dev
# Wait for this to load and navigate to the URL mentioned in the terminal.
ctrl+click https://local.webaverse.com
Loading the Server
You will need to let the server load and for the browser process to begin before starting up. Once it is ready, you will see the following message:
event - compiled client and server successfully in _ (_ modules)
After navigating to the URL using โctrl+clickโ you might see a warning to open an external website.
Click โOpenโ and your designated browser will begin to build your first testing scene.
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Once the server has loaded, you will now be able to test out your avatars and create your own scenes.
Congratulations, you now have a first look at what is possible with Webaverse! This should be the first display that you see:
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Installation for Windows
The above steps will work just as described for Operating Systems (OS) like Linux, however, Windows will require Windows Subsystem for Linux (WSL) to be set up in advance for installation.
This video shows you how you can set up WSL and Ubuntu.
Alternatively, you can open up your terminal and type wsl --install. This should fully download and install all requirements needed to run WSL and load the Ubuntu distribution.
For more details, visit Microsoftโs guide here.
In case you are running an old version of WSL, make sure you have upgraded to WSL2. You can check this version using wsl -l -v.
Once you have fully installed WSL, the main difference between installation will be entering a Linux shell.
You can either type wsl into your terminal or (hold shift + right-click) the folder you want to open and click 'Open Linux Shell here'.
Following this, type these commands into your terminal:
# Enter WSL to enter your Linux shell.
wsl
# Clone this repository
git clone https://github.com/webaverse-mmo/webaverse.git
# Go into the webaverse folder you created.
cd webaverse
# Install dependencies
npm install
# Run the app
npm run dev
# Navigate to the URL mentioned in the terminal
ctrl+click https://local.webaverse.com
Hosting Source Files
You can host the source files on either your Windows file system or on the Ubuntu file system in WSL's virtual drive.
Windows File System: Run the Git commands to clone and pull source files from a Windows command prompt. You may find this best if you're using programs such as SourceTree as a Git GUI. You can also edit source using your usual IDE.
Ubuntu File System: Run the Git commands to clone and pull source files from a WSL command prompt. In this case consider using the Visual Studio Code WSL extension as your dev environment - for features such as hot reload.
Creating a New Scene
Now that you have your environment set up and the initial view of your world, we can finish by showing how to create your own scene.
This will focus on adding a new environment to this repository, so we recommend becoming familiar with the code layout of each folder.
Code Layout
The main area you will work with in this example is the "scenes" folder, which is displayed as follows:
packages โ client โ public โ scenes folder
The "packages" folder contains the majority of files you will engage with, all from the "client" itself to the README images you see in "docs".
Next, we will open client to visit the public folder.
Within the public folder, we can view each folder's use case, such as the avatars we will use and the overarching scenes that we can display within Webaverse.
This layout can be viewed in the other test folders such as test-e2e.
As you begin building your own world, the scenes folder and its files can be formed around any avatar, item, or environment you upload.
To show this in more detail, we will create a new Scene (labeled as .scn files) to portray an environment with our own avatar for in-game use.
Building your Test Model
First, you will need to download an environment and avatar for this example.
For the environment, we can visit the glTF Sample Models Repo and click "Download" in the top right corner.
If you would like to explore other 3D models to download, we suggest browsing Sketchfab and choosing from any of their categories.
We have released our Character Creator Studio for you to build your own avatar to use within Webaverse. To learn more about the Studio, visit here.
For this example, we have chosen a VRoid Hub Sample Character. You can also build a similar model through the VRoid Studio.
Once you have chosen your avatar, click "Use this Model" to download.
After these files have downloaded, open up your Webaverse directory.
We will start by clicking on the client folder and creating a new folder called test-models.
Drag your new models into this folder and rename them accordingly.
Editing the scenes Folder
Next, we will go to the previously mentioned public folder and open scenes.
Here we will see an extensive list of scenes that can be loaded into Webaverse.
As the foundation for our new Scene, we will be using the block.scn file.
You can either save this file as a new .scn file and label it "test-environment" or create a new file and simply copy-paste the code over.
For this example, we have left the block.scn file as is and created a new test-environment.scn file.
After this has been set up, go to the scenes.json file within this folder.
You will see a list of all the added scenes, which is one way how your local Webaverse will be able to switch between scenes. You can also type in the location of any scene while in Webaverse, even if the scene is stored somewhere else!
Scroll down to the bottom of this list and add "test-environment.scn" at the end.
Make sure to add a comma after the scene above this.
Now you can go back and visit the local instance of Webaverse that you have running and select this file.
Click on the "Maps" icon on the top right, next to your profile and you should see your new test-environment.scn file appear here.
With this displayed, you can make changes to the underlying file and see your changes whenever you refresh the browser.
Adding to your Test Environment
Up next is editing your new Scene!
As you become more familiar with Webaverse, modifying
anything in your world is as simple as putting together various code blocks and experimenting as you learn.
For an initial example of this, revisit the test-environment.scn file. Each Scene starts out with "objects" which references the different parts of the scene you will be creating.
This covers everything from the position of your avatar, the lighting within the scene, and the full environment that we have downloaded.
Our first step will be to remove the next section under the directional light object so that we can add a new position.
Once removing these, we can add in new objects.
We will start by adjusting the render settings to add in fog and a depth of field.
Copy the following code block underneath the object, beginning with },:
},
{
"type": "application/rendersettings",
"content": {
"fog": {
"fogType": "exp",
"args": [[255, 255, 255], 0.001]
},
"dof": {
"focus": 1.5,
"aperture": 0.0004,
"maxblur": 0.002
}
}
},
Then we will place the downloaded environment into the center of our scene and increase its scale by 10x.
Place this code block right underneath the one above:
{
"position": [
0,
0,
0
],
"scale": [
10,
10,
10
],
"start_url": "/test-models/environment.glb"
},
Finally, we can add the avatar and place it two meters to the right of our view.
When you initially opened your local scene, you most likely noticed the first-person view. With this example, and others in the scenes folder, you can play around with different ways for your avatar to be displayed.
Copy this code block underneath the environment and close it out like this:
{
"position": [
2,
0,
0
],
"start_url": "/test-models/avatar.vrm",
"dynamic": true
}
]
}
Now save your file, go back to your browser's local instance, and refresh! You should now be able to move around in a brand new city scene with an equippable avatar.
Additional Tips
Exploring
With your brand new scene up and running, we suggest getting familiar with even more as you learn.
You can start by testing out different parameters or looking at other files in the scenes folder to understand how everything works.
For your avatars, you can also drag and drop each .vrm file into your browser window.
Eventually, your experimentation will lead you toward new ideas to build out and help you understand what is possible in Webaverse.
Helping Out
We always encourage everyone to contribute where they can! To make changes as simple as possible, we suggest forking the repository to your own Github account.
Then, go through the Installation steps as described.
Whenever you are ready to have your changes reviewed, refer to Let's Build Together! on best practices and our current processes.
Contributors โจ
A very special thanks goes out to these wonderful people who have made this possible (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
Support
Let's Build Together!
We would love for you to come build with us. Before getting started, please review the documentation in it's entirety before contributing.
We have provided both the User Documentation and the Developer Documentation for you to begin with.
For additional questions and to meet our contributors, join our Discord and introduce yourself!
New Issues and Features
For developers adding to this repository, please search Github issues before reporting a new issue or starting a new feature.
If you are starting a new feature or bug fix, we ask that you summarize and reference the issue, then indicate that you are working on it.
Pull Requests
Please make sure your PRs change as little existing code as is necessary to prevent upstream merge conflicts.
When posting a pull request, document what the PR does and how it can be reviewed for Quality Assurance (QA).
PRs will be reviewed and accepted if they conform to our linting and code conventions. These include PRs that do not cause any bugs and will not decrease performance of the app.
We Hope to See You Soon!
