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.
Everything you need to get started with building in the Webaverse is contained in this repository.
- 🎮 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
Developer documentation is here
User documentation is here
- Key Features
- Table of Contents
- Minimum Requirements
- Installation
- Installation for Windows
- Creating a New Scene
- Additional Tips
- Contributors ✨
- Support
- We Hope to See You Soon!
- 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
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.
Within this platform, the app will primarily be using these programs:
Begin by opening the Webaverse repository on your device.
After installing the above tools, open VS Code and create 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.
For example, name your folder “webaverse” and type cd webaverse in your terminal to navigate to this folder.
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 you created.
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.comYou 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.
Once the server has loaded, you will now be able to test out your avatars and create your own scenes!
This should be the first display that you see:
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, type these commands:
# Go into the webaverse folder you created.
cd webaverse
# Enter WSL
wsl
# Clone this repository
git clone https://github.com/webaverse-mmo/webaverse.git
# Go into the repository
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.comYou 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.
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.
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.
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.
For an avatar, we have chosen this VRoid Hub Sample Character. 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.
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 how your local Webaverse will be able to switch between scenes.
Scroll down to the bottom 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 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.
Up next is editing your new Scene!
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.
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.
Eventually, your experimentation will lead you toward new ideas to build out and help you understand what is possible in Webaverse.
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.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind are welcome!
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!
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.
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.
