Melooly can be installed with npm i melooly. The meloolyLauncher class requires an API Key and Website ID from the developer page,
but the other exports do not.
meloolyLauncher classThis class can be used to get Meloolies from the melooly website. It is responsible for opening the popup, fetching user Meloolies, and fetching Demo Meloolies.
constructor(websiteID, key)Produces the class with the websiteID and key. These can be empty strings if you are not using the initiatePopup or getMelooly functions.
The API Key expires a year after it is issued and will no longer work with the getMelooly function. It can be rotated anytime on the developer page.
initiatePopupThe function produces a promise waiting for a popup in environments where a window exists (in
other environments, the promise will reject). The promise will resolve with a user ID if the
user selects to share any Meloolies (there is no distinction between sharing only the user's
primary Melooly to sharing all of their meloolies). If the user rejects sharing or closes the
popup, the promise resolves to null. You can set the popup to open an arbitrary domain with the
static popupURL variable.
monitorSpeedControls how frequently popup close events are checked, in milliseconds. Defaults to 100. Higher values will mean the rejection events only populate after longer periods, and could lead to the user waiting for processing their closure.
getMeloolyFetches user meloolies from the internet. Takes in a userID string (probably from initiatePopup) and returns an array of Meloolies. Throws errors as listed below, in {status: number, error: string} format.
| Code # | Code Description | Code Meaning |
|---|---|---|
| 401 | No API Key Provided | API key was not found in the request headers. Make sure meloolyLauncher is constructed correctly. |
| 401 | Unauthorized Key | Key is invalid, expired, or inactive. Check that your key has not expired. |
| 401 | Unauthorized User | User has not approved data sharing. Run initiatePopup again. |
| 404 | Invalid User | The user has no Meloolies, or the user ID is invalid. |
| 500 | Database error (api_keys_get) | Internal server error. Retry request. |
| 500 | Database error (api_keys_update) | Internal server error. Retry request. |
| 500 | Database error (characters_get) | Internal server error. Retry request. |
| 500 | Database Error (access_rights_get) | Internal server error. Retry request. |
getDemoGets a demo Melooly from the server. Returns a Melooly, or an error if an error is encountered during the fetch (see getMelooly for specifics on the error structure).
demoIDID (numeric) of demo Melooly to get. If left unset, a random Melooly is got.
getDemosGets multiple demo Meloolies from the server. Throws a relatively nondescript error.
countThe number of demo meloolies to get. If less than the number on the server (this is represented
as static property demoCount), random demo Meloolies are got (no duplicate
Meloolies are provided). If it is higher (e.g. infinity) or unset, all Meloolies are got in
sequential order.
meloolyLauncherVarious static properties of the function are available to change what URL to fetch Meloolies
from. You cannot change the demoCount static variable, but the serverURL, demoServerURL, and popupURL properties can be changed. The respective functions
using these properties append the filename needed to reach the appropriate URL. These shouldn't be
changed in most scenarios.
Melooly classClass responsible for drawing, altering, and saving Meloolies.
constructor(file: string)A Melooly can be constructed directly from a Melooly save file (.melooly) or from the meloolyLauncher class. The save files can be produced from the melooly maker by clicking the ⎇ key to add Export and Import buttons to the view page (replacing the save button).
componentsThe components property is a record of layer, color, and value. This property can be used to
alter the Melooly's look with code such as melooly.components.mouth.value = 'smirk'. If you only need to temporarily change the melooly (such as to make it frown after it has
lost a game), use draw instead. If you want to change the hair color, use applyHairColor.
drawThe draw function applies the melooly face to a canvas. The face is 270×270 and can be scaled up with the scale param. Items need to be saved before draw is called with the saveComponent, saveSelectedComponents, and saveAllComponents functions.
The componentAdjustments param provides the ability for components to be temporarily adjusted
and is in the format of the components property. For instance, a
Melooly can be drawn winking with melooly.draw(ctx, 2, {eyes: {value: 'wink'}})
saveComponentFetches a component render from the internet for use with the draw function. The static componentURL property
enables direct setting of the URL components use. This property is a string using \l to represent layer and \v for the canvas (both of these need to be prefixed with a backslash
so that they are not interpreted as escapes).
saveSelectedComponents and saveAllComponentsThese functions save components in bulk, with saveSelectedComponent saving those used by the current state of the Melooly and saveAllComponents saving all components from the web (this should be avoided unless all components are needed).
Saved components can by copied to other Meloolies and deleted from the current melooly through the copySavedComponents and clearSavedComponents functions. Copying saved components can be an effective way of saving components to multiple meloolies.
Other than having components, Meloolies have a name (saved under the name property), a gender (saved as 'M' for male, 'F' for female, 'P' for prefer not to say, and 'O' for other), and a favorite color (saved numerically, see primaryColors for more details).
Meloolies can be saved to a melooly save file (.melooly) with the toSaveFile function, and
cloned with melooly.clone().
If you want to map each component to your own variant (such as rendering all Meloolies as a robot), the componentURL property can be set. See fetchComponent for more details. All components should be a .canvas file.
addComponentThe addComponent function adds a single component to a melooly. The component should be a .canvas file, with the primary color marked as \c throughout the file, such as fill style \c. The function requires the layer, component name, and the file
contents.
primaryColorsThe favorite color of a melooly can be converted from the numeric form saved as Melooly.prototype.favoriteColor to a hex value through the primaryColors record (with the keys set to the primaryColor number). If a custom primary color, such as a pale version, is desired, a custom record can be created. Demo Meloolies beyond demo 15 alternate between colors with the last hexadecimal digit equal to the color ID. The primary colors are as follows:
| Code | Name | Default hex value |
|---|---|---|
| 0 | Black | #382E2E |
| 1 | Red | #FF0040 |
| 2 | Orange | #FF8000 |
| 3 | Yellow | #FFFF00 |
| 4 | Green | #00A82A |
| 5 | Sky | #00BFFF |
| 6 | Blue | #2050DF |
| 7 | White | #F2F3F3 |
| 8 | Gray | #879292 |
| 9 | Pink | #FF80DF |
| 10 | Brown | #704010 |
| 11 | Olive | #808000 |
| 12 | Lime | #BFFF00 |
| 13 | Teal | #107070 |
| 14 | Purple | #6040BF |
| 15 | Fuchsia | #BF409F |
componentsThe components export lists all of the possible values and colors of each layer that can be selected in the Melooly maker. For all properties other than hair, the variable lists colors and values as an array of strings. For hair, values is an array of objects of front/back pairs.
Complex applications using meloolies can have large load times to fetch necessary Meloolies and
components. Promise.all should be used where possible during the loading stage.
Other ways to decrease load times include loading components that will be needed for all
Meloolies (e.g. frown) with an invalid Melooly created with new Melooly('') while
loading other Meloolies from the web, and then using melooly.copySavedComponents.
See licenses.txt for details of use. We request that, on top of other licenses, Meloolies: