initiative-sh / initiative.sh

A web-based command line for game masters

Introducing initiative.sh

initiative.sh's design philosophy is to minimize the time and effort between the question ("Is there a blacksmith nearby?") and the answer ("Yes, it's called Frosthammer & Sons, and Fenrik Frosthammer is at the forge.").

• Keyboard first: All commands can be typed. Most can be run at any time, so you don't need to waste time navigating menus to find the tool you want.
• Persistence: The people and places you generate remain visible in your scrollback history and can be saved to your journal, so you don't need to worry about forgetting to scribble down a generated name that came up in conversation.

Other features on the roadmap

The following features have not yet been implemented:

• Context: With your guidance, initiative.sh will track your party's location and the demographics in the area. If you're in a dwarvish settlement, the innkeeper and most of the patrons will probably be dwarves.
• Integrations: Integrate with Spotify to switch playlists as your players move through the world, with Home Assistant to dim the lights as the party beds down for the night, or use web hooks to build your own integrations.
• Cloud sync: Keep your journal in sync between devices.

Running the project

Dependencies:

• Rust/Cargo
• wasm-pack (for web)
• npm (for web)

Note that the project includes 5e-database as a Git submodule, so actions such as building and starting a dev server may fail until you run:

git submodule update --init

Web

1. Run ./dev-server.sh from the project root at the command line.
2. Find the dev server URL in the command line output and open it in your browser. Typically, this will be localhost:8080.

Command line

Note: The command line interface lost feature parity with the web version early in the development process. Notably, it lacks autocomplete support, and the "rich" version doesn't support scrolling or text formatting. For details, see #287.

Rich version

cargo run

Light version

The light version is selected when the input is not from a tty, such as when you pipe a command into cargo run.

echo npc | cargo run

Contributing to the project

Please see CONTRIBUTING.md for details.

initiative.sh's Issues

Changelog is truncated at 10 lines

As of 9bd2b02, the changelog appears as follows:

* Enhancement: Adopted Source Code Pro for the interface font. Most importantly, the common font ensures that the blocks in the logo are always the same width.
* Bug: Fixed the page not scrolling predictably. Scrolling behaviour should also respect browsers configured to prefer reduced motion.
* Enhancement: Added equipment, all of the essentials like Dagger and Bagpipes, as well as categories like weapons and ships.
* Enhancement: New command: spells.
* Bug: Fixed rendering inline lists in spell descriptions.
* Bug: Fixed capitalization of possessives: Arcanist's Magic Aura is no

Expected behaviour should show 10 bullets, not 10 lines of input.

Add detail to storage autocomplete

When offering autocomplete suggestions, indicate a) the type of thing being suggested, and b) whether that thing is generated or persisted.

Cross-compile to WASM

Now that we have a functional proof of concept, it's time to get going on making the app cross-compile to WebAssembly.

• Refactor almost all code into project workspaces, leaving only bootstrapping code in the root. #20
• Build a very simple JS frontend for the command input/response. #22

Autocomplete placeholders

Given a link or autocomplete suggestion like save [npc name], fill the text box with save [npc name] with the bracketed phrase selected and do not submit.

Implement tutorial

Once the features and interface are a bit more mature, build a tutorial highlighting the major features of the application.

Dependencies:

• #78
• #34
• #79

Disambiguate conflicted commands

Eg. for input "Shield", expected behaviour:

• Output best guess (spell descrption?)
• List all additional matches
• Provide explicit commands for specifying which match you want (eg. "spell Shield", "item Shield")

Code refactor

The time has come for refactor number 1, reorganizing the code to better enforce a separation of concerns that makes sense.

• app
  • context
  • interface
    • light
    • rich
    • web
  • parser
    • syntax
      • adjective
      • noun
      • verb
• storage
  • memory
  • sqlite
  • wasm
• world
  • demographics
  • location
  • npc
  • region

Overall, the top-level components interact as follows:

• app: user interaction - interface, context tracking, and command parsing
• parser: transforms String input into a Command object
• storage: handles saving and loading world entities
• world: represented entities and their respective random generators, hierarchical by type

Related issues:

#16 Reorganize code

Add SRD equipment

Add equipment and equipment categories from the SRD.

Implement scrolling for rich CLI

Currently, the output clears every time a new command is sent. Instead, the output should scroll with the most recent output shown at the bottom.

Ideation: rationalize process for executing commands once parsed.

• Figure out a way to execute parsed commands without relying on a massive if/else tree.
• Out of scope: implementation.

Add markdown support

Most markdown features won't be supported because, hey, it's a terminal, but it should be possible to achieve the equivalents of terminal escape sequences for colours, bold, underline, etc.

Persist generated content (short-term)

Save all randomly generated content (NPCs, locations, etc.) to in-memory storage for retrieval later in the same session.

The intention behind this is to enable syntax like

save Dumbledore

Bad example.

Implement quality-of-life commands

• #56
• New command: help Resolved by #56
• New command: news Implemented as changelog in #56
• New command: tutorial Split off as #66

Less permissive commands

Parsing commands based on best guesses is good and all, but it makes syntax (not to mention consistency) much more challenging. While we're still at the phase of using one-word commands anyhow, better to pivot to being prescriptive with command syntax.

Update welcome message

Light CLI encapsulation

Improve encapsulation of the light CLI to make the rich CLI (and indeed web UI) a drop-in replacement.

Mobile: Define viewport settings & fix autocapitalization

