Mechanics Breakdown

What you’re building

You have spent the last four lessons building the business case. Market analysis, financial projections, storefront economics, runway planning. The spreadsheet side of starting a game company is solid. Now comes the part that actually matters: what does the game play like?

If you watch BloodRayne gameplay footage on YouTube, you see a lot happening at once. Rayne swings blades in multi-hit combos. A blood rage meter fills up and triggers a powered state. Aura vision highlights enemies and objectives through walls. She runs, jumps, climbs walls, grinds on rails. Enemies patrol, get alerted, attack in patterns. It looks fluid in motion, but underneath all of that is a set of discrete mechanical systems — each one with inputs, states, transitions, and parameters.

To remake the game, someone needs to document every one of those mechanics in a format that a game designer or programmer can implement. Right now, that documentation process is “watch footage, take notes, organize notes into a document.” You are going to build a CLI tool that takes your freeform gameplay observations and converts them into structured JSON specifications — one per mechanic, with states, triggers, parameters, and relationships to other systems. The output is something you could hand to a developer and say “build this.”

💬The gap between watching and building

Everyone who has played BloodRayne can describe what it feels like. “The combat is fast.” “The blood rage is cool.” “The aura vision is useful.” But you cannot build a game from feelings. You need: “Blood Rage activates when the meter reaches 100, lasts 15 seconds, increases attack damage by 2x, grants health regeneration at 5HP/sec, and the meter drains at 6.67 units/sec during activation.” That is the difference between a fan and a game designer. This tool bridges that gap.

By the end of this lesson you will have a Node.js CLI tool that accepts freeform gameplay observations (plain text notes from watching footage), parses them into mechanical categories, and outputs structured JSON specifications for each system. It comes pre-loaded with a complete BloodRayne breakdown covering combat, movement, enemy AI, and special abilities.

ℹSoftware pattern: Unstructured text to structured specification

Freeform natural-language input organized into a rigid schema with typed fields, state machines, and relationship graphs. This pattern appears in requirements engineering, scientific observation logging, and any domain where experts think in prose but engineers need specifications. The key technique is defining the output schema first and then mapping observations to it.

The showcase

Here is what the finished tool produces:

Input: Freeform text observations from watching gameplay. Example: “Rayne has a 3-hit blade combo, the third hit does extra damage. If she holds attack she does a spinning slash. Blood rage meter fills when she hits enemies, about 10 hits to fill. When activated she does double damage and heals.”
Output: Structured JSON for each identified mechanic, with:
- System name, category, description
- States (idle, active, cooldown, etc.) with transitions
- Parameters (damage values, durations, rates, thresholds)
- Input triggers (button presses, conditions, timers)
- Relationships to other systems (“Blood Rage depends on Combat Hit Counter”)
Pre-filled BloodRayne data: A complete breakdown of all core mechanics, ready to use as-is or modify
Multiple output formats: JSON (for code), Markdown (for documentation), or both
Validation: Warns about incomplete specs (e.g., “Blood Rage has no defined cooldown — is that intentional?”)

# Use the pre-filled BloodRayne breakdown
node src/index.js --preset bloodrayne --output ./specs

# Analyze custom observations
node src/index.js --input observations.txt --output ./specs

# Generate both JSON and Markdown
node src/index.js --preset bloodrayne --format both --output ./specs

The prompt

Open your terminal, navigate to a project folder, start your AI CLI tool, and paste this prompt:

Build a Node.js CLI tool called mechanics-breakdown that converts freeform
gameplay observations into structured mechanical specifications. This is for
documenting BloodRayne's game mechanics in preparation for a remake.

PROJECT STRUCTURE:
mechanics-breakdown/
  package.json
  src/
    index.js           (CLI entry point)
    parser.js          (text observation parser and categorizer)
    schema.js          (mechanic specification schema definitions)
    analyzer.js        (mechanic analysis, validation, and relationship mapping)
    formatter.js       (JSON and Markdown output formatters)
  presets/
    bloodrayne.js      (pre-filled BloodRayne mechanic observations and specs)

REQUIREMENTS:

