# Reading values

These give you a value. Compare them, add them, feed them to a step.

## Stats: read by role, never by name

```js
$.stat('might')
```

**This is the one convention worth learning first.** Stats are read by their *role*, not
their display name. A game might call its strength stat "Might", "Brawn" or "Thew" — all
three answer to `might`.

```js
$.stat('brawn')       // breaks the moment someone renames the stat
$.stat('might')  // keeps working
```

A stat nobody has reads as `0`.

### Worked example: a damage bonus

A heavy weapon that hits harder in strong hands:

```js
5 + $.stat('might') * 1.5
```

## Fields: your own declared values

A **field** is a value you declared on an entity — `satiety`, `infection`, `mana`. Read one
with `$.field()`:

```js
$.field('satiety')            // on the subject of this rule
$.field('satiety', 'player')  // explicitly on the host player
$.field('infection', 'target')
```

The second argument is `'player'` or `'target'`. Leave it off and you get the subject —
whoever the rule is currently about.

A field nobody has reads as `null`, **not** `0`. That difference decides whether your rule
fires; see [Missing values](/docs/missing-values).

### Worked example: a fever that worsens

Inside an `onTimePasses` hook, climbing faster the sicker you already are:

```js
$.field('fever') * 0.1 + 0.2
```

## Carried totals

```js
$.carried('weight')
```

Sums a carryable field across everything the subject is holding. This is how encumbrance
works, and it is the only reader that walks an inventory for you.

## Dials: your plugin's tuning numbers

```js
$.dial('foodDrainPerHour')
```

Reads one of your own plugin's dials — the numbers exposed in its editor panel so they can
be tuned without editing code.

**Never freeze a dial's value as a literal.** Writing `0.4` where you meant
`$.dial('foodDrainPerHour')` works perfectly until someone retunes the dial, at which point
you have two numbers that disagree and no error anywhere. See [Formulas and dials](/docs/formulas).

## Time, and whether there is any

```js
$.event.minutes   // how long this stretch was
$.timed           // whether this world has a clock at all
```

`$.timed` exists because not every game runs a clock, and a rule that charges an hourly
rate in a clockless game is charging against the narrator's guess at how long the prose
took — which has varied from 3 to 22 minutes for comparable turns. The safe shape:

```js
$.timed ? $.dial('drainPerHour') * ($.event.minutes / 60) : $.dial('drainPerTurn')
```

See [Minutes are not time](/docs/minutes-are-not-time) for why this matters more than it
looks.

## Everything readable

<!-- api:generated:entities -->
| Path | Answers |
|---|---|
| `$.subject` | The entity this rule is about. |
| `$.subject.name` | The subject's name. |
| `$.subject.location` | Where the subject is. |
| `$.subject.health` | Current health. |
| `$.subject.maxHealth` | Maximum health. |
| `$.subject.dead` | Whether the subject is dead. |
| `$.subject.fields` | The subject's declared fields, by key. |
| `$.subject.bonds` | The subject's NPC bonds. |
| `$.source` | Who caused it — attacker, user, emitter. |
| `$.player` | The HOST player only. Use `$.party` for everyone. |
| `$.player.name` | The host player's name. |
| `$.player.health` | The host player's health. |
| `$.player.fields` | The host player's declared fields. |
| `$.party` | Every player — host and guests. |
| `$.location` | Where this is happening. |
| `$.world` | World state flags. |
| `$.here` | What is in the current location. |
| `$.mobs` | Creatures present. |
| `$.turn` | The turn number. |
| `$.timeMinutes` | Minutes on the world clock. Advances once per tick. |
| `$.minutesPerDay` | Minutes in one day under this world's calendar (Earth: 1440). |
| `$.timed` | Whether this world has a clock. Charge per hour where true, per turn where false — in a clockless game `$.event.minutes` is the narrator's estimate, not a measurement. |
| `$.setting` | The game's setting. |
| `$.killCount` | Kills so far. |
| `$.event` | What the firing trigger carried. `{}` outside a hook, so a read there is undefined rather than an error. |
| `$.item` | The item in play. Null outside the item-use path. |
| `$.item.name` | The item's name. |
| `$.item.state` | Shorthand for the item's `state` variable. Any other variable reads through `$.item.tags`. |
| `$.item.fields` | The item's number variables. |
| `$.item.tags` | The item's word variables, by key — `$.item.tags.mood`. |
| `$.target` | The aimed-at entity. |
| `$.target.name` | The target's name. |
| `$.target.state` | Shorthand for the target's `state` variable. |
| `$.target.fields` | The target's declared fields. |
<!-- /api:generated:entities -->

Payload fields (`$.event.*`) are listed per trigger on [Hooks](/docs/hooks), because which
ones exist depends on what fired.

## Next

[Asking questions](/docs/questions) — the true/false half of the API.