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.
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.
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
[string] [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.
To easily build and serve frontend content, you will need to run the following:
VITE_SERVER_URL=http://localhost:8080 npm run client-dev
Prepending VITE_HTTP_SERVER_URL=<url>
as environment variable is essential, as it tells the Vue.js app which base url to use 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 of various changes.
aw2db
is the basic utility to import AW worlds into a Wide Worlds' database (sqlite3) from attr and prop dump files.
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: true]
--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]
tools/aw2db.js wideworlds.sqlite3 --attr ./atworld.txt --prop ./propworld.txt
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).
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"]
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
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.
doc.js
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: []