The open-source, high-performance standard for interconnected TTRPG campaign mapping.
The UVTT v2 specification provides a modern, robust, and extensible framework for TTRPG map data. Designed to replace the legacy 2D-only flat formats (.dd2vtt / .df2vtt), UVTT v2 enables verticality, complex spatial triggers, hardware-accelerated rendering, and multi-file campaign networking.
Legacy V1 standards were ground-breaking, but they suffer from significant architectural bottlenecks. UVTT v2 solves these by treating maps not as static images, but as nodes within a Topological Spatial Network.
uvtt-v2-workspace/ # Open the parent folder directly in VS Code
├── .github/ # Automated repository workflows and templates
│ └── workflows/
│ └── validate-uvtt2-ci.yml # GitHub Actions automated CI validation pipeline
├── .git/ # Hidden directory (created automatically by 'git init')
│ └── hooks/
│ └── pre-commit # Git Hook: Blocks commits on test/schema failure
├── schemas/ # Machine-readable standards validation files
│ ├── manifest.schema.json # Standard validation rules for global manifest properties
│ ├── geometry.schema.json # Standard validation rules for vector coordinates and walls
│ └── entities.schema.json # Standard validation rules for lighting, weather, and triggers
├── reference-parsers/ # Zero-dependency reference parsing files
│ ├── go/
│ │ └── uvtt2_parser.go # Backend reference parser suite (zero-dependency)
│ └── typescript/
│ └── uvtt2_parser.ts # Client-side parser with Web Crypto decryption and curve math
├── clearinghouse/ # Zero-Knowledge-Storage serverless edge infrastructure
│ ├── zks-clearinghouse-worker.js # Cloudflare Worker edge key-derivation script
│ ├── wrangler.toml # Deployment environment & database configurations
│ ├── seed_revocations.js # Utility script to bulk hash and seed revoked transactions
│ └── manage_revocations.js # Node.js command-line tool to manage revoked transaction IDs
├── tests/ # Programmatic validation & security checking engines
│ ├── master-test-suite.py # Consolidated master test runner (verifies schemas, geometry, & ZKS handshakes)
│ ├── validate_conformance.go # Go-based high-concurrency binary validation suite
│ └── webgpu-purge-test.ts # TypeScript unit tests validating WebGPU volatile RAM scrubbing
├── tools/ # Repository automation and campaign asset creators
│ ├── verify-all.sh # Unified Bash script coordinating all tests & environment audits
│ └── generate-mock-uvtt2z.py # Dynamic script to generate conforming signed test maps
├── samples/ # Compliant testing files to feed into validators
│ └── tavern_three_story.uvtt2z # Multi-story sample campaign archive conforming to standard
├── RFCs/ # Request for Comments proposal directory
│ └── rfc-template.md # Standard proposal template for community extensions
├── CHANGELOG.md # Detailed ledger of version milestones & technical fixes
├── CONTRIBUTING.md # Open-source developer rules of engagement & standards
└── README.md # Landing page, feature matrices, and getting-started guide
| Feature | Legacy v1 | UVTT v2 |
|---|---|---|
| Asset Delivery | Base64-in-JSON | Zipped Directory (.uvtt2z) |
| Grid Logic | Square Only | Square, Hex, Isometric |
| Verticality | Flat Plane | 3D Bounds (Bottom/Top Z) |
| Curves | Jagged Line Segments | Native SVG Bézier Paths |
| Visibility | Symmetrical | Directional (Right-Hand Rule) |
| Interoperability | Disconnected Islands | Topological Spatial Network |
| Weather | None | Bounded Particle Emitters |
| Graphics Baseline | WebGL 1.0 / Canvas | WebGL 2.0 / WebGPU (PixiJS v8 Native) |
The UVTT v2 specification is a Living Document. We welcome contributions from VTT engine developers and map-making tool authors.
To propose a new feature (e.g., new atmospheric shaders, advanced lighting physics), please follow these steps:
Core features—including basic walls, portals, and landing zones—are immutable. Any new functionality (e.g., advanced WebGPU compute shaders) must be implemented as additive, optional properties within the extensions block to ensure that existing engines remain compliant.