docs/opcodes_reference.md

# LovecaSim Opcode Reference

This document provides a technical breakdown of all opcodes used by the LovecaSim game engine. Opcodes are processed by the bytecode interpreter in `engine_rust_src/src/core/logic/interpreter.rs`.

## 1. Flow Control & Meta
| ID | Name | Description | Example Cards |
|---|---|---|---|
| 1 | RETURN | Ends the current ability execution and returns to the calling state. | LL-bp1-001-R＋ |
| 2 | JUMP | Unconditionally jumps to a specific instruction offset in the bytecode. | PL!-PR-005-PR |
| 3 | JUMP_IF_FALSE | Jumps to an offset if the last conditional check (cond) failed. | - |
| 29 | META_RULE | Modifies global gameplay rules (e.g., Cheer mod count). | PL!-pb1-018-P＋ |
| 34 | FLAVOR_ACTION | Placeholder for actions that have no mechanical effect but show text/UI. | - |

## 2. State Modification (Direct)
| ID | Name | Description | Example Cards |
|---|---|---|---|
| 10 | DRAW | Draws `X` cards from the deck to the hand. | PL!-PR-005-PR |
| 11 | ADD_BLADES | Adds `X` Blades to the targeted member slot. | LL-bp2-001-R＋ |
| 12 | ADD_HEARTS | Adds `X` Hearts of color `C` to the targeted slot. | PL!-bp3-008-P |
| 13 | REDUCE_COST | Reduces the cost of the next member played by `X`. | LL-bp2-001-R＋ |
| 18 | BUFF_POWER | Temporarily increases the power/stats of a member. | LL-bp2-001-R＋ |
| 23 | ENERGY_CHARGE | Adds `X` cards from the top of the deck to the energy zone. | PL!N-bp3-007-P |
| 37 | SET_SCORE | Sets the player's current score to exactly `X`. | PL!S-bp3-019-L |
| 50 | ADD_STAGE_ENERGY | Adds raw energy pips directly to a member slot. | - |
| 81 | ACTIVATE_ENERGY | Forces an energy card to become "Active" (untapped). | LL-bp3-001-R＋ |

## 3. Complex Interactions (Response Required)
| ID | Name | Description | Example Cards |
|---|---|---|---|
| 15 | RECOVER_LIVE | Moves a Live card from the discard pile to the Live Zone. | PL!-PR-003-PR |
| 17 | RECOVER_MEMBER | Moves a Member card from the discard pile to the Hand. | LL-bp1-001-R＋ |
| 41 | LOOK_AND_CHOOSE | Looks at `X` cards from `Zone`, picks `Y` to move to `Dest`. | LL-bp4-001-R＋ |
| 45 | COLOR_SELECT | Prompts the player to choose a heart color (Pink, Red, etc.). | PL!-sd1-003-SD |
| 58 | MOVE_TO_DISCARD | Prompts player to discard `X` cards from `Source`. | PL!-sd1-007-SD |
| 63 | PLAY_FROM_DISCARD | Plays a member directly from the discard pile to a slot. | PL!HS-bp1-002-P |
| 65 | SELECT_MEMBER | Prompts player to select a member on the stage. | PL!-pb1-018-P＋ |
| 68 | SELECT_LIVE | Prompts player to select a Live card in the Live Zone. | - |

## 4. Targeting Opcodes
These opcodes set the `target` register for subsequent instructions.
- **100**: SET_TARGET_SELF
- **101**: SET_TARGET_PLAYER
- **102**: SET_TARGET_OPPONENT
- **104**: SET_TARGET_MEMBER_SELF
- **110**: SET_TARGET_MEMBER_SELECT

## 5. Triggers
| ID | Name | Description |
|---|---|---|
| 1 | ON_PLAY | Fires when the member is played to the stage. |
| 2 | ON_LIVE_START | Fires at the beginning of a Live performance. |
| 3 | ON_LIVE_SUCCESS | Fires when a Live is successfully completed. |
| 6 | CONSTANT | Active as long as the card is in the correct zone. |
| 7 | ACTIVATED | Requires manual activation by the player. |
| 8 | ON_LEAVES | Fires when the member leaves the stage. |

## 6. Conditions (Check Logic)
Used within abilities to determine if an effect should execute.
- **201**: CHECK_HAS_MEMBER (Does the player have a specific member?)
- **204**: CHECK_COUNT_HAND (Does the player have `X` cards in hand?)
- **206**: CHECK_IS_CENTER (Is the member in the Center slot?)
- **213**: CHECK_COUNT_ENERGY (Does the player have `X` energy?)
- **221**: CHECK_HAS_CHOICE (Did the player make a specific choice in a previous step?)