Rank Card Builder

This page is a work in progress.

Rank card creation has been the most common use case for Canvacord to this date. Canvacord provides a RankCardBuilder class to create rank cards with ease. The RankCardBuilder class offers a lot of helper methods to customize the rank card to your liking.

API Documentation

Refer to https://canvacord.js.org for the complete API documentation. In the following sections, we will only cover the most common use cases.

Let’s get started

Importing the Required Classes

First, we need to import the Font and RankCardBuilder classes from the canvacord module.

import { Font, RankCardBuilder } from "canvacord";

const { Font, RankCardBuilder } = require("canvacord");

Loading fonts

Canvacord does not load fonts by default. If your use case does not involve writing texts, this step can be omitted. However, rank cards require texts to be written on them, so we need to load the font into canvacord’s font registry. Canvacord by default ships with a font called Geist (by Vercel). This font can be loaded with the Font.loadDefault() method:

Font.loadDefault();

If you want to use a custom font instead, you can skip Font.loadDefault() method and utilize Font.fromFile or Font.fromBuffer method to load the font from a file or buffer respectively.

// synchronous method
Font.fromFileSync("./my-font.ttf");

// asynchronous method
await Font.fromFile("./my-font.ttf");

Font.fromBuffer(buffer);

Good to know: Currently only TTF, OTF and WOFF font formats are supported.

Creating a rank card builder

Now that we have loaded the font, we can create a new RankCardBuilder instance. This is a builder class exported by canvacord to specifically create rank cards. It offers a lot of helper methods to customize the rank card to your liking. The following is an example of a rank card builder with common properties set:

const card = new RankCardBuilder()
  .setDisplayName("Wumpus") // Big name
  .setUsername("@wumpus") // small name, do not include it if you want to hide it
  .setAvatar("https://cdn.discordapp.com/embed/avatars/0.png?size=256") // user avatar
  .setCurrentXP(300) // current xp
  .setRequiredXP(600) // required xp
  .setLevel(2) // user level
  .setRank(5) // user rank
  .setOverlay(90) // overlay percentage. Overlay is a semi-transparent layer on top of the background
  .setBackground("#23272a") // set background color or,
  .setBackground("./path/to/image.png") // set background image
  .setStatus("online"); // user status. Omit this if you want to hide it

Generating the image

const image = await card.build({
  format: "png",
});

// image is a buffer. It can be written to a file or sent as an attachment over internet

Result

Advanced Usage

Overriding default texts

The setTextStyles method is used to customize the text styles for different elements in a rank card or leaderboard. This method allows for the modification of default labels for level, experience points (XP), and rank display.

card.setTextStyles({
  level: "NIVEAU :", // Custom text for the level
  xp: "EXP :", // Custom text for the experience points
  rank: "CLASSEMENT :", // Custom text for the rank
});

Result

Customizing the colors

The setStyles method can be used to customize the colors of different elements in a rank card or leaderboard. This method allows for the modification of the background, progress bar, and text colors, etc. The style object is a key-value pair of the style name and the value to be set. The style behaves similar to css properties.

Syntax 1 (Style object)

// Group of elements
ElementGroup {
  // Element name
  ElementName {
    // Style object
    style {
      attribute-name: value;
    }
  }
}

Syntax 2 (Tailwind classes)

// Group of elements
ElementGroup {
  // Element name
  ElementName {
    // Style object
    tw = "tailwind-classes"
  }
}

Examples

// changing progress bar thumb color
card.setStyles({
  progressbar: {
    thumb: {
      style: {
        backgroundColor: "red",
      },
    },
  },
});

// alternative syntax
card.setStyles({
  progressbar: {
    thumb: {
      tw: "bg-red-500",
    },
  },
});

Modifying progress bar width

The internal progress calculator may not be suitable for all use cases. You can set a custom progress calculator using the setProgressCalculator method. The progress calculator is a function that returns a number between 0 and 100, representing the progress percentage.

card.setProgressCalculator((currentXP, requiredXP) => {
  // do some crazy math here
  // The value returned must be in the range of 0 to 100. It represents the width of the progress bar
  return Math.floor((currentXP / requiredXP) * 100);
});

Overriding emoji providers

Canvacord uses the twemoji provider by default. You can override this by using the setGraphemeProvider method. The setGraphemeProvider method accepts a GraphemeProvider enum value.

// Twemoji
card.setGraphemeProvider(BuiltInGraphemeProvider.Twemoji);

// FluentEmojiHighContrast
card.setGraphemeProvider(BuiltInGraphemeProvider.FluentEmojiHighContrast);

// FluentEmoji
card.setGraphemeProvider(BuiltInGraphemeProvider.FluentEmoji);

// FluentEmojiColor
card.setGraphemeProvider(BuiltInGraphemeProvider.FluentEmojiColor);

// FluentEmojiFlat
card.setGraphemeProvider(BuiltInGraphemeProvider.FluentEmojiFlat);

// Openmoji
card.setGraphemeProvider(BuiltInGraphemeProvider.Openmoji);

// Noto
card.setGraphemeProvider(BuiltInGraphemeProvider.Noto);

// Blobmoji
card.setGraphemeProvider(BuiltInGraphemeProvider.Blobmoji);

// None
card.setGraphemeProvider(BuiltInGraphemeProvider.None);

Get Started

Builders

Image Manipulation

API Documentation

Let’s get started

Importing the Required Classes

Loading fonts

Creating a rank card builder

Generating the image

Result

Advanced Usage

Overriding default texts

Result

Customizing the colors

Syntax 1 (Style object)

Syntax 2 (Tailwind classes)

Examples

Modifying progress bar width

Overriding emoji providers

​API Documentation

​Let’s get started

​Importing the Required Classes

​Loading fonts

​Creating a rank card builder

​Generating the image

​Result

​Advanced Usage

​Overriding default texts

​Result

​Customizing the colors

​Syntax 1 (Style object)

​Syntax 2 (Tailwind classes)

​Examples

​Modifying progress bar width

​Overriding emoji providers

API Documentation

Let’s get started

Importing the Required Classes

Loading fonts

Creating a rank card builder

Generating the image

Result

Advanced Usage

Overriding default texts

Result

Customizing the colors

Syntax 1 (Style object)

Syntax 2 (Tailwind classes)

Examples

Modifying progress bar width

Overriding emoji providers