1. MECHANIC SCHEMA (src/schema.js)
   Define the specification format for game mechanics. Each mechanic spec contains:

   {
     id: string,              // unique slug, e.g., "combat-blade-combo"
     name: string,            // display name, e.g., "Blade Combo System"
     category: string,        // "combat" | "movement" | "ability" | "enemy-ai" | "progression"
     description: string,     // one-paragraph summary
     states: [                // state machine definition
       {
         name: string,        // e.g., "idle", "combo-1", "combo-2", "combo-3", "recovery"
         description: string,
         transitions: [       // what triggers moving to another state
           { target: string, trigger: string, condition: string }
         ]
       }
     ],
     parameters: [            // tunable numeric values
       {
         name: string,        // e.g., "combo1_damage"
         value: number|string,// e.g., 15 or "estimated: 15-20"
         unit: string,        // e.g., "HP", "seconds", "units/sec", "multiplier"
         notes: string        // e.g., "observed from gameplay, may vary by difficulty"
       }
     ],
     inputs: [                // player inputs that affect this mechanic
       {
         action: string,      // e.g., "press attack", "hold attack", "press special"
         context: string,     // e.g., "while grounded", "while in blood rage"
         result: string       // e.g., "starts combo chain", "triggers spinning slash"
       }
     ],
     dependencies: [string],  // IDs of mechanics this system depends on
     relatedSystems: [string],// IDs of mechanics that interact with this one
     estimatedComplexity: string, // "low" | "medium" | "high" | "very-high"
     implementationNotes: string, // suggestions for the remake team
     sourceConfidence: string     // "observed" | "estimated" | "speculated"
   }

2. BLOODRAYNE PRESET (presets/bloodrayne.js)
   Pre-filled specifications for BloodRayne's core mechanics:

   a. COMBAT: Blade Combo System
      - States: idle -> combo-1 (light hit) -> combo-2 (medium hit) -> combo-3 (heavy finisher) -> recovery -> idle
      - Hold attack: spinning slash (AoE damage, ~1.5x single target damage)
      - Parameters: combo1 damage ~15HP, combo2 ~20HP, combo3 ~35HP, spinning slash ~25HP AoE
      - Attack speed: ~0.4s between combo hits, 0.8s recovery after combo-3
      - Combo window: 0.6s to chain next hit (miss window = reset to idle)
      - Dependencies: none (core system)
      - Complexity: medium

   b. COMBAT: Blood Rage System
      - States: inactive (meter filling) -> ready (meter full, flashing) -> active (powered up) -> depleted (cooldown) -> inactive
      - Meter: 0-100, fills by ~10 per enemy hit, triggers at 100
      - Active duration: ~15 seconds
      - Active effects: 2x attack damage, health regen at ~5HP/sec, visual red tint
      - Drain rate: meter drops at ~6.67/sec during active state (100/15s)
      - Auto-activates or player-triggered (games differ by version)
      - Dependencies: combat-blade-combo (meter fills from hits)
      - Complexity: medium

   c. COMBAT: Feed / Bite Attack
      - States: idle -> targeting (aim at stunned/grabbed enemy) -> feeding (draining health) -> release
      - Grab range: melee range, requires stunned or low-health enemy
      - Health drain: ~20HP/sec from enemy, healed to Rayne
      - Duration: hold to continue, release to stop, or enemy dies
      - Vulnerability: Rayne is vulnerable during feeding (can be hit by other enemies)
      - Dependencies: combat-blade-combo (stun enemies first)
      - Complexity: medium

   d. ABILITY: Aura Vision
      - States: off -> active (toggle)
      - Effect: highlights enemies through walls (red), objectives (yellow), collectibles (blue)
      - Range: ~30 meters (estimated from gameplay observation)
      - Cost: none (free toggle in most versions)
      - Performance note: requires render pass for outline/glow shader
      - Dependencies: none
      - Complexity: medium (shader/rendering work)

   e. MOVEMENT: Core Locomotion
      - States: idle -> walk -> run -> sprint
      - Run speed: base movement, always available
      - Sprint: faster, may have stamina cost in remake
      - Jump: single jump, ~2 meter height
      - Wall climb: approach climbable surface, auto-attach, climb up/down
      - Rail grind: approach rail, auto-attach, grind with balance (if implemented)
      - Parameters: run speed ~5m/s, sprint ~8m/s, jump height ~2m
      - Complexity: medium (wall climb and rail grind add complexity)

   f. MOVEMENT: Wall Interactions
      - States: grounded -> approach wall -> wall attach -> climbing -> wall jump/detach -> airborne -> grounded
      - Climbable surfaces: flagged in level design (not all walls)
      - Climb speed: ~2m/s
      - Wall jump: detach with lateral leap, ~3m distance
      - Dependencies: core-locomotion
      - Complexity: high (collision detection, animation blending)

   g. ENEMY AI: Patrol and Alert System
      - States: patrol (waypoint loop) -> suspicious (heard noise / saw ally die) -> alert (spotted player) -> combat (attacking) -> search (lost player) -> patrol
      - Patrol: walk between waypoints, fixed path
      - Suspicious: move toward sound/event, look around for 5s, return to patrol if nothing found
      - Alert: instant transition to combat, alert nearby allies within 15m radius
      - Combat: engage player with attack pattern (melee enemies close distance, ranged enemies maintain distance)
      - Search: move to last known player position, search for 10s, return to patrol
      - Parameters: sight range ~20m, hearing range ~10m, alert radius ~15m
      - Complexity: high (full state machine with sensory system)

   h. ENEMY AI: Attack Patterns
      - Melee enemies: approach -> wind-up (0.5s, telegraphed) -> attack -> recovery (0.3s) -> approach
      - Ranged enemies: maintain distance (~10-15m) -> aim (0.8s) -> fire -> reposition
      - Heavy enemies: slow approach -> heavy wind-up (1.0s, very telegraphed) -> slam (AoE) -> long recovery (1.5s)
      - Boss patterns: phase-based, each phase introduces new attacks, transitions at HP thresholds (75%, 50%, 25%)
      - Dependencies: patrol-alert-system (combat state triggers attack patterns)
      - Complexity: high (per enemy type, boss patterns are very-high)

