Pinwheel MUD Engine

A highly opinionated fork of the Ranvier MUD engine.

Current Version: 0.5.0

Pinwheel is a new MUD engine built entirely in ES6 (JavaScript). It doesn't require a database and can be online for players within moments of downloading. Originally based on Shawn Biddle's Ranvier, Pinwheel is a rewrite of the engine and its bundles into a highly opinionated format. The engine makes decisions about world persistence and core features so you can focus on building your world and community.

Pinwheel is an experimental game engine that aims to fuse MUD and browser gameplay. To get an idea of what version 1.0.0 of Pinwheel will entail, check out our Roadmap.

✏️ Latest devlog post: Initial Release of Pinwheel - January 26, 2019

📖 Table of Contents

• Install
• Usage
  • Package Scripts
  • JSON Configuration
• Features
• Roadmap
• Maintainer
• Contributing

💾 Install

Pinwheel requires Node v8.9.4 or greater.

To install, run the following commands from your terminal:

git clone https://github.com/azigler/pinwheel/
cd pinwheel
npm install
npm run

Pinwheel can get up and running immediately, but it's recommended to configure your game via the pinwheel.json file. For more information, see the Usage section.

🚀 Usage

Pinwheel has several built-in scripts that you can use with npm run. To launch the server, use npm run start. To launch the server quicker and without logging to a file (useful for development), use npm run dev.

This repository comes with a default account and administrator character, or you can make your own with the included aspects. To access the default account, use the following credentials:

username: Admin
password: pinwheel

🔩 Package Scripts

• start: launches the server
• dev: launches the server without logging to a file, connecting to Grapevine, or running the default gulp task (useful for development)
• istanbul: uses Istanbul to test coverage with Chai
• test: runs the default gulp task and fires the istanbul script
• build-docs: uses JSDoc to build documentation in docs/jsdoc/ from src/
• bundle-install: installs npm packages for all bundles
• postinstall: automatically fires bundle-install after npm install
• clean-areas: deletes the files in data/area/ (useful for rapid testing)
• clean-bugs: deletes the files in data/bug/ (useful for rapid testing)
• clean-logs: deletes the files in data/log/ (useful for rapid testing)
• clean-all: fires all of the cleaning scripts (clean-logs, clean-bugs, clean-areas, and clean-all)

Many elements of Pinwheel can be configured via the pinwheel.json file.

⚡ JSON Configuration

(in alphabetical order)

• allowMultiplay: whether accounts can have multiple characters logged in at once (default: true)
• aspects: array of Aspect names (default: ["archetype", "species", "trait"])
• bundles: array of bundle names to include at runtime (default: all bundles in this repository)
• creation: object with properties whose values indicate default Aspect options available at character creation (default: {"archetype": ["tester"], "species": ["administrator"], "trait": ["immortal"]})
• currency: name of default currency (default: "cowries")
• debugArea: name of area where combat debugging will output (default: "start")
• entityTick: time between entity update ticks, in miliseconds (default: 500)
• grapevine: false if disabled, or object with your game's authentication details for Grapevine (example: {"clientId": "YOUR-CLIENT-ID", "clientSecret": "YOUR-CLIENT-SECRET"}), (default: false)
• introEvent: initial input-event shown on connection (default: "intro")
• logLevel: configures logging to file, either "verbose" or "none" (default: "verbose")
• maxCharacters: number of active characters allowed on an account (default: 3)
• maxFailedLoginAttempts: number of failed login attempts allowed before being kicked (default: 3)
• maxIdleMinutes: number of minutes a character can idle before being kicked, 0 if disabled (default: 0)
• maxNameLength: maximum name length for an account or character (default: 20)
• maxPlayerInventory: maximum number of items that can be carried by a player (default: 16)
• meta: (example: {"author": "John Doe", "gameName": "Pinwheel", "twitterHandle": "@johndoe"}), (default: false)
• minNameLength: minimum name length for an account or character (default: 3)
• minPasswordLength: minimum character length for an account password (default: 6)
• motd: filename in data/motd/ to show on intro event (default: "pinwheel")
• moveCommand: default command used to navigate a character (default: "move")
• playerTick: time between player update ticks, in milliseconds (default: 500)
• reportBugsToAdmins: whether to notify valid online users of reported bugs, typos, and suggestions (default: true)
• skillLag: default lag after skill use, in milliseconds (default: 1000)
• startingRoom: entity reference for room in which all characters start after creation (default: "start:spawn")
• startingTraits: number of traits that can be chosen at character creation (default: 1)
• telnetPort: port for Telnet server (default: 4000)
• web: object with information for web server (example: "web": {"header": {"description": "Powered by Pinwheel, a JavaScript MUD engine.", "faviconUrl": "/path/to/favicon.ico", "googleId": "YOUR-GOOGLE-ANALYTICS-TRACKING-ID", "image": "https://full.weburl.to/image.jpg"}, "https": {"fullchain": "/full/path/to/fullchain.pem", "port": 443, "key": "/full/path/to/privkey.pem"}, "port": 80}), (default: {"header": false, "https": false, "port": 80})
• webSocketPort: port for WebSocket server (default: 4001)

📍 Features

• Full game state persistence across sessions (areas, NPCs, players, and items)
• Diku-esque commands
• Customization of players and NPCs with species, archetypes, and traits
• Usage of human-readable YAML for game data in bundles
• Entity-based scripting with few differences between NPCs and players
• Turn-based combat with abilities, spells, and disciplines
• Usage-based improvement of skills with branching skill trees
• Communication channels and player parties
• Compatibility with the Grapevine MUD Chat Network
• Player accounts
• Telnet and WebSocket support
• Data storage in JSON files, no database required
• Web server bound to state (for a website and/or API)

📈 Roadmap

• Refactor Ranvier into Pinwheel
• Reduce the differences between player characters and NPCs
• Convert class system into aspects, allowing fine-tuned customization of players and NPCs alike with stackable components (e.g., species, archetypes, and traits)
• Rewrite foundation for new combat system
• Add configurable time, seasons, and weather
• Implement hot reloading of bundles and core
• Enable online creation (OLC) of bundle content
• Create customizable player organizations
• Redesign quests into dynamic events
• Add crafting, resources, and a basic economy
• Expand emoting complexity with syntax for referencing the world
• Build an API with Express for the engine and game state, allowing extensibility beyond the original platform (e.g., apps, widgets, and third-party clients)
• Expand the web server to allow for gameplay, building, and administration in the browser
• Convert to NPM package

🏇 Maintainer

Pinwheel is maintained by Andrew Zigler, a member of the MUD Coders Guild. Andrew can be reached on Twitter (@andrewzigler) or Slack (@Zig).

📥 Contributing

Feedback and contributions are encouraged! After reading our Code of Conduct, use the Bug Report or Feature Request issue templates to discuss any bugs or potential contributions to Pinwheel. For more information, please read our Contributing Guide.