The Blades of Ronnin

A fast-paced 2D samurai slasher fusing precision parries, gory executions, and explosive ninjutsu in an endless flow-state survival battle.

Comment

Blade of the Ronin: Blood & Blossoms (刀匠の道)

Technical Specification & Game Architecture Overview

1. Executive Summary

Blade of the Ronin is a high-speed, precision 2D samurai action slasher built with TypeScript, Phaser 3, and the Web Audio API. The game emphasizes fluid movement, frame-tight parry and counter mechanics, anime-inspired Ninjutsu arts, and an infinite survival loop powered by a dynamic AI Combat Director.

graph TD
    A[BootScene / AssetGenerator] --> B[MainMenuScene]
    B --> C[GameScene]
    C --> D[Player Subsystem]
    C --> E[Combat & DeathFinisher Manager]
    C --> F[Flow State Engine]
    C --> G[AI Director & Infinite Waves]
    C --> H[Procedural Web Audio Engine]
    C --> I[UIManager & HUD]
    D --> J[Ninjutsu Projectiles: Chidori / Katon / Flame Blaze]
    E --> K[Hit-Stop & Screen Trauma FX]
    G --> L[Scaling Boss Tiers & Bodyguards]
    C --> M[Save & Persistence Manager]

2. The FLOW Combat Engine

The core gameplay centers on the FLOW State—a dynamic momentum mechanic that rewards aggression, flawless parries, and evasive discipline while punishing mistakes.

2.1. Mathematical Formulation of FLOW

The current Flow level $F(t) \in [0, 100]$ evolves dynamically with player combat actions and idle decay:

$$\frac{dF}{dt} = \sum_{k} \Delta F_k \cdot \delta(t - t_k) - \lambda \cdot \Theta(t - t_{\text{last}} - \tau_{\text{decay}})$$

Where:

  • $\Delta F_k$ represents instantaneous Flow gains: $$\Delta F_{\text{kill}} = +15, \quad \Delta F_{\text{parry}} = +20, \quad \Delta F_{\text{hit}} = +6, \quad \Delta F_{\text{dodge}} = +4, \quad \Delta F_{\text{hurt}} = -25$$
  • $\Theta(x)$ is the Heaviside step function, activating decay after an idle window $\tau_{\text{decay}} = 3.5\text{ s}$.
  • $\lambda = 8.0\text{ s}^{-1}$ is the linear decay rate.

2.2. Style Rank Thresholds & Speed Multipliers

The player transitions across stylistic tiers based on $F(t)$, granting scaling movement speed $v_{\text{mult}}$ and attack acceleration:

Rank Title Threshold ($F_{\min}$) Speed Boost ($v_{\text{mult}}$) Attack Cooldown Reduction Visual Aura
D DISCIPLINE $0$ $1.00\times$ $0\%$ Base
C CLEAVE $20$ $1.06\times$ $5\%$ Subtle Embers
B BRAVERY $40$ $1.12\times$ $10\%$ Crimson Ribbons
A ASCENSION $60$ $1.18\times$ $15\%$ Electric Aura
S SHADOW $80$ $1.25\times$ $20\%$ Ghost Speed Trails
SS SHINIGAMI $95$ $1.32\times$ $25\%$ Chromatic Aberration

2.3. Scoring Metric

Run score $S_{\text{total}}$ scales with both base action value $B_k$ and the active rank index $R \in [0, 5]$:

$$S_{\text{total}} = \sum_{k=1}^{N} B_k \cdot \left(1 + 0.50 \cdot R_k\right) \cdot \left(1 + 0.05 \cdot C_k\right)$$

Where $C_k$ is the uninterrupted combo kill count at event $k$.

3. Ninjutsu Arts & Projectile Mechanics

In addition to traditional katana strikes, the samurai commands three anime-inspired Ninjutsu techniques:

                  ┌──────────────────────────────────────────────┐
                  │            NINJUTSU ABILITY SUITE            │
                  └──────────────────────────────────────────────┘
                       │                 │                 │
             [Q] 千鳥 (CHIDORI)    [E] 豪火球 (KATON)   [R] 豪火滅却 (GREAT FLAME)
             • Piercing Dash       • Ranged AoE Blast   • Screen-Wide Inferno Tsunami
             • $1050\text{ px/s}$  • $R=110\text{ px}$  • Multi-Hit Continuous Wave
             • Electric Stun       • Sine Oscillation   • $3.5\text{s}$ Inferno Burn

3.1. 千鳥 — Chidori (Lightning Assault)

