The MUSH Portal is an integrated web platform for PennMUSH servers (PennMUSH v1.8.7p0 or higher required). The web client has a fully customizable 256-color terminal emulator designed with a responsive mobile-friendly UI. The Javascript controlled user interface is completely user configurable using the editing tools. It can integrate with the provided server-side JSON event handler and command API to provide unprecedented interactivity. Automatic JSON API fallbacks executed by the client's player provide enhanced functionality on standard servers without the JSON API installed.

If you are a user looking for help creating your own user-defined action scripts or hacking the client source code, see the User Documentation.

See the installation instructions below for information about hosting MUSH Portal on your own website. See the build instructions if you are interested in modifying the source code.

The MUSH Portal website at http://www.mushportal.com connects to grapenut's JSON API-enhanced development MUSH by default, but can easily be connected to any PennMUSH server with WebSockets. See http://www.mushportal.com?mush.pennmush.org:4201 to connect to the standard, un-enhanced M*U*S*H development server.

• Blood of Dragons (enhanced)

• User-defined Configuration
  • Create and modify taskbar buttons, text triggers, command macros, key binds and timers.
  • Execute MUSH commands or Javascript code on activation.
  • Override ANSI color CSS and onLoad scripts for complete customization.
  • Load pre-made examples of typical user-defined actions to use as templates.

• Sidebar
  • Configurable docked panel with interactive context command buttons.
  • Show basic information about the room (contents, players, exits).
  • Sidebar automatically updates via JSON API when you or another object moves.

• Spawn Windows
  • Append text, e.g. from matched triggers, with full 256-color support.
  • Update taskbar icon of minimized window on new activity.
  • Secondary input window with optional command prefix so you don't have to type say or +p.

• Taskbar
  • Customize icon buttons that execute MUSH commands or Javascript code.
  • Stay aware of minimized spawn windows with new activity counters.
  • Launch client task windows and change settings from the task menu.
    • Configuration editing tool gives complete control over all UI and client functionality.
    • Edit and upload MUSH commands from a file, a URL, captured from @dec/tf, or edited manually.
    • Download terminal output logs to a local file.
    • Backup client configuration to a JSON file, restore from file/url, or directly edit in the browser.
    • Show interactive command history listing.
    • Clear the terminal output or reconnect to the server.

• Mailbox & BBoard
  • List, view, and compose @mail messages and bbposts with full 256-color output.
  • Automatic player and bboard name validation in message composer.
  • Unread message counts are automatically synced with taskbar icons via JSON API.

• Command Recall
  • Press Ctrl+p (previous) and Ctrl+n (next) to cycle history, or use the buttons.
  • Interactive list of prior commands available from the task menu.
  • Command recall history is automatically saved and restored after page refresh.

• Output History
  • Update browser tab icon on new activity when not in focus.
  • Automatically save output history and restore on page refresh.
  • Separate output history buffers for the main terminal and spawn windows.

• Server-side JSON API
  • Execute MUSH softcode and return the results to the client using JSON.
  • Server-side events and global JSON API commands with server support.
  • Client-side fallbacks for sidebar updates and @mail without server support.
  • Execute MUSH softcode as your player and receive JSON results.

• Custom UI Settings
  • Change server host, port, and SSL encryption.
  • Terminal font, font size, and word wrapping width.
  • Default ANSI background/foreground colors and invert black/white color scheme.
  • Command recall size and output history size.
  • Sidebar size, position, contents, and navigation compass.
  • @decompile/tf multiple attributes directly to the command upload editor.
  • Dev console output for debugging user-defined Javascript and MUSH events.
  • Mobile friendly screen space and text visibility enhancements.

• Over 4300+ Icons Available
  • Choose any icon from Game-Icons.net and Google Material Icons.
  • See http://www.mushportal.com/icons.html for a complete list of icons.

NOTE: When hosting the website on HTTPS clients may only connect to MUSH servers on the SSL port due to browser security rules. When hosting on HTTP you can connect to either the standard telnet port or the encrypted SSL port.

A proxy may be configured in your HTTP/HTTPS server to relay WebSocket SSL connections to a non-secure standard telnet port, useful for tunneling through corporate firewalls. Examples for grapenut's development MUSH can be seen using http://www.mushportal.com?mushportal.com:80 for HTTP or https://mushportal.com?mushportal.com:443 for HTTPS/SSL.

After cloning the repository with

git clone https://github.com/grapenut/mush-portal.git

you can find the pre-built app in build/. Many customizations can be achieved at run-time without modifying the source code or installing additional dependencies. To get started just copy the contents of build/ to your web server directory.

cp -r mush-portal/build/* /your/html/directory/

Integration between the server and client is provided by the included JSON API softcode object jsonapi.mush. Quote this file as a Wizard and configure the created object as your event_handler in mush.cnf. The object should be placed in the global master room. It provides web client specific commands and functions to facilitate bi-directional out-of-band communication with JSON objects. In particular, it provides automatic updates of the sidebar when objects move.

If you plan to modify and build the source code you must have an updated NodeJS installation with npm to install the Javascript dependencies.

cd mush-portal
npm install

Compile the MUSH Portal source into the build/ directory.

npm run build

If you are hosting the MUSH Portal in a subdirectory on your web server you can explicitly set the PUBLIC_URL environment variable or the "homepage" key in package.json. To build the MUSH Portal hosted at http://domain.com/mygame/index.html use

PUBLIC_URL=/mygame npm run build

You can start a development web server on port 3000 that hot-loads your code changes automatically and avoids file caching issues.

npm start

Or test out HTTPS.

HTTPS=true npm start

• public/ contains the source for files that get copied directly to build/ like styles, fonts, mobile configuration files, and the local client customization file local.js.

• public/local.js contains site-specific customizations. Access the MUSH Portal Client API using the client object.

• src/ contains the Javascript source code for the client and UI. This code must be compiled using npm run build.

• src/client/ contains the WebSocket client source files, which handle low-level networking and terminal emulation.

• src/modules/ contains the React component source files, which are used to build the user interface.

• src/index.js is the main entry point for source. It is embedded in the HTML file and is responsible for initiating the rest of the app libraries.

Back to the top.