Text Mapper

What is Text Mapper?

Text Mapper is a text-based format for creating hex maps. Each map is defined in a markdown file using a code block with the language text-mapper. The map renders as an interactive SVG that you can pan and zoom.

Map File Structure:

Frontmatter with mapId (e.g., mapId: map-1234)
A text-mapper code block containing hex definitions
The map renders automatically when viewed

Hex Coordinate System:

Hexes use a coordinate system with X and Y values
Coordinates can be formatted as:
- 00.00 or -38.15 (dot separated)
- 00 00 or -38 15 (space separated)
- 0000 or 3815 (4 digits, both positive)
- 00-01 or -01-01 (hyphen indicates negative y coordinate)
Important: Hyphens are NEVER separators - they are ALWAYS part of negative numbers
- 00-01 means x=00, y=-01 (the dash is the negative sign for y)
- -01-01 means x=-01, y=-01 (both are negative)
Each hex has 6 adjacent neighbors (positions 1-6)

Map Themes

Maps can use three different themes that affect terrain/district types and visual styling:

Terrain Theme - For wilderness travel (forest, plains, mountain, swamp, etc.)
City Theme - For fantasy urban travel (central, market, residential, slums, etc.)
Modern Theme - For modern urban travel (high-class, financial, middle-class, downtown, tech, etc.)

Creating a Map

Using the Travel Tab (Automated)

Open the Tag and Tally sidebar
Select the "Travel" tab
Choose your theme (Terrain, City, or Modern)
Click the "New Map" button

The system automatically:

Generates a unique map ID (e.g., map-1234)
Creates a new markdown file named map-1234.md
Rolls for starting terrain/district from the appropriate table
Rolls for starting level (1d4+2, resulting in level 3-6)
Rolls for a feature (terrain-feature or modern-feature table)
Rolls for a landmark (landmark-type table)
- For City theme: If landmark-type is "Geographic", automatically rolls on city-geographic-landmark table (1d20)
Rolls for faction (Modern theme only): Rolls 2d6 for faction presence
- 2-3: New Faction HQ
- 4-5: Known Faction HQ
- 6-12: No Faction HQ
Generates terrain for all 6 adjacent hexes using adjacent terrain tables
Creates the text-mapper code block with all hex definitions
Creates a hex note for the starting hex (00.00)

Creating a Map Manually

To create a map manually, you'll need to make the following rolls and then create the map file:

Roll for starting terrain/district:
- Terrain theme: Roll on terrain table (1d8)
- City theme (fantasy): Roll on fantasy-districts table (2d8)
- Modern theme: Roll on districts table (2d8)
Roll for starting level:
- Roll 1d4+2 (results in level 3-6)
Roll for feature:
- Terrain theme: Roll on terrain-feature table (1d12)
- City theme (fantasy): Roll on modern-feature table (1d12)
- Modern theme: Roll on modern-feature table (1d12)
Roll for landmark:
- Roll on landmark-type table (3d6)
- For City theme only: If the result is "Geographic", roll on city-geographic-landmark table (1d20) to determine the specific landmark type
Roll for faction (Modern theme only):
- Roll 2d6:
  - 2-3: New Faction HQ
  - 4-5: Known Faction HQ
  - 6-12: No Faction HQ
Roll terrain for all 6 adjacent hexes:
- For each of the 6 adjacent hexes (positions 1-6), roll on the appropriate adjacent table:
  - Terrain theme: terrain-adjacent-{terrain} table (2d6), where {terrain} is the starting terrain type (e.g., terrain-adjacent-forest, terrain-adjacent-plains)
  - City theme (fantasy): fantasy-adjacent-{district} table (2d6), where {district} is the starting district type in lowercase with spaces replaced by hyphens (e.g., fantasy-adjacent-noble, fantasy-adjacent-market)
  - Modern theme: modern-adjacent-{district} table (2d6), where {district} is the starting district type in lowercase with spaces replaced by hyphens (e.g., modern-adjacent-high-class, modern-adjacent-middle-class)
Create a new markdown file with a unique name (e.g., map-1234.md)
Add frontmatter:
```
---
mapId: map-1234
---
```

Create a text-mapper code block:

```text-mapper
id map-1234
option coordinates-format {X}.{Y}
option travel-theme terrain

0000 forest-bg forest easy level-3
0100 plains-bg plains
-0100 mountain-bg mountain
0010 swamp-bg swamp
00-10 forest-bg forest
-1000 plains-bg plains
```