A high-velocity piercing dash concentrating crackling chakra in the blade hand:

  • Dash Velocity Vector: $$\vec{v}_{\text{chidori}} = \left(d \cdot 1050\text{ px/s}, \, 0\right), \quad d \in {-1, 1}$$
  • Damage Distribution: $$D_{\text{pierce}}(n) = \begin{cases} 85\text{ HP} & n = 1 \ 65\text{ HP} & n = 2 \ 45\text{ HP} & n \ge 3 \end{cases}$$
  • Electric Stun: Immobilizes targets for $t_{\text{stun}} = 850\text{ ms}$.

3.2. 豪火球 — Katon (Fireball Projectile)

A concentrated plasma sphere traveling with vertical sine-wave disturbance:

$$y(t) = y_0 + A \cdot \sin(\omega t), \quad A = 6\text{ px}, \quad \omega = 15\text{ rad/s}$$

  • Horizontal Velocity: $v_x = d \cdot 720\text{ px/s}$.
  • Radial Splash Damage: $$D_{\text{splash}}(r) = D_0 \cdot \max\left(0, \, 1 - \frac{r}{1.5 \cdot R_{\text{splash}}}\right), \quad R_{\text{splash}} = 110\text{ px}, \quad D_0 = 75\text{ HP}$$

3.3. 豪火滅却 — Great Flame Blaze

A massive, expanding tsunami flame wall designed for full-screen crowd control:

  • Wavefront Expansion Geometry: $$H_{\text{wave}}(t) = H_0 \cdot \left(0.85 + 0.50 \cdot \frac{t}{t_{\text{life}}}\right), \quad H_0 = 120\text{ px}, \quad t_{\text{life}} = 1600\text{ ms}$$
  • Multi-Hit Interval: Each enemy $E_i$ inside the bounding box can be hit up to 2 times: $$\Delta t_{\text{hit}} \ge 220\text{ ms}, \quad D_{\text{tick}} = 70\text{ HP} \implies D_{\max} = 140\text{ HP}$$
  • Inferno Burn DoT: $$\frac{d\text{HP}}{dt} = -8\text{ HP/tick}, \quad \Delta t_{\text{tick}} = 500\text{ ms}, \quad T_{\text{burn}} = 3500\text{ ms}$$

4. AI Director & Infinite Wave Survival

The game implements an uncapped survival system where waves progress infinitely ($w \in {1, 2, 3, \dots, \infty}$) without artificial endpoints.

4.1. Wave Scaling Equations

  • Enemy Quota per Wave: $$N_{\text{enemies}}(w) = \min\left(22, \, 5 + \lfloor 1.8 \cdot w \rfloor\right)$$
  • Spawn Delay Intervals: $$\Delta t_{\text{spawn}}(w) = \max\left(700\text{ ms}, \, 1400 - 60 \cdot w\text{ ms}\right)$$

4.2. Boss Scaling Matrix ($w \pmod 3 \equiv 0$)

Every 3rd wave triggers a Boss Duel with dynamic scaling based on Boss Tier $T = \frac{w}{3}$:

$$H_{\text{boss}}(T) = 400 + 180 \cdot (T - 1)\text{ HP}$$ $$P_{\text{posture}}(T) = 250 + \min\left(200, \, \lfloor 45 \cdot (T - 1) \rfloor\right)$$ $$N_{\text{bodyguards}}(T) = \min\left(6, \, 2 \cdot (T - 1)\right)$$

Wave 3  (Tier 1) ──► ⚔ CORRUPTED KENSEI ⚔             [400 HP | Solo Duel]
Wave 6  (Tier 2) ──► ⚔ VOID BLADE KENSEI ⚔            [550 HP | 2 Assassins]
Wave 9  (Tier 3) ──► ⚔ INFERNAL KENSEI ⚔              [730 HP | 2 Heavies + 2 Archers]
Wave 12 (Tier 4) ──► ⚔ ABYSSAL OVERLORD KENSEI ⚔      [910 HP | 6 Mixed Elites]
Wave 3N (Tier N) ──► ⚔ ASCENDED DEMON KENSEI ⚔        [Scaled HP & Minions]

4.3. Token-Based Aggression Controller

To ensure combat readability, enemies must request attack permissions from the Director:

  • Maximum concurrent melee tokens: $N_{\text{melee}} = 3$.
  • Maximum concurrent ranged tokens: $N_{\text{ranged}} = 2$.

5. Death Finisher & Physics Clamping Engine

Generic instant deaths are replaced with 10 contextual death finisher archetypes with zero ground-clipping guarantees.

5.1. Finisher Selection Matrix