• Set reasonable viewport settings for mobile users.
• Add an alternative logo for narrow displays, since I don't think we want the text to be any smaller.
• Update input field to not capitalize by default.

Rewrite lexer

• Implement greedy multi-word parsing (eg. "young adult" can be treated as a single adjective) #7
• Implement adjectives
• Implement positional nouns
• Implement positional verbs
• Implement objects for verbs

Numeric aliases can be ambiguous

---- numeric_aliases_exist_for_npcs stdout ----
thread 'numeric_aliases_exist_for_npcs' panicked at 'assertion failed: `(left == right)`
  left: `"# Lance\n*adult human, he/him*\n\n**Species:** human\\\n**Gender:** masculine\\\n**Age:** 37 years\\\n**Size:** 5'5\", 148 lbs (medium)"`,
 right: `"# Lance\n*Weapon (Martial Melee)*\n\n**Cost:** 10 gp\\\n**Damage:** 1d12 piercing\\\n**Properties:** Reach, special\\\n**Weight:** 6 lbs\n\nYou have disadvantage when you use a lance to attack a target within 5 feet of you. Also, a lance requires two hands to wield when you aren't mounted.\n\n*Lance is Open Game Content subject to the `Open Game License`.*"`', core/tests/world_npc.rs:132:21

🤦

Related to #75.

Add `save` alias

Rather than always typing the full name (save Mikkel Paulson), we should be able to use save immediately after viewing an unsaved entity.

Persist to local storage

• #82
• #83
• #84
• #85
• #93
• #102
• #99
• #98
• #100
• #103
• #105

Implement time

• #118
• Add status display for current day number / time of day.
• #160
• Implement moon phases.
• Swap light/dark theme depending on time of day.
• Implement prompts when moving between locations to advance time. (Depends on #79)

Regenerated NPC subtypes are not respected

When inputting a species (eg. "gnome"), all results should be of that species. Instead, the first result is of the correct species, but the subsequent suggestions are a mix according to available demographics.

Show item type in autocomplete suggestions list

When suggesting an autocomplete option, also show the option category in the dropdown (eg. command, npc, reference).

Add SRD spells

Text isn't selectable

It isn't possible to select text in the web interface.

Better UX on JS error

• Show a placeholder message if the dependencies take more than 1 second to load.
• Don't show the input form until you're ready to take input.
• Switch the placeholder message to an error if loading fails. (If possible.)

Display suggestions in web UI

Based on suggestions provided by the core crate, display autocomplete suggestions in the web UI. Find a workable/lightweight JS library to power this.

Add in-browser tests

Now that the web app is becoming more complex, it's time to start testing browser behaviour as well.

• #62
• Add Selenium (or similar) end-to-end tests.

Move Warforged behind a feature flag

Warforged are not part of the Open Game License, so need to be removed from the public build.

Implement location

• Implement commands to move between locations.
• Persist current location between sessions.
• Display current location on status bar.
• Remind user to update the time when moving between locations.
• #199

Rich CLI feature parity

Bring the rich CLI to feature parity with the light CLI (ie. take input, return output).

Out of scope: anything the light CLI does not currently support.

Fallback font is not set

Set the font to fall back to monospace when Source Code Pro is not available.

Show reminder on unsaved content

Show a reminder to the user when viewing content that has not yet been saved to the journal.

Save and load from local storage

• Implement: save Potato Johnson
• Load all data from local storage on page load
• Fetch autocomplete and loaded keys from both temp and cache

Rich CLI usability improvements

• #42
• Implement autocomplete for rich CLI

Autocomplete input

• #39
• #41
• #44
• Display suggestions in rich CLI
• #47

Chromium for Linux: Input form displays autocomplete suggestions

Steps to reproduce:

1. Go to initiative.sh.
2. Run about.
3. Type a.

Add terminal web font

Chrome for Android seems to want graphical glyphs to be 1.5 glyphs wide, ruining everything.

• Pick a web font.
• Use the web font.

Chrome for Android: Links have unnecessary padding

Links (about and changelog in the screenshot) have too much padding on Chrome for Android.

• Links rendered after page load lack the padding for some reason.
• TODO: Check Chrome for Linux.

Copy doesn't work

Since the text box is automatically focused on keypress, ^C doesn't work to copy output.

Disable focus for keypress with control modifier.

Ideation: case sensitivity

• Should autocorrect be case sensitive?
• Should reference data be case sensitive?
• Should reference data be capitalized? Convention is to capitalize spells but not other items.

Implement weather

• Generate weather based on current location (#79) and time of day (#78).
• Display current weather on status bar.
• Implement commands to override weather.

Add in-browser WASM tests

• Add WASM sanity tests that run in-browser (no JS coverage).
• Automate tests using various browsers: Chrome, Firefox, and Safari.

Recall generated content

Add the ability to recall content from short/long-term storage by typing its name.

Implement cache busting

The JS and CSS dependencies are not being immediately refreshed when initiative.sh is deployed, while the HTML is.

Configure Webpack to add a cachebusting query string or some such.

Ref: https://webpack.js.org/guides/caching/

Firefox Focus doesn't load

Firefox Focus will not load the command prompt. Suspect this is because Firefox Focus doesn't expose the IndexedDB API.

Regression of #94.

Replace non-OGL content

Remove all content not licensed under the Open Game License:

• #71
• #153
• Update all species to use BMI
• #109
• #151

Add reference data from SRD

• #51
• #73
• #111

Add `save` autocomplete

• Autocomplete sa to save [name]
• Autocomplete save P to save Potato Johnson