BMS Forge

BattleMap Notation Schema (BMS) Renderer for DnD/TTRPG Maps

A web-based tool for rendering and editing DnD/TTRPG battlemaps using the structured Battlemap Notation Schema (BMS) format. Create, share, and customize battlemaps with a clean, semantic YAML-based format.

✨ Features

• BMS Schema Support: Parse and validate BMS 1.0 YAML files
• Real-time Rendering: Instant visual feedback as you edit
• "Paperly" Style: Clean, vector-style default theme (always free)
• Export Options: PNG, JSON, and BMS YAML formats
• Future Plans: Texture packs, AI generation, VTT integration

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm/yarn/pnpm

Installation

# Clone the repository
git clone ssh://git@git.bouncypixel.com:222/helm/bms-forge.git
cd bms-forge

# Install dependencies
npm install

# Start development server
npm run dev

Visit http://localhost:3000 to see the app in action.

Build for Production

npm run build
npm run preview

📁 Project Structure

bms-forge/
├── src/
│   ├── types/          # BMS TypeScript interfaces
│   ├── schema/         # Zod validation schemas
│   ├── parser/         # YAML parsing utilities
│   ├── renderer/       # Konva.js rendering engine
│   │   ├── layers/     # Individual layer renderers
│   │   └── styles/     # Paperly + texture pack styles
│   ├── components/     # React components (type-based)
│   │   ├── layout/     # Layout components
│   │   ├── canvas/     # Map rendering components
│   │   ├── editor/     # YAML editor components
│   │   └── shared/     # Common UI components
│   ├── hooks/          # Custom React hooks
│   ├── utils/          # Helper functions
│   ├── App.tsx
│   └── main.tsx
├── docs/               # Project documentation
├── public/             # Static assets
└── package.json

🛠️ Technology Stack

• Frontend: React 19 + TypeScript
• Build Tool: Vite
• Canvas Rendering: Konva.js
• Validation: Zod
• YAML Parsing: js-yaml
• Code Editor: Monaco Editor
• Styling: Tailwind CSS + CSS Modules
• Linting: ESLint + TypeScript ESLint

📋 Development

Available Scripts

npm run dev          # Start development server
npm run build        # Build for production
npm run preview      # Preview production build
npm run lint         # Run ESLint
npm run type-check   # TypeScript type checking

Code Style

• TypeScript with strict mode (pragmatic about any)
• Functional components with hooks
• Type-based component organization
• Tailwind utilities for layout, CSS modules for complex styles

📚 BMS Schema

The Battlemap Notation Schema (BMS) is a YAML-based format for describing DnD/TTRPG battlemaps. See the complete specification.

Example BMS File

BMS Version: 1.0
Map Name: Guard Room
Grid Size: 20x15
Grid Unit: 5ft
Style: Stone Fortress
Lighting: Torchlight

ROOMS:
- R1: Guard Room (0,0)-(20,15)
  Walls: Stone-1ft-Smooth
  Floor: Flagstones
  Ceiling: 15ft, wooden beams

DOORS:
- D1: Wooden Door (20,6)-(20,9)
  Type: Wood-Single-Reinforced
  Connects: R1 -> Corridor
  State: Closed-Unlocked

🎯 Roadmap

Phase 1: MVP (Current)

• Project setup and structure
• BMS TypeScript interfaces and validation
• Basic YAML parsing
• Grid and room rendering
• Door and object rendering
• Export functionality
• Alpha deployment to maps.bouncypixel.com

Phase 2: Texture Packs

• Texture pack system architecture
• Pack management UI
• Texture rendering engine
• Marketplace integration

Phase 3: AI Integration

• OpenAI API integration
• Chat-based schema generation
• Iterative editing workflow
• Subscription system

Phase 4: Community & VTT

• Template sharing
• VTT export (FoundryVTT, Roll20)
• User accounts
• Collaboration features

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 Contact

Project maintained by Lukas Parsons.

• Project: BMS Forge (coming soon)
• Repository: ssh://git@git.bouncypixel.com:222/helm/bms-forge.git

---

Built with ❤️ for the TTRPG community