Phoenix Wright Visual Novel Engine

Expert guidance for working on a Phoenix Wright-style visual novel engine built with Next.js. This skill helps you navigate the codebase, understand the architecture, and implement new features following established patterns.

Project Overview

This is a vibe-coded visual novel engine inspired by Ace Attorney, featuring investigation sequences, dialogue systems, and court records. Built with Next.js, TypeScript, Zustand for state management, and Firebase for deployment.

Development Workflow

Available Commands

When running commands, use these scripts:

Key Architecture Principles

1. **Always consult BLUEPRINT.md first** - This file contains the architectural vision. New code MUST align with the blueprint. If your changes would diverge from it, confirm with the user before proceeding.

2. **Modular component design** - The engine uses discrete, reusable components for different game systems (dialogue, investigation, court records).

3. **Centralized state management** - All game state flows through the Zustand store (`src/lib/stores/gameStore.ts`).

Core Systems Guide

Game State Management

The game uses Zustand for state management located in `src/lib/stores/gameStore.ts`. Key state includes:

When modifying state, always use the provided actions rather than direct mutations.

Case Data Structure

Cases are stored as JSON files in `src/cases/case-*/case.json`. Each case contains:

**Scene Types:**

Asset Management Pattern

Assets are referenced by keys (e.g., "izzy-idle", "bg-office") in case JSON and resolved through the assets object. This enables:

When adding new assets:

1. Place files in `/src/cases/case-*/assets/`

2. Add key-path mappings in case JSON assets object

3. Reference by key in dialogue nodes or scenes

Component Architecture

Core Components

**GameEngine.tsx** (`src/components/game/`)

**DialogueBox.tsx** (`src/components/game/`)

**CharacterSprite.tsx** (`src/components/game/`)

**InvestigationScene.tsx** (`src/components/investigation/`)

**HotspotOverlay.tsx** (`src/components/investigation/`)

File Organization

```

/src/cases/ # Case data and assets

/src/components/game/ # Core game UI components

/src/components/investigation/ # Investigation mode

/src/components/court-record/ # Evidence and profiles

/src/lib/game-engine/ # Core logic (DialogueEngine, SceneManager)

/src/lib/stores/ # Zustand state management

/src/lib/types.ts # TypeScript interfaces

```

Implementation Patterns

Adding New Dialogue Scenes

1. Create DialogueNode array in case JSON

2. Define character sprites and emotions needed

3. Add any actions (flags, evidence, profiles)

4. Reference scene in chapter progression

Adding Investigation Hotspots

1. Define scene with background image

2. Add hotspots array with coordinates and click handlers

3. Specify conditions for hotspot visibility

4. Link hotspot actions to scene transitions or examinations

Modifying Game State

Always use store actions:

```typescript

// Good

gameStore.getState().setCurrentScene(newScene);

// Bad - never mutate directly

gameStore.getState().currentScene = newScene;

```

Working with Conditions and Actions

DialogueNodes support:

Example patterns are in existing case JSON files.

Best Practices

1. **Type safety**: Use TypeScript interfaces from `src/lib/types.ts`

2. **Asset references**: Always use key-based asset references, never hardcoded paths

3. **State immutability**: Use Zustand actions, never direct mutations

4. **Component isolation**: Keep game logic in engine/stores, not in UI components

5. **Blueprint alignment**: Check BLUEPRINT.md before architectural changes

Common Tasks

Creating a New Case

1. Create `/src/cases/case-X/` directory

2. Add `case.json` with metadata, chapters, scenes

3. Add `/assets/` subdirectory for backgrounds, sprites, evidence

4. Update case list in main menu

Adding New Evidence

1. Add evidence image to case assets

2. Define evidence in case JSON assets

3. Add action in dialogue node: `{ type: 'addEvidence', evidenceId: 'key' }`

Creating Investigation Sequences

1. Define investigation scene in case JSON

2. Add background image

3. Create hotspots array with coordinates and handlers

4. Link hotspot clicks to scene transitions or state changes

Debugging Tips

When to Confirm with User