Hex Entry Format: Each hex is defined on a single line:

XXYY terrain-bg terrain [difficulty] [level-X] ["XXYY|XX.YY"]

Where:

XXYY - Hex coordinates (4 digits, e.g., 0000, 0405, 00-01 for negative y, -01-01 for both negative)
- Note: Hyphens are part of negative numbers, not separators. 00-01 means x=00, y=-01
terrain-bg - Background color tag (e.g., forest-bg, plains-bg)
terrain - Terrain type (e.g., forest, plains, mountain)
difficulty - Optional: easy, rough, or dangerous
level-X - Optional: Level tag (e.g., level-3, level-5)
"XXYY|XX.YY" - Optional: Link to hex note file

Create hex notes (optional but recommended):

Create a folder named after your map (e.g., map-1234/)
Create a note file for each hex (e.g., 00.00.md)

Add frontmatter with hex information:

---
hex: "00.00"
mapId: "map-1234"
level: 3
terrain: "Forest"
feature: "Dense undergrowth (Rough)"
landmark: "Settlement"
event: "Wandering Creatures"
exits:
  - "01.00"
  - "-01.00"
  - "00.10"
  - "00.-10"
  - "-10.00"
  - "10.00"
---

Text Mapper Hex Format

Basic Format:

XXYY terrain-bg terrain

With Difficulty:

XXYY terrain-bg terrain easy
XXYY terrain-bg terrain rough
XXYY terrain-bg terrain dangerous

With Level:

XXYY terrain-bg terrain level-3
XXYY terrain-bg terrain easy level-5

With Hex Note Link:

XXYY terrain-bg terrain level-3 "0000|00.00"

Complete Example:

0000 forest-bg forest easy level-3 "0000|00.00"
0100 plains-bg plains
-0100 mountain-bg mountain level-4
00-01 swamp-bg swamp "00-01|00.-01"
-01-01 forest-bg forest "-01-01|-01.-01"

Note on Negative Coordinates:

Hyphens are part of negative numbers, not separators
00-01 means x=00, y=-01 (the dash is the negative sign for y)
-01-01 means x=-01, y=-01 (both coordinates are negative)

Road Path (Movement Trail): Roads are defined as paths connecting hex coordinates:

road path 0000 0100 0200

This creates a visual dashed line showing the path of travel between those hexes.

Barriers: Barriers can be added to hex sides to indicate impassable terrain, cliffs, or other obstacles. Add barrier1 through barrier6 to a hex definition to place barriers on specific sides:

0000 forest-bg forest barrier1 barrier3

Barrier positions correspond to hex directions:

barrier1 - Top (position 1)
barrier2 - Top-right (position 2)
barrier3 - Bottom-right (position 3)
barrier4 - Bottom (position 4)
barrier5 - Bottom-left (position 5)
barrier6 - Top-left (position 6)

Example with barriers:

0000 forest-bg forest barrier1 barrier4
0100 plains-bg plains barrier3

This places barriers on the top and bottom of the first hex, and on the bottom-right of the second hex.

Faction Overlays

Faction overlays allow you to visualize faction control areas on your map. You assign a color (0-9) and a ring size (0-10) to each faction, and overlays show transparent colored backgrounds with darker borders to indicate faction influence.

Faction Syntax

Add faction attributes to hex definitions using faction-(color)-(ring) where:

color is a number from 0 to 9 (10 different colors available)
ring is a number from 0 to 10 (number of rings of coverage)

XXYY terrain-bg terrain faction-0-1
XXYY terrain-bg terrain faction-1-2
XXYY terrain-bg terrain faction-2-0

Faction Coverage:

faction-X-0 - Covers only the hex it's on (1 hex)
faction-X-1 - Covers the hex plus 1 ring of neighbors (7 hexes total)
faction-X-2 - Covers the hex plus 2 rings (19 hexes total)
faction-X-3 - Covers the hex plus 3 rings (37 hexes total)
...and so on up to faction-X-10 (331 hexes total)

Where X is the color number (0-9).

Note: Ring numbers are limited to 0-10 to match other game element limits. Color numbers are limited to 0-9 (10 colors total).

Visual Appearance