$$\text{Finisher} = f\left(\text{AttackType}, \, \text{IsHeavy}, \, \text{IsAirborne}, \, \text{WallDist}, \, \text{RecentHistory}\right)$$

                               ┌─────────────────────────────────┐
                               │     ENEMY HP REDUCED TO 0       │
                               └─────────────────────────────────┘
                                                │
                 ┌──────────────────────────────┼──────────────────────────────┐
                 ▼                              ▼                              ▼
          [WALL PROXIMITY]               [AERIAL / PLUNGE]             [GROUND ARCHETYPES]
          • Wall Splat                   • Ground Impalement           • Decapitation
          • Kinetic Pinning              • Heavy Crater Smash          • Torso Bisection
                                                                       • Throat Slit Dash
                                                                       • Heavy Gut Thrust

5.2. Level Geometry Surface Clamping

Corpses and death animations strictly clamp to the nearest terrain surface to eliminate falling out of bounds:

$$y_{\text{corpse}} = \min\left(y_{\text{ground}}, \, \min_{p \in \text{Platforms}} { y_p \mid x_p^{\text{left}} \le x \le x_p^{\text{right}} \text{ and } y_p \ge y_{\text{entity}} - 16 }\right)$$

6. Procedural Japanese Web Audio Synthesizer

The sound system generates audio in real-time without external .mp3/.wav assets using the Web Audio API.

6.1. Pentatonic Hirajoshi Scale

Interactive background music and stingers synthesize pitches from the traditional Japanese Hirajoshi mode across 3 octaves:

$$\mathcal{S}_{\text{Hirajoshi}} = { 146.83, 155.56, 196.00, 220.00, 233.08, \dots, 932.33 }\text{ Hz}$$

6.2. Procedural Audio Graph

$$\text{OscillatorNode} \xrightarrow{\text{Frequency Sweep}} \text{BiquadFilterNode (LowPass/BandPass)} \xrightarrow{} \text{GainNode (Envelope)} \xrightarrow{} \text{MasterGain} \xrightarrow{} \text{Destination}$$

  • Dynamic Tempo: $\text{BPM}(F) = 116 + \lfloor 28 \cdot \frac{F}{100} \rfloor$.
  • Hit-Stop Time Dilation: Instantaneous freeze frames ($\Delta t_{\text{hitstop}} \in [60, 120]\text{ ms}$) coupled with screen camera trauma: $$\text{ShakeOffset}(t) = \text{Trauma}^2 \cdot \text{MaxOffset} \cdot \sin(2\pi f t)$$

7. Storage & Persistence Specification

All player settings and achievements persist across sessions via namespaced localStorage keys:

{
  "ronin_highscores": {
    "bestScore": 24850,
    "bestKills": 86,
    "bestCombo": 24,
    "bestFlow": 98,
    "bestWave": 11,
    "lastPlayedTimestamp": 1787319000000
  },
  "ronin_controls": {
    "MOVE_LEFT": "A",
    "MOVE_RIGHT": "D",
    "JUMP": "SPACE",
    "SPRINT": "SHIFT",
    "SLIDE": "S",
    "ATTACK": "J",
    "PARRY": "K",
    "SPECIAL": "L",
    "CHIDORI": "Q",
    "FIREBALL": "E",
    "GREAT_FLAME": "R"
  },
  "ronin_settings": {
    "masterVolume": 0.8,
    "musicVolume": 0.65,
    "sfxVolume": 0.9,
    "screenShake": true,
    "particleQuality": "HIGH",
    "showDamageNumbers": true,
    "showBloodGore": true
  }
}

8. Summary of Controls

Action Primary Key Alternate Binding Description
Movement A / D Left / Right Arrows Ground locomotion
Sprint / Dash Shift Double-tap direction High-speed dash with invulnerability frames
Jump / Wall Jump Space W / Up Arrow Vertical leap & wall parkour
Slide S (while moving) Down Arrow Low katana sweep
Katana Strike J Left Mouse Click 3-hit fluid attack chain
Precision Parry K Right Mouse Click Frame-tight posture deflection
Chidori (千鳥) Q U / 1 High-speed electric piercing melee assault
Katon (豪火球) E I / 2 Oscillating explosive fireball projectile
Great Flame Blaze (豪火滅却) R O / 3 Wide-area multi-hit expanding fire wave
Flow Slash (絶命) L — Screen-wide Judgement Cut execution (Requires Flow $\ge 60$)
Pause Menu ESC P Opens pause overlay, settings & custom rebinding
Share this project:

Updates

Submission history