Solo TTRPG Notation

A plugin for recording and tracking solo tabletop RPG sessions using a standardized notation system.

What is Solo TTRPG Notation?

Solo TTRPG Notation is a lightweight text-based system for documenting your solo TTRPG sessions. It lets you:

• Record actions, oracle questions, and dice rolls in a consistent format
• Tag NPCs, locations, and story threads as they appear
• Track progress with clocks, tracks, and timers
• Review your campaign history with powerful browsing tools

All notation lives in code blocks within your markdown files, keeping your narrative text clean and readable.

Features

📊 Six Interactive Views

Access all views from the left sidebar ribbon icons or the command palette:

• Campaign Dashboard (🎲) - Overview of all campaigns with statistics
• Tag Browser (🏷️) - Browse NPCs, Locations, Threads, and References
• Progress Tracker (🕐) - Visual clocks, tracks, and timers
• All Elements Reference (🗄️) - Complete searchable reference
• Random Events (🎲🎲) - All table lookups and generator results
• Meta Notes (📝) - Out-of-character notes organized by category

⌨️ Quick Commands

• Insert Campaign Template - Start a new campaign file
• Insert Session Template - Add a new session
• Insert Scene Template - Add a new scene
• Reindex Current Campaign - Refresh the current file's data
• Reindex All Campaigns - Refresh all campaign data

🔍 Automatic Indexing

The plugin automatically tracks:

• NPCs and their mentions
• Locations visited
• Story threads (open/closed/abandoned)
• Progress trackers (clocks, tracks, timers, events)
• Table lookups and generator results
• Meta notes and reflections

Getting Started

1. Create Your First Campaign

Use the command palette (Ctrl/Cmd + P) and select "Insert Campaign Template". This creates:

---
type: solo_campaign
ruleset: Your System
genre: Fantasy
created: 2025-12-31
last_update: 2025-12-31
---

# Campaign Title

Campaign description...

## Session 1
*Date: 2025-12-31 | Duration: 2h*

### S1 *Opening scene*

Your adventure begins...

2. Write Your First Scene

All notation goes inside code blocks (triple backticks). Outside the code blocks, write your narrative:

### S1 *Dark alley, midnight*

```
> Sneak past the guards
d: Stealth d6=4 vs TN 5 => Fail
=> My foot kicks a barrel. [E:AlertClock 1/6]

? Do they see me?
-> No, but... (d6=3)
=> They're suspicious. [N:Guard|watchful]
```

The guard's torch sweeps across the alley. I press myself against the wall.

```
> Wait for them to pass
tbl: d100=42 => "A distant scream distracts them"
=> Perfect timing. [Thread:Investigation|Open]
```

3. Open the Views

Click the dice icon (🎲) in the left sidebar to open the Campaign Dashboard, or use the command palette to open any view.

Notation Reference

Core Symbols

Tags & Trackers

NPCs & Locations

