# 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
```typescript
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
```typescript
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
```typescript
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*