Game

Resource class for interacting with the GunSpec Game API. Wraps all /v1/game endpoints. These endpoints provide game-balanced firearm data suitable for game development, including normalized stats, tier rankings, and balance analysis. Instantiated internally by the GunSpec client and exposed as client.game.

Auth RequiredStudio+

client.game.balanceReport()

Get a balance report showing outlier firearms. Identifies firearms whose game stats deviate significantly from the average, useful for game balancing.

balanceReport(params?: BalanceReportParams): Promise<APIResponse<BalanceEntry[]>>

GET/v1/game/balance-report

Studio+

stringheaderrequired
Your API key. Authorization: Bearer <key> is accepted in its place.

numberdefault20
How far from the mean a stat must sit to be flagged
Range
0 – 100
Example

application/json

object[]
The response payload.
string
Slug of the firearm this row belongs to.
string
Display name of the firearm this row is about.
object[]
Every stat on this firearm that sits further from the mean than threshold.
string
Which statistic this row is about, named as the field is: weightEmptyG, damage.
number
This firearm value for the stat.
number
Arithmetic mean across the records counted.
number
Standard deviation across the records counted.
number
Standard deviations from the mean. Positive is above it; the sign says which way the firearm is out of line.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Full rate limits

Minimum tier: Studio+
Monthly quota: 150,000/mo
Rate limit: 120/min
Daily cap: 10,000

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.game.balanceReport({ threshold: 15 });6console.log(data.length, 'firearms flagged as outliers');

1{2  "success": true,3  "data": [4    {5      "firearmId": "m2-browning",6      "firearmName": "M2 Browning",7      "deviations": [8        {9          "stat": "damage",10          "value": 98,11          "mean": 54.2,12          "stdDev": 12.9,13          "zScore": 3.414        }15      ]16    }17  ]18}

Auth RequiredBuilder+

client.game.tierList()

Get a tier list of firearms ranked by a specific stat.

tierList(params?: TierListParams): Promise<APIResponse<TierList>>

GET/v1/game/tier-list

Builder+

stringheaderrequired
Your API key. Authorization: Bearer <key> is accepted in its place.

stringdefaultdamage
Which stat to tier by
Accepts
Example
string
Restrict the tier list to a category slug
Example

application/json

object
The response payload.
string
Which statistic this row is about, named as the field is: weightEmptyG, damage.
object
Firearms grouped into tiers, strongest first.
object[]
Top tier for this stat.
object[]
Second tier.
object[]
Third tier.
object[]
Fourth tier.
object[]
Bottom tier for this stat.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Full rate limits

Minimum tier: Builder+
Monthly quota: 25,000/mo
Rate limit: 60/min
Daily cap: 2,000

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.game.tierList({6  stat: 'accuracy',7  category: 'rifle',8});9console.log('S-tier:', data.tiers.S.map(f => f.name));

1{2  "success": true,3  "data": {4    "stat": "damage",5    "tiers": {6      "S": [7        {8          "id": "ak-47",9          "name": "AK-47",10          "categoryId": "assault-rifle",11          "value": 7212        }13      ],14      "A": [15        {16          "id": "ak-47",17          "name": "AK-47",18          "categoryId": "assault-rifle",19          "value": 7220        }21      ],22      "B": [23        {24          "id": "ak-47",25          "name": "AK-47",26          "categoryId": "assault-rifle",27          "value": 7228        }29      ],30      "C": [31        {32          "id": "ak-47",33          "name": "AK-47",34          "categoryId": "assault-rifle",35          "value": 7236        }37      ],38      "D": [39        {40          "id": "ak-47",41          "name": "AK-47",42          "categoryId": "assault-rifle",43          "value": 7244        }45      ]46    }47  }48}

Auth RequiredBuilder+

client.game.matchups()

Get a game-balanced matchup between two firearms.

matchups(params: MatchupsParams): Promise<APIResponse<MatchupResult>>

GET/v1/game/matchups

Builder+

stringheaderrequired
Your API key. Authorization: Bearer <key> is accepted in its place.

stringrequired
First firearm slug
Max length
255
Example
stringrequired
Second firearm slug
Max length
255
Example

application/json

object
The response payload.
object
The firearm named by the a parameter.
string
Slug of the first firearm.
string
Display name, as the maker writes it.
object
The editorial game stats, with the game prefix the column carries stripped.
object
The firearm named by the b parameter.
string
Slug of the second firearm.
string
Display name, as the maker writes it.
object
The editorial game stats, with the game prefix the column carries stripped.
object
The per-stat verdict, keyed by stat rather than listed.
string
Which firearm wins on damage: a, b, or draw.
string
Which firearm wins on accuracy.
string
Which firearm wins on range.
string
Which firearm wins on rate of fire.
string
Which firearm wins on mobility.
string
Which firearm wins on recoil control.
string
Which firearm wins on reload speed.
string
Which firearm wins on concealment.
integer
How many statistics the first firearm wins.
integer
How many statistics the second firearm wins.
integer
How many statistics are tied.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
404NOT_FOUNDResource not found
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Full rate limits

Minimum tier: Builder+
Monthly quota: 25,000/mo
Rate limit: 60/min
Daily cap: 2,000

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.game.matchups({ a: 'ak-47', b: 'm4-carbine' });6console.log(data.winner, data.statComparisons);

