gamertag-generator

Zero-dependency TypeScript library and CLI for generating gamertags. Same engine that powers namesforgames.com.

Mixes 300+ tagged word fragments into compound names (ShadowHunter), spaced jokes (Cereal Killer), and standalone picks (FrostByte). Filter by style and gender, roll variants when a platform already took the exact string.

Get the code

git clone https://github.com/editself/gamertag-generator.git
cd gamertag-generator
npm install
npm run build

If you already have the namesforgames monorepo, the same package is at packages/gamertag-generator.

CLI

After npm run build:

node dist/cli.js --style cool --count 5
node dist/cli.js --style legendary --gender boy --json

| Flag | Values | Default | |------|--------|---------| | --style | any, cool, cute, unique, legendary | any | | --gender | any, boy | any | | --count | 1–100 | 10 | | --json | print structured output | off |

API

Build first, then import from the compiled output or wire the package into your bundler:

import { generateBatch, variantOf, countCombinations } from "./dist/index.js";

const batch = generateBatch(
  { style: "cool", gender: "any", platform: "any" },
  10,
);

console.log(batch[0].display); // e.g. "FrostByte"

// Platform took the exact tag? Roll a spelling variant, same vibe.
const alt = variantOf(batch[0]);
console.log(alt.display); // e.g. "FrostByteX"

console.log(countCombinations()); // 10000+

Filters

type GeneratorFilters = {
  style: "cool" | "cute" | "unique" | "legendary" | "any";
  gender: "any" | "boy";
  platform: "any"; // reserved for future platform-specific banks
};

Output shape

type GeneratedName = {
  id: string;
  base: string;    // canonical compound before variant tweaks
  display: string; // what you copy into Xbox / Steam / Roblox
  mode: "compound" | "spaced" | "standalone";
};

Seeded randomness

Pass a custom RNG as the third argument to generateBatch or the second to variantOf — useful for tests and deterministic demos.

generateBatch(filters, 10, () => 0.42);

Word bank

Advanced use: import the raw fragments and build your own pipeline.

import { PREFIXES, SUFFIXES, STANDALONES, FRAGMENTS } from "./dist/index.js";

How it works

1. Pick prefix + suffix (or a standalone) from fragments matching your filters.
2. Join as compound (Shadow + Hunter) or spaced (Cereal + Killer) when tagged.
3. Optionally apply a display variant (X suffix, remove spaces, The prefix, etc.).
4. ~16% chance to pull a pre-written standalone instead of composing one.

Development

npm test      # build + vitest
npm run build # emit dist/

License

MIT

Related

• Live generator UI: namesforgames.com
• Site repo: editself/namesforgames