@open-rgs/ext-reels 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 open-rgs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# @open-rgs/ext-reels
+
+Reel-spin utilities for open-rgs Lua maths. The reference implementation
+of the [`LuaExtension`](https://github.com/open-rgs/open-rgs/blob/main/packages/contract/src/index.ts)
+contract — use it directly, or copy the shape to ship your own.
+
+## What's in it
+
+- A pure-Lua module (`reels.lua`) that math files `require("reels")` for:
+  `spin`, `spin_column`, `symbol_at`, `count_symbol`, `positions_of`,
+  `line_symbols`.
+- A native helper, `weighted_pick(weights, r)`, for hot paths where
+  iterating a big bucket list in Lua is slower than doing it in TS
+  (mostly relevant inside simulator loops, not normal in-game spins).
+- Lua-language-server annotations in `meta/reels.d.lua` so your editor
+  knows the types on the Lua side.
+
+## Install
+
+```bash
+bun add @open-rgs/ext-reels
+```
+
+## Wire into a game
+
+```ts
+import { loadLuaMath } from "@open-rgs/core";
+import { reels } from "@open-rgs/ext-reels";
+
+const math = await loadLuaMath("./maths/spin.lua", {
+  extensions: [reels],
+});
+```
+
+Then in Lua:
+
+```lua
+local r = require("reels")
+
+local STRIPS = {
+  {"A","K","Q","J","T","S","A","K","S","Q"},
+  {"K","Q","A","S","T","J","S","A","Q","K"},
+  -- …
+}
+
+return {
+  kind = "simple", name = "demo", version = "0.1.0", rtp = 0.95,
+  play = function(prev, ctx)
+    local grid     = r.spin(STRIPS, 3, host.rng_next)
+    local scatters = r.count_symbol(grid, "S")
+
+    local mult = 0
+    if scatters >= 3 then mult = 5 end
+
+    return {
+      multiplier = mult,
+      ops = {
+        { kind = "grid",    cells = grid },
+        { kind = "scatter", count = scatters },
+      },
+      type = mult > 0 and "trigger" or "spin",
+    }
+  end,
+}
+```
+
+## Editor types on the Lua side
+
+Add this to your game's `.luarc.json`:
+
+```json
+{
+  "workspace.library": ["./node_modules/@open-rgs/ext-reels/meta"]
+}
+```
+
+You get completion + type-checking on `r.spin`, `r.count_symbol`, etc.
+
+## Test it
+
+```bash
+bun install
+bun test
+```
+
+The smoke test spins up a real Lua VM, registers the extension, and
+verifies a deterministic grid against a known RNG seed.
+
+## Build your own extension
+
+The shape is two-and-a-half things:
+
+```ts
+import type { LuaExtension } from "@open-rgs/contract";
+
+export const ext: LuaExtension = {
+  name: "your-module",     // require("your-module") in Lua
+  version: "0.1.0",
+  lua: `-- optional pure-Lua source; should return a table
+        local M = {}
+        function M.hello() return "hi" end
+        return M`,
+  host: (vm) => ({
+    // optional TS-backed functions; shadow same-named lua keys
+    fast_thing(x: number) { return x * 2; },
+  }),
+  transform: (src, path) => src,  // optional preprocessor
+};
+```
+
+Then publish under `@your-scope/<name>` and document the require() shape.
+That's it.
+
+## License
+
+MIT.

package/meta/reels.d.lua

@@ -0,0 +1,128 @@
+---@meta
+--
+-- lua-language-server type annotations for @open-rgs/ext-reels.
+-- Add this file's directory to the workspace.library setting in
+-- .luarc.json to get editor completion and type-checking on the
+-- Lua side.
+
+---@alias reels.Symbol string
+---@alias reels.Strip  reels.Symbol[]
+---@alias reels.Grid   reels.Strip[]
+---@alias reels.Pos    integer[]
+---@alias reels.Line   integer[]
+---@alias reels.Rng    fun(): number
+
+---@class reels.LineWin
+---@field symbol     reels.Symbol
+---@field count      integer
+---@field payout     number
+---@field wild_mult  number       multiplier applied from wilds on the line
+
+---@class reels.PaylineWin : reels.LineWin
+---@field line_index integer
+
+---@class reels.PaylinesResult
+---@field total number
+---@field lines reels.PaylineWin[]
+
+---@alias reels.Paytable        table<reels.Symbol, table<integer, number>>
+---@alias reels.ScatterPaytable table<integer, number>
+---@alias reels.WildMultGrid    table<integer, table<integer, number>>
+
+---@class reels
+local M = {}
+
+---Spin a single column. Returns `rows` symbols starting from a uniform
+---random offset, wrapping at the strip end.
+---@param strip reels.Strip
+---@param rows  integer
+---@param rng   reels.Rng
+---@return reels.Strip
+function M.spin_column(strip, rows, rng) end
+
+---Spin a whole reelset.
+---@param strips reels.Strip[]
+---@param rows   integer
+---@param rng    reels.Rng
+---@return reels.Grid
+function M.spin(strips, rows, rng) end
+
+---Get the symbol at a {col, row} position. nil if out of range.
+---@param grid reels.Grid
+---@param pos  reels.Pos
+---@return reels.Symbol?
+function M.symbol_at(grid, pos) end
+
+---Count occurrences of `symbol` across the entire grid.
+---@param grid   reels.Grid
+---@param symbol reels.Symbol
+---@return integer
+function M.count_symbol(grid, symbol) end
+
+---Find every {col, row} where `symbol` appears.
+---@param grid   reels.Grid
+---@param symbol reels.Symbol
+---@return reels.Pos[]
+function M.positions_of(grid, symbol) end
+
+---Read the column-by-column symbols along a payline.
+---@param grid reels.Grid
+---@param line reels.Line  per-column row indices
+---@return reels.Symbol[]
+function M.line_symbols(grid, line) end
+
+---Evaluate ONE payline left-to-right. Wilds substitute for any symbol
+---except scatter; per-position wild multipliers compound across the
+---winning run. Returns nil on no-win.
+---@param symbols    reels.Symbol[]
+---@param paytable   reels.Paytable
+---@param wild_id    reels.Symbol
+---@param scatter_id reels.Symbol
+---@param wild_mults table<integer, number>?
+---@return reels.LineWin?
+function M.eval_payline_left(symbols, paytable, wild_id, scatter_id, wild_mults) end
+
+---Evaluate every payline against the grid, return total + per-line winners.
+---@param grid           reels.Grid
+---@param paylines       reels.Line[]
+---@param paytable       reels.Paytable
+---@param wild_id        reels.Symbol
+---@param scatter_id     reels.Symbol
+---@param wild_mult_grid reels.WildMultGrid?
+---@return reels.PaylinesResult
+function M.eval_paylines(grid, paylines, paytable, wild_id, scatter_id, wild_mult_grid) end
+
+---Book-of mechanic: fill every reel containing `symbol` with `symbol`
+---on all rows. Mutates and returns `grid` for chaining.
+---@param grid   reels.Grid
+---@param symbol reels.Symbol
+---@return reels.Grid
+function M.expand_symbol(grid, symbol) end
+
+---Pick a string key from a name→weight map proportional to weights.
+---@param weights table<string, number>
+---@param rng     reels.Rng
+---@return string?
+function M.pick_weighted_key(weights, rng) end
+
+---Scatter pay lookup. `count` >= the smallest key with a non-zero value triggers.
+---@param count        integer
+---@param scatter_pays reels.ScatterPaytable
+---@return number
+function M.count_scatter_pay(count, scatter_pays) end
+
+---10 classic 5×3 paylines (rows then diagonals then zigzags).
+---@type reels.Line[]
+M.PAYLINES_5x3_10 = {}
+
+---20-line 5×3 set (10 classic + 10 alternating).
+---@type reels.Line[]
+M.PAYLINES_5x3_20 = {}
+
+---Native: pick a 1..#weights index with probability ∝ weights[i]. `r` ∈ [0,1).
+---@param weights number[]
+---@param r       number
+---@return integer
+function M.weighted_pick(weights, r) end
+
+return M

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@open-rgs/ext-reels",
+  "version": "0.2.0",
+  "description": "Reel-spin utilities for open-rgs Lua maths. Reference LuaExtension implementation.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-rgs/ext-reels.git"
+  },
+  "homepage": "https://github.com/open-rgs/ext-reels",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": ["src", "meta", "README.md"],
+  "keywords": ["open-rgs", "lua-extension", "rgs", "slot", "reels"],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "@open-rgs/contract": "^0.3.0"
+  },
+  "devDependencies": {
+    "@open-rgs/contract": "^0.3.0",
+    "@open-rgs/core":     "^0.5.0",
+    "@types/bun": "latest",
+    "typescript": "^5.4.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+// @open-rgs/ext-reels
+//
+// Reference LuaExtension for open-rgs. Adds a `reels` module the math
+// can `require("reels")` to get reel-spin utilities.
+//
+// Two parts:
+//   • A pure-Lua module (src/reels.lua) with spin / symbol_at / count /
+//     positions_of / line_symbols. Editor-friendly via meta/reels.d.lua.
+//   • A native helper (weighted_pick) for cases where Lua iteration is
+//     slow enough to matter — e.g. running an exhaustive RTP simulator.
+//
+// Wiring (in the integrator's boot file):
+//
+//   import { reels } from "@open-rgs/ext-reels";
+//   const math = await loadLuaMath("./maths/spin.lua", {
+//     extensions: [reels],
+//   });
+//
+// Lua-side usage:
+//
+//   local r = require("reels")
+//   local grid = r.spin(STRIPS, 3, host.rng_next)
+//   local scatters = r.count_symbol(grid, "S")
+
+import type { LuaExtension } from "@open-rgs/contract";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const luaSource = readFileSync(join(here, "reels.lua"), "utf-8");
+
+export const reels: LuaExtension = {
+  name: "reels",
+  version: "0.1.0",
+  lua: luaSource,
+  host: () => ({
+    /** Pick an index 1..weights.length with probability proportional
+     *  to each weight. `r` ∈ [0, 1) selects the slot.
+     *
+     *  Faster than the equivalent Lua loop for big buckets — useful
+     *  inside hot simulator loops; for normal in-game spins the Lua
+     *  side is fine. */
+    weighted_pick(weights: readonly number[], r: number): number {
+      let total = 0;
+      for (const w of weights) total += w;
+      if (total <= 0) return 1;
+      const target = r * total;
+      let acc = 0;
+      for (let i = 0; i < weights.length; i++) {
+        acc += weights[i]!;
+        if (target < acc) return i + 1; // 1-indexed for Lua
+      }
+      return weights.length;
+    },
+  }),
+};
+
+export default reels;

package/src/reels.lua

@@ -0,0 +1,280 @@
+-- @open-rgs/ext-reels — reel-spin utilities for open-rgs Lua maths.
+--
+-- Conventions:
+--   • Strips are column-major: strips[col][index] (1-indexed)
+--   • Grids are column-major: grid[col][row]      (1-indexed)
+--   • Positions are { col, row }
+--   • Symbols are strings; nothing else is opaque
+--   • Paylines are arrays of row indices (one per column)
+
+local M = {}
+
+-- ─── Spin primitives ───────────────────────────────────────────────────
+
+-- Spin one column: pick a starting offset uniformly, return `rows` symbols
+-- starting at that offset (wrapping the strip end → start). `rng` is a
+-- function returning a float in [0, 1).
+function M.spin_column(strip, rows, rng)
+  local n = #strip
+  local start = math.floor(rng() * n)
+  local out = {}
+  for r = 1, rows do
+    out[r] = strip[((start + r - 1) % n) + 1]
+  end
+  return out
+end
+
+-- Spin a whole reelset. `strips` is the per-column strip table.
+function M.spin(strips, rows, rng)
+  local cols = #strips
+  local grid = {}
+  for c = 1, cols do
+    grid[c] = M.spin_column(strips[c], rows, rng)
+  end
+  return grid
+end
+
+-- ─── Grid lookups ──────────────────────────────────────────────────────
+
+-- Lookup the symbol at a {col, row} position. Returns nil if out of range.
+function M.symbol_at(grid, pos)
+  local col = grid[pos[1]]
+  if not col then return nil end
+  return col[pos[2]]
+end
+
+-- Count how many times `symbol` appears across the whole grid.
+function M.count_symbol(grid, symbol)
+  local n = 0
+  for c = 1, #grid do
+    local col = grid[c]
+    for r = 1, #col do
+      if col[r] == symbol then n = n + 1 end
+    end
+  end
+  return n
+end
+
+-- Find every {col, row} position where `symbol` appears.
+function M.positions_of(grid, symbol)
+  local out = {}
+  for c = 1, #grid do
+    local col = grid[c]
+    for r = 1, #col do
+      if col[r] == symbol then
+        out[#out + 1] = { c, r }
+      end
+    end
+  end
+  return out
+end
+
+-- Read the symbols along a payline. `line` is a per-column row index.
+-- Returns the list of symbols column-by-column.
+function M.line_symbols(grid, line)
+  local out = {}
+  for c = 1, #line do
+    out[c] = grid[c][line[c]]
+  end
+  return out
+end
+
+-- ─── Payline evaluation ───────────────────────────────────────────────
+
+-- Evaluate ONE payline left-to-right.
+--
+-- A "win" is the longest prefix of matching symbols starting from the
+-- leftmost reel. Wilds substitute for any symbol except scatter. If the
+-- entire prefix is wilds, the run is treated as "wild" itself (paid
+-- via paytable[wild_id] if present, otherwise no pay).
+--
+-- Per-position wild multipliers compound on the winning run only.
+--
+-- Args:
+--   symbols    : array of symbols along the line (one per column)
+--   paytable   : { [symbol] = { [count] = mult, ... }, ... }
+--                count is the number of matching symbols starting at left.
+--   wild_id    : symbol id that substitutes for non-scatter symbols
+--   scatter_id : symbol id that NEVER substitutes (skip from line pays)
+--   wild_mults : optional { [col_index] = mult } — multiplier carried by
+--                the wild at that position. Compounds across all wilds
+--                that participate in the winning run.
+--
+-- Returns: { symbol, count, payout, wild_mult } or nil on no-win.
+function M.eval_payline_left(symbols, paytable, wild_id, scatter_id, wild_mults)
+  local n = #symbols
+  if n == 0 then return nil end
+
+  -- Anchor: first non-wild symbol from the left. If everything is wild,
+  -- anchor is the wild itself (so the wild's own paytable entry, if any,
+  -- determines the prize for an all-wild line).
+  local anchor
+  for i = 1, n do
+    if symbols[i] ~= wild_id then
+      anchor = symbols[i]
+      break
+    end
+  end
+  if anchor == nil then anchor = wild_id end
+
+  -- Scatters never pay by line — only by count.
+  if anchor == scatter_id then return nil end
+
+  -- Walk the prefix: count {anchor, wild} matches, compound wild mult.
+  local run_count = 0
+  local wild_mult = 1
+  for i = 1, n do
+    local s = symbols[i]
+    if s == anchor or s == wild_id then
+      run_count = run_count + 1
+      if s == wild_id and wild_mults and wild_mults[i] and wild_mults[i] > 0 then
+        wild_mult = wild_mult * wild_mults[i]
+      end
+    else
+      break
+    end
+  end
+
+  local pt = paytable[anchor]
+  if not pt then return nil end
+  local base = pt[run_count] or 0
+  if base == 0 then return nil end
+
+  return {
+    symbol    = anchor,
+    count     = run_count,
+    payout    = base * wild_mult,
+    wild_mult = wild_mult,
+  }
+end
+
+-- Evaluate every payline against `grid`. Returns the total payout (sum
+-- of all line wins) and a per-line breakdown of every winning line.
+--
+-- `wild_mult_grid` is OPTIONAL: { [col] = { [row] = mult } }. Lets the
+-- math attach a multiplier to specific wild landings on the grid, which
+-- the per-line evaluator picks up when a wild participates in a winning
+-- run. Pass nil if your wilds carry no multiplier.
+function M.eval_paylines(grid, paylines, paytable, wild_id, scatter_id, wild_mult_grid)
+  local total = 0
+  local lines = {}
+  for li = 1, #paylines do
+    local line = paylines[li]
+    local row_syms = {}
+    local row_mults
+    for c = 1, #line do
+      row_syms[c] = grid[c][line[c]]
+      if wild_mult_grid and wild_mult_grid[c] then
+        local m = wild_mult_grid[c][line[c]]
+        if m and m > 0 then
+          row_mults = row_mults or {}
+          row_mults[c] = m
+        end
+      end
+    end
+    local r = M.eval_payline_left(row_syms, paytable, wild_id, scatter_id, row_mults)
+    if r then
+      total = total + r.payout
+      lines[#lines + 1] = {
+        line_index = li,
+        symbol     = r.symbol,
+        count      = r.count,
+        payout     = r.payout,
+        wild_mult  = r.wild_mult,
+      }
+    end
+  end
+  return { total = total, lines = lines }
+end
+
+-- ─── Book-of mechanic ─────────────────────────────────────────────────
+
+-- Expand a symbol across every column that contains it: any reel with
+-- at least one landing of `symbol` is filled with `symbol` on all rows.
+-- Mutates AND returns the grid for chaining convenience.
+function M.expand_symbol(grid, symbol)
+  for c = 1, #grid do
+    local col = grid[c]
+    local has = false
+    for r = 1, #col do
+      if col[r] == symbol then has = true; break end
+    end
+    if has then
+      for r = 1, #col do
+        col[r] = symbol
+      end
+    end
+  end
+  return grid
+end
+
+-- ─── Weighted picking ─────────────────────────────────────────────────
+
+-- Pick a string key from a name→weight map proportional to weights.
+-- Iteration order of pairs() is implementation-defined; for repeatable
+-- results across runs, sort the keys upstream and call weighted_pick.
+function M.pick_weighted_key(weights, rng)
+  local total = 0
+  for _, w in pairs(weights) do total = total + w end
+  if total <= 0 then return nil end
+  local target = rng() * total
+  local acc = 0
+  local last_k
+  for k, w in pairs(weights) do
+    last_k = k
+    acc = acc + w
+    if target < acc then return k end
+  end
+  return last_k
+end
+
+-- ─── Scatter pay lookup ───────────────────────────────────────────────
+
+-- Tiny helper kept here for parity with line evaluator: scatters pay
+-- by count (3+ usually), independent of position.
+function M.count_scatter_pay(count, scatter_pays)
+  return scatter_pays[count] or 0
+end
+
+-- ─── Standard payline shapes ──────────────────────────────────────────
+
+-- 10 classic paylines for a 5×3 grid. Row 1 = top.
+-- Order matches industry convention (rows first, then diagonals, zigzags).
+M.PAYLINES_5x3_10 = {
+  { 2, 2, 2, 2, 2 },  -- 1: middle row
+  { 1, 1, 1, 1, 1 },  -- 2: top row
+  { 3, 3, 3, 3, 3 },  -- 3: bottom row
+  { 1, 2, 3, 2, 1 },  -- 4: V down-up
+  { 3, 2, 1, 2, 3 },  -- 5: V up-down
+  { 1, 1, 2, 3, 3 },  -- 6: top→bottom diag
+  { 3, 3, 2, 1, 1 },  -- 7: bottom→top diag
+  { 2, 1, 1, 1, 2 },  -- 8: middle, top hump
+  { 2, 3, 3, 3, 2 },  -- 9: middle, bottom hump
+  { 1, 2, 1, 2, 1 },  -- 10: zigzag top
+}
+
+-- 20-line set (10 above + 10 more).
+M.PAYLINES_5x3_20 = {
+  { 2, 2, 2, 2, 2 },
+  { 1, 1, 1, 1, 1 },
+  { 3, 3, 3, 3, 3 },
+  { 1, 2, 3, 2, 1 },
+  { 3, 2, 1, 2, 3 },
+  { 1, 1, 2, 3, 3 },
+  { 3, 3, 2, 1, 1 },
+  { 2, 1, 1, 1, 2 },
+  { 2, 3, 3, 3, 2 },
+  { 1, 2, 1, 2, 1 },
+  { 3, 2, 3, 2, 3 },
+  { 2, 1, 2, 1, 2 },
+  { 2, 3, 2, 3, 2 },
+  { 1, 1, 2, 1, 1 },
+  { 3, 3, 2, 3, 3 },
+  { 2, 2, 1, 2, 2 },
+  { 2, 2, 3, 2, 2 },
+  { 1, 2, 2, 2, 1 },
+  { 3, 2, 2, 2, 3 },
+  { 1, 3, 1, 3, 1 },
+}
+
+return M