phaserjs/phaser · error · Error

invalid random() format

Error message

invalid random() format

What it means

Thrown by Phaser.Tweens.Builders.GetValueOp when a tween property value is a string starting with 'random' or 'int' but the parenthesis/comma syntax is malformed. The parser requires all three of '(', ')', and ',' to be present (via indexOf truthiness) to split the two numeric bounds. If any delimiter is missing, or if the indexOf check returns a falsy value, Phaser cannot build the getEnd function and aborts. The valid forms are `random(min, max)` for a float and `int(min, max)` for an integer.

Source

Thrown at src/tweens/builders/GetValueOp.js:159

                if (isRandom)
                {
                    getEnd = function ()
                    {
                        return FloatBetween(value1, value2);
                    };
                }
                else
                {
                    getEnd = function ()
                    {
                        return Between(value1, value2);
                    };
                }
            }
            else
            {
                throw new Error('invalid random() format');
            }
        }
        else
        {
            op = op[0];
            var num = parseFloat(propertyValue.substr(2));

            switch (op)
            {
                case '+':
                    getEnd = function (target, key, value)
                    {
                        return value + num;
                    };
                    break;

                case '-':
                    getEnd = function (target, key, value)

View on GitHub (pinned to 41be1e462b)

Solutions

1. Use the exact form: 'random(min, max)' or 'int(min, max)' with ASCII comma and parentheses, no spaces inside required but both delimiters mandatory.
2. If the bounds are dynamic, prefer a function: props: { x: (target, key, value) => Phaser.Math.FloatBetween(min, max) } which avoids string parsing entirely.
3. Sanitize/normalize the string before passing it: replace smart quotes and full-width commas with ASCII equivalents.
4. Log the offending propertyValue right before the tween to confirm its exact characters.

Example fix

// before
this.tweens.add({ targets: sprite, x: 'random(10 100)', duration: 1000 });

// after
this.tweens.add({ targets: sprite, x: 'random(10, 100)', duration: 1000 });
// or, safer with dynamic values:
this.tweens.add({ targets: sprite, x: () => Phaser.Math.FloatBetween(10, 100), duration: 1000 });

function isValidRandomString(str) {
  if (typeof str !== 'string') return true; // not a random string at all
  var lower = str.toLowerCase();
  if (!(lower.startsWith('random') || lower.startsWith('int'))) return true;
  return lower.indexOf('(') > 0 && lower.indexOf(')') > 0 && lower.indexOf(',') > 0;
}

function isTweenableValue(v) {
  if (typeof v === 'number' || typeof v === 'function') return true;
  if (Array.isArray(v)) return true;
  if (typeof v === 'string') {
    var op = v.toLowerCase();
    if (op.startsWith('random') || op.startsWith('int')) {
      return op.indexOf('(') > 0 && op.indexOf(')') > 0 && op.indexOf(',') > 0;
    }
    return ['+=', '-=', '*=', '/='].some(function (p) { return op.startsWith(p); });
  }
  return false;
}

try {
  this.tweens.add({ targets: obj, props: { x: raw }, duration: 1000 });
} catch (e) {
  if (e.message === 'invalid random() format') {
    this.tweens.add({ targets: obj, props: { x: () => Phaser.Math.FloatBetween(10, 100) }, duration: 1000 });
  } else { throw e; }
}

When it happens

Trigger: Passing props like `{ x: 'random(10,100)' }` works, but `{ x: 'random(10 100)' }` (missing comma), `{ x: 'random 10, 100' }` (missing parens), `{ x: 'int(10)' }` (missing comma), or `{ x: 'random(10,100' }` (missing close paren) all throw. Also triggered by typos such as `radom(...)` that happen to still start with the checked prefix in a future revision, or non-ASCII punctuation (full-width comma/parens) copied from rich text.

Common situations: Authoring tween props in a data file or editor that strips/normalizes punctuation. Copy-pasting example strings from a blog that uses smart quotes or en-dashes. Localizing a config where a translator replaced the comma. Using a template literal that injects undefined for one bound: `\`random(${min},${max})\`` with min/max undefined still parses but a missing template expression can drop the comma.

Related errors

• TextureManager.SpriteSheet: Invalid frameWidth given.
• TextureManager.SpriteSheetFromAtlas: Invalid frameWidth give

AI-assisted analysis of phaserjs/phaser@41be1e462b (2026-08-13). Data as JSON: /api/errors/6446a2bfe75defda. Report an issue: GitHub.