# fink.js, for makers

fink.js is the one script that connects your game to Fink. Add one line, and
the minutes people really spend playing your game count on their Fink
record: 1 XP a minute, every minute, with no daily cap.

## Add it

```html
<script src="https://finkinc.space/fink.js"></script>
```

That is all a game needs. When someone walks through your door in Fink, the
page opens with a pass at the end of its address (`#fink=...`), and fink.js
keeps a clock of **active** play:

- it starts at the player's first input: a click, a tap, a key, the mouse
  moving, the wheel;
- it counts only while the page is visible and the player has done something
  in the last 5 minutes, so a tab left open counts nothing;
- it sends the time to Fink once a minute, and when the page is hidden or
  closed.

A person has one clock: two tabs, or two games at once, never count the same
minute twice.

## Two calls, if you want them

```js
fink.start();                                                    // start the clock now (your Start button)
fink.report({ score: 7, max: 10, result: "7 of 10 intervals" }); // at the end of each round
```

- `fink.start()` starts the clock at once rather than at the first input, and
  shows the corner tag straight away.
- `fink.report()` puts how the round went on the player's record and pays the
  time so far. `score` is what the player got, `max` is the most possible in
  that round (a number above 0), and `result` is a few words, if you like.
- Report once a round, not every second: Fink refuses more than 8 reports a
  minute from one player.
- Both return a promise. `r.paid` is the XP just paid, and `r.outcome` says
  what happened:

  | outcome | what it means |
  |---|---|
  | `paid` | the minutes went on their record |
  | `held` | more than two hours in one report: two hours now, the rest with the next |
  | `overlap` | those minutes were already paid for in another game or tab: one clock a person |
  | `short` | under 15 seconds unpaid; it carries to the next report |
  | `practice` | the game wasn't opened through a Fink door, so nothing was sent |
  | `own` | you, playing your own game: makers don't earn from their own door |
  | `frozen` | Fink froze this door, so it plays and pays nothing |
  | `rejected` | not a result Fink believes (below) |
  | `limited` | too many reports too fast |
  | `refused` | Fink couldn't be reached, or the pass has run out (a walk lasts six hours; walk through the door again) |

  The small tag fink.js puts in the corner already says what counted, so the
  game doesn't have to. Never work out XP yourself, and never send a time.

And two things to read: `fink.door.practice` is `true` outside a door, and
`fink.door.played()` is the seconds of active play so far.

## How Fink pays

- 1 XP = 1 minute of active play, as community XP on your game's subject.
- Fink pays the minutes that really passed by its own clock, never more than
  the page's clock of active play says, and never a minute the player was
  already paid for somewhere else. There is no daily cap.
- Refused, and marked on your door as a flag:
  - a perfect score in under 15 seconds;
  - a score higher than `max`;
  - a clock that ran faster than real time;
  - more than 8 reports a minute from one player.

  Enough flags and Lain looks at your door.
- A maker playing their own door earns nothing, and someone who isn't signed
  in to Fink plays in practice. Everyone else's minutes count.

## What your game never gets

Who is playing. Inside a door the game holds a pass for your game and one
player, and nothing else: no name, no account, no login. Don't ask for them,
and don't call `fink.login()`.

## Practice

Opened any other way (double-clicked on your computer, or on your own site
without a pass) the page runs in **practice**: every call works, nothing is
sent, and the corner tag says "Fink · practice". That is how you test it.

## Where your game runs

- **Hosted on Fink**, your game has an address of its own, so
  `localStorage`, `sessionStorage` and IndexedDB work and belong to your game
  alone (wrap them in `try { } catch { }`: a private window can switch them
  off). No cookies, no server code. If your page doesn't load fink.js, Fink
  adds the line, and loading it twice is safe.
- **Linked from your own site**, include the line yourself. On itch.io, which
  plays games inside its own frame, the pass may not reach your game, so
  minutes may not count there.
- Either way, `alert()`, `confirm()` and `prompt()` don't work (put messages
  on the page), and the game can't navigate the page around it.

## Check yourself

- [ ] one `<script src="https://finkinc.space/fink.js"></script>`
- [ ] `fink.report({ score, max })` at the end of each round, checking
      `window.fink` first and catching any error
- [ ] no alert, no login, nothing about who is playing
- [ ] a perfect round takes longer than 15 seconds