Dreamlo.js NPM

👨‍🔧 Examples

Using dreamlo.js for your game's leaderboard? Send me a message with a link and I'll add it to the examples listed below:

Tic-Tac-Toe

⚙️ Demo

Are you new to dreamlo? Want to test it out without having to commit? 😕

Just use the Swagger UI-like demo page to test requests and retrieve leaderboard data 😎

🔩 Requirements

Go to dreamlo's official website for a unique pair of public and private codes. Bookmark your leaderboard's page, you won't be given the URL after the first time!

If you can afford it, I recommend upgrading your leaderboard, which:

🔒 enables HTTPS for your board's URL
🙌 removes the limit of 25 scores

🔧 Installation

There are a few ways to start working, all of which globally expose the dreamlo variable: 1. Manually download the compiled file dreamlo.js from dist to your appropriate project folder and load using a relative path:

<script src="/path/to/dreamlo.js"></script>

Use <script> to reference the code through jsDelivr's CDN:

<script src="https://cdn.jsdelivr.net/npm/dreamlo.js@1.3.2/dist/dreamlo.min.js"></script>

Install the package via npm with the following command:

npm install dreamlo.js

🤖 Usage

The methods below, except initialize(), are all Promises, so they can wait for the HTTP response. Failed HTTP requests will throw an Error containing the HTTP status code.

You can use these methods with Promise chains:

dreamlo.getScores()
    .then((scores) => {
      // do stuff with scores
    })
    .catch((error) => {
      // do something with error
    });

or async/await:

try {
  var scores = await dreamlo.getScores();
  // do stuff with scores
} catch (error) {
  // do something with error
}

initiailize

dreamlo.initialize(publicCode, privateCode, useHttps)

The initialize function sets the public and private codes and specifies whether the base URL uses HTTP or HTTPS protocol. Call this method before any others.

publicCode: the public code of your leaderboard
privateCode: the private code of your leaderboard
useHttps: toggles HTTP or HTTPS on the base URL (default: false)

getScore

dreamlo.getScore(name, format)

The getScore function sends a request for one leaderboard entry and returns it in the desired format.

name: the name value of the score to request
format: the format type of the returned leaderboard entry (default format: Object; see Formats for which properties use to change formats)

Object: returns a single entry object or null if no entries match score.name
JSON: returns a single entry for getScore as a string or null as a string if no entries match score.name
XML: returns a single entry for getScore as a string or an empty string if no entries match score.name
Pipe: returns a single entry for getScore as a string or an empty string if no entries match score.name
Quote: returns a single entry for getScore as a string or an empty string if no entries match score.name

getScores

dreamlo.getScores(format, sortOrder, skip, take)

The getScores function sends a request for multiple leaderboard entries and returns them in the specified format and order.

format: the format type of the returned leaderboard entries (default format: Object; see Formats for which properties use to change formats)
sortOrder: the sorting order of the retrieved scores (default order: Descending by Points; see Sorting Order for which properties use to adjust orders)
skip: the score rank you want to start sorting at (default: 0; zero-based index)
take: the number of scores you want to retrieve (default: undefined; retrieves all scores)

Object: returns an array of entry objects
JSON: returns an array of entries nested within dreamlo.leaderboard.entry as a string
XML: returns <entry>s nested within <dreamlo><leaderboard></leaderboard></dreamlo> as a string or "<dreamlo></leaderboard /></dreamlo>" if no entries are found
Pipe: returns entries with pipe-delimited values, each entry separated with a new line character as a string or an empty string if no entries are found
Quote: returns entries with double-quoted values, separated with a comma, each entry with a new line character as a string or an empty string if no entries are found

All parameters are optional or have default values; calling with no parameters will return all scores, sorted by points in descending order, as an array of objects.

addScore

dreamlo.addScore(score, format, sortOrder, canOverwrite)

The addScore function sends a request to add a score to the leaderboard and returns all leaderboard entries in the specified format and order.

