Gavatar

A Geometry Dash avatar provider and icon renderer. Fetch player profiles directly from GD servers, render icons client-side with PIXI.js, and work with GD color/icon data.

Features

• Avatar Provider - Fetch any player's icons by username or account ID
• Icon Rendering - Render all 9 icon forms (cube, ship, ball, UFO, wave, robot, spider, swing, jetpack)
• Batch Rendering - Render multiple icons at once, get all player icons in one call
• Multiple Output Formats - Get icons as Canvas, DataURL, or Blob
• 107 GD Colors - Full color palette with named exports and conversion utilities
• Animated Forms - Robot and spider with animation support
• Direct GD Access - Communicates directly with Geometry Dash servers (no proxy needed)
• TypeScript Support - Written in TypeScript with full type definitions
• GDPS Support - Works with private servers via custom endpoints

Installation

npm install gavatar

For browser rendering, you also need PIXI.js (v7 or v8):

npm install pixi.js

Quick Start

Get Player Avatar Data

import { getAvatar, getAllAvatars, getPlayer } from 'gavatar/client';

// Get a player's avatar data for their display icon
const avatar = await getAvatar('RobTop');
// { form: 'cube', iconID: 1, col1: 0, col2: 3, glow: false, col1RGB: {...}, col2RGB: {...} }

// Get a specific form
const shipAvatar = await getAvatar('RobTop', 'ship');

// Get all avatars at once
const allAvatars = await getAllAvatars('RobTop');

// Get full player profile
const player = await getPlayer('RobTop');
console.log(player.stars, player.demons, player.username);

Render a Single Icon

import * as PIXI from 'pixi.js';
import { getAvatar } from 'gavatar/client';
import { renderIcon } from 'gavatar';

const avatar = await getAvatar('RobTop');

const canvas = await renderIcon(PIXI, {
  form: avatar.form,
  iconID: avatar.iconID,
  col1: avatar.col1,
  col2: avatar.col2,
  glow: avatar.glow,
  size: 200
}, { assetsPath: '/assets' });

document.body.appendChild(canvas);

Render All Player Icons

import * as PIXI from 'pixi.js';
import { renderPlayerIcons } from 'gavatar';

const result = await renderPlayerIcons(PIXI, 'RobTop', {
  assetsPath: '/assets',
  size: 150
});

result.icons.cube;     // HTMLCanvasElement
result.dataURLs.cube;  // data:image/png;base64,...

Work with Colors

import { lime, cyan, red, white } from 'gavatar/colors';

console.log(lime);
// { r: 125, g: 255, b: 0, index: 0, hex: '#7dff00', decimal: 8257280 }

import { getColorRGB, colorIndexToHex, parseIconColor } from 'gavatar/utils';

getColorRGB(10);          // { r: 255, g: 125, b: 0 }
colorIndexToHex(10);      // '#ff7d00'
parseIconColor('#ff0000'); // 16711680

Note on Color Names: The 107 color names in gavatar/colors were generated with AI assistance. Manually naming that many colors would be an unreasonable use of my sanity, so I let Claude Code handle it. The names are descriptive and consistent, but not official GD color names.

Package Exports

import { ... } from 'gavatar';           // Everything
import { ... } from 'gavatar/client';    // GDClient, Player, getPlayer, getAvatar, getAllAvatars
import { ... } from 'gavatar/renderer';  // IconRenderer, Icon, IconPart, IconLayer
import { ... } from 'gavatar/colors';    // Named color constants (lime, cyan, etc.)
import { ... } from 'gavatar/utils';     // Color + icon utility functions

Icon Forms

| Form Name | Aliases | Animated | Max ID | |-----------|---------|----------|--------| | cube | icon, player | No | 485 | | ship | | No | 169 | | ball | player_ball | No | 118 | | ufo | bird | No | 149 | | wave | dart | No | 96 | | robot | | Yes | 68 | | spider | | Yes | 69 | | swing | | No | 43 | | jetpack | | No | 8 |

You can use either the user-friendly names (cube, ufo, wave) or internal names (player, bird, dart).

API Overview

GDClient

import { GDClient } from 'gavatar/client';

const client = new GDClient({
  cache: true,        // Enable caching (default: true)
  cacheTTL: 300000,   // Cache TTL in ms (default: 5 min)
  endpoint: 'https://www.boomlings.com/database'  // For GDPS support
});

