Spinative docs · Math & GDD

Math & GDD

Math & GDD

The math pillar covers everything quantitative about your slot: paytable, RTP target, volatility, reels, paylines, bet range, max win, hit frequency. It's also the layer most slot creators don't *input* directly — most of it gets parsed in from a GDD upload or inferred from your feature configuration, and the workspace surfaces fields to refine, not build from scratch.

This chapter covers three things: how to get a math model into a project, what lives where, and what comes out at handoff.

Getting math into a project

Three paths in:

1. Parse from a GDD upload

The fastest path. From the project creation flow (or from Game design → Import GDD), upload a PDF, DOCX, MD or TXT file containing your existing GDD or art brief.

The parser:

  • Extracts text via mammoth (DOCX) or pdf-parse (PDF) — up to 40,000 characters.
  • Runs it through a vision-capable language model with a structured-extraction prompt hardened against prompt-injection (untrusted-input wrappers, authority neutralisation).
  • Returns a GDDFields object that maps 1-to-1 onto Project Settings field IDs.

The fields extracted:

GroupFields
Game identitygameName, theme
Theme / art directionsetting, story, mood, bonusNarrative, artStyle, artRef, artNotes
Reelsreelset (e.g. "5x3", "6x4")
Mechanicsrtp, volatility, paylines
JackpotsjackpotMini, jackpotMinor, jackpotMajor, jackpotGrand
Featuresarray of feature keys to enable
SymbolssymbolHighCount, symbolLowCount, symbolSpecialCount, plus per-symbol name arrays

The parser populates the Game design tab and toggles the right features in the Features tab. Review and refine; the parse won't be 100% correct but it's the right shape.

2. Configure via Features + Project

The manual path. Set the reelset in Game design, toggle the features you need in Features and configure each one's knobs (Free Spins → spins awarded, multiplier; Cascade → fall direction, win multiplier; Megaways → max ways; etc.).

Spinative derives the math model from this configuration. You won't get a tuned RTP target this way — that's a math-team responsibility — but you'll get a coherent feature spec that the math team can build on.

3. Import a pre-existing math model

If your math team has authored the model elsewhere (a real RTP simulator, an Excel spec, a JSON payload), they can drop it straight into the project payload's math field via the project JSON backup / restore flow. The structure expected:

math: {
  rtpTarget:   number          // e.g. 96.1
  volatility:  string          // "Low" | "Medium" | "High" | "Very High"
  bet:         { min, max, steps }
  maxWin:      number
  reelStrips:  string[][]      // per-reel symbol key strips
  paylines:    number[][]      // each path is row indices per reel
  symbols:     [{ key, label, kind, pays }, …]
  features:    { freeSpins?, bonus?, wilds?, … }
}

This is the wire format the math_json export emits, so round-tripping a math model in and out of Spinative is symmetric.

What lives where

SurfaceWhat you set there
Game design tabReelset, theme, palette, narrative, symbol counts, symbol names, jackpot amounts, character/ante toggles
Features tabWhich mechanics are on, with their configured values (spins awarded, multiplier, gamble type, etc.)
Logic tabThe qualitative flow — which screens connect, what triggers each transition
Math model (payload.math)Quantitative spec: RTP, volatility, bet range, reel strips, paylines, paytable, symbol pays

The first three are authored in the UI. The math model is either imported or built from the first three. The handoff exports merge all four into coherent deliverables.

The math handoff exports

Three exports specifically for the math/build team:

Math spec (math_json)

A single JSON document with the canonical math model. Stable wire format independent of our internal payload shape — what a math team or certification lab needs to run a real RTP simulator and run regulatory checks.

Free, no credits. Always available.

Logic spec (logic_md)

Auto-derived from the math model. Structured Markdown — no LLM, no hand-written prose, just facts. Sections include:

  1. Spin resolution order — stop selection, payline evaluation, wild substitution order.
  2. Wild substitution rules — which symbols wilds substitute for.
  3. Scatter / bonus trigger conditions.
  4. Feature payouts.
  5. Paytable references.

This is what game engineers want: an unambiguous spec of how a spin resolves into payouts.

Free, no credits.

Game Design Document (gdd_pdf)

The polished version — multi-page PDF with cover, theme, math, symbols, screens and asset inventory. AI-polished prose runs over the auto-extracted facts to produce something a stakeholder can read end-to-end.

5 credits. Plan-gated to write permission on the project.

You'll want to render this at least once mid-project (so stakeholders have something to react to) and once at handoff (so the final spec lands clean).

RTP, volatility, and what Spinative does *not* compute

Spinative is not a math engine. It does not:

  • Compute RTP from your reel strips and paytable.
  • Simulate spins to verify hit frequency.
  • Run certification-grade variance analysis.
  • Iterate paytable values to hit a target RTP.

What it *does* hold is the authored values — the RTP the math team has signed off on, the volatility band they've committed to, the bet range, the max-win cap. These travel with the project as metadata so every export and PDF references the same numbers.

If you're in an in-house team with a math department, your workflow is: math model authored externally → imported into Spinative → handoff bundle includes the model alongside the art + design + flow.

If you're indie or a freelancer without a math team, you can still ship a coherent design spec (theme + features + symbol counts + reels) and pair it with an external service for the math model.

The Art Direction Document (add_pdf)

Worth mentioning here because it ships alongside the GDD as a stakeholder deliverable.

The ADD is a polished PDF style guide: palette swatches, references, asset specs, per-asset prompt summaries. AI-polished prose, 5 credits, plan-gated.

Use it when you need a printed-format art bible to send to external illustrators, marketing partners, or as a leave-behind in client meetings.

Project Health and math readiness

The Project Health pill (topbar) counts math-related items in its "open items" tally:

  • Missing reelset
  • Missing RTP target
  • Missing symbol counts
  • Empty paytable when features are configured

Click the pill, scan the math section, deep-link to the offending field. The pill turns green when every section — Game design, Features, Art, Math — passes its readiness checks.

Future math features

Out of scope for today, tracked for the roadmap:

  • In-app RTP simulator. Spin 10k / 100k / 1M times against the reel strips and report empirical RTP + hit frequency.
  • Paytable solver. Given target RTP, suggest paytable values that hit it.
  • Variance analyser. Volatility bands from simulation runs.

If you need any of these today, see the Future math features section on the Troubleshooting page for which third-party tools the design team most often pairs Spinative with.

Open questions

Some math-pillar details are intentionally underspecified because the codebase doesn't fully wire them yet:

  • Reel-strip authoring UI. Strips are imported from external math models today; no in-product authoring view ships yet.
  • Paytable editor UI. Symbol pays are present in the math payload structure; the in-product editor for them is not feature-complete in the current release.

Both will follow as the math pillar matures. The handoff exports already understand the wire format, so an externally-authored math model travels through the system cleanly today.

Built for slot creators · Assisted by AI · Try Spinative free →