# Shogun's Storm — Revised Technical Plan ## Why This Plan Exists The first technical analysis recommended Phaser.js (2D) because it was safe — high Claude Code reliability, proven with kids, easy deployment. But it produced a game that looked like every other 2D game Sebastian had already built. No wow. No atmosphere. No Ghost of Tsushima. The problem: the first plan chose the engine first and then tried to fit Sebastian's vision into it. This plan does the opposite. It starts from Sebastian's design decisions — the brilliant ones — and works backward to the technology that serves them. --- ## Sebastian's Design Decisions — The North Stars These are non-negotiable. The technology serves these, not the other way around. ### 1. Ghost Mode The screen drains to black and white. The wind picks up. Jin becomes unstoppable — except against bosses. Limited duration. The most powerful ability in the game, and the most cinematic. The moment everyone in the room goes quiet. **What this requires:** Post-processing shader (desaturation), wind particle burst, damage multiplier with boss exception, timer UI, camera effects. ### 2. Cherry Blossoms as Storytelling Castle Shimura: blossoms fall everywhere, constantly, regardless of combat. Beauty persists through violence. Iki Island: blossoms fall only from the place where Kazumasa died. Same particle, completely different meaning. **What this requires:** Global particle emitter (Castle Shimura), localized point emitter (Iki Island), particles that run on their own clock independent of game state. ### 3. Ryuzo's Betrayal First playthrough: Ryuzo fights beside you on blue team. Every playthrough after: he's on red team. The game remembers. Not a cutscene. Not dialogue. The roster changes. Storytelling through mechanics. **What this requires:** localStorage persistence, roster assignment logic that checks first-playthrough flag. ### 4. Every Character Fights Differently Picking Ishikawa vs Yuna isn't picking a skin — it's picking a different combat experience. Ishikawa controls space with arrows. Yuna gets in close with daggers. Jin switches stances. Lord Shimura is disciplined and powerful. Team composition matters because abilities complement each other. **What this requires:** Per-character animation sets, per-character state machines, distinct attack ranges/speeds/patterns, team AI that uses character abilities. ### 5. Bosses Resist the Ultimate Ghost Mode can't kill Khotun Khan or the Eagle. The feeling of invincibility against soldiers but vulnerability against the real threat — that tension is what makes boss fights matter. **What this requires:** Boss entity flag, Ghost Mode damage check, multi-phase boss AI, health bar with phase indicators. --- ## Tech Stack Every choice here is made to serve the design decisions above. ### Core Engine: Three.js **Why:** Sebastian's vision is atmospheric and cinematic. Three.js delivers 3D environments with post-processing effects (Ghost Mode), volumetric particles (cherry blossoms), and the spatial depth that makes Castle Shimura feel like a place, not a backdrop. Claude Code generates reliable Three.js code, and multiple skill files exist for scene setup, animation, materials, and rendering. **Why not Phaser:** 2D cannot deliver the atmosphere Sebastian described. It can't deliver Ghost Mode's cinematic black-and-white drain in a way that feels different from a CSS filter on a sprite. It can't deliver cherry blossoms drifting through 3D space. It can't deliver the feeling of being inside Castle Shimura. ### Character Pipeline: All-in-Claude-Code (Gemini MCP + Meshy MCP) Sebastian creates the characters without leaving Claude Code. Not a stock asset library — his characters, his game, his conversation. **Workflow per character (one continuous Claude Code session):** 1. Sebastian describes the character to Claude Code. Claude uses the **Gemini MCP** to generate concept art. Sebastian iterates through conversation — "the armor should be darker, the katana longer" — until the image matches his vision. This is the controllable step: text-to-3D is a slot machine, but image gen through conversation gives him creative control. 2. Claude sends the locked concept art to **Meshy MCP** (`create_image_to_3d_task`) — image-to-3D conversion happens in the background. More consistent than text-to-3D because Meshy has a visual reference. 3. Claude calls **Meshy MCP auto-rig** — Meshy auto-detects humanoid body structure, applies skeleton. 4. Claude applies **animation presets** via Meshy MCP — Sebastian chooses which combat moves to give his character: - `Idle` — standing ready - `Combat_Stance` — fighting ready position - `Sword_Judgment` / `Left_Slash` — attack moves - `Double_Combo_Attack` / `Triple_Combo_Attack` — combo sequences - `Sword_Parry` / `Two_Handed_Parry` — parry/deflect - `Block1` through `Block10` — blocking stances - `BeHit_FlyUp` — hit reaction - `Dying` / `Dead` — death sequence - `Walking` / `Run_02` — movement 5. Claude downloads the final animated model as **FBX** — one file with mesh + skeleton + all animation clips. 6. Load into Three.js with `FBXLoader` + `AnimationMixer` — access animations by name. **Sebastian never leaves Claude Code.** The Gemini MCP handles images, the Meshy MCP handles 3D/rig/animate/export. His workflow is pure conversation. **Why FBX over GLB:** Known texture loading issues with Meshy GLB exports in Three.js. FBX preserves animation data better and loads reliably. **Why no Mixamo:** Friction. Requires FBX conversion, Blender intermediate step, skeleton mapping. Meshy Animate presets (500+) cover the combat moveset. If we need more animation control later, Mixamo is a growth-path option — not a dependency. **Meshy MCP setup:** `npx -y meshy-ai-mcp-server` with `MESHY_API_KEY` environment variable. 24 tools covering the full pipeline. Credit-based (~5-30 credits per image-to-3D, ~5 per rig, ~3 per animation). ### Particles: three.quarks Production-grade particle engine for Three.js. Supports localized point emitters (cherry blossoms from Kazumasa's memorial), force fields (wind during Ghost Mode), billboard rendering (petals always face camera), and behaviours like gravity, drift, color-over-lifetime. Used in published games. ### Post-Processing: pmndrs/postprocessing The library for Three.js screen effects. Desaturation pass for Ghost Mode's black-and-white drain. Bloom for sword impacts and atmospheric glow. Vignette for cinematic framing. All composable through EffectComposer. ### Input: Gamepad API (native browser) Xbox controller mapping is native to modern browsers. No library needed. LB+RB maps directly to Ghost Mode activation — same muscle memory as Ghost of Tsushima. ### Deployment: itch.io Sebastian wants to send the game to friends. itch.io hosts browser games for free. Friends click a link and play. No installs. ### Juice Stack The combat feel layer. Applied to every hit in the game: - **Hitstop** — 3-5 frame pause on impact (both characters freeze) - **Screen shake** — 2-3 frame camera displacement - **Hit flash** — white overlay for 1 frame on the hit character - **Knockback** — physics impulse pushing hit character back - **Hit spark** — particle burst at point of contact - **Damage numbers** — floating text showing damage dealt These are individually trivial. Together they make a sword hit feel like a sword hit. --- ## Build Sequence Every session ends with something playable. The wow moments are front-loaded. Sebastian's design decisions drive the order, not technical convenience. ### Phase 1: Jin Lives (Sessions 1–2) **Before Session 1 — Sebastian's Homework:** Sebastian designs Jin Sakai as a 2D image first — talking to Claude Code, which uses the Gemini MCP for image generation. He iterates through conversation until the stance, the armor, the katana, the expression are right. That image is his concept art. Then Meshy image-to-3D turns it into a model. Rig. Animate with combat presets (idle, combat stance, sword attacks, parry, block, hit reaction, death, walk). Download as single FBX. This is the moment the game becomes *his*. Not an asset pack character. His concept art, realized in 3D, animated, ready to fight. **Session 1 — Jin Fights** - Three.js scene: simple arena with moody lighting (directional light + ambient, warm/cool contrast) - Load Sebastian's Jin model (FBX → AnimationMixer) - Xbox controller input: left stick moves, face buttons attack - One Mongol enemy (can be a placeholder model — Meshy-generated or basic geometry) - **Full juice stack on every hit:** hitstop, screen shake, hit flash, knockback, spark particles, damage numbers - Health bars for both characters - Cherry blossom particles drifting constantly (global emitter, gentle gravity + horizontal drift) > **Wow moment:** Jin — Sebastian's Jin, the one he built in Meshy — stands in a 3D arena with cherry blossoms falling. He swings his sword. The enemy staggers. The screen shakes. Particles burst. This is not a 2D sprite game. **Session 2 — Combat Depth** - Enemy AI: approach → attack → block cycle (finite state machine) - Jin's block/parry mechanic — timing-based, visual feedback on perfect parry (time slows for 200ms, camera punches in slightly, distinct sound) - Second stance for Jin (different attack animations, different range/speed) - Death animation and round reset - Difficulty modes: easy (300ms parry window), medium (200ms), hard (100ms) > **Wow moment:** The first perfect parry. The enemy attacks. Sebastian times the block. Time slows. The enemy staggers. This is the mechanic that defines samurai games. ### Phase 2: Ghost Mode (Session 3) This is the signature moment of Shogun's Storm. It gets its own session because it deserves full attention. **Session 3 — Ghost Mode** - LB+RB activation - Post-processing pipeline: desaturation shader ramps from full color to black-and-white over 0.5 seconds - Wind particle system kicks in — horizontal particle burst, increasing intensity - Camera: subtle zoom-out to show more of the battlefield - Jin's attacks become instant kills on non-boss enemies (damage multiplier + special kill animation) - Ghost Mode duration bar (drains over ~8 seconds) - Cooldown timer before reuse - Spawn 4-5 Mongol enemies to demonstrate the power difference - When Ghost Mode ends: color ramps back in, wind dies down, Jin returns to normal > **Wow moment:** Ghost Mode. The screen drains. The wind rises. Jin cuts through everything. The cherry blossoms keep falling — they don't care about Ghost Mode. Then it ends, and the color comes back, and Sebastian is just a samurai again. That contrast is the entire game. ### Phase 3: Castle Shimura (Session 4) The game gets a world. **Session 4 — The Battlefield** - Castle Shimura environment: 3D arena with architectural elements (pillars, walls, elevated platforms) - Can be AI-generated (Sebastian creates the environment in Meshy or uses Claude Code to build geometry) or assembled from basic shapes with textures - Parallax depth: multiple layers of background elements at different distances - Cherry blossom particle system refined: petals catch light, drift realistically, accumulate on the ground - Atmospheric lighting: warm interior light through windows, cool shadows, god-ray effect (volumetric light shafts via post-processing) - Character select screen (Jin for now, with locked slots showing silhouettes of future characters) - Team select (blue/red) - 1v1 mode fully functional against AI with difficulty selection > **Wow moment:** Castle Shimura. Cherry blossoms drift through shafts of light. Jin stands ready. The game has atmosphere now. It's a place, not a test scene. ### Phase 4: The Roster Begins (Sessions 5–7) Each new character is a new way to play. Sebastian designs each one — concept art first (via Claude Code + Gemini MCP for image generation), iterate until it matches his vision, then Meshy image-to-3D, rig, animate. Each warrior is his design from concept art to fighter. **Session 5 — Yuna** - Sebastian designs Yuna as 2D concept art first via Claude Code + Gemini MCP (daggers, lighter armor, fast-looking), iterates until right, then Meshy image-to-3D - Different animation set: quick slashing attacks, shorter range, faster recovery - Stealth ability: Yuna can briefly turn semi-transparent and reposition (short dash + opacity tween) - Character select screen now has Jin and Yuna — picking between them feels meaningfully different - AI can play as either character **Session 6 — Sensei Ishikawa** - Sebastian designs Ishikawa as concept art via Claude Code + Gemini MCP (bow, robes, archer stance), then Meshy image-to-3D - Ranged combat: aim with right stick, draw/release with trigger - Ishikawa gameplay is fundamentally different — keep distance, punish approach, control space - AI Ishikawa stays at range and retreats when enemies close in - Playing against an AI Ishikawa as Jin forces different tactics than fighting a melee enemy **Session 7 — Lord Shimura and Ryuzo** - Two characters, completing the blue team roster - Lord Shimura: heavy, powerful, slow but devastating hits. Traditional samurai — discipline over speed. - Ryuzo: fast swordsman, aggressive, high damage but lower defense - **Ryuzo's betrayal mechanic:** - First time playing Castle Shimura → Ryuzo is on blue team roster - `localStorage.setItem('castleShimuraCompleted', 'true')` after first completion - Every subsequent session → Ryuzo appears on red team roster - No dialogue. No explanation. The roster just changes. Players who know, know. > **Wow moment (Session 7):** Sebastian finishes Castle Shimura for the first time. Starts again. Goes to pick his team. Ryuzo is on the other side now. "Wait — what?" That's storytelling through game mechanics. ### Phase 5: The Boss and Team Mode (Sessions 8–10) **Session 8 — Khotun Khan** - Sebastian designs Khotun Khan as concept art via Claude Code + Gemini MCP (imposing, armored, Mongol leader), then Meshy image-to-3D - Boss AI: multiple attack patterns, phase transitions (health bar segments) - **Ghost Mode immunity:** Khotun Khan has a boss flag. Ghost Mode damage check: `if (target.isBoss) return normalDamage`. Jin's ultimate power doesn't work. The player feels the shift. - Boss arena: cleared space within Castle Shimura, dramatic lighting change when boss phase begins **Session 9 — Team Battle** - 4v4 mode: player picks one character, AI controls three teammates and four enemies - Team AI uses character abilities: Ishikawa stays back, Yuna flanks, Shimura holds center - Wave structure or continuous battle against Mongol forces, culminating in Khotun Khan **Session 10 — Polish and Ship** - Title screen with atmosphere (cherry blossoms, moody lighting, Shogun's Storm logo) - Sound: sword clashes, arrow impacts, Ghost Mode wind, ambient music - Tutorial mode for new players (Sebastian designed this for "someone like your mom") - Local multiplayer: second controller for 1v1 - Deploy to itch.io - Sebastian sends the link to his friends > **Wow moment (Session 10):** Sebastian's friends open a link. They're playing Shogun's Storm. A game with 3D characters Sebastian created, atmospheric environments, Ghost Mode, and a combat system where every character fights differently. This is not a template game. This is his. ### Phase 6: Iki Island — The Expansion (Sessions 11+) **Session 11 — Iki Island** - New map: different atmosphere from Castle Shimura (more wild, less refined) - **The Kazumasa memorial:** Cherry blossoms fall from ONE specific point on the map — a localized emitter positioned where Kazumasa died. Everywhere else is bare. That single detail changes the mood of the entire battlefield. - Tenzo and raider characters (concept art via Claude Code + Gemini MCP → Meshy image-to-3D) - The Eagle as new boss (different fight pattern than Khotun Khan, different threat) > **Wow moment:** Iki Island loads. No cherry blossoms. Then Sebastian walks to one spot on the map and there they are — falling from one place, gently, endlessly. If he knows the story, it hits. If he doesn't, it's beautiful. Both reactions are right. That's Sebastian's design. --- ## Wow-Factor Map | Session | Wow Moment | Design Decision Honoured | |---------|-----------|--------------------------| | 1 | Sebastian's own 3D Jin fights in a cherry blossom arena with full juice stack | Beauty persists through violence | | 2 | First perfect parry — time slows, enemy staggers | Each character fights differently | | 3 | Ghost Mode — screen drains, wind rises, Jin becomes unstoppable | Ghost Mode as constrained power | | 4 | Castle Shimura with atmospheric lighting and depth | The world matters | | 5 | Playing as Yuna — daggers, speed, completely different feel | Each character fights differently | | 6 | Ishikawa — ranged combat changes everything | Team composition matters | | 7 | Ryuzo switches sides. The game remembers. | Ryuzo's betrayal | | 8 | Ghost Mode can't save you from Khotun Khan | Bosses resist the ultimate | | 10 | Friends play Sebastian's game | Shareable | | 11 | Cherry blossoms fall from one spot on Iki Island | Cherry blossoms as storytelling | --- ## Risk Points ### Where Frustration Might Spike 1. **Meshy model quality variation (Session 1).** Text-to-3D can produce inconsistent results. Some models will look great; others won't. **Mitigation:** Sebastian generates 2-3 versions of Jin and picks the best one. He already does this with Meshy — iteration is his workflow. 2. **Meshy Animate preset animations may feel generic (Session 1-2).** The combat presets are functional but not custom. A "Sword_Judgment" animation is generic samurai, not specifically Jin Sakai. **Mitigation:** Start with presets. They're good enough for the combat to feel real. If specific characters need custom feels later, that's polish — not a blocker. The juice stack (hitstop, shake, flash) does more for combat feel than the animation itself. 3. **FBX loading in Three.js (Session 1).** FBXLoader is reliable but occasionally has material/texture issues. **Mitigation:** Test the pipeline once before the session. Load one Meshy FBX into a blank Three.js scene. Verify textures render. Solve any issues before Sebastian is in the room. 4. **Parry timing (Session 2).** The feel of the parry window requires playtesting. Too strict = unfair. Too generous = no tension. **Mitigation:** Start generous (300ms), let Sebastian play, tighten based on his feedback. The difficulty modes exist for this — easy has a forgiving window, hard punishes. 5. **3D environment creation (Session 4).** Castle Shimura needs to look good but doesn't need to be architecturally accurate. **Mitigation:** Start with basic geometry (walls, pillars, floor) plus strong lighting and particles. Atmosphere comes from light and particles more than polygon count. A simple room with cherry blossoms and god-rays looks better than a detailed room with flat lighting. 6. **Scope creep on the roster (Sessions 5-7).** Sebastian knows every Ghost of Tsushima character. He'll want them all. **Mitigation:** The build sequence has Jin fully polished with Ghost Mode and atmosphere before any second character. Each new character is an expansion. The rule: if it doesn't make the combat feel better, it waits. 7. **Team AI (Session 9).** Making AI teammates fight intelligently is hard. **Mitigation:** Simple is fine. AI teammates attack nearby enemies, use abilities on cooldown, stay roughly in formation. "Good enough" AI that doesn't ruin the experience is the bar, not sophisticated tactical AI. ### Where Scope Creep Is Most Likely - Adding characters before combat feels right - Wanting online multiplayer immediately (v1.0 is local) - Wanting Iki Island before Castle Shimura is polished - Adding story/cutscenes before gameplay works - Requesting specific Ghost of Tsushima scenes that require environment art beyond our pipeline **The rule stays:** If it doesn't make hitting an enemy feel better, it waits. --- ## Pre-Session 1 Checklist (Andres Does This Before the Kids Touch It) 1. **Test the Meshy → Three.js pipeline end to end.** - Create a throwaway character in Meshy - Rig it, add 2-3 animation presets - Export as single FBX - Load into a blank Three.js scene with FBXLoader - Verify: model renders with textures, animations play via AnimationMixer, controller input works - Fix any issues. Sebastian should never see a pipeline failure. 2. **Set up the Three.js project scaffold.** - Scene, camera, renderer, lighting, resize handling - FBXLoader configured - AnimationMixer ready - Gamepad API polling - three.quarks particle system imported - pmndrs/postprocessing imported with EffectComposer - This is the "blank canvas" Sebastian walks into 3. **Install Phaser MCP server? No. Install Three.js skills for Claude Code.** - [claude-skills-threejs-ecs-ts](https://github.com/Nice-Wolf-Studio/claude-skills-threejs-ecs-ts) - [threejs-skills](https://github.com/CloudAI-X/threejs-skills) - These give Claude Code informed opinions about Three.js patterns 4. **Verify itch.io deployment works.** - Build a minimal Three.js scene - Deploy to itch.io - Open on another device - Confirm it loads and runs --- ## Growth Path ### After v1.0 - **Iki Island** — second map, new roster, the Kazumasa memorial cherry blossoms, the Eagle boss - **Online 1v1** — WebRTC or similar, share link, friend joins, browser-based duel - **Sound design session** — sword clashes, arrow impacts, Ghost Mode wind, atmospheric music - **More characters** — every Ghost of Tsushima character Sebastian wants ### Medium-term - **WebGPU upgrade** — all major browsers support it as of January 2026. Volumetric lighting, ray-traced shadows, millions of particles. Same Three.js codebase, dramatically better visuals. - **Roblox port** — if multiplayer with a wider audience becomes priority. Same game design, different platform. ### Long-term - **Unity via MCP** — if the game outgrows browser constraints. Claude Code interfaces with Unity through CoplayDev MCP (86+ tools). Highest ceiling, heaviest setup. But by then, Sebastian will have a proven game design and 10+ sessions of experience directing AI to build it. **The key insight from the first plan still holds:** The game design is engine-independent. Sebastian's vision document describes the GAME, not the technology. If Shogun's Storm v1.0 in Three.js proves the combat and the feel, the same design ports to any engine. Nothing is wasted. --- ## A Note on What Changed The first technical analysis said: "The atmosphere is achievable in 2D." It was wrong. The atmosphere Sebastian described — cherry blossoms drifting through a castle interior, the screen draining to black and white during Ghost Mode, the contrast between beauty and violence — requires spatial depth, lighting, and post-processing that 2D cannot deliver. The first analysis prioritized Claude Code reliability (Phaser 9/10) over wow factor. This plan prioritizes Sebastian's design vision and uses technology that can actually deliver it. Three.js is slightly less reliable with Claude Code than Phaser, but the gap is manageable — and the ceiling is incomparably higher. Sebastian didn't design a 2D game. He designed a 3D experience. The technology should match the ambition.