1{2  "success": true,3  "data": {4    "a": {5      "id": "ak-47",6      "name": "AK-47",7      "stats": {8        "damage": 72,9        "accuracy": 64,10        "range": 58,11        "fireRate": 70,12        "mobility": 55,13        "recoilControl": 48,14        "reloadSpeed": 60,15        "concealment": 3016      }17    },18    "b": {19      "id": "m16a1",20      "name": "M16A1",21      "stats": {22        "damage": 72,23        "accuracy": 64,24        "range": 58,25        "fireRate": 70,26        "mobility": 55,27        "recoilControl": 48,28        "reloadSpeed": 60,29        "concealment": 3030      }31    },32    "verdicts": {33      "damage": "a",34      "accuracy": "b",35      "range": "draw",36      "fireRate": "a",37      "mobility": "b",38      "recoilControl": "b",39      "reloadSpeed": "a",40      "concealment": "b"41    },42    "aWins": 4,43    "bWins": 3,44    "draws": 145  }46}

Auth RequiredBuilder+

client.game.roleRoster()

Get a roster of firearms best suited for a specific game role.

roleRoster(params: RoleRosterParams): Promise<APIResponse<RoleRosterItem[]>>

GET/v1/game/role-roster

Builder+

stringheaderrequired
Your API key. Authorization: Bearer <key> is accepted in its place.

stringrequired
Gameplay role
Accepts
Example
integerdefault5
How many to return
Range
1 – 25
Example

application/json

object[]
The best-scoring firearms for the role, strongest first.
string
Slug of the firearm.
string
Display name, as the maker writes it.
number
Fit for this role, 0 to 100, from the role weighting of the game stats.
object
The editorial game stats, with the game prefix the column carries stripped.
integer | null
Editorial damage rating, 0-100. Not a measured figure.
integer | null
Editorial accuracy rating, 0-100.
integer | null
Editorial range rating, 0-100.
integer | null
Editorial rate-of-fire rating, 0-100.
integer | null
Editorial mobility rating, 0-100.
integer | null
Editorial recoil-control rating, 0-100.
integer | null
Editorial reload-speed rating, 0-100.
integer | null
Editorial concealment rating, 0-100.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Full rate limits

Minimum tier: Builder+
Monthly quota: 25,000/mo
Rate limit: 60/min
Daily cap: 2,000

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.game.roleRoster({6  role: 'sniper',7  count: 10,8});9for (const firearm of data) {10  console.log(firearm.name, firearm.roleScore);11}

1{2  "success": true,3  "data": [4    {5      "id": "m4a1",6      "name": "M4A1",7      "roleScore": 78.2,8      "stats": {9        "damage": 72,10        "accuracy": 64,11        "range": 58,12        "fireRate": 70,13        "mobility": 55,14        "recoilControl": 48,15        "reloadSpeed": 60,16        "concealment": 3017      }18    }19  ]20}

Auth RequiredStudio+

client.game.statDistribution()

Get the statistical distribution for a specific game stat. Shows how firearms are distributed across value ranges for a given stat, useful for understanding the spread and identifying balance issues.

statDistribution(params: StatDistributionParams): Promise<APIResponse<StatDistribution>>

GET/v1/game/stat-distribution

Studio+

stringheaderrequired
Your API key. Authorization: Bearer <key> is accepted in its place.

stringrequired
Which stat to profile
Accepts
Example

application/json

object
The response payload.
string
Which statistic this row is about, named as the field is: weightEmptyG, damage.
integer
How many records fall in this bucket.
number
Arithmetic mean across the records counted.
number
Middle value of the stat across the catalog.
number
Standard deviation across the records counted.
number
Lowest value of the stat across the catalog.
number
Highest value of the stat across the catalog.
object
Percentile cut points for the stat.
number
10th percentile.
number
25th percentile.
number
50th percentile, equal to median.
number
75th percentile.
number
90th percentile.
object[]
Firearm counts across ten fixed bands of width 10, from 0-10 to 90-100.
string
The band this bucket covers, lo-hi. Half-open, so a value equal to hi falls in the next bucket, except 90-100, which includes 100.
integer
How many records fall in this bucket.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Full rate limits

Minimum tier: Studio+
Monthly quota: 150,000/mo
Rate limit: 120/min
Daily cap: 10,000

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.game.statDistribution({ stat: 'damage' });6console.log(data.mean, data.median, data.buckets);

1{2  "success": true,3  "data": {4    "stat": "damage",5    "count": 842,6    "mean": 54.31,7    "median": 55,8    "stdDev": 17.62,9    "min": 8,10    "max": 98,11    "percentiles": {12      "p10": 30,13      "p25": 42,14      "p50": 55,15      "p75": 67,16      "p90": 7817    },18    "histogram": [19      {20        "bucket": "50-60",21        "count": 18422      }23    ]24  }25}

Game

AuthorizationStudio+

Query Parameters

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationBuilder+

Query Parameters

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationBuilder+

Query Parameters

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationBuilder+

Query Parameters

Response200application/json

Errors

Rate limitsFull rate limits

AuthorizationStudio+

Query Parameters

Response200application/json

Errors

Rate limitsFull rate limits

Studio+

application/json

Full rate limits

Builder+

application/json

Full rate limits

Builder+

application/json

Full rate limits

Builder+

application/json

Full rate limits

Studio+

application/json

Full rate limits