An LLM IF doodle project – personal, but trying to be compatible with others

1 month ago 2

whisker is a powerful, flexible interactive fiction engine written in Lua. Create text-based games, visual novels, and branching narratives with an easy-to-use scripting system - inspired by Twine, but built with Lua's power and flexibility.

Whisker is a complete interactive fiction engine that allows you to create choice-based stories, text adventures, and narrative games. Whether you're a writer wanting to create branching stories, a game developer prototyping dialogue systems, or an educator building interactive learning materials, whisker provides the tools you need.

🎮 Full-Featured Engine - Complete story system with passages, choices, and variables
📝 Lua Scripting - Powerful scripting for complex game mechanics and logic
🔄 Twine Compatible - Import and export stories from Twine (Harlowe, SugarCube, Chapbook, Snowman)
🌐 Multi-Platform - Run on console, web browsers, and desktop
💾 Save System - Multiple save slots with autosave support
🐛 Development Tools - Built-in debugger, profiler, and validator
📱 Responsive Web UI - Beautiful HTML5 player included
🎨 Highly Customizable - Extensive configuration and theming options
📦 No Dependencies - Pure Lua implementation, batteries included

Lua 5.1 or higher (installation instructions)

# Clone the repository git clone https://github.com/jmspring/whisker.git cd whisker # Run an example story lua main.lua examples/stories/simple_story.lua

Create a file called my_story.lua:

local Story = require("src.core.story") local Passage = require("src.core.passage") local Choice = require("src.core.choice") local story = Story.new({ title = "My First Adventure", author = "Your Name" }) local start = Passage.new({ id = "start", content = "You wake up in a strange place. What do you do?" }) start:add_choice(Choice.new({ text = "Look around", target = "look_around" })) start:add_choice(Choice.new({ text = "Go back to sleep", target = "sleep" })) story:add_passage(start) story:set_start_passage("start") return story

Run it:

lua main.lua my_story.lua

Getting Started - Complete installation guide and first story tutorial
API Reference - Detailed API documentation
Documentation Overview - Full feature list and architecture guide
Snowman Converter - Converting Twine Snowman stories
Metatable Preservation - Advanced Lua features

Whisker includes several example stories to help you learn:

simple_story.lua - A minimal cave exploration story
tutorial_story.lua - Learn whisker features interactively

adventure_game.lua - Full RPG with inventory, combat, and quests

CLI Runtime - Command-line interface
Desktop Runtime - LÖVE2D desktop application
Web Runtime - Browser-based player
Web Demo - Single-file web example

Run any example:

lua main.lua examples/stories/simple_story.lua

Or try the web demo by opening examples/web_demo.html in your browser!

Passage-based narrative structure
Dynamic choice generation
Variable tracking and state management
Conditional content and branching
Script execution on passage enter/exit

Import HTML stories from Twine
Support for multiple formats: Harlowe, SugarCube, Chapbook, Snowman
Convert between formats
Export to JSON or whisker format

Validator - Check story structure and find issues
Debugger - Set breakpoints and inspect state
Profiler - Measure performance and optimize
Console - Interactive testing environment

CLI - Terminal-based player for any platform
Web - HTML5 player with responsive design
Desktop - LÖVE2D integration for native apps

whisker/ ├── src/ │ ├── core/ # Story engine (passages, choices, state) │ ├── format/ # Twine import/export and converters │ ├── infrastructure/ # Save system, file handling, assets │ ├── parser/ # Story file parsing │ ├── runtime/ # Platform-specific runtimes │ ├── tools/ # Developer tools (debugger, profiler, validator) │ ├── ui/ # User interface components │ └── utils/ # Utility functions ├── examples/ # Example stories and runtimes │ ├── stories/ # Example story files │ ├── cli_runtime/ # Command-line player │ ├── desktop_runtime/# LÖVE2D desktop player │ └── web_runtime/ # HTML5 web player ├── tests/ # Test suite and fixtures ├── docs/ # Documentation ├── main.lua # Main entry point └── config.lua # Configuration file

Interactive Fiction - Text adventures and choice-based games
Visual Novels - Story-driven experiences with complex branching
Educational Tools - Interactive tutorials and learning experiences
Game Prototyping - Rapid dialogue and narrative system prototyping
Narrative Design - Story structure visualization and testing

# Play a story lua main.lua story.lua # Validate story structure lua main.lua --validate story.lua # Convert from Twine HTML to JSON lua main.lua --convert json story.html -o output.json # Debug mode with breakpoints lua main.lua --debug story.lua # Performance profiling lua main.lua --profile story.lua # Show help lua main.lua --help

Contributions are welcome! Whether it's bug fixes, new features, documentation improvements, or example stories, we'd love your help.