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