score: the score to add to the leaderboard (see Score for the expected shape of this object)
format: the format type of the returned leaderboard entries (default format: Object; see Formats for which properties use to change formats)
sortOrder: the sorting order of the retrieved scores (default order: Descending by Points; see Sorting Order for which properties use to adjust orders)
canOverwrite: when adding a score whose score.name is already present on the leaderboard, if this is set to true, the score with higher score.points is saved; if set to false, an Error is thrown (default: false)

Object: returns an array of entry objects
JSON: returns an array of entries nested within dreamlo.leaderboard.entry as a string
XML: returns <entry>s nested within <dreamlo><leaderboard></leaderboard></dreamlo> as a string or "<dreamlo></leaderboard /></dreamlo>" if no entries are found
Pipe: returns entries with pipe-delimited values, each entry separated with a new line character as a string or an empty string if no entries are found
Quote: returns entries with double-quoted values, separated with a comma, each entry with a new line character as a string or an empty string if no entries are found

TIP: if updating a score on the leaderboard, set canOverwrite to true, if adding a new score, set canOverwrite to false.

deleteScore

dreamlo.deleteScore(name)

The deleteScore function sends a request to to delete one score from the leaderboard.

name: the name value of the score to delete

deleteScores

dreamlo.deleteScores()

The deleteScores function sends a request to delete all scores from the leaderboard.

Score

{
    name: string,
    points: number,
    seconds: number,
    text: string
}

A score is a data object sent to the leaderboard.

name: the unique identifier for scores; instead of using a player's name, try a distinct value, like a timestamp
points: the first numeric value that can be used to sort multiple entries
seconds: the second numeric value that can be used to sort multiple entries; this property is optional
text: contains extra data relating to the score; this property is optional

TIP: if you have lots of extra data you want to store, you can use score.text to save a pipe-delimited string and then decode/recode the information in your program.

dreamlo doesn't allow the use of the asterisk character ( * ); all occurrences will be replaced by the underscore character ( _ ).

See Score for this Typescript interface.

Entry

{
    name: string,
    score: string,
    seconds: string,
    text: string,
    date: string
}

An entry is a score retrieved from the leaderboard. Shown above is what it looks like with the Object format; JSON and XML use properties that have the same names as Object. Pipe and Quote don't use key-value pairs, but values are listed similarly.

name: correlates to score.name
score: correlates to score.points
seconds: correlates to score.seconds
text: correlates to score.text
date: when the entry was last updated, in US format (mm-dd-yyyy HH:MM:ss AM/PM), using the UTC timezone.

Score Formats

The format type of entries returned from the leaderboard can be specified using the following properties: Format | Property ------------------| ------------ Javascript Object | dreamLo.ScoreFormat.Object JSON | dreamlo.ScoreFormat.Json XML | dreamlo.ScoreFormat.Xml Pipe-delimited | dreamlo.ScoreFormat.Pipe Quoted with comma | dreamlo.ScoreFormat.Quote

See ScoreFormat for this Typescript enum.

Sorting Order

The sorting order of entries returned from the leaderboard can be specified using the following properties: Order | Property --------------------- | ------------ Descending by Points | dreamlo.SortOrder.PointsDescending Ascending by Points | dreamlo.SortOrder.PointsAscending Descending by Seconds | dreamlo.SortOrder.SecondsDescending Ascending by Seconds | dreamlo.SortOrder.SecondsAscending Descending by Date | dreamlo.SortOrder.DateDescending Ascending by Date | dreamlo.SortOrder.DateAscending

See SortOrder for this Typescript enum.

🤔 About

What is dreamlo?

dreamlo is a cloud server for hosting leaderboards for game developers. Out of love for Unity, Carmine Guida started hosting dreamlo. He created an asset for the game engine so anyone can effortlessly add a leaderboard to their games.

Check out dreamlo's official FAQs page for more info.

Why use dreamlo with Javascript?

Previously, I used the dreamlo game asset for the game my team built for the GTMK 2020 game jam.

Years later, I started sprucing up an old TicTacToe game I made years ago and wanted to add a leaderboard. The first thing that came to mind was dreamlo, but there was a problem, the script for dreamlo that comes with the Unity game asset was written in C#.

I created this script because any game that can make HTTP requests can use dreamlo. Happily, I've extended Carmine's original dream(lo) to Javascript 😊