# Mobile-SR

**Spaced repetition for Obsidian that works on your phone, with five games to make the practice stick.**

Write flashcards in plain Markdown, review them with the FSRS scheduler on desktop or mobile, and when you are tired of flipping cards, shoot asteroids, race the clock or save the hangman using the same decks. Keeping up with your reviews unlocks new ships, designs and weapons in the games.

## Play your decks

Every game has its own menu, and each one keeps your records. The games are practice only: they never change your review schedule, so you can play as much as you like without disturbing FSRS.

### 🚀 Blast

A question appears at the top and asteroids carrying answers float around the space above your ship. Shoot the right one.

- You have 60 seconds per level to reach the target: 50 points on level 1, 100 on level 2, and so on.
- The first hit is worth 5 points, and every hit in a row raises the multiplier.
- A wrong shot costs 2 points and resets your streak.
- Higher levels bring more asteroids that move faster.
- Your high score and best streak are saved.

### 🧩 Match

Six random cards from your deck are split into twelve tiles. Pair each question with its answer and clear the board as fast as you can.

- The clock counts up and a wrong match adds one second.
- Your best time is saved separately for every deck.

### 🪢 Hangman

One side of a card is the clue, the other is hidden. Guess it letter by letter before the figure is complete.

- Six wrong letters end the run. Your score is how many cards you solve in a row, saved per deck.
- Stuck? Reveal up to half of the letters one at a time, or skip the card without breaking your streak.
- Works in any alphabet. The on-screen keyboard follows the script of the hidden word, and a physical keyboard works too.

### 👾 Aliens

A 2D arcade shooter that is a reward for studying rather than a quiz. Steer the ship by dragging, with the mouse or with the arrow keys; it fires by itself.

- Three levels: scouts, raiders and the mothership.
- You have three lives. The number of levels is fixed, so your record is the fastest time in which you clear them all.
- Five weapons, from the basic blaster to the Nova Storm. Which ones you can use depends on your reviews (see below).

### ⚔️ Sword

A second reward game: a warrior with a sword against monsters that close in from both sides.

- Move left and right with the arrow keys or the on-screen buttons, and click or tap the arena to swing the sword in that direction.
- Three levels, ending with a boss. Your record is the fastest time in which you clear them all.
- Five swords, from wooden to legendary, each stronger and longer than the last. Which one you carry depends on your reviews (see below).

Open the games from the **Games** section at the bottom of the dashboard, or with the commands **Play Blast Game**, **Play Match Game**, **Play Hangman Game**, **Play aliens game** and **Play sword game**.

### ⭐ Unlocks

Your regular reviews are what upgrade you in the games. By default the plugin counts the cards you have reviewed that are not due again yet, and every 50 of them opens the next item:

- **Blast:** five ship designs.
- **Match:** five card designs.
- **Hangman:** five figure designs.
- **Aliens:** five weapons.
- **Sword:** five swords.

Fall behind on your reviews and the count drops, so the items lock again until you catch up. In the settings you can count the reviews you did in the last 24 hours instead. The games only read your progress; they still never change it.

### 🎵 Music

Each game has its own playlist, set up under **Music** in the game's menu.

- Add as many audio files of your own as you like (MP3 and other common formats). They are copied into a `game-music` folder in your vault, next to the game records, so they sync with your notes.
- Four built-in electronic tracks are included. They are generated by the plugin itself, so they are free of copyright. Choose which of them play in which game.
- Tracks are picked at random and play one after another.

### 🌍 Leaderboard

Blast, Aliens and Sword have a shared leaderboard, opened with the **Leaderboard** button in the game's menu. It shows the best 50 results from everyone who chose to take part, with the ship, weapon or sword they used. Every finished game counts, including one lost on the first level: completed games are ranked by time, and the rest by the level reached and the progress made.

Taking part is optional and **off by default**. To appear on the board, first choose a **username** in the settings. It is unique and permanent: once locked it can never be changed. Then turn on **Share my records online**. Your **display name**, shown above the username, can be changed whenever you like.

## Network use and privacy

The plugin works fully offline. It contacts a server only for the leaderboard:

- **Viewing a leaderboard** requests the list of results from the leaderboard server. Nothing about you is sent.
- **Locking a username** sends the username and a random id created on your device.
- **If you turn on sharing**, finishing a game of Blast, Aliens or Sword sends your display name, the result, the name of the ship, weapon or sword you used, and the same random id.
- **Never sent:** your notes, your cards, your decks' names or your review schedule.

