Create hex maps in Obsidian using simple text descriptions. This plugin is a TypeScript port of Alex Schroeder's Text Mapper, enhanced with additional features for Obsidian integration. It is forked from the original repo with several improvements and additional features.
Create a map by inserting a text-mapper code block into an obsidian file:
0101 forest "Forest Grove"
0102 mountain "High Peak"
0103 castle "King's Keep"
0102-0103 trail "Mountain Path"
XXYY type "label": Place a terrain type at coordinates XX,YY with optional labelXXYY type "link|label": Add a clickable link to the labelXXYY-XXZZ type: Create a sequence of identical hexes (horizontal or vertical)
option horizontal: Switch to pointy-top hexes (default is flat-top)option coordinates-format {X}.{Y}: Customize coordinate display formatoption swap-even-odd: Change hex offset patternoption global: Use global element IDsoption no-underline: Remove underline from links in hexesoption hexflower A center:1010: map tile numbers to a letter format in a hexflower spiral centered on a specific tileoption counterclockwise: arrange the hexflower pattern counterclockwiseoption flower-start northwest: allows the flower to spiral out from any point, e.g. 'northwest' (12'oclock is due north)option subhex-relabel: relabels all border hexes automatically based on cardinal and rotation directionoption map AG=1008: map a specific hexnumber to a different name
- Add labels with
"text"after terrain type - Create paths between hexes using
trailorriver - Customize path contour (a sinusoidal wave) with:
frequency=N: Number of wave cycles (default: 1)depth=N: Wave amplitude (default: 0.1)rate=N: Wave smoothness (default: 0.1)
- Example path:
0102-0304 trail frequency=2 depth=0.3 rate=0.4 "Mountain Path" - Customize label size by adding a number:
"Big Label" 30 - Add Obsidian links with
"PageName|Display Text"
The plugin includes three tilesets:
0101 forest "Forest"
0102 castle "Castle"
0103 mountain "Mountain"
0101-0103 river
0101 apoc-ruin "Ruins"
0102 apoc-fort "Fortress"
0103 apoc-volcano "Volcano"
0101 planet "Earth"
0102 spacestation "Alpha Base"
0103 asteroidfield "Danger Zone"
You may enable/disable tilesets in the plugin settings. You may use more than one tileset at a time, though be on the lookout for conflicts between them!
Click "Download Map" above any rendered map to export as a high-quality PNG file.
Create custom tilesets in your vault:
- Create a tilesets folder
- Configure folder path in plugin settings
- Add tileset definition files:
Example of a minimal custom tileset in a custom.ts file:
// custom-tileset.ts
export const TEST_TILESET = {
name: "test",
description: "A custom tileset example",
defaultAttributes: "stroke=\"black\" stroke-width=\"1\"",
tiles: {
blue: {
id: "blue",
attributes: "fill=\"blue\"",
paths: [],
svgDefs: []
},
star: {
id: "star",
paths: [],
svgDefs: [
'\n\n'
]
}
}
};Simple hex fills just need:
typescriptCopy{
id: "name",
attributes: "fill=\"color\"",
paths: [],
svgDefs: []
}Custom shapes need:
typescriptCopy{
id: "name",
paths: [],
svgDefs: [
'<g id="name">\n<your svg here/>\n</g>'
]
}SVG coordinates should be centered around (0,0) with appropriate scale (around -20 to 20 seems good)
Keep the empty paths array even when not used.
Default fantasy-themed tileset with terrain and settlements.
white: Paper whitelight-soil,soil,dark-soil: Agricultural landsrock,dust,sand: Arid/desert terrainwater,ocean: Water bodieslight-grey,grey,dark-grey: Wetland variationsblue-green: Swamp/marsh colorpoisoned: Corrupted terrainlight-green,green,dark-green: Forest variations
tree,trees,forest: Deciduous woodlandbush,bushes,brushland: Shrublandfir,firs,fir-forest: Coniferous woodlandhill: Single hillmountain: Single mountainmountains: Mountain rangeforest-hill,forest-mountain,forest-mountains: Forested elevationsfir-hill,fir-mountain,fir-mountains: Conifer-covered elevationsfields: Agricultural patterngrass: Grasslandmarsh: Marshlandswamp,swamp2: Swamplanddesert: Desert patternlake: Water body
thorp: Smallest settlementvillage: Small settlement with housetown: Medium settlementlarge-town: Large settlementcity: Largest settlementkeep: Defensive structuretower: Watchtowercastle: Fortified settlementshrine: Religious sitelaw: Lawful settlementchaos: Chaotic settlement
trail: Path or trackriver: Water routecanyon: Deep ravine
Post-apocalyptic themed terrain and landmarks.
apoc-sand,apoc-coast,apoc-sea: Coastal featuresapoc-desert: Desert terrainapoc-red: Danger zoneapoc-debug: Debug overlay
apoc-tundra: Frozen wastelandapoc-wetland: Marsh areaapoc-swamp: Swampy terrainapoc-forest: Dense woodlandapoc-woodland: Light forestapoc-hill: Elevated terrainapoc-grass: Grasslandapoc-mountain: Mountainapoc-jungle: Dense vegetationapoc-volcano: Active volcano
apoc-fort: Fortified positionapoc-ruin: Destroyed structureapoc-pyramid: Ancient structureapoc-cave: Underground entranceapoc-fin: Irradiated zone
apoc-road: Travel routeapoc-river: Water courseapoc-border: Territory boundary
Science fiction themed tileset for space maps.
void: Empty spaceoccupied-space: Controlled territoryasteroid-space: Asteroid field regionnebula-space: Nebula regionplasma-space: Plasma storm regionzone-space: Special zone overlay
star-yellow,star-blue,star-red: Different star typesplanet: Default planetplanet-terran: Earth-like worldplanet-gas: Gas giantplanet-ice: Ice worldplanet-rock: Rocky planetplanet-lava: Volcanic worlddeadplanet: Lifeless world
spacestation: Orbital facilityasteroidfield: Dense asteroid clusterhazard: Danger zoneoutpost: Small stationcolony: Established settlementstarport: Major space port
Usage example:
use tileset gnomeyland
mountain forest castle
river
- Added support for hex sequences to create consecutive hexes with the same terrain. This allows for more concise map definitions:
- Horizontal sequences:
1020-1023 voidcreates four void hexes at 1020, 1021, 1022, and 1023 - Vertical sequences:
1020-1040 voidcreates three void hexes at 1020, 1030, and 1040 - The format is
XXYY-XXYY typewhere XX is the x-coordinate and YY is the y-coordinate
- Horizontal sequences:
- This port does not include support for square grids, verticality, or the
includecommand. - I have included the Gnomeyland Map Icons created by Gregory B. MacKenzie by default. No other icon set is supported.
- Added support for "pointy top" hexes. To switch between modes, simply add
option horizontalto your block. - Added support for links in labels. To add a link, use the following syntax:
link|label. The link will be applied to the entire label. - Added the ability to swap even and odd positions. With flat top hexes, for a hex (x, y), (x+1, y) is to the to the southeast if x is odd and to the northeast if x is even. Adding
option swap-even-oddwill reverse this: (x+1, y) is to the to the southeast if x is even and to the northeast if x is odd. This swapped numbering scheme is compatible with maps like the one for Wolves Upon the Coast. - Added support for very simple coordinate formatting. Use
option coordinates-format.- The formatter will replace
{X}with the x value and{Y}with the Y value. - EXAMPLE: To render (4, 5) as
04.05, useoption coordinates-format {X}.{Y}.
- The formatter will replace
- Namespaced all element IDs: HTML/SVG assumes that a DOM element
idis unique. Prior to this change, we did not ensure unique IDs, which led to issues when there was more than one map in the same document.- You can turn off namespacing by using
option global.
- You can turn off namespacing by using
I have used this with the output of the "Alpine" maps generated by the original Text Mapper. It takes a while to render very large maps, so be patient. But it works! Here's an example that was generated in Obsidian:
- Text Mapper: https://campaignwiki.org/text-mapper
- Alex Schroeder's blog explaining how to use Text Mapper: https://alexschroeder.ch/wiki/Text_Mapper
- Perl source for Text Mapper: https://alexschroeder.ch/cgit/text-mapper/
- Clone this repo.
npm ioryarnto install dependenciesnpm run devto start compilation in watch mode.
This is paraphrasing information from Obsidian's documentation: Community plugins and Build plugins.
- Copy over
main.js,styles.css,manifest.jsonto your vaultVaultFolder/.obsidian/plugins/text-mapper/.- If you ran
npm run dev, these will be in the root folder. - i.e.
cp main.js styles.css manifest.json ~/Dropbox/Obsidian/.obsidian/plugins/text-mapper - You can get a prebuilt version in the releases tab
- If you ran
- In Obsidian, navigate to Preferences > Community plugins. Toggle
Text Mapperon.
This is pulled from: https://campaignwiki.org/contrib/gnomeyland-example.txt
However, since Gnomeyland icons are included by default, the include gnomeyland.txt line is not required. The following block should produce output similar to this:
```text-mapper
0101 tree "tree"
0102 trees "trees"
0103 forest "forest"
0201 bush "bush"
0202 bushes "bushes"
0203 brushland "brushland"
0301 fir "fir"
0302 firs "firs"
0303 fir-forest "fir-forest"
0401 hill "hill"
0402 mountain "mountain"
0403 mountains "mountains"
0501 fir-hill "fir-hill"
0502 fir-mountain "fir-mountain"
0503 fir-mountains "fir-mountains"
0601 forest-hill "forest-hill"
0602 forest-mountain "forest-mountain"
0603 forest-mountains "forest-mountains"
0604 fields "fields"
0605 desert "desert"
0701 grass "grass"
0702 marsh "marsh"
0703 swamp "swamp"
0704 lake "lake"
0705 shrine "shrine"
0801 keep "keep"
0802 tower "tower"
0803 castle "castle"
0804 law "law"
0805 chaos "chaos"
0806 swamp2 "swamp2"
0901 thorp "thorp"
0902 village "village"
0903 town "town"
0904 large-town "large-town"
0905 city "city"
1001 dust "dust"
1002 light-soil "light-soil"
1003 soil "soil"
1004 dark-soil "dark-soil"
1005 sand "sand"
1006 rock "rock"
1101 light-green "light-green"
1102 green "green"
1103 dark-green "dark-green"
1104 blue-green "blue-green"
1105 water "water"
1106 ocean "ocean"
1201 light-grey "light-grey"
1202 grey "grey"
1203 dark-grey "dark-grey"
1204 poisoned "poisoned"
1205 zone "zone"
# trail example and larger label example
0106 dark-green fir-forest "Deep Forest" 30
0206 green bushes
0306 soil keep "The Keep"
0406 light-soil town "Safe Town"
0005-0506 trail "The Auld Trail" 30%
# larger label example
other <text x="100" y="1170" font-size="40pt">Small Example</text>
```