@bwland/sdk

SDK

Introduction

The bw.land SDK is a lightweight 3D metaverse engine that empowers developers and creators to build immersive virtual experiences. This is the same technology that powered the McDonald's My Happy Place campaign in June 2024.

With this SDK, you can:

• Create custom virtual worlds
• Implement unique experience logic
• Utilize pre-built entities and interactions
• Focus on creative work rather than technical implementation

The SDK abstracts away complex technical challenges, allowing creators to concentrate on designing engaging experiences for their users.

Usage Example

Below is a basic example of how to initialize and configure the bw.land SDK in your web application:

// Define the canvas ID where the 3D world will be rendered
const bwlandCanvasId = "bwland-canvas";

// Add event listener to prevent default space key action on the canvas
window.addEventListener("keydown", function (e) {
  // Get canvas child element in root element
  // If the key is space and the target is the canvas element
  // Prevent the default action
  var canvas = document.getElementById(bwlandCanvasId).querySelectorAll("canvas")[0];
  if (e.keyCode == 32 && e.target === canvas) {
    e.preventDefault();
  }
});

// Initialize the SDK when the DOM content is loaded
window.addEventListener("DOMContentLoaded", (event) => {
  // Get the BWLand object from the window
  const { BWLand } = window["bwland"];
  
  // Configure your virtual world
  const config = {
    id: "myspace",                        // Unique identifier for your world
    name: "My Space",                   // Name of your virtual world
    cover: "",                        // Cover image URL (optional)
    world: {},                        // World configuration
    author: {                         // Author information
      id: "1",
      name: "Bandwagon Labs",
      username: "bandwagonlabs",
      email: "[e-mail]",
      image: "/images/bw_author_image.jpg",
    },
    spawnPosition: { x: 19, y: 14, z: 13 },  // Starting position for users
    worldFeatures: {                  // Enable/disable features
      nameLabel: true,                // Show user names
      chat: true,                     // Enable chat functionality
      emotions: true,                 // Enable emotions/emotes
    },
    assetUrl: 'https://cdn.bw.land/spaces/beach-quest/scene',    // URL for 3D assets
    imagesUrl: 'https://cdn.bw.land/spaces/beach-quest/images',  // URL for images
    mediaUrl: 'https://cdn.bw.land/spaces/beach-quest/media',    // URL for media files
    excludeWearables: [],             // Wearables to exclude
    assets: {                         // Custom assets configuration
      levelGltfUrlsWithFeatures: {
        BeachQuest_Bush1: {
          // Asset-specific configuration
        }
      }
    }
  };
  
  // Initialize the BWLand SDK with your configuration
  const bwland = new BWLand(config);
  
  // Additional initialization code can go here
});

HTML Setup

Ensure you have a canvas element in your HTML:

<div id="bwland-canvas" style="width: 100%; height: 100vh;"></div>

Including the SDK

Include the SDK in your HTML:

<script src="https://cdn.bw.land/sdk/latest/main.js"></script>

SDK Versioning

Please refer to this (link)[https://www.w3resource.com/yarn/yarn-version-and-yarn-versions-cli-commands.php] for versioning.

// increment major version
yarn version --major

// increment minor version
yarn version --minor

// increment patch version
yarn version --patch

Versioning Strategy

Use Semantic Versioning (SemVer)

Follow the MAJOR.MINOR.PATCH format:

• MAJOR: Increases for breaking changes.
• MINOR: Increases for new, backward-compatible features.
• PATCH: Increases for bug fixes and minor improvements.

During the alpha stage, append a pre-release identifier like -alpha.X to indicate that the software is in an experimental phase.

Examples

• 0.1.0-alpha.1 (First alpha release)
• 0.1.0-alpha.2 (Second alpha release with changes)
• 0.1.0 (Stable release for the first version)

Start with 0.x.x for Alpha/Beta Versions

• Using a 0 as the major version indicates that the software is still in early development and subject to changes.
• Increment the minor version for significant improvements or milestones.
• Increment the patch version for smaller changes.

Pre-release Identifiers

Use alpha, beta, rc (release candidate), etc., to clarify the release stage.

Examples

• Alpha: 0.1.0-alpha.1
• Beta: 0.1.0-beta.1
• Release Candidate: 1.0.0-rc.1

Reset Pre-release Numbers for New Versions

When moving from one stage to another (e.g., alpha to beta), reset the pre-release number.

Example

• 0.1.0-alpha.5 → 0.1.0-beta.1

Building the SDK

Using yarn build

This build method creates a complete package with ESM, CommonJS, and TypeScript type definitions:

• Run the build command:

$ yarn build

• This will:
  • Clean the dist directory
  • Compile TypeScript
  • Process aliases
  • Bundle with Rollup
  • Create a build directory with ESM, CJS, and type definitions
  • Copy necessary files to the build directory
  • Generate a minimized package.json

Using yarn build:webpack

This build method creates a webpack bundle optimized for deployment:

• Run the webpack build command:

$ yarn build:webpack

• Next, cd to the dist directory:

$ cd dist

• Run the following command to gzip the SDK files:

for file in $(find . -name "*.js"); do gzip -9 "$file" && mv "$file.gz" "${file%.js}.js"; done

• Deploy to S3:

aws s3 cp . s3://cdn.bw.land/sdk/$(yarn --version)/ --recursive --exclude "*" --include "*.js" --acl public-read --content-type "application/javascript" --content-encoding "gzip"