Welcome to the Benthic docs!

Benthic is a project with the goal of enabling developers to easily create fast and straightforward open metaverse applications.

What is Benthic?

Benthic is a collection of tools built for accessing the open metaverse, a network of federated 3d virtual worlds running the open metaverse protocol.

These docs aim to be a resource for understanding high-level concepts that surround open metaverse projects. Things like handshake flows, rendering pipeline logic, and the assumptions existing metaverse servers make will be explained in high-level here, along with links to the rust crate docs containing specific implementation information.

Async

Benthic is entirely asyncronous, using the actix actor framework for message sending and receiving.

Open Standards

This project aims to be fully compatable with existing open metaverse standards, while working to streamline the adoption of more modern ones.

Extensible

Benthic's goal is for any component to be usable by any project, in any language. Messages are sent between components using open formats, allowing your project to implement only what it needs.

Modular

Using rust's feature capabilties, you can compile only the parts of the project you need.

Project Goals

Documentaton

This project aims to be fully documented, and developer friendly. These docs, along with the rust crate's docs should be able to function as a complete spec for the protocol, enabling other projects to implement open metaverse functionality into their own projects.

If given a choice between implicit functionality and verbosity, always favor verbosity.

Modularity

Each part of this project should be useful on its own to other projects. Viwer core, UI, server, mesh generation, and message handling should all exist entirely seperately from each other. External-facing parts of the project should use language-agnostic interfaces, like JSON or UDP packets.

If given a choice between monolithic and modular, always choose modular.

Community

People write code for other people. The community surrounding this project aims to be deliberate, welcoming, and curious.

If given a choice between welcoming new contributors and developer efficiency, always choose the new contributors.

Standardization

Whenever possible, this project should prioritize well-documented and standardized tools and frameworks.

If given the choice between purpose-built and common standards, always choose common standards.

Testability

All code should prioritize being written in a way that is machine-testable, both through unit testing and end to end testing.

If given the choice between testable code and efficient code, prioritize testability.

Getting Started

The benthic project stretches across several repos, containing several different crates. There are four primary crates that contain the majority of the project's code.

Metaverse Client

The base rust crate which contains the core functionality and structs for metaverse clients. This contains functionality for packet parsing, capability handling, and inventory management, along with the metaverse_messages crate, which contain rust structs for server data.

Benthic Viewer

A simple godot frontend for the metaverse client project. This can be used as a reference for creating other viewer projects that implement the core.

Metaverse Mesh

mesh file generation for client and server projects. Converts JSON files of mesh data into usable file formats which can be used by servers to create 3d file serving endpoints, or clients to easily render objects using common 3d file formats.

Serde LLSD

A fork of John Nagle's serde-llsd, containing extra serializing and deserializing functions that include non-documented protocols, and somewhat niche types used by the project like XMLRPC.

The recommended project layout for developing looks like this:


benthic_project/
  ├── metaverse_client/
  ├── metaverse_gltf/
  ├── benthic_viewer/
  └── serde-llsd/

OpenSimulator
  └── bin/

In order to test the project live, an instance of OpenSimulator must be running. Download the software here and run locally, or connect to an existing server using your username and password for that grid.

Local Testing

Due to the way the opensim server capability endpoint urls work, you must be connected to a wifi network to test, even when running both server and client locally.

The majority of the business logic lives in metaverse_client, and will be "home base" when developing. Each crate within metaverse_client has its own depenencies, and can be built and tested independently from each other. When building and testing locally, make sure that your local dependencies are specified in the Cargo.yaml, and not the release version.


[dependencies]
  metaverse_messages = {path = "../messages/"}
  metaverse_environment = {path = "../environment/"}
  metaverse_agent = {path = "../agent/"}
  metaverse_inventory = {path = "../inventory/"}
  metaverse_gltf = {path = "../../../metaverse_mesh/"}
  benthic-serde-llsd = {path = "../../../serde-llsd/"}
  // more dependencies ...

Metaverse_client contains a debug UI, and can be run as a standalone project using

cargo run

Benthic creates a directory at ~/.local/share/benthic/, which will be used by the project to store generated files. It is a useful directory to check when debugging.

Docs.rs

Alternate docs can be found at docs.rs, containing implementation specific information.