Useful at the table. Quite a lot going on underneath.

There is not one set of Mahjong rules. Different traditions score differently. Clubs have their own conventions. Similar-looking hands can mean different things. The same idea can have different names, and occasionally two perfectly respectable sources disagree.

That makes a universal “Mahjong calculator” rather more interesting than it first appears.

So Mahjong Reference does not try to squash everything into one giant set of switches. Where rules genuinely share something, the system can share it. Where they are different, they stay different.

Use the rules your table actually plays, from the profiles currently supported.

A hand has a rules context. It has evidence: the tiles, how the hand was won, the Winds, exposure and whatever else matters under those rules.

Then there is the score. Then settlement: who actually pays whom. Then progression: who is East, what Wind comes next, whether the game continues.

Those things are connected, but they are not the same thing.

Keeping them separate makes the thing on screen simpler — and gives the system somewhere sensible to grow when another ruleset does something completely different.

There is a short walkthrough of the table companion if you want to see it in use.

I don't particularly like software producing a number and expecting you to believe it.

The longer-term idea behind Mahjong Reference is fairly simple: keep the rules, the source and the result connected.

If the system knows something, it should be possible to see why. If two rulesets differ, that difference should survive. If a source is unclear, the software should not quietly make the uncertainty disappear.

And if I have misunderstood something, I would much rather make that easy to find and correct than confidently bake it into everything else.

There is considerably more machinery behind that idea than I expected. You can look under the hood if that sort of thing interests you.

The useful bit of having all this underneath is that Mahjong Reference does not have to remain the thing it is today.

A new ruleset does not necessarily need a new app. A different scoring system does not have to pretend to be British Mahjong with different numbers. A reference page, worked example, comparison or future table tool should not need its own private copy of the rules.

The aim is to establish things once, keep their context attached, and then use them wherever they are useful.

That leaves quite a lot of room: more rules, different scoring systems, local ways of playing, better explanations, deeper reference material and things I have not thought of yet.

Not everything is implemented, and not every kind of Mahjong will fit neatly into the same shape. That is rather the point.

I joined some friends for a game of Mahjong without our usual expert helper.

Then we got to scoring.

We could all do the maths. Remembering all the rules, exceptions and what happened next was the difficult bit. So I wondered whether I could make something that helped.

I thought I was building a calculator. Apparently not.

I am learning Mahjong as I build this.

What I am quite good at is taking something complicated, pulling it apart until I understand how the pieces relate, and putting it back together in a way that is easier to use.

Here, that means checking sources, keeping different rules separate, testing what the software actually does and leaving uncertainty visible when I cannot resolve it.

There will be things to correct. The system should make that easier, not embarrassing.