bms-forge/docs/PROJECT_PLAN.md

BMS BattleMap Generator - Project Plan

Project Overview

A web-based tool for rendering DnD/TTRPG battlemaps using the Battlemap Notation Schema (BMS) format.

Primary Goal: Create a frontend renderer that parses BMS YAML and renders battlemaps with a default "Paperly" style.

Monetization Strategy:

• Free Tier: Basic rendering with Paperly style
• Paid Features: Texture packs, AI integration (future)
• Subscription: Access to all texture packs + AI features

Technology Stack

Frontend

• Framework: React 19 + TypeScript
• Build Tool: Vite
• Canvas: Konva.js (via react-konva)
• Validation: Zod
• YAML Parsing: js-yaml
• Editor: Monaco Editor
• Styling: Tailwind CSS

Optional Backend (Future)

• Runtime: .NET 8 Minimal API
• Validation: JSON Schema.NET
• YAML: YamlDotNet
• AI: OpenAI SDK

Project Structure

bms-forge/
├── public/
├── src/
│   ├── types/          # BMS TypeScript interfaces
│   ├── schema/         # Zod validation schemas
│   ├── parser/         # YAML parsing utilities
│   ├── renderer/       # Konva.js rendering engine
│   │   ├── layers/     # Individual layer renderers
│   │   └── styles/     # Paperly + future texture packs
│   ├── components/     # React components
│   ├── hooks/          # Custom React hooks
│   ├── utils/          # Helper functions
│   └── App.tsx
├── package.json
└── vite.config.ts

Phase 1: Frontend Renderer MVP (2-3 weeks)

Week 1: Core Foundation

Days 1-2: Project Setup

• Initialize repository with Vite + React + TypeScript
• Install core dependencies
• Configure development environment

Days 3-4: BMS Schema Implementation

• Complete TypeScript interfaces for BMS 1.0
• Zod validation schemas
• YAML parser with error handling

Days 5-7: Basic Rendering Engine

• Grid renderer
• Paperly style system
• Room rendering

Week 2: Complete BMS Support

Days 8-10: Element Rendering

• Door renderer (open/closed states)
• Object renderer (simple geometric icons)
• Hazard renderer (visual patterns)

Days 11-12: Advanced Features

• Lighting renderer (radius visualization)
• Annotation renderer (text labels)
• Export system (PNG, JSON, BMS YAML)

Week 3: Polish & Alpha Testing

• UI refinement
• Performance optimization
• Alpha testing with trusted users
• Bug fixes and improvements

BMS Schema Implementation

Core Types

type Coordinate = [number, number]; // (x, y)
type Rectangle = { from: Coordinate; to: Coordinate };

interface BMSHeader {
  bmsVersion: string;
  mapName: string;
  gridSize: { width: number; height: number };
  gridUnit: string;
  style: string;
  lighting: string;
  ambientSound?: string;
  temperature?: string;
}

interface BMSSchema extends BMSHeader {
  rooms?: Room[];
  doors?: Door[];
  objects?: MapObject[];
  hazards?: Hazard[];
  lightingSources?: LightSource[];
  connections?: Connection[];
  annotations?: Annotation[];
}

Paperly Style Definition

const paperlyStyle = {
  grid: { color: "#ccc", opacity: 0.3, lineWidth: 1 },
  rooms: { fill: "#f8f8f8", stroke: "#666", strokeWidth: 2 },
  walls: { color: "#333", thickness: 3 },
  doors: { 
    open: { fill: "#8BC34A", stroke: "#689F38" },
    closed: { fill: "#795548", stroke: "#5D4037" }
  },
  objects: { color: "#666", size: 20 },
  hazards: { color: "#f44336", pattern: "diagonal" },
  lighting: { glow: "#FFEB3B", opacity: 0.3 }
};

Rendering Engine Architecture

Layered Rendering System

1. Layer 7: Annotations (text, labels)
2. Layer 6: Lighting effects (glows, shadows)
3. Layer 5: Objects & Hazards (icons, patterns)
4. Layer 4: Doors (with state indicators)
5. Layer 3: Room interiors (floor textures, features)
6. Layer 2: Walls (with material styles)
7. Layer 1: Grid & Background

Renderer Class Structure

class PaperlyRenderer {
  private stage: Konva.Stage;
  private layers: Map<string, Konva.Layer>;
  
  render(schema: BMSSchema): void {
    this.setupCanvas(schema.gridSize);
    this.renderGrid();
    this.renderRooms(schema.rooms);
    this.renderDoors(schema.doors);
    // ... other elements
  }
}

UI Component Structure

Main Layout

Header
└── App Title, Version, Links

Main Content (flex)
├── EditorPanel (Monaco Editor with YAML)
├── PreviewPanel (Konva Canvas)
└── ToolsPanel (Export buttons, options)

StatusBar
└── Grid info, errors, zoom level

Key Components

1. EditorPanel: Monaco editor with YAML syntax highlighting
2. PreviewPanel: Konva canvas with rendered map
3. ToolsPanel: Export buttons, style options, validation status
4. Header: App title, version, links
5. StatusBar: Grid info, errors, zoom level

Future Features

Texture Pack System

• Individual texture pack purchases ($4.99 each)
• Subscription access to all packs
• Pack structure:

  texture-packs/
  ├── medieval-stone/
  │   ├── pack.json
  │   ├── walls/
  │   ├── floors/
  │   └── objects/
  

AI Integration

• Free tier: Bring-your-own-API key
• Paid tier: Managed API with rate limits
• Chat-based iteration: Natural language to modify BMS schemas

VTT Export

• FoundryVTT scene format
• Roll20 compatibility
• Universal VTT format

Deployment

Alpha Testing

• URL: maps.bouncypixel.com
• Build: Vite production build
• Hosting: Self-hosted subdomain
• Testing: 5-10 trusted alpha testers

Production Considerations

• Custom Domain: bms-forge.com or similar
• CDN: For texture packs and assets
• Analytics: Basic usage tracking (optional)
• CI/CD: Automated build and deployment

Success Criteria

MVP Completion

• Parse and validate BMS 1.0 YAML
• Render all BMS elements with Paperly style
• Real-time editor + preview
• Export to PNG and JSON
• Deploy to maps.bouncypixel.com
• Gather feedback from alpha testers

Phase 2 Goals

• Texture pack system
• AI integration
• VTT export functionality
• Community template sharing
• Monetization system

Notes

• Version Control: Private Forgejo at git.bouncypixel.com
• Analytics: Optional future feature
• Community: Discord for user feedback
• Browser Support: Modern browsers only for V1
• Mobile: Desktop-focused initially

---

Last Updated: March 19, 2026