For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Input
Behavior

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 0 when 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 of 1,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:

Magnitude
Output
Example

< 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).

Suffixed output is fixed at 2 decimal places ("1.23B", "5.00M"); the precision is not configurable. Once a value passes Dc the formatter switches to exponential notation rather than inventing new suffixes. formatDecimalCurrency wraps this method, so it inherits the same suffix table, 2-decimal precision, and exponential ceiling.

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.

Parameter
Type
Description

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

Method
Returns
Description

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.appStorage with string serialization.

Last updated