# BYOND Dream Maker IDE - Compilation & Execution Workflow Research

## Overview
This document compiles research on BYOND's Dream Maker IDE workflow to compare with Craft++ IDE implementation.

---

## 1. COMPILATION WORKFLOW ("Compile" Button)

### File Generation Process

When you click "Compile" in Dream Maker, it generates three primary files:

#### **`.dmb` File (Dream Maker Bytecode)**
- **Purpose**: Compiled bytecode executable
- **Contains**: All compiled DM code transformed into bytecode
- **Size Impact**: Increases ~10% when compiled with DEBUG flag
- **Distribution**: Required for running the world
- **Notes**: 
  - This is the main executable file
  - Can be distributed with `.rsc` file without source code
  - Contains debug symbols if `#define DEBUG` is enabled

#### **`.rsc` File (Resource Cache)**
- **Purpose**: World cache file for resources
- **Contains**: All resources specified in single quotes at compile time
  - Icons (.dmi, .bmp, .png, .jpg, .gif)
  - Sounds (.mid, .midi, .mod, .it, .s3m, .xm, .oxm, .wav, .ogg, .mp3, .raw, .wma, .aiff)
- **Runtime Behavior**: 
  - Downloaded by players into their `byond.rsc` file
  - Can grow at runtime with player-uploaded files
  - Automatically removes unused resources based on `cache_lifespan` var
- **Incremental Compilation**: 
  - Compiler reuses existing `.rsc` if possible for faster builds
  - Can be manually deleted to rebuild from scratch
- **Distribution**:
  - Can distribute `.dm` + `.rsc` files without individual resource files
  - Additional `.rsc` files can be included via `#include` statement

#### **`.int` File (Intermediate/Interface File)**
- **Purpose**: Interface definitions and map data
- **Contains**: World interface metadata
- **Note**: Less documented than `.dmb` and `.rsc`

### Compilation Process

1. **Preprocessing Phase**:
   - Process `#define`, `#include`, `#pragma` directives
   - Auto-include `<stddef.dm>` before all other code
   - Resolve FILE_DIR paths for resource files
   - Handle conditional compilation (`#if`, `#ifdef`, etc.)

2. **Code Compilation**:
   - Parse DM source files (.dm, .dme)
   - Type checking and validation
   - Generate bytecode for `.dmb`

3. **Resource Bundling**:
   - Collect all files in single quotes
   - Search paths: current dir → FILE_DIR paths
  - Package into `.rsc` cache file

4. **Output & Feedback**:
   - Display warnings and errors
   - Show file/line numbers if DEBUG enabled
   - Report compilation success/failure

### Compilation Output Format

```
Compiling project...
Loading resources...
[Warnings/Errors with file:line references if DEBUG enabled]
Build successful! 
```

---

## 2. EXECUTION WORKFLOW ("Run" Button)

### Runtime Components

BYOND has two primary execution environments:

#### **Dream Daemon** (Server Mode)
- **Purpose**: Headless server for hosting multiplayer worlds
- **Use Case**: Run dedicated game servers
- **Features**:
  - No graphical interface required
  - Handles multiple client connections
  - Runs `world` initialization
  - Network hosting

#### **Dream Seeker** (Client Mode)
- **Purpose**: Graphical client for playing/testing
- **Use Case**: 
  - Single-player testing during development
  - Client for connecting to Dream Daemon servers
- **Features**:
  - Full graphical rendering
  - Input handling
  - UI/HUD display
  - Can auto-launch Dream Maker after library installation

### "Run" Button Behavior

When clicking "Run" in Dream Maker:

1. **Check Compilation Status**:
   - Verify `.dmb` file exists and is up-to-date
   - Trigger compilation if needed

2. **Launch Dream Seeker** (Development Mode):
   - Start Dream Seeker process
   - Load the compiled `.dmb` file
   - Initialize world in local testing mode

3. **Display Runtime Output**:
   - Show world output in Dream Seeker window
   - Enable runtime debugging if DEBUG defined
   - Display runtime errors with file:line if debug symbols present

---

## 3. WORLD INITIALIZATION SEQUENCE

Based on BYOND's object-oriented model, world initialization follows this sequence:

### Initialization Order

1. **World Object Creation**:
   ```dm
   world
       New()  // World constructor called first
   ```

2. **Global Variables Initialization**:
   - Initialize all global vars
   - Process var init expressions

