roguemap 0.1.0

Parser and renderer for procedural dungeon map generation in roguelike games
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172

# RogueMap

A domain-specific language (DSL) parser and renderer for procedural dungeon map generation in roguelike games.

## Description

RogueMap is a specialized parser that reads declarative dungeon definitions and transforms them into visual ASCII representations. It allows game developers to define rooms, corridors, connections, and metadata tags in a human-readable format that can be easily parsed, validated, and rendered.

## Usage

### Installation

```bash
cargo install roguemap
```

### CLI Commands

```bash
# Render dungeon map
roguemap -i dungeon.rmap

# Save output to file
roguemap -i dungeon.rmap -o output.txt

# Display Abstract Syntax Tree
roguemap -i dungeon.rmap --ast

# Show credits
roguemap --credits
```

## Example

### Input File (`example.rmap`)

```rmap
# Starting area of the dungeon

tag biome = "underground"
tag difficulty = hard

room start 10x8 at (2, 3) {
    name = "Entrance"
    loot = [gold:10]
    monster = none
}

room hall 20x4 at (2, 15) {
    name = "Main Hall"
    loot = [potion:2, scroll:1]
}

corridor 6 from start to hall
connect hall to start via west

room boss 12x12 at (20, 20) {
    name = "Boss Room"
    loot = [gold:100, potion:5, relic:1]
    monster = dragon
}

connect hall to boss via south
```

### Generated Diagram

```
                    ############
                    #..........#
                    #..........#
                    #..........#
                    #..........#
                    #boss......#
                    #..........#
                    #..........#
                    #..........#
                    #..........#
                    #LM........#
                    ############
                                
  ####################          
  #hall..............#          
  #L........+........#          
  ##########+#########          
            +                   
            +                   
            +                   
            +                   
  ##########+                   
  #........#+                   
  #........#+                   
  #star++++++                   
  #........#                    
  #........#                    
  #LM......#                    
  ##########                    
```

## Technical Parsing Process

### 1. Lexical Analysis

The input text is tokenized according to grammar rules. The lexer identifies:
- **Keywords**: `room`, `corridor`, `connect`, `tag`, `via`, `from`, `to`, `at`
- **Identifiers**: Alphanumeric sequences (room names, item types)
- **Literals**: Integers (`10`, `8`) and strings (`"Entrance"`)
- **Operators**: `=`, `:`, and delimiters `{`, `}`, `[`, `]`, `(`, `)`
- **Comments**: Lines starting with `#` (ignored)
- **Whitespace**: Spaces, tabs, newlines (ignored)

### 2. Syntax Analysis

The parser constructs a hierarchical parse tree based on grammar rules:

```
dungeon
  └── statement*
       ├── tag_decl: tag biome = "underground"
       ├── tag_decl: tag difficulty = hard
       ├── room_decl: room start 10x8 at (2, 3) { ... }
       ├── room_decl: room hall 20x4 at (2, 15) { ... }
       ├── corridor_decl: corridor 6 from start to hall
       ├── connect_decl: connect hall to start via west
       └── ...
```

Each statement type has specific sub-rules that must be satisfied for valid syntax.

### 3. AST Construction

The parse tree is transformed into strongly-typed Rust structs:

```rust
Dungeon {
    statements: Vec<Statement>
}

Statement = Room | Corridor | Connection | Tag

Room {
    name: String,
    width: usize,
    height: usize,
    x: usize,
    y: usize,
    props: Vec<RoomProp>
}

RoomProp = Name(String) | Loot(Vec<LootItem>) | Monster(String)
```

This ensures type safety and enables pattern matching during processing.

### 4. Validation

During AST construction, the parser validates:
- **Syntax correctness**: Grammar compliance
- **Required fields**: Room dimensions, coordinates, names
- **Type correctness**: Integers for sizes, valid direction keywords
- **Structural integrity**: Proper nesting of properties

### 5. Semantic Processing

The validated AST is used for:
- **Rendering**: Traversing statements to draw rooms and corridors on a 2D character grid
- **Analysis**: Extracting metadata tags, calculating dungeon bounds

---

**Author**: Maksym Stetsyk | **Year**: 2025  
**Repository**: [github.com/femedron/rogue_map](https://github.com/femedron/rogue_map)