5.1 KiB
5.1 KiB
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 https://git.bouncypixel.com/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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📞 Contact
Project maintained by Lukas Parsons.
- Project: BMS Forge (coming soon)
- Repository:
https://git.bouncypixel.com/helm/bms-forge.git
Built with ❤️ for the TTRPG community