Reader Inputs

Reader inputs

Reader inputs place a story's customization controls directly inside chapter prose. They let readers choose a name, preference, number, or other reader detail without opening Customize. An input edits a reader variable; it never changes Game State.

How the input behaves

After the story's reader variable is created, {input reader:call_sign} appears as the control for that variable's type. A Text variable appears as an inline text field, a Dropdown as a choice list, and Yes/No as a two-choice control. The control's appearance follows the story's Element Theme.

Changing the value immediately updates visible uses such as {reader:call_sign} on the current page. For example, if call_sign defaults to Nova, entering Raven changes “Welcome, Nova” to “Welcome, Raven.”

Copyable syntax

Write a visible label or sentence, then place the reader variable's exact name after input reader::

Call sign: {input reader:call_sign}

Welcome, {reader:call_sign}.

The first tag creates the editable field. The second inserts the current value as text. If the reader changes Nova to Raven, the sentence on the current page updates to “Welcome, Raven.”

Create the variable before using the input, following Reader and Game Variables. Open Edit Story, enable Readers can customize story variables, and add a Reader Variable on Story variables. Names in chapter text are case-sensitive, so use the exact spelling and capitalization shown there.

What readers experience

The tag creates only the control, not a visible field label. Add enough surrounding prose for the reader to understand what to enter:

How should the crew address you? {input reader:name}

After the reader types or chooses a value, CHYOA saves it automatically after a short pause. Other inputs for the same variable, its Customize control, {reader:...} substitutions, and conditional text on the current page stay in sync.

Until the reader chooses a custom value, the variable's default is used. Signed-in readers keep saved customization with their account. A signed-out reader's choice belongs to the current visit.

Inputs follow the variable type

One syntax form works for every reader-variable type:

For example, these tags all have the same shape even though readers see different controls:

Name: {input reader:name}
Route: {input reader:route}
Lucky number: {input reader:lucky_number}
Age: {input reader:age}
Include the optional scene? {input reader:include_scene}

Each named reader variable must already exist with the intended type. Changing a definition later changes the control; an older saved value that no longer fits the type or Dropdown choices falls back to the current default.

Respond to a customized value

Use {reader:name} to show the current value. Use an if statement when the chapter should respond to a particular choice:

Choose a route: {input reader:route}

{if reader:route = "forest"}
The guide points toward the trees.
{else}
The guide waits for your decision.
{endif}

The conditional passage refreshes when the reader changes the field. Use the exact Dropdown choice in a comparison.

A condition containing only the reader-variable name checks whether the reader saved a value different from its default:

Your name: {input reader:name}

{if reader:name}
The guard records your chosen name: {reader:name}.
{else}
The guard is still using the default name.
{endif}

The input and condition are separate features: {input reader:name} creates the field, while {if reader:name} checks whether the value is customized.

Reader values are not Game State

Reader inputs work without starting a game. They cannot use game: and cannot set, increase, or decrease game variables:

{input reader:name}

Do not use {input game:name}. If a reader-facing button should change Game State, use an action or another state-changing interactive element instead.

Because reader customization is separate from the saved game, Back, Reset Game, and Start Over do not undo it. The reader can choose another value through the inline field or Customize. Leaving a Text field blank restores its default.

Placement and limits

An author can place the same input more than once; all copies edit the same saved reader value. Pair inputs with nearby {reader:...} text when immediate feedback helps the reader understand the choice.

Keep the input tag in ordinary prose rather than putting it inside a link, a button label, another tag's quoted option, or formatted example. Put it in backticks or a fenced block when the chapter should display the syntax literally.

Reader-entered Text is inserted as plain text. It is not interpreted as Markdown or another chapter tag. The story's Element Theme controls field, Dropdown, Percent, and Yes/No presentation without changing the saved value.

Before publishing

Preview the chapter and check that:

1. every input uses an existing reader variable's exact name and capitalization;
2. surrounding prose gives each control a clear visible purpose;
3. Text, Dropdown, Number, Percent, Age, and Yes/No variables show the expected control;
4. defaults appear before a reader makes a custom choice;
5. repeated inputs, Customize, and {reader:...} text stay in sync;
6. conditional text refreshes for both matching and non-matching values;
7. blank Text and invalid older values return to the intended default;
8. the layout remains readable with long choices, narrow screens, and White, Black, and Sepia appearance.