WideWorlds

Metaverse accessible from your favorite web browser, in the steps of Active Worlds.

HTTP API documentation is available here.

Working on it

The simplest way to work on this project is to run the Node.js server for the http/ws backend and Vite to build and serve the Vue.js frontend on the fly.

Install dependencies

Run the following in the root folder of the project:

npm i

You will of course need a working version of npm installed on your system.

Node.js backend server app

To start the server, simply run the following command, note that pino-pretty is there to prettify logger messages in the console (errors, warnings, etc.):

npm run server | npx pino-pretty

This will run the http/ws server app listening on port 8080.

Log level can be customized via the LOG_LEVEL environment variable, defaulting to info when nothing is provided, use silent to disable logging entirely:

LOG_LEVEL=silent npm run server

You can customize the port by running the following:

npm run server -- -p <port>

For additional info, you can still invoke some help:

npm run server -- -h

Options:
      --version      Show version number                               [boolean]
      --db           Path to the SQLite3 database file, will be created if need
                     be                 [string] [default: "wideworlds.sqlite3"]
  -p, --port         Port to listen on for http and ws requests  [default: 8080]
  -w, --worldFolder  Folder holding world-related files, will be created if need
                      be                          [string] [default: "./worlds"]
  -h, --help         Show help                                         [boolean]

Note that, for the server to be useful, you'll need some database with existing worlds, props and users... See aw2db in the Tools section.

Vue.js frontend building with Vite

To easily build and serve frontend content, you will need to run the following:

VITE_SERVER_PORT=8080 npm run client-dev

Prepending VITE_SERVER_PORT=<port> as environment variable is essential, as it tells the Vue.js app which port to query when performing http requests.

You can then browse the app going to http://localhost:5173 on your favorite web browser, note that building and serving the Vue.js app this way is only meant for development and debugging purposes, as editing source files from the frontend should trigger a thorough rebuilding and automatically reload the web page, which is convenient for live-testing various changes.

Docker

A Docker image can be built out of both the Node.js backend and the Vue.js frontend, it also runs an Nginx HTTPS server in front of them for production purposed.

# Build it
docker build -t wideworlds:latest .

# Run it
docker run -v /persistent/storage/data:/data --name wideworlds -p 443:443 -e WW_SERVER_NAME='my-server.com' --rm -it wideworlds:latest

Where /persistent/storage/data denotes an actual host folder that the docker container will mount to fetch and store anything meant to persist across runs of the container, it is internally mounted onto /data.

When provided, /data/nginx/ww.key and /data/nginx/ww.cert will be loaded as key and certificate for the Nginx front web server running to offer HTTPS (and WSS), shall those files be missing: the container will still generate ones on the spot (self-signed certificate), which is enough to locally test the container.

Note that my-server.com denotes the actual, real domain name that you intent to use for a production deployement of WideWorlds, this domain name needs to match the one of the certifcate when signed by a trusted tier.

Omitting the WW_SERVER_NAME environment variable will just result in localhost being picked by default, which is enough to just fiddle with the container locally, then you don't need to provide any custom certifcate or key as the self-signed configuration will be enough.

docker build -t wideworlds:latest .
docker run -v /persistent/storage/data:/data -e WW_SERVER_NAME=my-server.com --name wideworlds -p 443:443 --rm -it wideworlds:latest

Created private key to sign HTTPS certifcate...
To use an existing one: mount the '/data' folder and copy it under '/data/nginx/ww.key'.
Created certificate signed with '/data/nginx/ww.key' to serve HTTPS...
To use an existing one: mount the '/data' folder and copy it under '/data/nginx/ww.crt'.

Nginx server will listen on port 443 to server HTTPS and WSS, visit https://localhost

> wideworlds@0.1.0 server
> node server/app.js --db /data/db.sqlite3 --worldFolder /data/worlds

Tools

aw2db

aw2db is the basic utility to import AW worlds into a Wide Worlds' database (sqlite3) from attr and prop dump files.

Usage:

aw2db.js [sql]

Import AW prop and attr dumps into a WideWorlds sqlite3 database

Positionals:
  sql  Path to the destination SQLite3 database file, will be created if need be
                                        [string] [default: "wideworlds.sqlite3"]

Options:
  -h, --help                 Show help                                 [boolean]
      --version              Show version number                       [boolean]
  -a, --attr                 Input AW world attributes dump file (e.g. atworld.t
                             xt)                                        [string]
  -p, --prop                 Input AW props dump file (e.g. propworld.txt)
                                                                        [string]
  -e, --encoding             Expected encoding from dump files
                                              [string] [default: "windows-1252"]
      --worldId, --wid       Fallback world ID if no World entry is created (no
                             attr file provided)                    [default: 0]
  -b, --batchSize            Maximum amount of props and users to commit to data
                             base a the same time                [default: 2000]
  -u, --autoGenerateUsers    Generate place-holder users based on unique user ID
                             s found in props         [boolean] [default: false]
      --pathOverride, --po   Set the object path value for the world to the prov
                             ided string, keep the original value otherwise
                                                        [string] [default: null]
      --enableTerrain, --et  Override the enableTerrain flag with the provided v
                             alue, keep the original one if none is provided
                                                       [boolean] [default: null]
      --fixEncoding, --fe    Try to fix common encoding errors from props action
                              and description strings [boolean] [default: false]
      --version5, --v5       Import a v5 propdump. Forces encoding to utf8
                                                      [boolean] [default: false]

Example:

tools/aw2db.js wideworlds.sqlite3 --attr ./atworld.txt --prop ./propworld.txt

elev2terrain

elev2terrain is the terrain handling tool, most notably used for importing AW Elevdump files into the native WideWorlds representation format (backed up by PNG files).

Usage:

elev2terrain.js import <elev>

Import AW elevation dump into a WideWorlds terrain folder (PNG files)

Positionals:
  elev  Path to the source AW elevation dump file            [string] [required]

Options:
      --version  Show version number                                   [boolean]
  -h, --help     Show help                                             [boolean]
  -o, --output   Output folder for the terrain, will be created if needed
                                                 [string] [default: "./terrain"]

Example:

Let's assume there is already an existing world saved in database with the ID 1 and that it's still missing any terrain data. By running the server (via npm run server) without any --worldFolder argument, the following directory will be expected to hold terrain data: ./worlds/1/terrain/

To import terrain data from an existing AW elevation dump file (let it be ./elevworld.txt), just run the following command:

tools/elev2terrain.js import ./elevworld.txt -o ./worlds/1/terrain

This will result in PNG files generated in ./worlds/1/terrain/ to store both elevation data (*_*.elev.png) and texture data (*_*.tex.png).

doc

doc is the documentation generation tool, it will print out a .yaml file describing the HTTP server API per OpenAPI version 3.0.0 specification.

This file can then be used by various UI generators to synthetize a readable API documentation.

Usage:

doc.js

Example:

tools/doc.js

openapi: 3.0.0
info:
  title: Wide Worlds
  version: 1.0.0
paths:
  /api/login:
    post:
      description: Authenticate a user based on the provided credentials
      summary: Submit credentials to get an authentication token
      operationId: login
      requestBody:
        description: Credentials for user authentication
        required: true
        content:
          application/json:
            schema:
              properties:
                username:
                  description: Username in plain text
                password:
                  description: Password in plain text
      responses:
        "200":
          description: Successful authentication
          content:
            application/json:
              schema:
                properties:
                  token:
                    description: Authentication token
        "401":
          description: Invalid credentials
        "500":
          description: Internal error
components: {}
tags: []