BMS Forge - Quick Start Guide

Project Context

What is this?

A web-based BattleMap Notation Schema (BMS) renderer for DnD/TTRPG maps.

Current Phase: Planning → Implementation

V1 Goal: Frontend-only BMS renderer with "Paperly" style
Deployment: maps.bouncypixel.com (alpha)
Tech Stack: React + TypeScript + Konva.js + Zod + js-yaml

Developer Preferences (Lukas)

TypeScript: Strict types but pragmatic about any
State Management: Context first, upgrade if needed
Error Handling: Graceful degradation, open to functional libs
Testing: Critical paths first, expand later
Components: Type-based with domain subfolders
Styling: Tailwind hybrid with CSS modules
Build: Vite

Getting Started (After Break)

Check context: Read .opencode-config.json and docs/
Review decisions: BMS schema format, tech stack, architecture
Continue from: Last completed task in roadmap

Key Decisions Made

Architecture

Frontend-only MVP: No backend needed initially
BMS 1.0 Schema: Defined in docs/BMS_SCHEMA_SPEC.md
Rendering Engine: Konva.js with layered rendering
Validation: Zod for runtime schema validation
Editor: Monaco Editor for YAML editing

Business Model

Free Tier: Paperly style rendering
Monetization: Texture packs + AI subscription
Community: BMS schema as sharing format

Deployment

Alpha: maps.bouncypixel.com
Version Control: Private Forgejo at git.bouncypixel.com
Future: Potential custom domain (bms-forge.com)

Next Immediate Actions

Based on current roadmap (docs/IMPLEMENTATION_ROADMAP.md):

Week 1, Days 1-2: Project Setup

npm create vite@latest bms-forge -- --template react-ts
cd bms-forge
npm install konva react-konva js-yaml zod @monaco-editor/react
npm install tailwindcss postcss autoprefixer
npm install -D @types/js-yaml @types/node

Project Structure to Create

src/
├── types/          # BMS TypeScript interfaces
├── schema/         # Zod validation schemas  
├── parser/         # YAML parsing utilities
├── renderer/       # Konva.js rendering engine
├── components/     # Type-based with domains
│   ├── layout/     # Header, Sidebar, etc.
│   ├── canvas/     # Map rendering components
│   ├── editor/     # YAML editor components
│   └── shared/     # Common UI components
├── hooks/          # Custom React hooks
├── utils/          # Helper functions
└── App.tsx

When You Return

Check status: What was last completed?
Read decisions: Review config and docs
Pick up: Continue from next logical step
Ask: "What should we work on next?"

Common Commands

# Development
npm run dev

# Build
npm run build

# Type checking
npm run type-check

# Linting
npm run lint

Questions to Consider When Continuing

Parsing complete? Can we parse BMS YAML yet?
Rendering working? Are rooms showing on canvas?
UI usable? Editor + preview layout functional?
Testing needed? Critical paths covered?

Last Updated: 2026-03-19 Project: BMS Forge - BattleMap Generator

3.2 KiB Raw Blame History