@hizi.io/engine-generator

TypeScript library for slot engine developers to write bet results as brotli-compressed JSONL files in the format the hizi engine runtime consumes. Runs in Node.js (writes to disk) and in the browser (writes to OPFS).

Install

npm install @hizi.io/engine-generator

Available on npm: https://www.npmjs.com/package/@hizi.io/engine-generator

Quick start

import { HiziEngineGenerator } from '@hizi.io/engine-generator';

const generator = new HiziEngineGenerator();
await generator.start('./output/');

for (let i = 0; i < 1_000_000; i++) {
  const spin = simulateSpin();
  generator.addResult(
    { reels: spin.reelPositions, symbols: spin.visibleSymbols },
    { win: spin.winAmount, metaTags: spin.winAmount === 0 ? ['no-win'] : [] },
  );
}

await generator.end({ config: { gameCode: 'my-slot' } });
// Output: entries.jsonl.br, scenarios.jsonl.br, config.json

Highlights

• Streaming output — entries and scenarios are written as you go, then brotli-compressed on end()
• Automatic entry merging — results with the same win, metaTags, and featureAwards collapse into one entry with accumulating weight
• Scenario limiting — configurable cap per entry (maxScenariosPerEntry, default 1000)
• Buy-feature support — resolve from entry metaTags via entrypool and stakeboost strategies
• Node and browser — auto-detects between fs and OPFS

Common patterns

Multi-step scenarios

generator.addResult(
  [
    { reels: spin1, sticky: [] },
    { reels: spin2, sticky: [[0, 1]] },
  ],
  { win: totalWin },
);

Multiple features

All features write to the same output directory, distinguished by the feature option:

generator.addResult(baseScenario, { win, metaTags, featureAwards });
generator.addResult(freespinScenario, { feature: 'freespin', win, metaTags });

Free-spin trigger

generator.addResult(scenario, {
  win: 0,
  metaTags: ['freespin-trigger'],
  featureAwards: {
    type: 'randomChoice',
    awards: [{ count: 10, feature: 'freespin' }],
  },
});

API surface

| Method | Purpose | | ---------------------------------------------------------------------- | -------------------------------------------------------- | | new HiziEngineGenerator({ maxScenariosPerEntry? }) | Create a generator | | start(outputDirectory) | Open the output directory and begin streaming | | addResult(scenario, options) | Record a result; merges with matching entries | | buildBuyFeatures(definitions) | Resolve buy-feature definitions from current entries | | end({ config?, buyFeatures?, buyFeatureDefinitions? }) | Finalize: write entries, compress to .br, write config | | dbEntryCount | Unique entry count (read before end()) | | featureTotalWeights | Feature → totalWeight map (after end()) | | HiziEngineGenerator.loadEntries(entriesJsonl, scenariosJsonl, feat?) | Static: load all entries with scenarios | | HiziEngineGenerator.loadEntryMetadata(entriesJsonl, feat?) | Static: load entry metadata without scenarios |

Build

npm install
npm run build   # tsc → lib/

Development

npm run dev         # tsc --watch
npm run lint
npm run lint:fix

License

ISC