dreamlo.js

A Javascript library for creating, retrieving, updating, and deleting scores on your dreamlo leaderboard via its web API.

Examples • Demo • Requirements • Installation • Usage • About • Acknowledgements • Technologies Used • License

👨‍🔧 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>

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

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/dreamlo.min.js"></script>

3. 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 are used to change formats)

Return behavior by format

• 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 are used to change formats)
• sortOrder: the sorting order of the retrieved scores (default order: Descending by Points; see Sorting Order for which properties are used 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)

Return behavior by format

• 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 are used to change formats)
• sortOrder: the sorting order of the retrieved scores (default order: Descending by Points; see Sorting Order for which properties are used 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)

Return behavior by format

• 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 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 😊

❤️ Acknowledgements

☁️ Carmine T. Guida for creating and hosting dreamlo

👩🏼‍🏫 Microsoft Learn for teaching me Typescript

👨🏽‍💻 Technologies Used

• Typescript - Javascript superset
• VSCode - code editor
• HTML - webpage markup language (used in demo page)
• Bootstrap - CSS Library (used in demo page)
• Javascript - webpage interactivity language (used in demo page)
• jQuery - Javascript shorthand library (used in demo page)

📃 License

The MIT License (MIT)

Copyright (c) 2022 Justin M Heartley