Code Monkey home page Code Monkey logo

page-turner's Introduction

PageTurner

npm version

An engine to build web-based games or stories where the primary interaction method is a multiple-choice selection.

What is it?

PageTurner is a simple engine to build web-based games or stories where the main way the player interacts is using multiple-choice selections. While this is similar to text adventures or visual novels, PageTurner aims to provide authors with the ability to easily define custom logic to run in response to player choices, resulting in a complex graph of pages rather than a tree.

It is not intended to have all visual the bells and whistles one could imagine. It intentionally provides few built-in primitives and options to encourage constraint-based design and interactivity via the page choices.

Why?

The design of PageTurner is driven by the question:

What sort of games could you make if everything were a page?

A "page" in this context is a single page in the "story book", containing:

  • some lines of text
  • (optional) a number of mutually-exclusive choices
  • (optional) background images
  • (optional) background music & sound effects

Basic Usage

The PageTurner class is the entry point into the engine. Both Javascript and Typescript are supported.

See the following template projects to get up and running quickly:

A basic setup might look like this:

index.html

<body>
  <div id="page-turner" style="width: 800px; height: 600px;"></div>
  <!-- This script reference will change depending on your build system and project structure -->
  <script type="module" src="/src/index.ts"></script>
</body>

src/index.ts

import { PageTurner } from '@neonfish/page-turner';
import { pages } from './pages';

const game = new PageTurner({
  settings: {                    // All these settings come with default values, but can be overridden here
    containerEl: "#page-turner", // A selector for the element to contain the PageTurner game
    content: {                   // These percentages are in terms of the container element's dimensions
      height: "40%",
      top: "10%",
    },
    choices: {
      height: "30%",
      top: "60%",
    },
  },
  pages: pages, // The list of pages defining the story
});

src/pages.ts

import { Page, Utils } from "@neonfish/page-turner";

/** Define IDs for pages so they can be easily targetted */
export const PAGE = {
  START: Utils.id,
  BAD: Utils.id,
};

export const pages: Page[] = [
  {
    id: PAGE.START,
    // By default, content lines are displayed one after the other
    content: [
      "Howdy! (click to continue)",
      "These lines of content appear one after the other.",
      "What do you think?\n(Click to reveal choices)",
    ],
    choices: [
      // If a next page is not specified, the next page to be displayed is the next in the list of all pages
      { text: "Cool!" },
      // Define a next page in a choice to jump to that page if the choice is clicked
      { text: "I'm not impressed.", next: PAGE.BAD },
    ],
    // Define a background image. By default, all images are "held" between pages,
    // so they do not need to be re-specified on following pages
    images: [
      { slot: "bg", url: "https://images.pexels.com/photos/548084/pexels-photo-548084.jpeg?auto=compress&cs=tinysrgb&dpr=2&h=650&w=940" },
    ],
  },
  {
    content: [
      "I'm very glad you like it!",
      "You can make your own story as well!",
    ],
    choices: [
      // Arbitrary functions can be executed in response to selecting a choice
      { text: "OK! Lets go!", onSelect: () => window.location.href = "https://github.com/neon-fish/page-turner" },
      // If no next page is specified, the choice uses the page's "next page" definition
      { text: "Not just yet." },
    ],
    next: PAGE.START,
  },
  {
    id: PAGE.BAD,
    content: [
      "I'm sorry to hear that.",
      "Are you sure I can't change your mind?",
    ],
    choices: [
      { text: "No. I'd rather watch YouTube.", onSelect: () => window.location.href = "https://youtu.be/dQw4w9WgXcQ" },
      { text: "I prefer Ren'Py.", onSelect: () => window.location.href = "https://www.renpy.org/" },
      // No next page is specified, and the page has no next page either.
      // However, the page list wraps round, so the "next" page after the last page is the first page.
      { text: "Well, maybe..." },
    ],
  },
];

Development

(Internal design doc)

  • Requires Node
  • Install dependencies with npm install
  • Start a hot-reloading dev server with npm run dev

TODO

  • Displaying images in other image slots
  • Selecting choices with keyboard
  • Positioning content and choices
  • Playing music
  • Playing sounds
  • Add options for blurring the background of the content panel
  • Styling/theming options (inc. choices, content text)
  • Fix bug skipping the end of last content line on next()
  • Page enter/exit animations
  • Simple image animations
  • "Speaker" labels for content strings

Deployment

PageTurner is available as an NPM package, available here.

To update the package, update the version in package.json then run npm run release

page-turner's People

Contributors

neon-fish avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.