phase 1

.gemini/tja-spec.md

@@ -0,0 +1,68 @@
+# TJA Format Specification (Rigorous)
+
+## 1. File Structure
+- **Extension**: `.tja`
+- **Encoding**: UTF-8 (with BOM) or Shift-JIS.
+- **Comments**: `//` (inline, until end of line).
+- **Sections**:
+    1. **Global Metadata**: Before any `#START`.
+    2. **Course Data**: Metadata specific to a difficulty (can be mixed with global).
+    3. **Song Notation**: Between `#START` and `#END`.
+
+## 2. Metadata (Key: Value)
+| Key | Type | Description |
+| :--- | :--- | :--- |
+| `TITLE` | string | Song title. |
+| `BPM` | float | Beats Per Minute. Default: 120. |
+| `WAVE` | string | Path to audio file. |
+| `OFFSET` | float | Seconds. Negative delays notes, positive advances them. |
+| `DEMOSTART`| float | Preview start time in seconds. |
+| `GENRE` | string | Category (e.g., アニメ, ゲームミュージック). |
+| `SCOREMODE`| 0, 1, 2| Scoring method. Default: 1. |
+| `COURSE` | enum | 0:Easy, 1:Normal, 2:Hard, 3:Oni, 4:Edit/Ura, 5:Tower, 6:Dan. |
+| `LEVEL` | int | 1-10 (Stars). |
+| `BALLOON` | int[] | Comma-separated hit counts for balloon/kusudama notes. |
+| `SCOREINIT`| int | Initial score per note. |
+| `SCOREDIFF`| int | Added score for combo milestones. |
+
+## 3. Song Notation: Notes
+| Code | Name | Description |
+| :--- | :--- | :--- |
+| `0` | Blank | No note. |
+| `1` | Don | Small Red. |
+| `2` | Ka | Small Blue. |
+| `3` | DON | Large Red. |
+| `4` | KA | Large Blue. |
+| `5` | Drumroll| Start of small drumroll. Ends with `8`. |
+| `6` | DRUMROLL| Start of large drumroll. Ends with `8`. |
+| `7` | Balloon | Start of balloon. Ends with `8`. |
+| `8` | End | Ends 5, 6, 7, or 9. |
+| `9` | Kusudama| Large balloon/Kusudama. Ends with `8` or `9`. |
+| `A` | DON(H) | Large Red (Hands/Multiplayer). |
+| `B` | KA(H) | Large Blue (Hands/Multiplayer). |
+
+## 4. Commands (#COMMAND [value])
+| Command | Value | Description |
+| :--- | :--- | :--- |
+| `#START` | (P1/P2) | Begin notation. |
+| `#END` | - | End notation. |
+| `#MEASURE` | n/d | Set time signature (e.g., 4/4). |
+| `#BPMCHANGE`| float | Change BPM. |
+| `#DELAY` | float | Delay in seconds (can be negative). |
+| `#SCROLL` | float | Multiplier for note scroll speed. |
+| `#GOGOSTART`| - | Start Go-Go Time (1.2x score). |
+| `#GOGOEND` | - | End Go-Go Time. |
+| `#SECTION` | - | Reset branch accuracy counters. |
+| `#BRANCHSTART`| type,v1,v2| Branching: `p` (accuracy) or `r` (drumrolls). |
+| `#N`, `#E`, `#M`| - | Branch paths: Normal, Advanced/Expert, Master. |
+| `#BRANCHEND`| - | End branching section. |
+| `#BARLINEOFF`| - | Hide measure lines. |
+| `#BARLINEON` | - | Show measure lines. |
+| `#LYRIC` | string | Display lyrics (`\n` for line break). |
+
+## 5. Logic & Formulas
+- **Measure Duration (ms)**: `60000 * (numerator / denominator) * 4 / BPM`
+- **Note Timing**: Equally spaced within a measure.
+- **Branching**:
+    - `p` (Percent): `(GOOD + OK*0.5) / TotalNotes * 100`.
+    - Calculated one measure before `#BRANCHSTART`.