244 lines
No EOL
6.4 KiB
Markdown
244 lines
No EOL
6.4 KiB
Markdown
# 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* |