Reason Me This

Overview

What Reason Me This is, the pieces it comes in, and the ideas every guide builds on.

After reading this guide, you will know:

  • What kind of problem Reason Me This is for.
  • What facts, steps, formulas and results are.
  • What the pieces are, and how to get each one.
  • Where to go next.

What it is for

Reason Me This is for rules that are more than a formula: game rules, pricing, eligibility, scoring, scheduling, anything written down as clauses and tables.

Facts go in, named steps run in order, and every result keeps a trace of how each value was reached. Rules, rates and tables are data you can edit; the mechanics that apply them are code.

The leading example is Call of Cthulhu 7th edition: skill checks, sanity, fights and chases written as blueprints from the Keeper Rulebook. Two more show other ground: an electricity bill priced by time-of-use window, and a sales commission plan with tiers, a cap, clawbacks and a recoverable draw.

The ideas

  • Facts are the inputs to a calculation.
  • Steps run in order. Each one can use the facts and any earlier step by name, and returns a value plus a detail that goes into the trace.
  • Formulas and conditions are spreadsheet-style expressions: the small, editable decisions inside a step.
  • Results hold every value and the trace.

The rule that keeps the design honest: mechanics are code, rules and tables are data, small decisions are formulas.

Numbers are exact. Decimals load as BigDecimal, ROUND(x, 2) rounds half up, and the CLI prints every number as an exact string.

What is in the box

Piece Get it with What it is
The service https://reason-me-this.com Workspaces of definitions: drafts, numbered versions and a JSON API
rmt gem install reason_me_this The CLI an agent or a person uses to check, test, push, publish and run blueprints
Ruby client require 'reason_me_this' ReasonMeThis.run from any Ruby app, and a reasons macro for models
The engine licensed on request Runs blueprints in your own process, with Studio and packs. See Licensed Engine

Two ways to write a calculation

As a blueprint, in YAML:

calculations:
  sanity_check:
    inputs:
      sanity: {type: number}
      san_roll: {type: number}
      success_loss: {type: number}
      failure_loss: {type: number}
    steps:
      - name: loss
        rules:
          pick: first
          rules:
            - {name: kept_their_nerve, when: san_roll <= sanity, value: success_loss}
            - {name: lost_their_nerve, when: true, value: failure_loss}
      - {name: sanity_after, formula: 'MAX(0, sanity - loss)'}
    outputs: [loss, sanity_after]

These guides use blueprints, because a blueprint can be checked, tested and published without anyone writing Ruby. With the licensed engine, the same calculation can also be written in Ruby (see Calculations in Ruby).

The hosted service

The same blueprints run on the hosted service at https://reason-me-this.com, where a workspace publishes numbered versions that applications call over a JSON API. The CLI drives it with the commands and exit codes it uses locally. See The Hosted Service.

Next Steps