NAME
    Story::Interact - tools for writing (and reading) an interactive story

SYNOPSIS
    Reading story from a directory:

      story-interact /path/to/story/

    Reading story from a SQLite database:

      story-interact /path/to/story.sqlite

    Reading story from an arbitrary database:

      story-interact 'dbi:...'

    Compiling a directory into an SQLite database:

      story-interact-dir2sqlite "/path/to/story/" "/path/to/story.sqlite"

DESCRIPTION
    Story::Interact is for choose-your-own-adventure-style stories, but with a
    difference. Pages can alter a global "state". This allows your character
    to achieve things, and those achievements alter the course of the story
    later on. This elevates stories to a full text-based game.

    Documentation is currently very limited. Tests are almost non-existent.

    Stories are written in pages. Each page is a Perl script using the
    functions defined in Story::Interactive::Syntax. They may contain
    arbitrary Perl code.

    Stories may contain arbitrary Perl code. Do not run untrusted stories.

    An example page:

      at 'kitchen';
  
      text "You are in the kitchen.";
  
      unless ( location->{apple_gone} ) {
        text "There is an *apple* on the counter.";
        next_page apple => 'Pick up apple';
      }
  
      next_page living_room => 'Go to the living room';

    The `text` function is just to add a paragraph of text. (It may use simple
    Markdown for **bold** and **italics**.) Pages can of course contain
    multiple paragraphs. From version 1.001003, `text` allows you to provide
    multiple paragraphs in a single string (just add a blank line between
    them), and will trim whitespace from the beginning and end of each
    paragraphs.

      text q{
        You are in the living room.
    
        You can see open doors to a bedroom and a kitchen.
      };

    The `next_page` function defines a path the story can take after this
    page. It takes a page identifier followed by a description. It can be used
    multiple times to present the user with a choice. If a page has no next
    page, then it is an end to the story. (The `next_page` function can
    actually be called as `next_page( $id, $description, %metadata )` though
    this metadata is not currently used for anything! In future versions it
    might be used to allow shortcut keys for certain choices, etc.)

    The `at` function should be used at the top of a page to indicate what
    place this page occurs at. It is an arbitrary string, so could be a room
    name, grid co-ordinates, etc. Multiple pages may be written for the same
    location.

    The abstract( $string ) function defines a title or concise summary for
    the page. It is not intended to be displayed to the reader, but may be
    useful for the writer as a quick reminder of the purpose of the page.

    The todo( $bool ) function indicates whether a page still needs writing.
    Again, it is not intended to be displayed to the reader, but may be useful
    for the writer.

    The `location` function returns a hashref associated with this location.
    This can be used to store state for this location. You can use location(
    $string ) to access another location's hashref; the string match must be
    exact.

    The `world` function returns a hashref for storing story-wide state.

    The `player` function returns a Story::Interactive::Character object
    representing the player. This object contains multiple hashrefs to store
    character state, including what things the player knows, items the player
    carries, and tasks the player has achieved.

    The npc( $id ) command returns a Story::Interactive::Character object for
    a non-player character, if such a character has been defined.

    The `define_npc( $id, %data )` function defines a new NPC. If an NPC
    already exists with that identifier, it does nothing. If the player
    character will need to interact with another character on multiple
    occasions, it is useful to define an NPC for them to track the character's
    state.

    The `visited` function returns the number of times this page has been
    visited as part of the narrative before.

    The `true` and `false` functions are just to make your code more readable.

    The random( $arrayref ) function returns a random value from the arrayref,
    which can be useful for adding some randomness to stories.

    The `match( $a, $b )` function is re-exported from match::simple.

    The first page always has id "main".

BUGS
    Please report any bugs to
    <https://github.com/tobyink/p5-story-interact/issues>.

SEE ALSO
    <https://story-interact.xlc.pl/>: Story-Interact's website and tutorial.

    Pod::CYOA, <https://en.wikipedia.org/wiki/Choose_Your_Own_Adventure>.

    Story::Interact::WWW: Mojo-based web interface for Story::Interact.

AUTHOR
    Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE
    This software is copyright (c) 2023 by Toby Inkster.

    This is free software; you can redistribute it and/or modify it under the
    same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTIES
    THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
    WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
    MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