The server is a Cloudflare Worker at `mobile-sr-leaderboard.mobile-sr.workers.dev`; its full source is in the [`server`](server) folder of this repository.

## Features

- **Shared leaderboard.** Optional, off by default, and limited to a username, a display name and a game result.
- **Built for mobile.** Everything works on Android and iOS: reviews, the dashboard and all five games.
- **FSRS scheduling.** Cards come back just before you would forget them. The classic SM-2 algorithm is available too.
- **Plain Markdown cards.** A deck is just a note. No special editor and no lock-in.
- **Syncs like a note.** Your progress is stored in a Markdown file inside the vault, so any sync that handles your notes also carries your review schedule between devices.
- **Dashboard.** See every deck with its due cards, start a session for one deck, and search a table of everything you have reviewed with its next due time.
- **Reversed cards.** One card can be studied in both directions.
- **Hints.** Mark a deck as a hint deck and each card gets a **Show hint** button.
- **Edit while reviewing.** Fix a typo in a card without leaving the session.
- **Interval previews.** The rating buttons can show when the card will return (for example 10m, 3d, 2mo).
- **Deck cleanup.** One command fixes spacing and removes duplicate cards from a note.
- **Self-cleaning data.** Cards you delete from your notes are removed from the saved schedule automatically.
- **Right-to-left friendly.** Decks and cards in right-to-left languages display correctly.

## Installation

Simply get it from obsidian community , but here are some alternatives:

### With BRAT (recommended, includes updates)

1. Install the **BRAT** plugin from **Settings → Community plugins → Browse** and enable it.
2. Open **Settings → BRAT → Add beta plugin**.
3. Paste `https://github.com/kfirgumay2005-hash/Mobile-SR` and select **Add plugin**.
4. Enable **Mobile-SR** in **Settings → Community plugins**.

This works the same way on mobile.

### Manually

1. Download `main.js`, `manifest.json` and `styles.css` from the [latest release](https://github.com/kfirgumay2005-hash/Mobile-SR/releases/latest).
2. Put them in `<your vault>/.obsidian/plugins/mobilesr/` (create the folder if needed).
3. Reload Obsidian and enable **Mobile-SR** in **Settings → Community plugins**.

## Writing cards

A deck is a note that contains the `#flashcards` tag. The note's name is the deck's name. Each card sits between two lines that contain only a hyphen, with a line containing only `?` between the question and the answer:

```markdown
#flashcards

- What is the capital of France?
  ?
  Paris
- enigma
  ?
  A mystery; something that cannot be deciphered.
-
```

- **The hyphen lines matter.** Every card needs a `-` line before it and after it. Neighbouring cards share the hyphen between them.
- **Reversed cards:** use `??` instead of `?` to study the card in both directions.
- **Hints:** add the `#hint` tag to the note as well. The first line of each card is then the question, and any lines between it and the `?` are hidden behind a **Show hint** button.

### Importing a deck

To bring in a deck from somewhere else (for example Quizlet), paste it into an AI assistant and ask it to put a `?` line between each term and its meaning, add the hyphen lines, and return plain text. Paste the result into a note and run **Fix Cards Spacing and Remove Duplicates** to tidy it up.

## Using the plugin

Select the plugin's icon in the ribbon, or run **Open Spaced Repetition Dashboard**.

- **Decks:** each deck shows how many cards are due and has its own **Start** button for a session with that deck only.
- **Reviewed flashcards status:** a searchable table of the cards you have studied, with the time left until the next review and the current interval.
- **Games:** Blast, Match, Hangman, Aliens and Sword.

## Settings

| Setting                              | What it does                                                                                                    |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| Algorithm                            | FSRS or SM-2. The plugin was built around FSRS, so that is the recommended choice.                              |
| Target request retention             | How likely you want to be to remember a card when it comes up. Higher means more frequent reviews.              |
| Maximum interval                     | The longest gap, in days, allowed between two reviews of a card.                                                |
| Flashcard deck tags / Hint deck tags | The tags that mark a note as a deck or as a hint deck.                                                          |
| Show interval previews               | Show the next review time on the rating buttons.                                                                |
| Duplicate detection mode             | Whether the cleanup command treats cards as duplicates when they are identical or when they share a first line. |
| Data folder path                     | The vault folder where your review progress is saved.                                                           |
| Games                                | Sound effects, what the unlocks are based on, leaderboard username, display name and sharing, where the game records are saved, and a button to reset them. |

## Related

[Mobile-Translate](https://github.com/kfirgumay2005-hash) is my other plugin. Its output builder can create new cards at the press of a button when configured for this card format.

## License

[0-BSD](LICENSE)