artlegend/MODULES.md

# ArtLegend — Module Design Reference

This document is the authoritative description of each training module: what it teaches, how it plays, and what variables control difficulty. Update this whenever a module's design changes. Its purpose is to prevent design decisions from being re-explained from scratch each session.

---

## Module: Corridor Scroll

**Skill trained:** Sustained stroke control — staying within a moving corridor, filling available space confidently, and tracking direction changes.

### Concept

A corridor (two parallel lines with a gap between them) scrolls across the screen continuously. The player holds the S-Pen inside the corridor as it moves. Think Guitar Hero, but instead of hitting notes at the right moment, the player is maintaining precise stylus position inside a moving channel.

The corridor's **scroll direction can change angle** over time — the player must follow smooth or abrupt directional shifts while keeping their stroke inside the walls. Eventually the corridor can scroll from any direction: top, bottom, left, right, or any diagonal. Early levels keep the scroll direction fixed; later levels introduce angle changes of increasing frequency and severity.

### What the player is scored on

Scoring is a running tally across the session:

| Component | Good outcome | Bad outcome |
|-----------|-------------|-------------|
| **Fill** | Stroke covers a large proportion of the corridor width | Stroke is too thin/timid — space left unused |
| **Containment** | Stroke stays inside both walls | Stroke crosses a wall — penalty applied |

There is no pressure consistency requirement in this module. The goal is spatial accuracy and confident use of the available space, not stylus pressure.

### Difficulty variables

All of these are independent knobs that can be tuned per difficulty tier:

| Variable | Easy | Hard |
|----------|------|------|
| **Scroll speed** | Slow | Fast |
| **Corridor width** | Wide | Narrow |
| **Angle change frequency** | None (straight) | Frequent |
| **Angle change severity** | — | Up to full 360° range |
| **Lookahead distance** | Generous (player can see far ahead) | Short (more reactive) |

### Angle design notes

- Early difficulty levels should have **no angle changes** — straight corridor only.
- As difficulty increases, angle changes are introduced: first gentle curves, then sharper bends.
- There is no artificial cap on angle range. The corridor can scroll in any direction including full direction reversals. Players need to handle all angles because later modules involve drawing at all angles.
- The player's stroke within the corridor can itself be at an angle relative to the corridor walls — this is valid and intentional. Filling the corridor width at an angle is still good fill coverage.

### Session structure

- Session runs for a fixed duration or until a fixed length of corridor has passed.
- Score is displayed at end of session as: Overall %, Fill %, Wall Penalty count (or %).
- Difficulty progresses between sessions (corridor narrows, speed increases, angle changes introduced).

---

## Module: Stroke-to-Drawing

**Skill trained:** Guided stroke execution — strokes the player makes during a session are recorded and compose a recognizable drawing at the end.

### Concept

The player follows guided stroke prompts and their actual stylus input is retained. At the end of the session the accumulated strokes form a picture. This module teaches the player to execute intentional marks with confidence, knowing each stroke is permanent and contributes to an image.

### Design notes

- The Guitar Hero scroll mechanic is **not used** here — the player is making deliberate, placed strokes, not tracking a moving corridor.
- Scoring is TBD — likely based on stroke accuracy relative to a guide path, with pressure and angle components relevant (unlike Corridor Scroll).
- This module is planned for a later phase after Corridor Scroll is solid.

---

## Module: Pressure Ramp

**Skill trained:** Dynamic stroke weight control — matching a target pressure curve over the length of a stroke.

### Design notes

- Player draws a stroke while matching a displayed target pressure profile.
- Scored via DTW (Dynamic Time Warping) between actual and target pressure curve.
- Difficulty tiers: linear ramp → S-curve → arbitrary profile.
- Planned for Phase 2.

---

## Module: Curve Sculptor

**Skill trained:** Smooth bezier curve shaping.

### Design notes

- Player strokes follow a target bezier curve.
- Scored on how closely the stroke follows the curve path.
- Optional control point hints at lower difficulty.
- Planned for Phase 3.

---

## Module: Vector Snap

**Skill trained:** Precision endpoint targeting.

### Design notes

- Random endpoint targets displayed; player taps each as accurately as possible.
- Scored on distance from target; speed bonus for fast accurate taps.
- Planned for Phase 3.

---

## Notes on future modules

Additional module types discussed but not yet designed:

- **Gradient fill** — fill a shape with a smooth pressure gradient; teaches pressure ramp within a spatial boundary.
- **Vector drawing tool practice** — precision exercises that map directly to using vector drawing tools in professional apps.

These are later-phase ideas. No implementation decisions have been made for them.