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

cargo install roguemap

CLI Commands

# 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)

# 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:

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