const player = await client.getPlayer('RobTop');
const avatar = await client.getAvatar('RobTop', 'cube');
const all = await client.getAllAvatars('RobTop');
client.clearCache();

Player

import { getPlayer } from 'gavatar/client';

const player = await getPlayer('RobTop');

player.username      // 'RobTop'
player.accountID     // 71
player.stars         // Star count
player.moons         // Moon count (2.2)
player.demons        // Demon count
player.col1          // Primary color index
player.col2          // Secondary color index
player.col3          // Glow color index (2.2+)
player.glow          // Glow enabled

player.getIcons();           // { cube: 1, ship: 5, ... }
player.getIcon('ship');      // Ship icon ID
player.getAvatar('cube');    // Avatar data for cube
player.getAllAvatars();       // All avatar data
player.getRenderData();      // Data formatted for IconRenderer
player.getDisplayIconForm(); // Player's selected display icon form

IconRenderer

import * as PIXI from 'pixi.js';
import { IconRenderer } from 'gavatar/renderer';

const renderer = new IconRenderer(PIXI, {
  assetsPath: '/assets',
  defaultSize: 300
});

const canvas = await renderer.render({ form: 'cube', iconID: 1, col1: 0, col2: 3 });
const dataUrl = await renderer.toDataURL({ form: 'ship', iconID: 5 });
const blob = await renderer.toBlob({ form: 'robot', iconID: 7 });

const result = await renderer.renderMultiple({
  forms: ['cube', 'ship', 'ball'],
  col1: 0, col2: 3, glow: true
});

await renderer.preload([{ form: 'cube', id: 1 }, { form: 'robot', id: 10 }]);
renderer.clearCache();

Convenience Functions

import { renderIcon, renderMultipleIcons, renderPlayerIcons, getIconDataURL, getIconBlob } from 'gavatar';

// One-shot render (creates a temporary renderer)
const canvas = await renderIcon(PIXI, { form: 'cube', iconID: 1 }, { assetsPath: '/assets' });

// Render multiple forms
const result = await renderMultipleIcons(PIXI, { forms: ['cube', 'ship'], col1: 0, col2: 3 }, { assetsPath: '/assets' });

// Render all of a player's icons
const icons = await renderPlayerIcons(PIXI, 'RobTop', { assetsPath: '/assets' });

// Get as data URL or blob
const dataURL = await getIconDataURL(PIXI, { form: 'cube', iconID: 1 }, { assetsPath: '/assets' });
const blob = await getIconBlob(PIXI, { form: 'ship', iconID: 5 }, { assetsPath: '/assets' });

Color Utilities

import {
  getColorRGB, colorIndexToHex, colorIndexToDecimal,
  parseIconColor, getAllColors, getColorCount,
  rgbToDecimal, decimalToRGB, decimalToHex, hexToDecimal,
  getGlowColor
} from 'gavatar/utils';

Icon Utilities

import {
  parseIconForm, getFormMetadata, isComplexForm,
  validateIconID, getIconCount, getAllForms, ALL_FORMS
} from 'gavatar/utils';

TypeScript

Full TypeScript support with exported types:

import type {
  RGB, ColorInfo, ColorValue,
  FormName, InternalFormName, FormMetadata,
  Avatar, AvatarSet,
  RenderOptions, RenderMultipleOptions, MultiIconResult,
  PlayerData, PlayerIcons, GDClientOptions, IconRendererOptions,
  PIXINamespace
} from 'gavatar';

Asset Setup

The package requires icon sprite assets to be served from your web server:

assets/
  icons/
    player_01_001.png
    player_01_2_001.png
    player_01_glow_001.png
    ship_01_001.png
    ...

Copy the assets/ folder from this package to your public directory.

Browser vs Node.js

| Feature | Browser | Node.js | |---------|---------|---------| | Profile fetching | Yes | Yes | | Icon rendering | Yes (PIXI) | Needs @pixi/node | | Color utilities | Yes | Yes | | Icon metadata | Yes | Yes |

License

MIT

Credits

• Icon rendering logic heavily inspired by GDBrowser's icon kit. Thank you, Colon!!!!! <3
• NicksNews for feedback and criticism
• Color names generated with AI assistance (because naming 107 colors manually would be insane)
• PIXI.JS for being AWESOME <3<3<3<3<3