Developer API - VimMaster Documentation

📋 Table of Contents

🚀 Development Setup

Prerequisites

Modern web browser (Chrome, Firefox, Safari, Edge)
Text editor with JavaScript support
Basic knowledge of HTML, CSS, and JavaScript
Git for version control

Quick Start

# Clone the repository
git clone https://github.com/renzorlive/vimmaster.git
cd vimmaster

# Switch to development branch
git checkout advanced-testing

# Open in browser
open index.html  # macOS
start index.html # Windows
xdg-open index.html # Linux

🏗️ Project Architecture

Core Modules

VimMaster is built with a modular architecture where each module has a specific responsibility:

// Main application modules
js/
├── main.js              // Application entry point and initialization
├── game-state.js        // Centralized state management
├── levels.js            // Level definitions and progression logic
├── vim-engine.js        // Core Vim command processing
├── ui-components.js     // UI rendering and user interactions
├── progress-system.js   // Progress tracking and persistence
├── challenge-mode.js    // Timed challenges and competitions
└── cheat-mode.js        // Hint system and help functionality

Data Flow

// Typical command execution flow
User Input → Vim Engine → Game State → UI Update → Level Validation

📁 File Structure

vimmaster/
├── index.html           # Main game interface
├── css/
│   └── main.css         # Game styling and themes
├── js/                  # Core JavaScript modules
│   ├── main.js          # App initialization
│   ├── game-state.js    # State management
│   ├── levels.js        # Level definitions
│   ├── vim-engine.js    # Vim command processor
│   ├── ui-components.js # UI components
│   ├── progress-system.js # Progress tracking
│   ├── challenge-mode.js # Challenge system
│   └── cheat-mode.js    # Hint system
├── docs/                # Documentation website
├── tests/               # Test files
└── README.md           # Project overview

🎮 Game State Management

GameState Class

Centralized state management for the entire game. All game data flows through this class.

class GameState { constructor() get content() set content(lines) get cursor() set cursor(position) get mode() set mode(vimMode) }

Properties

Property	Type	Description
`content`	`string[]`	Array of text lines in the editor
`cursor`	`{row: number, col: number}`	Current cursor position (0-indexed)
`mode`	`'NORMAL' \| 'INSERT' \| 'VISUAL'`	Current Vim mode
`currentLevel`	`number`	Current level index (0-based)

Example Usage

// Initialize game state
const gameState = new GameState();

// Set initial content
gameState.content = [
  "Hello, World!",
  "Welcome to VimMaster"
];

// Move cursor
gameState.cursor = { row: 0, col: 7 };

// Switch to insert mode
gameState.mode = 'INSERT';

📚 Level System

Level Definition Structure

Each level is defined as an object with specific properties that control the learning experience.

interface Level { name: string instructions: string initialContent: string[] targetContent?: string[] setup?: function validation: function hints?: string[] }

Level Properties

Property	Required	Description
`name`	Yes	Display name for the level
`instructions`	Yes	What the player needs to accomplish
`initialContent`	Yes	Starting text content for the level
`validation`	Yes	Function that returns true when level is complete
`setup`	No	Function to initialize level-specific state
`hints`	No	Array of progressive hints for the level

➕ Adding New Levels

Step-by-Step Guide

1. Define the Level Object

// Example: New level for teaching 'f' command
const findCharacterLevel = {
  name: "Find Character",
  instructions: "Use 'f' followed by a character to jump to it. Find the 'x' in the line below.",
  
  initialContent: [
    "The quick brown fox jumps over the lazy dog"
  ],
  
  setup: function(gameState) {
    // Set cursor to beginning of line
    gameState.cursor = { row: 0, col: 0 };
    gameState.mode = 'NORMAL';
  },
  
  validation: function(gameState) {
    // Check if cursor is on the 'x' character
    const line = gameState.content[0];
    const cursorChar = line[gameState.cursor.col];
    return cursorChar === 'x' && gameState.usedFindCommand;
  },
  
  hints: [
    "Try typing 'f' followed by the character you want to find",
    "The 'f' command moves the cursor to the next occurrence of a character",
    "Type 'fx' to jump to the letter 'x'"
  ]
};

2. Add to Levels Array

// In levels.js, add your level to the levels array
const levels = [
  // ... existing levels
  findCharacterLevel,
  // ... more levels
];

3. Test Your Level

// Test the level by playing through it
// Ensure validation works correctly
// Check that hints are helpful
// Verify the learning objective is clear

⚙️ Vim Engine

Command Processing

The Vim engine processes keyboard input and executes Vim commands based on the current mode.

class VimEngine { constructor(gameState) processKeypress(event) executeCommand(command, mode) handleNormalMode(key) handleInsertMode(key) handleVisualMode(key) }

Adding New Commands

// Example: Adding the 'f' (find) command
handleNormalMode(key) {
  switch(key) {
    case 'f':
      // Enter find mode, wait for next character
      this.waitingForFindChar = true;
      break;
      
    default:
      if (this.waitingForFindChar) {
        this.findCharacter(key);
        this.waitingForFindChar = false;
      }
  }
}

findCharacter(char) {
  const currentLine = this.gameState.content[this.gameState.cursor.row];
  const startCol = this.gameState.cursor.col + 1;
  const foundIndex = currentLine.indexOf(char, startCol);
  
  if (foundIndex !== -1) {
    this.gameState.cursor = {
      row: this.gameState.cursor.row,
      col: foundIndex
    };
    this.gameState.usedFindCommand = true;
  }
}

🧪 Testing Guidelines

Manual Testing Checklist

✅ Level loads with correct initial content
✅ Instructions are clear and actionable
✅ Validation triggers correctly when objective is met
✅ Hints provide progressive guidance
✅ Commands work as expected in real Vim
✅ No console errors during gameplay
✅ Progress saves correctly

Testing New Commands

// Test command in isolation
function testFindCommand() {
  const gameState = new GameState();
  gameState.content = ["hello world"];
  gameState.cursor = { row: 0, col: 0 };
  
  // Simulate 'fw' command
  const engine = new VimEngine(gameState);
  engine.processKeypress({ key: 'f' });
  engine.processKeypress({ key: 'w' });
  
  // Verify cursor moved to 'w'
  console.assert(gameState.cursor.col === 6, "Find command failed");
}

🔄 Pull Request Process

Contribution Workflow

# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/vimmaster.git
cd vimmaster

# 2. Create a feature branch
git checkout -b feature/new-level-find-command

# 3. Make your changes
# - Add new level or command
# - Test thoroughly
# - Update documentation if needed

# 4. Commit with descriptive message
git add .
git commit -m "Add level 17: Find character command (f)"

# 5. Push and create pull request
git push origin feature/new-level-find-command

PR Requirements

✅ Clear description of changes
✅ Manual testing completed
✅ No breaking changes to existing levels
✅ Code follows existing style conventions
✅ Documentation updated if needed

Menu

Developer Documentation