README file from
GithubAtlasVTT
A game system agnostic virtual tabletop for tabletop RPGs that runs inside Obsidian.
I built Atlas as part of my bachelor's thesis to give the TTRPG community a virtual tabletop that's open source, hackable, and free to use. Every file Atlas creates, every token, every map, every world you build, stays yours and stays local. It follows the same philosophy as Obsidian: your work lives on your machine, in formats you control, with no account and no server in between.
TTRPG worlds in my opinion are something very personal and players and DMs get attached to them. That attachment deserves better than a subscription and someone else's database. Atlas makes sure your creative output stays yours, just like a sheet of paper would.
Ease of use matters just as much to me. Atlas aims for a minimal, streamlined interface that feels native to Obsidian, with clear controls and simple workflows that keep your attention on the game.
AtlasVTT is desktop only for now
At the table
- Maps and grids: Build scenes from your own map images. Align square or hex grids manually or with automatic detection.
- Tokens and encounters: Import characters, move and resize tokens, and save groups as reusable encounters. Link creature notes with the optional Fantasy Statblocks plugin. Simple die syntax like 2d8+2 will be turned into a clickable dice roll.
- Fog and player view: Reveal the map as your players explore. Show a separate player window on a second screen while keeping GM information hidden.
- Drawing and notes: Sketch, add text, measure distances, and pin Markdown notes or other Atlas maps to locations.
- Dice and initiative: Roll dice, review the roll log, track turns, and keep counters and timers close at hand.
- Music and controls: Play audio from your vault, customise map hotkeys, and undo or redo map edits.
Your notes, right on the map
Pin an Obsidian markdown note or even another Atlas map to a location, then read and edit it in a floating panel without leaving the map. Keep room descriptions, session prep, and character details close at hand, with Obsidian's familiar note linking built in.
Organise your campaign
Keep scenes, maps, encounters, and characters together in collections. Use folders and tags to find what you need, then bring it onto the map.
Install
Requires Obsidian 1.8.7 or newer on desktop. Atlas VTT is available through Obsidian's community plugins.
- Open Settings → Community plugins and turn off Restricted mode if it is enabled.
- Select Browse and search for Atlas VTT.
- Select Install, then Enable.
Check for updates under Settings → Community plugins.
Want to try upcoming features early? Beta builds are available through BRAT, see docs/beta-testing.md.
Download main.js, manifest.json, and styles.css from a GitHub release. Place them in <your vault>/.obsidian/plugins/atlas-vtt/, then enable Atlas VTT under Settings → Community plugins.
Your first scene
- Run Atlas VTT: Open dashboard from the command palette.
- Use the + button in the asset manager to import a map image, then create a scene using that map.
- Align the grid with automatic detection or the manual alignment tool.
- Import tokens and place them on your scene.
- For a local game, open the player view and move it to your second screen.
Privacy and network use
Atlas works offline with files in your vault. It has no accounts, telemetry, or ads. Scenes are saved as .atlasmap files; asset tags and thumbnails live in the vault's hidden .atlas-data folder.
If you use an external image URL for a token or map background, or copy an externally hosted image from a note, Atlas downloads that image from the supplied address. Vault images require no network access. When you explicitly submit an issue report, Atlas sends it to https://srv1871379.hstgr.cloud/atlas/reports, which creates a public GitHub issue. See PRIVACY.md for details.
Help and contributing
Found a bug or have an idea? Run the Report an issue command inside Obsidian or use Settings → Atlas VTT → Help and feedback. Atlas fills in your versions and submits your report directly, without a GitHub account or a second form; see docs/reporting-issues.md. To contribute code, see CONTRIBUTING.md.
Requires Node.js 22 or newer.
npm ci
npm run build # production build into ./dist
npm run dev # watch build
npm test
The build also copies the plugin into local test vaults when they are present.
Credits and license
Widget icons, map pin icons, light marker icons, the token icon and the end-combat icon are by Lorc, Delapouite, Skoll, sbed, Carl Olsen, and Caro Asercion from game-icons.net, under CC BY 3.0. Their backgrounds were removed and glyphs recoloured. The starter class tokens are icons by Sketch Studio, commissioned by Maatlock of maatlockstavern.com, under CC BY 4.0, redrawn as pencil sketches on parchment. Other asset and library credits are in THIRD_PARTY_NOTICES.md.
Atlas VTT is free software. Copyright (C) 2025-2026 Fabian Urbanek.
You can use it for any purpose, including streamed, recorded, and paid games. You can redistribute and modify it under the terms of the GNU Affero General Public License, version 3 (AGPL-3.0-only) as published by the Free Software Foundation. If you distribute Atlas VTT or a modified version, or let others use a modified version over a network, you must make the complete source code available under the same license. It is distributed in the hope that it will be useful, but without any warranty; see the license for details.
Additional permission under GNU AGPL version 3 section 7: if you modify this program, or any covered work, by linking or combining it with Obsidian (or a modified version of that program), the licensors of this program grant you additional permission to convey the resulting work.
Releases up to and including 0.1.6 were published under the PolyForm Noncommercial License 1.0.0. If you want to use the code under different terms, contact Fabian Urbanek.
Your campaign content remains yours. Third-party components retain their own licenses.