179 lines
No EOL
5.1 KiB
Markdown
179 lines
No EOL
5.1 KiB
Markdown
# BMS Forge
|
|
|
|
> BattleMap Notation Schema (BMS) Renderer for DnD/TTRPG Maps
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://www.typescriptlang.org/)
|
|
[](https://reactjs.org/)
|
|
[](https://vitejs.dev/)
|
|
|
|
A web-based tool for rendering and editing DnD/TTRPG battlemaps using the structured [Battlemap Notation Schema (BMS)](docs/BMS_SCHEMA_SPEC.md) 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
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
|
|
```bash
|
|
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](docs/BMS_SCHEMA_SPEC.md).
|
|
|
|
### Example BMS File
|
|
```yaml
|
|
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)
|
|
- [x] 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](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](https://github.com/lukasparsons).
|
|
|
|
- **Project**: [BMS Forge](https://maps.bouncypixel.com) (coming soon)
|
|
- **Repository**: `ssh://git@git.bouncypixel.com:222/helm/bms-forge.git`
|
|
|
|
---
|
|
|
|
<p align="center">
|
|
<i>Built with ❤️ for the TTRPG community</i>
|
|
</p> |