3. **Map Loading** (if `.dmm` file included):
   - Create all turf objects
   - Create map-placed objects
   - Establish loc relationships

4. **Area Initialization**:
   - Areas created and linked to turfs
   - Area-specific initialization

5. **Object Creation**:
   - Create all objects defined in code
   - Call `New()` constructors in dependency order

6. **World.New() Completion**:
   - Custom world initialization logic
   - Network setup (if multiplayer)

7. **Main Loop Start**:
   - Begin processing game tick
   - Handle client connections
   - Process scheduled procs

### Cleanup Sequence (Shutdown)

```dm
world/Del()  // Called when world shuts down
```

- All objects destroyed (even if referenced)
- Garbage collection runs final cleanup
- Network connections closed

---

## 4. FILE FORMATS & TECHNICAL DETAILS

### Debug Mode (`#define DEBUG`)

**Benefits**:
- Source file + line number tracking in `.dmb`
- Runtime error reporting with code location
- Enables run-time profiler in Dream Seeker
- CPU usage profiling per proc

**Costs**:
- ~10% larger `.dmb` file
- Slightly slower execution
- Exposes source structure to players

**Recommendation**: 
- Enable during development
- Disable for public distribution

### Resource File Search Path

Priority order:
1. Current source file directory
2. First `FILE_DIR` path
3. Second `FILE_DIR` path
4. ...continuing through all defined paths

Example:
```dm
#define FILE_DIR icons
#define FILE_DIR icons/mobs
mob/clown
    icon = 'clown.dmi'  // Searches: ./clown.dmi → ./icons/clown.dmi → ./icons/mobs/clown.dmi
```

### Garbage Collection

BYOND uses **reference counting** for automatic memory management:

**Objects are kept alive by**:
- Variables referencing them
- List membership
- Having a non-empty tag
- Being on the map (turfs always alive)
- Atom contents relationships
- Active running/sleeping procs (via `src`)
- Mobs with non-empty key

**Manual Deletion**:
```dm
del(object)  // Force delete even if referenced
            // Automatically nulls all references
```

**Important**: 
- Circular references never auto-deleted
- Must manually break circular references or use `del()`
- World shutdown destroys all objects regardless of references

---

## 5. PROFESSIONAL POLISH & UX OBSERVATIONS

### What BYOND Does Well

1. **Incremental Compilation**:
   - Reuses `.rsc` file for faster rebuilds
   - Only recompiles changed code

2. **Integrated Workflow**:
   - Single IDE for code, icons, maps, and sounds
   - Automatic resource bundling
   - One-click compile and run

3. **Distribution Simplicity**:
   - Two files (`.dmb` + `.rsc`) for complete distribution
   - No need to package individual resources
   - Source code optional

4. **Debug Support**:
   - Optional debug symbols
   - Runtime profiling
   - Line-level error reporting

5. **Resource Management**:
   - Automatic resource caching
   - Runtime resource uploads via savefiles
   - Auto-cleanup of old resources

### Potential Pain Points

1. **Limited Error Messages**:
   - Documentation suggests basic error reporting
   - Debug mode required for detailed info

2. **File Format Opacity**:
   - `.dmb`, `.rsc`, `.int` are proprietary binary formats
   - No documented format specifications for external tools

3. **Single-Threaded Execution**:
   - Traditional single-threaded game loop
   - No apparent parallel compilation

---

## 6. COMPARISON POINTS FOR CRAFT++ IDE

### Questions to Address

1. **Compilation Speed**:
   - How fast is BYOND's compiler?
   - Does Craft++ match or exceed it?

2. **Error Reporting Quality**:
   - How detailed are BYOND's error messages?
   - Can Craft++ provide better diagnostics?

3. **Resource Handling**:
   - How does Craft++ bundle resources?
   - Is the workflow as seamless?

4. **Distribution Model**:
   - Does Craft++ generate similarly compact output?
   - How many files needed for distribution?

5. **Debug Experience**:
   - Runtime profiling capabilities
   - Breakpoint support
   - Variable inspection

6. **Incremental Builds**:
   - Does Craft++ support incremental compilation?
   - Cache invalidation strategy?

---

## 7. TECHNICAL ARCHITECTURE INSIGHTS

### Component Separation