Transparent Backgrounds: Each faction color gets a unique color with 30% opacity
Darker Borders: Borders are fully opaque (100%) and 4px wide for clear visibility
Color Assignment: Colors are assigned by the color number (0-9) from a predefined palette:
- Color 0 = Red (#FF6B6B)
- Color 1 = Teal (#4ECDC4)
- Color 2 = Blue (#45B7D1)
- Color 3 = Light Orange (#FFA07A)
- Color 4 = Mint (#98D8C8)
- Color 5 = Yellow (#F7DC6F)
- Color 6 = Purple (#BB8FCE)
- Color 7 = Sky Blue (#85C1E2)
- Color 8 = Orange (#F8B739)
- Color 9 = Green (#52BE80)
Contested Areas: Hexes covered by multiple different colors appear in gray (#888888)

Examples

Single Faction:

0000 plains-bg plains faction-0-0
0100 forest-bg forest faction-1-1

Multiple Factions with Same Color:

0000 plains-bg plains faction-0-1
0100 forest-bg forest faction-0-1

Multiple Factions with Different Colors:

0000 plains-bg plains faction-0-1
0100 forest-bg forest faction-1-2
0200 mountain-bg mountain faction-2-0

Overlapping Control (Contested):

0000 plains-bg plains faction-0-1
0100 forest-bg forest faction-1-1

In the last example, hex 0100 would be contested (covered by both color 0 and color 1) and appear in gray.

Toggling Faction Overlays

You can hide or show faction overlays using the right-click context menu:

Right-click anywhere on the map canvas
If the map has faction overlays, you'll see a menu option:
- "Hide Faction Overlays" (when overlays are visible) - Click to hide all faction overlays
- "Show Faction Overlays" (when overlays are hidden) - Click to show all faction overlays
The visibility preference is saved automatically and will persist across Obsidian restarts
When you toggle visibility, it applies to all open maps simultaneously

Note: The toggle option only appears in the context menu if the map actually contains faction overlays.

Important Notes

Faction overlays render on top of terrain backgrounds but below paths and labels
Overlays are rendered for all hexes within the coverage area, even if those hexes aren't explicitly defined in your map
This allows you to see faction control extending into unexplored territory
Ring numbers above 10 are ignored
Color numbers above 9 are ignored
Faction overlay visibility is a global setting that applies to all maps

Traveling on a Hex Map

Using the Travel Tab

Select a Map
- Choose from the dropdown of available maps in your vault
- Maps are identified by their mapId from the frontmatter
- If a map has option travel-theme in its text-mapper code block, the theme dropdown will automatically update to match when the map is selected
Enter Starting Position
- Enter hex coordinate in the input field (formats: 00.00, 0000, 00 00, or 00-01 for negative coordinates)
- Note: Hyphens are part of negative numbers, not separators. 00-01 means x=00, y=-01
- Click "Locate" to view hex information without moving
- The display shows: Level, Terrain/District, Feature, Landmark, Event, Faction (Modern theme only), and Exits
Moving Between Hexes
- Enter destination hex coordinate
- Click "Move" button
- System automatically:
  - Updates the road path in the map (creates a visual trail showing your movement)
  - Tracks your movement history
  - Rolls for Event: Each time you enter a hex, rolls on event table (3d6):
    - Terrain/City theme: event-type table
    - Modern theme: modern-event-type table
  - Updates the displayed hex information
Populating a Hex
- When you move to a hex, click "Populate" button
- System automatically:
  - Generates Level: Based on previous hex level using dice formulas:
    - Leaving Level 1-2: Roll 1d4+2 (Level 3-6)
    - Leaving Level 3-4: Roll 1d6+2 (Level 3-8)
    - Leaving Level 5-6: Roll 1d8+2 (Level 3-10)
    - Leaving Level 7-10: Roll 1d10+2 (Level 3-10, 11-12 = Level 10)
  - Generates Terrain/District: If hex is empty or has "ghost" terrain, rolls from main terrain/district table
  - Generates Feature: Rolls from terrain-feature or modern-feature table (may include difficulty: Easy, Rough, or Dangerous)
  - Generates Landmark: Rolls from landmark-type table (3d6)
    - City theme only: If landmark-type is "Geographic", automatically rolls on city-geographic-landmark table (1d20)
  - Generates Faction (Modern theme only): Rolls 2d6 for faction presence
    - 2-3: New Faction HQ
    - 4-5: Known Faction HQ
    - 6-12: No Faction HQ
  - Generates Adjacent Hexes: For any empty adjacent hexes, rolls terrain using adjacent terrain tables
  - Creates/Updates Hex Note: Creates a note file with all hex information
  - Updates Map: Adds terrain tags, difficulty, and level to the map
Hex Notes
- Automatically created when you populate a hex
- Stored in a folder named after the map (e.g., map-1234/)
- File named by coordinate (e.g., 00.00.md, 04.05.md)
- Contains frontmatter with:
  - hex: Coordinate in display format (e.g., "00.00")
  - mapId: Reference to the map
  - level: Hex level (number)
  - terrain: Terrain or district type
  - feature: Special feature (text, may include difficulty)
  - landmark: Special location or discovery (text, generated when hex is populated)
  - event: Event that occurs when entering the hex (text, rolled each time you enter)
  - faction: Faction presence (Modern theme only): "New Faction HQ", "Known Faction HQ", or "No Faction HQ"
  - exits: Array of adjacent hex coordinates
- Content section displays the information in readable format

Manual Travel Process

If you want to travel manually without the plugin:

Track Your Position
- Keep note of your current hex coordinate
- Update as you move between hexes
When Entering a New Hex:
- Roll for level using the dice formula based on previous hex level (see Travel mechanics)
- Roll for terrain/district if hex is undefined:
  - Terrain theme: Roll on terrain table (1d8)
  - City theme (fantasy): Roll on fantasy-districts table (2d8)
  - Modern theme: Roll on districts table (2d8)
- Roll for feature:
  - Terrain theme: Roll on terrain-feature table (1d12)
  - City theme (fantasy): Roll on modern-feature table (1d12)
  - Modern theme: Roll on modern-feature table (1d12)
- Roll for landmark (when first populating the hex): Roll on landmark-type table (3d6)
  - City theme only: If the result is "Geographic", roll on city-geographic-landmark table (1d20)
- Roll for event (each time you enter the hex):
  - Terrain/City theme: Roll on event-type table (3d6)
  - Modern theme: Roll on modern-event-type table (3d6)
- Roll for faction (Modern theme only, when first populating the hex): Roll 2d6
  - 2-3: New Faction HQ
  - 4-5: Known Faction HQ
  - 6-12: No Faction HQ
- Roll terrain for any empty adjacent hexes:
  - Terrain theme: terrain-adjacent-{terrain} table (2d6)
  - City theme (fantasy): fantasy-adjacent-{district} table (2d6)
  - Modern theme: modern-adjacent-{district} table (2d6)
Update the Map File:
- Edit the text-mapper code block
- Add or update the hex line with terrain, difficulty, and level tags
- Update road path if tracking movement visually
Create/Update Hex Note:
- Create note file in the map's folder
- Add frontmatter with all hex information
- Add content describing the hex

Movement Tools

Direction Calculator:

Select direction (1-6) representing the 6 hex directions
Enter distance (number of hexes to move)
Click "Calculate" to determine destination coordinate
Option to add calculated hex to map as "ghost" terrain for future exploration

Random Movement:

Click "Random" button
System rolls random direction (1d6) and random distance type
Distance types: Short (1d6), Standard (2d6), or Long (3d6)
Automatically fills direction and distance fields

Map Interactions

Right-Click Context Menu

Right-clicking anywhere on the map canvas opens a context menu with the following options:

Re-center - Resets the map view to center on the map content
Save canvas as PNG - Exports the current map view as a PNG image file
Hide/Show Faction Overlays - Toggles the visibility of faction overlays (only appears if the map has faction overlays)
- The visibility preference is saved automatically and persists across Obsidian restarts
- When toggled, it applies to all open maps simultaneously

Pan and Zoom

Pan: Click and drag to move around the map
Zoom: Use the mouse wheel to zoom in and out
Double-click: Double-click anywhere on the map to re-center the view

Table of Contents

Text Mapper

Text Mapper

What is Text Mapper?

Map Themes

Creating a Map

Using the Travel Tab (Automated)

Creating a Map Manually

Text Mapper Hex Format

Faction Overlays

Faction Syntax

Visual Appearance

Examples

Toggling Faction Overlays

Important Notes

Traveling on a Hex Map

Using the Travel Tab

Manual Travel Process

Movement Tools

Map Interactions

Right-Click Context Menu

Pan and Zoom