[N:Name]              - First mention of an NPC
[N:Name|tags]         - NPC with descriptive tags
[#N:Name]             - Reference existing NPC
[#N:Name|tag]         - Reference with additional context

[L:Place]             - First mention of a location
[L:Place|tags]        - Location with tags
[#L:Place]            - Reference existing location
[#L:Place|tag]        - Reference with context

Story Threads

[Thread:Name|Open]        - New/active thread
[Thread:Name|Closed]      - Resolved thread
[Thread:Name|Abandoned]   - Dropped thread

Progress Trackers

[Clock:Name X/Y]      - Danger/pressure (fills up = bad)
[Track:Name X/Y]      - Progress (fills up = goal reached)
[Timer:Name X]        - Countdown (reaches 0 = trigger)
[E:Name X/Y]          - Event countdown

Player Characters

[PC:Name]                     - Simple PC mention
[PC:Name|warrior|hero]        - PC with tags
[PC:Name|HP:12|Armor:3]      - PC with stat-like tags
[PC:Name|warrior|HP:12]       - PC with mixed tags

Random Generation

Table Lookups

tbl: d100=42 => "A merchant arrives"
tbl: Weather=Rain => "Heavy downpour begins"

Generators

gen: Mythic => "Gratify Fears"
gen: MUNE => "And also... (Positive)"

Meta Notes

Meta notes are out-of-character observations that don't appear in References:

(note: Remember the shopkeeper's hint)
(reflection: This scene dragged, need more action)
(house rule: Using advantage on group checks)
(reminder: Follow up on the missing sword)
(question: Did I mark XP for this session?)

Views Guide

Campaign Dashboard

Shows all campaigns with:

• Session and scene counts
• NPC, location, and thread statistics
• Active vs closed threads
• Progress tracker counts
• Click any campaign to open its file

Tag Browser

Four tabs for browsing game elements:

NPCs Tab

• All characters encountered
• Tags and descriptive labels
• Mention count and last appearance
• Click to jump to first mention

Locations Tab

• All places visited
• Geographic tags
• Visit history
• Click to navigate to location

Threads Tab

• Story threads by status (Open/Closed/Abandoned)
• Color-coded badges
• Timeline of mentions
• Click to jump to thread origin

References Tab

• All uses of [#N:Name] and [#L:Name]
• Shows reference type (NPC/Location)
• Mention count and context
• Click to jump to reference

Progress Tracker

Visual representation of all progress elements:

Clocks - Fill as danger increases (e.g., Alert Clock, Enemy Reinforcements) Tracks - Fill as progress is made (e.g., Quest Progress, Relationship Building) Timers - Count down to zero (e.g., Time Until Dawn, Potion Duration) Events - Special countdown trackers

Filter by type, search by name, and click any tracker to jump to its latest mention.

All Elements Reference

Complete searchable database of everything in your campaigns:

• All NPCs, locations, threads, and trackers in one view
• Type filters (NPC, Location, Thread, Clock, Track, Timer)
• Full-text search
• Sort and browse by campaign

Random Events

Chronological view of all randomization:

• Table lookups (tbl:)
• Generator results (gen:)
• Filter by type (Tables/Generators)
• Search by content
• Review your oracle consultation history

Meta Notes

Your out-of-character notes organized by category:

• Notes - General observations
• Reflections - Session reviews
• House Rules - Custom mechanics
• Reminders - Things to follow up
• Questions - Unresolved queries

Filter by category and search across all notes.

Configuration

Open Settings → Solo TTRPG Notation to configure:

General

• Enable/disable automatic indexing
• Control when files are parsed

Templates

• Use default templates or specify custom template files
• Customize campaign, session, and scene templates

Display

• Choose progress bar style (bars, circles, or segments)
• Set theme (auto, light, or dark)

Advanced

• Enable debug mode for troubleshooting
• View index statistics
• Force reindex all campaigns

Tips & Best practices

Organization

One campaign per file - Each campaign file should contain all sessions for that campaign.

Consistent session numbering - Use ## Session 1, ## Session 2, etc. (the plugin looks for this format).

Scene IDs - Use ### S1, ### S2, etc. for simple scenes, or ### S1a, ### T2-S3 for more complex tracking.

Notation

Code blocks are required - All notation MUST be inside triple backtick code blocks. Narrative text goes outside.

First mention vs references - Use [N:Name] when first introducing an NPC, then [#N:Name] for later mentions.

Tags are optional - [N:Bob] and [N:Bob|merchant|friendly] both work. Tags help you remember context.

Update trackers - When a clock advances, write a new line: [Clock:Alert 2/6]. The plugin tracks the latest value.

Workflow

1. Start each session with the session template (date and duration)
2. Write notation in code blocks as you play
3. Add narrative outside code blocks after the scene
4. Review the dashboard to see campaign statistics
5. Use the Tag Browser to remember NPCs and locations
6. Check Progress Tracker to see active clocks and tracks

Troubleshooting

Elements not appearing in views?

• Make sure notation is inside code blocks (```)
• Check that session headers use ## Session N format
• Use Reindex Current Campaign command to refresh
• Enable debug mode in settings to see parsing errors

Views not updating?

• The plugin parses files on load and when modified
• Use the refresh button (↻) in any view
• Try Reindex All Campaigns from command palette

Performance issues with large vaults?

• Disable automatic indexing in settings
• Manually index campaigns when needed
• Use the file explorer to isolate campaign files

Support

• Issues & Bugs: GitHub Issues
• Notation Spec: See Solo TTRPG Notation
• Examples: Check the examples/ folder for sample campaigns

Credits

This plugin implements the Solo TTRPG Notation system (v2.0).

The notation system is inspired by the Sigil Standard.

License

MIT License - Free to use and modify.

Happy solo gaming! 🎲

For developer documentation, see CONTRIBUTING.md in the GitHub repository.