```
Dream Maker (IDE)
    ↓ Compiles to
[.dmb] + [.rsc] + [.int]
    ↓ Runs on
Dream Daemon (Server) OR Dream Seeker (Client/Dev)
```

### Network Model

- Client-Server architecture built-in
- Automatic client state synchronization
- Network transparency for multiplayer

### Object Model

```
/datum (base type)
    /atom (visual objects)
        /turf (tiles)
        /obj (objects)
        /mob (characters)
        /area (regions)
```

All objects support:
- Garbage collection
- Network replication (in multiplayer)
- Proc overriding
- Visual representation (atoms)

---

## 8. MISSING INFORMATION & FURTHER RESEARCH NEEDED

### Questions Still Unanswered

1. **Exact Compilation Output Format**:
   - What does the compiler console look like?
   - How are errors formatted exactly?
   - Progress indicators during build?

2. **.int File Purpose**:
   - What exactly goes in the .int file?
   - Is it required for execution?
   - Can it be distributed separately?

3. **Build Performance**:
   - Typical compilation times
   - Large project handling
   - Memory usage during compilation

4. **IDE Features**:
   - Integrated icon editor capabilities
   - Map editor workflow
   - Code completion/IntelliSense?

5. **Runtime Debugging**:
   - Breakpoint support?
   - Step-through debugging?
   - Variable watches?

6. **Version Control Integration**:
   - How do binary files (.dmb, .rsc) work with VCS?
   - Best practices for team development?

---

## 9. KEY TAKEAWAYS FOR CRAFT++ IMPLEMENTATION

### Must-Have Features (Based on BYOND)

1. **Simple Distribution**: Minimal output files
2. **Resource Bundling**: Automatic resource packaging
3. **Debug Mode**: Optional debug symbols for development
4. **Clear Errors**: File:line error reporting
5. **One-Click Run**: Compile + execute in one step

### Opportunities to Improve on BYOND

1. **Better Error Messages**: Modern IDE-quality diagnostics
2. **Faster Compilation**: Parallel builds, better caching
3. **Modern Debugging**: Full debugger with breakpoints
4. **Open Formats**: Documented file formats for tooling
5. **Incremental Features**: Better incremental compilation
6. **Real-time Feedback**: Compile-on-save, error squiggles

### UX Flow to Match or Exceed

```
User clicks "Compile":
    → Show progress indicator
    → Display incremental build info
    → Show all errors/warnings with file:line
    → Success notification with build stats

User clicks "Run":
    → Auto-compile if needed
    → Launch runtime immediately
    → Connect IDE to runtime for debugging
    → Show runtime output in integrated console
```

---

## 10. COMMUNITY INSIGHTS & REAL-WORLD USAGE

### Common Developer Workflows (From Forum Analysis)

Based on the BYOND Developer Help forum, typical workflows include:

1. **Development Cycle**:
   - Write code in Dream Maker
   - Click Compile to build
   - Click Run to test in Dream Seeker
   - Iterate on bugs/features

2. **Common Pain Points**:
   - Runtime errors without clear stack traces (when DEBUG not enabled)
   - Compiler errors that require hunting through code
   - Resource file path issues (FILE_DIR confusion)
   - Garbage collection misunderstandings (circular references)
   - Call stack overflow errors

3. **Professional Development Patterns**:
   - Large projects (like SS13) use extensive code organization
   - Teams work with VCS (Git) but face challenges with binary files
   - DEBUG mode typically disabled for production builds
   - Resource management becomes critical for large games

### IDE Feature Expectations

Based on community discussions:

**Expected Features**:
- Syntax highlighting (basic)
- File tree navigation
- Integrated icon/map editors
- One-click build & run
- Error/warning output panel

**Not Commonly Available**:
- Advanced IntelliSense/autocomplete
- Refactoring tools
- Git integration
- Real-time error checking
- Advanced debugging (breakpoints, watches)

### Professional Polish Observations

**Strengths**:
- **Stability**: BYOND IDE has been refined over 20+ years
- **Integrated Tools**: Icon editor, map editor, code editor in one package
- **Simple Workflow**: Minimal friction from code to running game
- **Resource Pipeline**: Automatic resource bundling works well

**Weaknesses**:
- **Dated UX**: Interface reflects older IDE design patterns
- **Limited Feedback**: Errors could be more descriptive
- **No Modern Features**: Lacks modern IDE conveniences
- **Performance**: Large projects can be slow to compile

---

