perceptle-rules
v0.1.0
Published
Scoring, five perception error measurements, UTC calendar, statistics and share formatting for Perceptle. Pure TypeScript, no runtime dependencies.
Downloads
362
Maintainers
Readme
perceptle-rules
The scoring and supporting rules used by Perceptle, the daily perception game with five quick challenges: Count, Track, Angle, Tempo and Split. Play the daily puzzle or Unlimited practice.
Pure TypeScript, no runtime dependencies, no I/O. This package measures supplied targets and player inputs; it does not generate daily puzzles or provide a game UI.
Install
npm install perceptle-rulesES modules and TypeScript declarations. Supported Node.js: 22.12 or newer. The runtime uses standard JavaScript and can also be bundled for browsers.
Quick start
import { gaussianScore, gradeOf, totalOf, measureCount, SIGMA } from "perceptle-rules";
const result = measureCount({ n: 50 }, { guess: 60 });
result.rawError; // 0.2
gaussianScore(result.rawError, SIGMA.count.normal); // 61
gaussianScore(120, 60); // 14
gradeOf(95); // "S"
totalOf([61, 14, 0, 100, 83]); // 52Scoring
gaussianScore(error, sigma) returns round(100 * exp(-0.5 * (error / sigma)^2)).
totalOf(scores) rounds their arithmetic mean; an empty array returns zero.
gradeOf(score) uses these inclusive thresholds:
| Grade | Minimum score | |---|---:| | S | 95 | | A | 85 | | B | 70 | | C | 55 | | D | 40 | | F | 0 |
SIGMA contains the normal and Friday scoring scales:
| Event | Raw-error unit | Normal | Friday | |---|---|---:|---:| | Count | Relative count error | 0.2 | 0.32 | | Track | Logical pixels | 60 | 90 | | Angle | Degrees | 8 | 14 | | Tempo | Milliseconds | 60 | 85 | | Split | Relative line-length error | 0.05 | 0.1 |
Error measurements
Each function returns { rawError, detail } without mutating its inputs.
Targets and inputs are structural types; no generated puzzle object is required.
| Function | Target | Input | Behavior |
|---|---|---|---|
| measureCount | { n } | { guess } | Absolute count difference divided by n |
| measureTrack | { landingX } | { clickX } | Absolute horizontal distance |
| measureAngle | { variant, targetAngle } | { finalAngle } | Shortest circular difference for normal; linear difference for Friday, preserving full turns |
| measureTempo | { variant, T } | { beats, syncTaps, freeTaps } | Phase-calibrated drift and jitter, with whole-beat shifts reported separately |
| measureSplit | { x1, x2, targetX } | { clickX } | Absolute target difference divided by line length |
variant is "normal" or "friday". Coordinates share one logical coordinate
system and angles are degrees. Tempo's T is the beat interval in milliseconds;
every timestamp must use the same monotonic time origin. The game records four
sync taps and eight free taps; the measurement function also accepts shorter
nonempty free-tap sequences for analysis.
Tempo estimates phase from sync taps relative to the nearest reference beat. A
tie uses the first beat in the supplied array. With no sync taps, the last beat
defines phase. Friday measures half-beats. Its raw error is
0.6 * drift + 0.4 * jitter; detail includes mean, slip and offsets too.
Empty beats or freeTaps throw RangeError.
Callers validate inputs: use finite numbers, positive n, T and sigma, and
x2 > x1. Inputs are already accepted game answers, not raw pointer events.
These functions do not clamp positions, sort timestamps or validate records.
UTC calendar
import { puzzleNumber, dateOfPuzzle, variantOf, nextRolloverAt } from "perceptle-rules";
puzzleNumber("2026-07-18"); // 1
dateOfPuzzle(14); // "2026-07-31"
variantOf("2026-07-24"); // "normal"
variantOf("2026-07-31"); // "friday"
nextRolloverAt(Date.parse("2026-11-13T00:00:00Z"));
// Date.parse("2026-11-14T00:00:00Z")utcDateOf(ms) returns a UTC YYYY-MM-DD string. isIsoDate(value) checks
whether a string is a real date; use it before date arithmetic on external data.
addDays(date, n) supports leap days and year boundaries. puzzleNumber and
dateOfPuzzle use ANCHOR_DATE; Friday variants start at FRIDAY_MIN_PUZZLE.
Pass valid ISO dates and positive integer puzzle numbers. nextRolloverAt(ms)
accepts and returns epoch milliseconds, always choosing the next UTC midnight.
Statistics and sharing
calculateStats(records, today) takes DailyRecord[] and a UTC date. It returns
played days, rounded average, best score, current and longest streaks, and the
full grade distribution. Duplicate dates use the first record. An unplayed today
does not break yesterday's streak. Pass valid, completed records dated no later
than today. The caller owns storage, validation and clock selection.
formatShare(input) returns three lines: puzzle/grade/total, ordered event
emoji/score pairs, and the caller's site URL. Supply a ShareInput with siteName,
siteUrl, puzzle, variant, total, grade and events. It does not use the clipboard.
Scope and development
The website remains the source of truth. Rule updates are exported here and checked for drift. This repository contains no puzzle generator, answer dataset, canvas/audio runtime, browser storage, analytics, website design or media. See SOURCES.md for the included modules.
npm install
npm run typecheck
npm test
npm run build
npm packThe tests run with synthetic inputs, without another repository or reference generator. Root exports are the supported API; internal file paths are not.
License
MIT. Maintained by Perceptle at theperceptle.com.