3. PARSER (src/parser.js)
   Parse freeform text observations into mechanic candidates:
   - Split text into sentences/observations
   - Categorize each observation by keyword matching:
     "attack", "combo", "hit", "damage", "slash" -> combat
     "run", "jump", "climb", "grind", "move" -> movement
     "meter", "rage", "vision", "ability", "power" -> ability
     "enemy", "patrol", "alert", "attack pattern" -> enemy-ai
   - Extract numeric values: "about 15 damage", "lasts 10 seconds", "fills in ~10 hits"
   - Group related observations into mechanic clusters
   - Return array of partially-filled mechanic specs for the analyzer to complete

4. ANALYZER (src/analyzer.js)
   Validate and enrich parsed mechanics:
   - Check for missing required fields and flag them as warnings
   - Identify cross-references between mechanics (e.g., "blood rage damage bonus" references both blood-rage and blade-combo)
   - Build a dependency graph: which mechanics require other mechanics
   - Estimate complexity based on state count and parameter count
   - Generate implementation notes (e.g., "This mechanic requires a state machine with 5 states and 8 transitions. Consider using a finite state machine library or engine-native state machine.")
   - Confidence scoring: "observed" (directly seen in footage), "estimated" (inferred from partial observation), "speculated" (assumed based on genre conventions)

5. FORMATTER (src/formatter.js)
   Two output modes:

   a. JSON: array of mechanic specs conforming to the schema, pretty-printed
      - File: <output>/mechanics.json

   b. Markdown: formatted document with sections per mechanic
      - Header with game title and analysis date
      - Table of contents
      - Per-mechanic section with: description, state diagram (text-based), parameter table, input table, notes
      - Dependency graph section (text-based)
      - Summary statistics: total mechanics, complexity breakdown, confidence breakdown
      - File: <output>/mechanics.md

6. CLI INTERFACE (src/index.js)
   - Usage: node src/index.js [options]
   - Options:
     --preset <name>     Use a preset (currently: "bloodrayne")
     --input <file>      Path to a .txt file with freeform observations
     --format <type>     "json" | "markdown" | "both" (default: "both")
     --output <path>     Output directory (default: ./specs)
     --validate          Run validation and print warnings without generating output
   - If neither --preset nor --input is provided, prompt the user to paste observations (read from stdin)
   - Print summary to console: mechanics found, categories, complexity estimates

DEPENDENCIES: commander, chalk

SAMPLE RUN (using preset):
node src/index.js --preset bloodrayne --format both --output ./specs

Expected console output:
  BloodRayne Mechanics Breakdown
  ==============================
  Total mechanics: 8
  Categories: combat (3), movement (2), ability (1), enemy-ai (2)
  Complexity: medium (5), high (3)
  Confidence: observed (6), estimated (2)

  Dependencies:
    blood-rage -> blade-combo (meter fills from hits)
    feed-attack -> blade-combo (requires stunned enemy)
    wall-interactions -> core-locomotion
    enemy-attack-patterns -> patrol-alert-system

  Warnings:
    - blood-rage: no cooldown period defined between deplete and inactive. Intentional?
    - rail-grind: referenced in core-locomotion but no dedicated spec. Create one?

  Output written to:
    specs/mechanics.json (8 mechanic specs, 247 parameters)
    specs/mechanics.md (formatted documentation, 12 pages)