## 11. CRAFT++ COMPETITIVE ADVANTAGES

### Areas Where Craft++ Can Excel

1. **Modern IDE Experience**:
   - Real-time error checking with squiggles
   - Intelligent autocomplete with type information
   - Inline documentation/hints
   - Modern UI with themes

2. **Better Error Reporting**:
   - Rich error messages with suggestions
   - Click-to-navigate error locations
   - Preview of error context
   - Suggested fixes

3. **Advanced Debugging**:
   - Full breakpoint support
   - Variable inspection
   - Call stack visualization
   - Watch expressions
   - Step-through debugging

4. **Build System**:
   - Faster compilation (parallel builds)
   - Better incremental compilation
   - Build configuration profiles
   - Progress indicators with details

5. **Developer Experience**:
   - Git integration
   - Code formatting
   - Find/replace across project
   - Code navigation (go-to-definition)
   - Symbol search

6. **Performance**:
   - Faster startup
   - Responsive UI
   - Efficient resource handling
   - Quick project loading

### Maintaining BYOND's Strengths

**Don't Lose**:
- One-click compile and run
- Automatic resource bundling
- Simple distribution (few output files)
- Integrated asset management
- Clear separation of debug/release builds

---

## 12. RECOMMENDED CRAFT++ WORKFLOW

### Ideal "Compile" Experience

```
User clicks "Compile" button:

1. Pre-build Validation:
   ✓ Check for syntax errors (already highlighted)
   ✓ Verify all resources exist
   ✓ Show build configuration (Debug/Release)

2. Build Progress:
   → "Building MyProject..."
   → Progress bar with current file/task
   → "Compiling source files... (15/23)"
   → "Bundling resources... (42 files)"
   → "Generating bytecode..."

3. Build Output:
   → Organized output panel:
      [Build] Started build at 14:32:15
      [Build] Configuration: Debug
      [Build] Files compiled: 23
      [Build] Resources bundled: 42
      [Build] Output: MyProject.cmb (2.4 MB)
      [Build] Build succeeded in 1.2s

4. Error Handling:
   → If errors:
      ✗ Build failed with 3 errors, 2 warnings
      
      Errors:
      ❌ player.craft:45:12 - Undefined variable 'helth' (did you mean 'health'?)
      ❌ weapon.craft:89:5 - Type mismatch: expected number, got string
      ❌ world.craft:12:1 - Missing closing brace
      
      Warnings:
      ⚠️ enemy.craft:33:8 - Unused variable 'temp'
      ⚠️ item.craft:67:4 - Deprecated function 'old_move()'
```

### Ideal "Run" Experience

```
User clicks "Run" button:

1. Compilation Check:
   → If not compiled or out-of-date:
      "Project modified since last build. Building..."
      [Auto-compile with progress]
   
   → If up-to-date:
      "Build is up-to-date. Launching..."

2. Runtime Launch:
   → "Starting Craft++ Runtime..."
   → Runtime window appears
   → IDE switches to Debug perspective (optional)
   → Console shows world initialization:
      [Runtime] Loading MyProject.cmb...
      [Runtime] Initializing world...
      [Runtime] Loading resources (42 files)...
      [Runtime] World ready! (initialized in 0.3s)

3. Debug Integration:
   → Runtime connected to IDE
   → Runtime errors appear in IDE with file:line links
   → Console output visible in IDE panel
   → Breakpoints active (if set)

4. Hot Reload (Advanced):
   → "Code modified. Reload? [Yes] [No]"
   → If yes: seamless runtime code refresh
```

### Ideal Error Reporting

```
Example Error in IDE:

File: player.craft
Line 45: 
    this.helth = 100;
         ^^^^^
    Error: Undefined variable 'helth'
    
    Did you mean 'health'? [Apply fix]
    
    Available variables in this scope:
    - health (number)
    - position (vector2)
    - sprite (Sprite)
```

---

## SOURCES

- BYOND DM Reference Documentation (www.byond.com/docs/ref)
- BYOND Developer Help Forum (www.byond.com/forum/?forum=8)
- File format info from cache, DEBUG, and compilation docs
- Garbage collection and object model documentation
- Preprocessor and compilation pipeline documentation
- Community usage patterns and pain points

**Note**: Much of BYOND's internal workflow is not publicly documented in detail. This research represents what can be gleaned from official documentation, community discussions, and observed behavior.