Big Numbers API
Handle exponential economies without losing precision. The Big Numbers API wraps break_eternity and exposes helpers for normalization, formatting, and progression math tuned for idle or incremental games.
Quick Start
import RundotGameAPI from '@series-inc/rundot-game-sdk/api'
const numbers = RundotGameAPI.numbers
const currency = numbers.normalize('BE:1.23e9')
const display = numbers.format.incremental(currency) // "1.23B"Type Checking
numbers.isBigNumber(value): boolean
// Check if a value is a big number
const isBig = numbers.isBigNumber(someValue)isBigNumber returns true for exactly three kinds of value:
Input
Returns true when
string
it starts with the BE: prefix (for example 'BE:1.23e9')
Decimal
it is a Decimal instance (from numbers.normalize or new numbers.Decimal(...))
number
it is a plain JS number outside the safe-integer range (> Number.MAX_SAFE_INTEGER or < Number.MIN_SAFE_INTEGER)
Every other value (a small plain number, a non-BE: string, null, undefined, objects) returns false.
numbers.normalize(value): Decimal
Converts any input into a Decimal instance. This is the canonical way to undo the BE: persistence prefix recommended in Best Practices.
Decimal
returned unchanged (no copy)
BE:-prefixed string
the first 3 characters are stripped, then the remainder is parsed with new Decimal(...) (for example 'BE:1.23e9' becomes Decimal(1.23e9))
any other string or number
passed straight to new Decimal(value)
Progression Math
Geometric Series Costs
calculateGeometricSeriesCost(baseCost, multiplier, currentQuantity, purchaseAmount) computes the total cost of buying purchaseAmount upgrades, starting from currentQuantity already owned. It returns a Decimal instance, so feed the result into format.incremental / formatDecimalCurrency for display, or compare it with .lt / .gt / .lte.
It uses the closed-form geometric series a * (r^n - 1) / (r - 1), where a = baseCost * r^currentQuantity. When multiplier is exactly 1, it short-circuits to the linear case baseCost * purchaseAmount (avoiding a divide-by-zero), so a flat-cost upgrade still works.
Max Affordable
calculateMaxAffordableDecimal(availableCash, baseCost, multiplier, currentQuantity) returns how many upgrades a player can buy with their current currency. It returns a plain number.
Two bounds to know:
Returns
0when the player cannot afford even a single upgrade.The affordability search is capped at a safety limit of
1,000,000, so the largest value it can ever return is on the order of1,000,000, even if more would technically be affordable. Size single purchase batches accordingly.
If the Decimal calculation throws, it logs a [RUN] console.error and falls back to Math.floor(Number(availableCash) / Number(baseCost)).
Direct Decimal Usage
Access the underlying class for custom math:
numbers.Decimal is the break_eternity.js Decimal class, so instances expose that library's full surface: arithmetic (times / mul, div, sub, pow), comparisons (lt, gt, lte, eq), log10, and formatters (toFixed, toExponential). Decimal.pow(...) is also available as a static. Refer to the break_eternity.js docs for the complete method list.
Display Formatting
numbers.format.incremental(value): string
Format a big-number or Decimal value for display with an abbreviated suffix. The output depends on the magnitude:
< 1000
plain integer string, toFixed(0) (any fractional part is dropped)
999 -> "999"
1000 up to the largest suffix
value divided down, then toFixed(2) plus the suffix
1.23e9 -> "1.23B"
above the largest suffix (Dc, 1e33); exponential begins around 1e36
2-digit exponential notation
1e40 -> "1e40"
The full suffix set, each step 1000x larger than the last:
K (1e3), M (1e6), B (1e9), T (1e12), Qa (1e15), Qi (1e18), Sx (1e21), Sp (1e24), Oc (1e27), No (1e30), Dc (1e33).
Currency Formatting
numbers.formatDecimalCurrency(decimalValue): string
Format a big-number or Decimal value as a currency string with a leading $. This wraps numbers.format.incremental, so it uses the same abbreviated suffixes (K, M, B, and so on) and falls back to Number(...).toLocaleString() if formatting fails.
decimalValue
Decimal | number
The value to format. Pass a Decimal (for example from numbers.normalize) or a plain number. BE:-prefixed strings must be run through numbers.normalize() first; formatDecimalCurrency does not strip the BE: prefix itself, so passing one directly mis-parses.
Returns a string, for example "$1.23B".
API Reference
numbers.isBigNumber(value)
boolean
true for a BE: string, a Decimal, or a number outside the safe-integer range
numbers.normalize(value)
Decimal
Convert string/number to a Decimal instance (strips the BE: prefix; passes a Decimal through unchanged)
numbers.format.incremental(value)
string
Format for display: integer below 1000, 2-decimal suffix up to Dc, exponential above
numbers.calculateGeometricSeriesCost(base, mult, level, qty)
Decimal
Total cost for upgrades (linear when mult === 1; native-math number on fallback)
numbers.calculateMaxAffordableDecimal(cash, base, mult, level)
number
Max purchasable quantity (0 if none affordable; capped at ~1,000,000)
numbers.formatDecimalCurrency(value)
string
Format a big number as a currency string (e.g. "$1.23B")
numbers.Decimal
class
Direct access to the break_eternity.js Decimal class
Best Practices
Store values as strings (e.g.,
BE:prefix) when persisting to avoid JSON precision issues.Normalize before performing comparisons so you're always working with Decimal instances.
Keep formatting on the client; send raw numbers to your backend for canonical calculations.
When storing big numbers, use
RundotGameAPI.appStoragewith string serialization.
Last updated