# BMS Forge

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

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-19-blue)](https://reactjs.org/)
[![Vite](https://img.shields.io/badge/Vite-6.0-purple)](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>