SAMPLE RUN (custom observations):
echo "The player has a three-hit sword combo. Third hit does big damage.
There is a rage meter that fills when you hit things. When full it makes
you stronger for about 15 seconds. Double damage and you heal." | \
node src/index.js --format json --output ./specs

Expected: parses 2 mechanics (blade combo, rage meter), extracts parameters
(3 hits, 15 seconds, 2x damage, healing), generates partial specs with
"estimated" confidence, flags missing details.

💡The preset is the point

For BloodRayne, you want the preset. It contains a complete, curated breakdown based on actual gameplay observation. The freeform parser is useful for analyzing other games or for adding mechanics you notice in footage that the preset does not cover. But the preset gives you a production-ready spec document from a single command.

What you get

After the LLM generates the tool:

mechanics-breakdown/
  package.json
  src/
    index.js
    parser.js
    schema.js
    analyzer.js
    formatter.js
  presets/
    bloodrayne.js

Fire it up

cd mechanics-breakdown
npm install
node src/index.js --preset bloodrayne --format both --output ./specs

You should see the summary printed to your console — 8 mechanics across 4 categories, with complexity ratings and dependency relationships. Open specs/mechanics.json to see the structured data. Open specs/mechanics.md to see the formatted documentation.

If something is off

Problem	Follow-up prompt
Preset data not loading	`The --preset bloodrayne flag produces "Preset not found." Make sure presets/bloodrayne.js exports an array of mechanic spec objects using module.exports, and that index.js loads it with require('../presets/' + presetName). Check the file path -- it should be relative to the src/ directory.`
Parser doesn’t extract numbers	`Freeform text like “about 15 damage” is not extracting the number 15. The parser needs regex patterns to find numeric values near keywords: /(\d+)\s*(damage
JSON output is nested too deep	`The mechanics.json output has specs nested multiple levels inside wrapper objects. The output should be a flat array of mechanic spec objects at the top level. Each spec should conform directly to the schema defined in schema.js.`
Markdown has no table of contents	`The Markdown output is a wall of text with no navigation. Add a table of contents at the top with links to each mechanic section using Markdown anchor format: [Blade Combo System](#blade-combo-system). Generate anchors from the mechanic name by lowercasing and replacing spaces with hyphens.`

How it works (the 2-minute version)

The schema defines what a complete mechanic spec looks like. States, parameters, inputs, dependencies, complexity, confidence. This is the contract between “someone watching gameplay” and “someone implementing gameplay.” Without the schema, observations are just notes. With the schema, they are actionable specifications.
The preset is a handcrafted dataset. The BloodRayne preset is not AI-generated guesswork. It is structured observations from watching actual gameplay, with parameters estimated from frame-by-frame analysis and genre conventions. The “confidence” field is honest — “observed” means it was directly visible in footage, “estimated” means it was inferred.
The parser converts freeform text into partial specs. It uses keyword matching to categorize observations and regex to extract numeric values. It is not a natural language understanding system — it is a structured extraction tool. If you write “the combo has 3 hits and the third does 35 damage,” the parser will extract: category = combat, parameter = hits: 3, combo3_damage: 35. It gets you 70% of the way there.
The analyzer fills gaps and builds relationships. It checks each spec against the schema and flags missing fields. More importantly, it identifies cross-references: “Blood Rage increases attack damage” links the blood rage system to the combat system. These dependency relationships are critical for implementation planning — you cannot build blood rage until the combo system works.
The formatter outputs two views of the same data. JSON is for machines — feed it into a game engine, a project management tool, or the next tool in your pipeline. Markdown is for humans — print it, share it in a meeting, hand it to a game designer. Same data, two audiences.

🔍From spec to prototype: what happens next

The JSON output from this tool is designed to be consumed by a game engine or prototyping framework. Here is how each mechanic spec translates to implementation:

State machines map directly to state machine implementations in every major engine. Unreal has its Blueprint state machines. Unity has Animator state machines and custom FSMs. Godot has its state machine nodes. The states and transitions in your spec become nodes and edges in the engine’s visual editor.

Parameters become tunable constants. In a game engine, you would expose these as configurable values (Unreal: UPROPERTY, Unity: SerializeField, Godot: export). During prototyping, designers adjust these numbers to tune how the game feels. “Combo window 0.6s” might become 0.5s or 0.7s based on playtesting.

Inputs map to the engine’s input system. “Press attack while grounded starts combo chain” becomes an input binding with a context condition. Modern engines have input action systems that make this straightforward.

Dependencies define your implementation order. You build core locomotion first because wall interactions depend on it. You build the blade combo system before blood rage because the meter fills from combo hits. The dependency graph is your sprint planning tool.

This is not theoretical. Studios working on remakes follow exactly this process: document the original mechanics, structure the documentation, prioritize by dependency, and implement in order. The only difference is that most studios do this with design documents written in Google Docs. You are doing it with a tool that outputs structured data a machine can read.

Customize it

Add visual state diagrams

Turn text-based state machines into actual diagrams:

Add a --diagrams flag that generates Mermaid.js state diagram syntax for each
mechanic. Output a .mmd file per mechanic. For example, the blade combo system
would generate:
stateDiagram-v2
  [*] --> Idle
  Idle --> Combo1: Press Attack
  Combo1 --> Combo2: Press Attack (within 0.6s)
  Combo2 --> Combo3: Press Attack (within 0.6s)
  Combo3 --> Recovery: Animation Complete
  Recovery --> Idle: 0.8s elapsed
  Idle --> SpinSlash: Hold Attack
  SpinSlash --> Recovery: Animation Complete
These render in GitHub, VS Code, and many documentation tools.

Add a remake comparison mode

Compare your spec against another game’s implementation:

Add a --compare flag that takes two preset names and generates a comparison
report. For each mechanic category, show side-by-side specs. For example,
comparing BloodRayne's combat against Devil May Cry's combat would highlight:
both have combo chains, but DMC has style ratings while BloodRayne has blood rage.
DMC has more combo variety (4 weapons) while BloodRayne has the feed mechanic.
Create a second preset "dmc" with basic Devil May Cry 1 mechanics for comparison.
This helps identify what makes BloodRayne's combat distinct and what to preserve
in the remake.

Add implementation time estimates

Plan the development sprint from the spec:

Add a --estimate flag that calculates implementation time estimates for each
mechanic. Use these base rates:
- Low complexity: 1-2 weeks for a single developer
- Medium complexity: 2-4 weeks
- High complexity: 4-8 weeks
- Very high complexity: 8-16 weeks
Factor in dependencies: if mechanic B depends on mechanic A, B cannot start
until A is at least 50% complete. Generate a Gantt-style text chart showing
the implementation order and timeline. Output total estimated development time
for all mechanics. For BloodRayne, the 8 core mechanics should estimate at
roughly 30-50 developer-weeks of implementation work.

Try it yourself

Open your CLI tool in an empty folder and paste the prompt.
Run npm install && node src/index.js --preset bloodrayne --format both --output ./specs.
Open specs/mechanics.json. Look at the blade combo system spec. Every state, transition, and parameter is structured and machine-readable. This is what implementation-ready documentation looks like.
Open specs/mechanics.md. Scroll through the formatted document. The state diagrams, parameter tables, and dependency graph give you a complete picture of what you are building.
Look at the dependency graph. Notice that combat (blade combo) is the foundation. Blood rage and feed attacks both depend on it. Core locomotion underpins wall interactions. This tells you what to build first.
Now try the freeform parser. Create a text file with observations from a different game you know well (or a different aspect of BloodRayne you noticed in footage). Run it through with --input and see how much the parser extracts. Fill in the gaps manually.
Try the state diagram customization. Seeing the state machines visually makes the mechanics concrete in a way that text tables cannot.

Key takeaways

Structured specs are the bridge between playing a game and building one. Watching BloodRayne and saying “the combat is cool” does not help a programmer. A JSON spec with states, transitions, parameters, and triggers does.
The schema forces completeness. When every mechanic must have states, parameters, and inputs defined, you cannot hand-wave past the details. Missing fields become explicit warnings, not silent omissions.
Dependencies define your implementation order. You cannot build blood rage until combos work. You cannot build wall jumps until basic movement works. The dependency graph is your project plan.
The preset is your starting asset. The pre-filled BloodRayne breakdown is not a demo. It is a real, usable specification document for the core mechanics of the game you want to remake. Modify it, extend it, and use it.
Freeform-to-structured is a reusable pattern. This same approach works for analyzing any game, documenting any system, or converting any set of observations into actionable specifications. The tool is specific to games. The pattern is universal.

What’s next

You have built five tools in this module: a market tracker, a comparable economics analyzer, a storefront revenue simulator, a studio runway planner, and a mechanics breakdown. Together, they form a complete toolkit for evaluating, planning, and documenting a retro game remake. The market data says cult revivals are profitable. The economics say BloodRayne fits the mid-budget profile. The storefront model shows where the revenue comes from. The runway planner shows how long you can operate. And the mechanics spec tells you exactly what you are building. The next phase is turning all of this into action — but that is your journey now, not another lesson.

What you'll learn