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.
- 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
npm install gavatarFor browser rendering, you also need PIXI.js (v7 or v8):
npm install pixi.jsimport { 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);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);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,...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'); // 16711680Note on Color Names: The 107 color names in
gavatar/colorswere 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.
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| 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).
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();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 formimport * 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();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' });import {
getColorRGB, colorIndexToHex, colorIndexToDecimal,
parseIconColor, getAllColors, getColorCount,
rgbToDecimal, decimalToRGB, decimalToHex, hexToDecimal,
getGlowColor
} from 'gavatar/utils';import {
parseIconForm, getFormMetadata, isComplexForm,
validateIconID, getIconCount, getAllForms, ALL_FORMS
} from 'gavatar/utils';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';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.
| Feature | Browser | Node.js |
|---|---|---|
| Profile fetching | Yes | Yes |
| Icon rendering | Yes (PIXI) | Needs @pixi/node |
| Color utilities | Yes | Yes |
| Icon metadata | Yes | Yes |
MIT
- 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