diff --git a/.github/resources/social-preview.svg b/.github/resources/social-preview.svg index f2a1009..b56aab0 100644 --- a/.github/resources/social-preview.svg +++ b/.github/resources/social-preview.svg @@ -6,4 +6,4 @@ Beautiful, powerful, RomM Docs - + \ No newline at end of file diff --git a/docs/API-and-Development/API-Reference.md b/docs/API-and-Development/API-Reference.md new file mode 100644 index 0000000..29c8cb9 --- /dev/null +++ b/docs/API-and-Development/API-Reference.md @@ -0,0 +1,165 @@ +# API Reference + +RomM provides a comprehensive REST API that allows you to programmatically interact with your RomM instance. Most API endpoints are authenticated and follow RESTful conventions. + +## Interactive Documentation + +RomM automatically generates interactive API documentation using OpenAPI (Swagger). You can access the interactive API docs directly from your running instance: + +- **Swagger UI**: Available at `http://your-instance:3000/api/docs` +- **ReDoc**: Available at `http://your-instance:3000/api/redoc` + +These interactive docs allow you to: + +- Browse all available endpoints +- View request/response schemas +- Test API calls directly from your browser +- Understand authentication requirements +- Download the OpenAPI specification + +## Base URL + +The API base URL is typically: + +```text +http://your-instance:3000/api +``` + +Replace `your-instance` with your actual RomM instance URL or IP address. + +## Authentication + +All API endpoints require authentication. RomM supports: + +- **Basic HTTP Authentication** - Username and password +- **OAuth2 Password Bearer** - Token-based authentication (recommended for API usage) + +When using OAuth2, you'll need to obtain a token from `/api/token` endpoint and include it in the `Authorization` header as `Bearer `. + +### OAuth2 Scopes + +The API uses OAuth2 scopes to control access to different resources: + +**Read Scopes:** + +- `me.read` - View your profile +- `roms.read` - View ROMs +- `platforms.read` - View platforms +- `assets.read` - View assets +- `firmware.read` - View firmware +- `roms.user.read` - View user-rom properties +- `collections.read` - View collections +- `users.read` - View users + +**Write Scopes:** + +- `me.write` - Modify your profile +- `assets.write` - Modify assets +- `roms.user.write` - Modify user-rom properties +- `collections.write` - Modify collections +- `roms.write` - Modify ROMs +- `platforms.write` - Modify platforms +- `firmware.write` - Modify firmware +- `users.write` - Modify users +- `tasks.run` - Run tasks + +## API Endpoints Overview + +The RomM API provides comprehensive endpoints for managing all aspects of your ROM collection: + +### Core Resources + +- **Platforms** - Manage and configure gaming platforms +- **ROMs** - Full CRUD operations for ROM files with extensive filtering, searching, and metadata matching +- **Collections** - Create and manage ROM collections, smart collections, and virtual collections +- **Users** - User management, authentication, invite links, and profiles + +### Supporting Features + +- **Authentication** - OAuth2 token management, OIDC login, password resets +- **Search** - Metadata provider search for ROMs and covers +- **Tasks** - Background task management and execution +- **Assets** - Save files, states, screenshots management +- **Firmware** - Upload and manage firmware files for emulation +- **Configuration** - System configuration, platform bindings, and exclusions +- **Feeds** - Integration feeds for WebRcade and Tinfoil +- **Statistics** - System statistics and resource tracking + +For complete endpoint documentation including request/response schemas, query parameters, and authentication requirements, visit the interactive API documentation at `/api/docs` or `/api/redoc` on your RomM instance. + +## Example Usage + +### Using cURL + +```bash +# Get all libraries +curl -u username:password http://your-instance:3000/api/libraries + +# Get a specific ROM +curl -u username:password http://your-instance:3000/api/roms/123 + +# Create a new ROM entry +curl -X POST -u username:password \ + -H "Content-Type: application/json" \ + -d '{"name": "New ROM", "platform_id": 1}' \ + http://your-instance:3000/api/roms +``` + +### Using Python + +```python +import requests +from requests.auth import HTTPBasicAuth + +# Setup authentication +auth = HTTPBasicAuth('username', 'password') +base_url = 'http://your-instance:3000/api' + +# Get all libraries +response = requests.get(f'{base_url}/libraries', auth=auth) +libraries = response.json() + +# Get a specific ROM +response = requests.get(f'{base_url}/roms/123', auth=auth) +rom = response.json() +``` + +### Using JavaScript/Node.js + +```javascript +const axios = require("axios"); + +// Setup authentication +const api = axios.create({ + baseURL: "http://your-instance:3000/api", + auth: { + username: "username", + password: "password", + }, +}); + +// Get all libraries +const libraries = await api.get("/libraries"); + +// Get a specific ROM +const rom = await api.get("/roms/123"); +``` + +## OpenAPI Specification + +You can download the complete OpenAPI specification from your RomM instance: + +```text +http://your-instance:3000/api/openapi.json +``` + +This specification can be imported into API testing tools like Postman, used to generate client libraries, or used for API mocking. + +## Getting Help + +For API-specific questions or issues: + +1. Check the interactive documentation at `/api/docs` or `/api/redoc` on your instance +2. Review the code in the [RomM repository](https://github.com/rommapp/romm) +3. Open an issue on [GitHub](https://github.com/rommapp/romm/issues) +4. Join the [Discord community](https://discord.com/invite/romm) diff --git a/docs/API-and-Development/Contributing.md b/docs/API-and-Development/Contributing.md new file mode 100644 index 0000000..d1b9c49 --- /dev/null +++ b/docs/API-and-Development/Contributing.md @@ -0,0 +1,81 @@ +# Contributing to RomM + +Thank you for considering contributing to RomM! This document outlines some guidelines to help you get started with your contributions. + +**If you're looking to implement a large feature or make significant changes to the project, it's best to open an issue first AND join the Discord to discuss your ideas with the maintainers.** + +## Code of Conduct + +Please note that this project adheres to the Contributor Covenant [code of conduct](CODE_OF_CONDUCT.md). By participating in this project, you are expected to uphold this code. + +## AI Assistance Notice + +> [!IMPORTANT] +> +> If you are using **any kind of AI assistance** to contribute to RomM, it must be disclosed in the pull request. + +If you are using any kind of AI assistance while contributing to RomM **this must be disclosed in the pull request**, along with the extent to which AI assistance was used (e.g. docs only vs. code generation). If PR responses are being generated by an AI, disclose that as well. As a small exception, trivial tab-completion doesn't need to be disclosed. + +An example disclosure: + +> This PR was written primarily by Claude Code. + +Or a more detailed disclosure: + +> I consulted ChatGPT to understand the codebase but the solution +> was fully authored manually by myself. + +Failure to disclose this is rude to the human operators on the other end of the pull request, but it also makes it difficult to determine how much scrutiny to apply to the contribution. + +In a perfect world, AI assistance would produce equal or higher quality work than any human. That isn't the world we live in today, and in most cases it's generating slop. + +Please be respectful to maintainers and disclose AI assistance. + +## Contributing to the Docs + +If you would like to contribute to the project's [documentation](https://docs.romm.app), open a pull request against [the docs repo](https://github.com/rommapp/docs). We welcome any contributions that help improve the documentation (new pages, updates, or corrections). + +## Adding Translations + +If you would like to translate the project into another language, create a new folder under the `frontend/src/locales` directory, and follow the existing language files as a template. Once you've created the new language file, open a pull request to add it to the project. + +## How to Contribute Code + +1. Fork the repository. +2. Clone your forked repository: `git clone https://github.com/your-username/romm.git` +3. Checkout the `master` branch: `git checkout master` +4. Follow the steps in the [developer setup guide](DEVELOPER_SETUP.md) +5. Create a new branch for your feature/fix: `git checkout -b feature-or-fix-name` +6. Make your changes and commit them with descriptive commit messages: `git commit -am 'Add feature XYZ'` +7. Push your changes to your fork: `git push origin feature-or-fix-name` +8. Open a pull request to the `master` branch of the original repository. + +## Pull Request Guidelines + +- Make sure your code follows the project's coding standards. +- Test your changes locally before opening a pull request. +- Update the documentation if necessary. +- Ensure all existing tests pass, and add new tests for new functionality. +- Use clear and descriptive titles and descriptions for your pull requests. + +## Code Style + +Follow the existing code style used throughout the project. If working with VSCode or a similar editor, consider installing these extensions: + +- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) +- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) +- [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) +- [Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) +- [Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar) + +## Issue Reporting + +If you encounter any bugs or have suggestions for improvements, please [create an issue](https://github.com/rommapp/romm/issues) on GitHub. Provide as much detail as possible, including steps to reproduce the issue if applicable. + +## Licensing + +By contributing to RomM, you agree that your contributions will be licensed under the project's [LICENSE](LICENSE). + +--- + +Thank you for contributing to RomM! Your help is greatly appreciated. diff --git a/docs/API-and-Development/Development-Setup.md b/docs/API-and-Development/Development-Setup.md new file mode 100644 index 0000000..faaddb8 --- /dev/null +++ b/docs/API-and-Development/Development-Setup.md @@ -0,0 +1,41 @@ +# Setting up RomM for development + +Docker provides a quick and easy way to get started with RomM by encapsulating all dependencies within Docker containers. This guide will walk you through the process of setting up RomM for development using Docker. + +## Environment setup + +### Create the mock structure with at least one rom and empty config for manual testing + +```sh +mkdir -p romm_mock/library/roms/switch +touch romm_mock/library/roms/switch/metroid.xci +mkdir -p romm_mock/resources +mkdir -p romm_mock/assets +mkdir -p romm_mock/config +touch romm_mock/config/config.yml +``` + +### Copy env.template to .env and fill the variables + +```sh +cp env.template .env +``` + +```dotenv +ROMM_BASE_PATH=/app/romm +DEV_MODE=true +``` + +### Build the image + +```sh +docker compose build # or `docker compose build --no-cache` to rebuild from scratch +``` + +### Spin up the Docker containers + +```sh +docker compose up -d +``` + +And you're done! You can access the app at `http://localhost:3000`. Any changes made to the code will be automatically reflected in the app thanks to the volume mounts. diff --git a/docs/API-and-Development/index.md b/docs/API-and-Development/index.md new file mode 100644 index 0000000..969ae7e --- /dev/null +++ b/docs/API-and-Development/index.md @@ -0,0 +1,14 @@ +--- +search: + exclude: true +--- + +# API & Development + +Welcome to the RomM API & Development documentation. This section contains resources for developers looking to interact with RomM programmatically or contribute to its development. + +## Contents + +- **[API Reference](API-Reference.md)** - Complete API documentation with endpoints, schemas, and examples +- **[Contributing](Contributing.md)** - Guidelines for contributing code, translations, and documentation +- **[Development Setup](Development-Setup.md)** - How to set up your development environment diff --git a/docs/Getting-Started/Authentication.md b/docs/Getting-Started/Authentication.md index 1a12cd6..0d58a7c 100644 --- a/docs/Getting-Started/Authentication.md +++ b/docs/Getting-Started/Authentication.md @@ -10,7 +10,7 @@ You'll want to set the following environment variable before starting RomM: ### Sessions -When the `/login` endpoint is called with valid credentials, a `session_id` is generated, stored as a cookie and sent to the browser. The same token is used to create a cache entry in Redis (or in-memory if Redis is disabled) which maps the token to the user. This way no sensitive information is stored on the client. +When the `/login` endpoint is called with valid credentials, a `session_id` is generated, stored as a cookie and sent to the browser. The same token is used to create a cache entry in Valkey (or in-memory if Valkey is disabled) which maps the token to the user. This way no sensitive information is stored on the client. ### Roles diff --git a/docs/Getting-Started/Configuration-File.md b/docs/Getting-Started/Configuration-File.md index c994861..492f129 100644 --- a/docs/Getting-Started/Configuration-File.md +++ b/docs/Getting-Started/Configuration-File.md @@ -1,133 +1,295 @@ -Below is a breakdown of each section of the `config.yml` file and its purpose: +Below is a breakdown of each section of the `config.yml` file and its purpose. You can find a full example of the file in the [config.example.yml](https://github.com/rommapp/romm/blob/master/examples/config.example.yml) file. -### `exclude` +--- + +## Exclude Section + +Control which platforms, ROMs, or files to ignore during scanning. -This section lets you tell RomM which platforms, ROMs, or files to ignore during scanning. +### Platforms -- **platforms** - Exclude entire platforms (folders) from being scanned. - Example: +Exclude entire platforms (folders) from being scanned. - ```yaml +**Example:** + +```yaml +exclude: platforms: ["ps", "ngc", "gba"] - ``` +``` -- **roms** - Fine-tune which ROMs or files are excluded. +### ROMs - - **single_file** - Applies to ROMs that are single files (not in subfolders). +Fine-tune which ROMs or files are excluded. - - **extensions**: Exclude files by extension. - Example: - ```yaml +#### Single File ROMs + +Applies to ROMs that are single files (not in subfolders). + +- **extensions**: Exclude files by extension +- **names**: Exclude files by name or pattern (supports Unix wildcards) + +**Example:** + +```yaml +exclude: + roms: + single_file: extensions: ["xml", "txt"] - ``` - - **names**: Exclude files by name or pattern (supports Unix wildcards). - Example: - ```yaml names: ["info.txt", "._*", "*.nfo"] - ``` +``` - - **multi_file** - Applies to ROMs stored as folders (multi-disc, with DLC, etc.). - - **names**: Exclude entire folders by name. - Example: - ```yaml +#### Multi-File ROMs + +Applies to ROMs stored as folders (multi-disc, with DLC, etc.). + +- **names**: Exclude entire folders by name +- **parts.names**: Exclude files by name or pattern from within multi-file ROM folders +- **parts.extensions**: Exclude files by extension from within multi-file ROM folders + +**Example:** + +```yaml +exclude: + roms: + multi_file: names: ["final fantasy VII", "DLC"] - ``` - - **parts**: Exclude specific files inside multi-file ROM folders. - - **names**: Exclude files by name or pattern. - Example: - ```yaml + parts: names: ["data.xml", "._*"] - ``` - - **extensions**: Exclude files by extension. - Example: - ```yaml extensions: ["xml", "txt"] - ``` +``` --- -### `system` +## System Section Customize how RomM interprets your folder and platform names. -- **platforms** - Map your custom folder names to RomM's recognized platform names. - Example: +### Custom Folder Names + +Map your custom folder names to RomM's recognized platform names. + +**Example:** + +```yaml +system: + platforms: + gc: "ngc" # Treats 'gc' folder as GameCube + psx: "ps" # Treats 'psx' folder as PlayStation +``` + +### Versions - ```yaml - platforms: { gc: "ngc", psx: "ps" } - ``` +Associate a platform with its main version. This also tells RomM to fetch metadata from the main version source. - This treats a `gc` folder as GameCube (`ngc`) and `psx` as PlayStation (`ps`). +**Example:** -- **versions** - Associate a platform with its main version. This also tells RomM to fetch medatata from the main version source. - Example: - ```yaml - versions: { naomi: "arcade" } - ``` +```yaml +system: + versions: + naomi: "arcade" +``` --- -### `filesystem` +## Filesystem Section -Specify the folder name where your ROMs are located if it differs from the default. For example, if your `roms` folder it's named `my_roms` (`/home/user/library/my_roms`), set this accordingly. +Specify the folder name where your ROMs are located if it differs from the default. -Example: +**Example:** + +If your ROMs folder is named `my_roms` instead of `roms`: ```yaml -filesystem: { roms_folder: "my_roms" } +filesystem: + roms_folder: "my_roms" ``` --- -### `scan` +## Scan Section + +Configure metadata scanning priorities and media assets to download. + +### Priority + +Customize the order in which metadata providers are queried during scans. + +#### Metadata + +Controls metadata provider priority order. + +**Provider list in default order:** + +- `igdb` - IGDB (highest priority) +- `moby` - MobyGames +- `ss` - Screenscraper +- `ra` - RetroAchievements +- `launchbox` - Launchbox +- `gamelist` - ES-DE gamelist.xml +- `hasheous` - Hasheous +- `flashpoint` - Flashpoint Project +- `hltb` - HowLongToBeat (lowest priority) + +**Example:** + +```yaml +scan: + priority: + metadata: + - "igdb" + - "ss" + - "moby" +``` + +#### Artwork + +Controls artwork provider priority order for cover art and screenshots. + +**Default:** Same as `priority.metadata` + +**Example:** + +```yaml +scan: + priority: + artwork: + - "igdb" + - "ss" + - "moby" +``` + +#### Region + +Sets preferred region for cover art and game title (Screenscraper only). + +**Default:** `["us", "wor", "ss", "eu", "jp"]` + +**Example:** + +```yaml +scan: + priority: + region: + - "us" + - "eu" + - "jp" +``` + +#### Language + +Sets preferred language for cover art and game title (Screenscraper only). + +**Default:** `["en", "fr"]` + +**Example:** + +```yaml +scan: + priority: + language: + - "en" + - "es" + - "fr" +``` + +### Media + +Configures which media assets to download (Screenscraper and ES-DE gamelist.xml only). + +**Media types:** + +- `box2d` - Normal cover art (always enabled) +- `box3d` - 3D box art +- `miximage` - Mixed image of multiple media +- `physical` - Disc, cartridge, etc. +- `screenshot` - Screenshot (enabled by default) +- `title_screen` - Title screen +- `marquee` - Transparent logo +- `fanart` - User uploaded artwork +- `bezel` - Bezel displayed around the EmulatorJS window +- `manual` - Manual in PDF format (enabled by default) +- `video` - Gameplay video (warning: large file size) + +**Example:** + +```yaml +scan: + media: + - box2d + - screenshot + - manual + - bezel +``` + +--- + +## EmulatorJS Section + +Configure EmulatorJS per-core options and controls. + +### Debug + +Enable debug mode to log available options to the browser console. + +**Example:** + +```yaml +emulatorjs: + debug: true +``` + +### Cache Limit + +Cache limit per ROM in bytes. Set to `null` for unlimited. + +**Example:** + +```yaml +emulatorjs: + cache_limit: 52428800 # 50 MB +``` + +### Settings + +Configure core-specific settings. Use `default` to apply settings to all cores. + +**Example:** + +```yaml +emulatorjs: + settings: + parallel_n64: # Use the exact core name + vsync: disable + snes9x: + snes9x_region: ntsc + default: # These settings apply to all cores + fps: show +``` + +### Controls + +Map keyboard and controller controls for each player. -The metadata scanners can have their priority changed by your config.yaml file. See the [config.example.yaml](https://github.com/rommapp/romm/blob/master/examples/config.example.yml) for the default values. +**Example (2-player SNES):** ```yaml -priority: { "metadata", "artwork", "region", "language" } +emulatorjs: + controls: + snes9x: + 0: # Player 1 + 0: # Button mapping + value: x # Keyboard mapping + value2: BUTTON_2 # Controller mapping + 1: # Player 2 + 0: + value: / + value2: BUTTON_2 ``` -- **metadata** - Changes the metadata provider preferred order for metadata sources. - Example: - - ```yaml - metadata: - { "igdb", "moby", "ss", "ra", "lb", "hasheous", "flashpoint", "hltb" } - ``` - -- **artwork** - Changes the metadata provider preferred order for cover art and screenshots. - Example: - - ```yaml - artwork: - { "igdb", "moby", "ss", "ra", "lb", "hasheous", "flashpoint", "hltb" } - ``` - -- **region** - Changes the metadata provider preferred region for cover art and game title (only used by Screenscraper) - Example: - - ```yaml - region: { "us", "wor", "ss", "eu", "jp" } - ``` - -- **language** - Changes the metadata provider preferred language for cover art and game title (only used by Screenscraper) - Example: - ```yaml - language: { "en", "fr" } - ``` +See [EmulatorJS documentation](https://emulatorjs.org/docs4devs/control-mapping/) for control mapping details. --- diff --git a/docs/Getting-Started/Environment-Variables.md b/docs/Getting-Started/Environment-Variables.md index 1210b5e..9427ede 100644 --- a/docs/Getting-Started/Environment-Variables.md +++ b/docs/Getting-Started/Environment-Variables.md @@ -18,7 +18,10 @@ This is a complete list of available environment variables; required variables a | KIOSK_MODE | Read-only mode for public displays or kiosks | | `false` | | UPLOAD_TIMEOUT | Timeout for file uploads (in seconds) | | `600` (10 minutes) | | SCAN_TIMEOUT | Timeout for the background scan/rescan tasks (in seconds) | | `14400` (4 hours) | +| SCAN_WORKERS | Number of worker processes for scanning tasks | | `1` | | TASK_TIMEOUT | Timeout for the the rest of the background tasks (in seconds) | | `300` (5 minutes) | +| TASK_RESULT_TTL | How long to keep task results in Valkey (in seconds) | | `86400` (24 hours) | +| SEVEN_ZIP_TIMEOUT | Timeout for 7-Zip operations (in seconds) | | `60` | | DISABLE_EMULATOR_JS | Disables playing in browser with [EmulatorJS](../Platforms-and-Players/EmulatorJS-Player.md) | | `false` | | DISABLE_RUFFLE_RS | Disables playing flash games with [RuffleRS](../Platforms-and-Players/RuffleRS-Player.md) | | `false` | | YOUTUBE_BASE_URL | Base URL for alternate frontends (Piped, Invidious, etc.) | | `https://www.youtube.com` | @@ -52,7 +55,7 @@ This is a complete list of available environment variables; required variables a | REDIS_USERNAME | Username for Redis/Valkey instance | | | | REDIS_PASSWORD | Password for Redis/Valkey instance | | | | REDIS_DB | Database number for Redis/Valkey instance | | `0` | -| REDIS_SSL | Enable SSL for Redis instance | | `false` | +| REDIS_SSL | Enable SSL for Redis/Valkey instance | | `false` | | SENTRY_DSN | DSN for Sentry error tracking | | | ## Metadata providers @@ -70,8 +73,8 @@ This is a complete list of available environment variables; required variables a | LAUNCHBOX_API_ENABLED | Enable LaunchBox API integration | | `false` | | PLAYMATCH_API_ENABLED | Enable PlayMatch API integration | | `false` | | HASHEOUS_API_ENABLED | Enable Hasheous API integration | | `false` | -| FLASHPOINT_API_ENABLED | Enable Flashpoint API integration | | `false` | -| HLTB_API_ENABLED | Enable HowLongToBeat API integration | | `false` | +| FLASHPOINT_API_ENABLED | Enable Flashpoint API integration | | `false` | +| HLTB_API_ENABLED | Enable HowLongToBeat API integration | | `false` | ## Authentication diff --git a/docs/Getting-Started/Folder-Structure.md b/docs/Getting-Started/Folder-Structure.md index 53137e6..b5be108 100644 --- a/docs/Getting-Started/Folder-Structure.md +++ b/docs/Getting-Started/Folder-Structure.md @@ -43,7 +43,7 @@ For multifile games (games stored as folders with multiple files or folders insi - @@ -116,11 +116,11 @@ For multifile games (games stored as folders with multiple files or folders insi │ │ ├─ dlc │ │ │ ├─ game_4_dlc_1.7z │ │ │ └─ game_4_dlc_2.7z - │ │ ├─ hacks + │ │ ├─ hack │ │ │ └─ game_4_hardmode.rar - │ │ ├─ manuals + │ │ ├─ manual │ │ │ └─ game_4_manual.pdf - │ │ ├─ mods + │ │ ├─ mod │ │ │ └─ game_4_crazy_mode.zip │ │ ├─ patch │ │ │ └─ game_4_patch_v1.1.zip @@ -135,8 +135,8 @@ For multifile games (games stored as folders with multiple files or folders insi └─ ps/ ├─ roms/ │ ├─ game_5/ - │ │ ├─ game_5_cd1.iso - │ │ └─ game_5_cd2.iso + │ │ ├─ game_5_cd_1.iso + │ │ └─ game_5_cd_2.iso │ │ │ └─ game_6.iso │ diff --git a/docs/Getting-Started/Metadata-Providers.md b/docs/Getting-Started/Metadata-Providers.md index 93b3e93..d8712c0 100644 --- a/docs/Getting-Started/Metadata-Providers.md +++ b/docs/Getting-Started/Metadata-Providers.md @@ -22,7 +22,7 @@ Here are some combinations you can use based on your needs: - Supports 125+ popular systems - ScreenScraper provides titles, descriptions, cover art, screenshots and manuals - - With the option for 3D boxes and CD/cartridge covers + - With the option for 3D boxes and CD/cartridge covers - Retroachievements provides achievement progress - **Use this if you want to avoid Twitch/Amazon products** @@ -74,7 +74,7 @@ To access the ScreenScraper API, create a [ScreenScraper](https://www.screenscra ### MobyGames -MobyGames is a metadata provider that offers medatada, cover art and screenshots. +MobyGames is a metadata provider that offers metadata, cover art and screenshots. To access the MobyGames API, [create a MobyGames account](https://www.mobygames.com/user/register/) and then visit your profile page. Click the **API** link under your user name to sign up for an API key. Copy the key shown and use it to set `MOBYGAMES_API_KEY`. @@ -84,7 +84,7 @@ To access the MobyGames API, [create a MobyGames account](https://www.mobygames. ### LaunchBox -The [LaunchBox](https://gamesdb.launchbox-app.com) Games Database is a community-driven database that provides metadata, cover art, and screenshots. Like the Launchbox desktop application, RomM downloads the entire database locally and matches games based on their exact filenames. +The [LaunchBox](https://gamesdb.launchbox-app.com/) Games Database is a community-driven database that provides metadata, cover art, and screenshots. Like the Launchbox desktop application, RomM downloads the entire database locally and matches games based on their exact filenames. To enable LaunchBox, set `LAUNCHBOX_API_ENABLED=true` in your environment variables. You can enable regular updates of the database by setting `ENABLE_SCHEDULED_UPDATE_LAUNCHBOX_METADATA`, and set the frequency on the cron job with `SCHEDULED_UPDATE_LAUNCHBOX_METADATA_CRON` (defaults to 5:00 AM every day). @@ -96,7 +96,7 @@ Simply set `HASHEOUS_API_ENABLED=true` in your environment variables, and future ### PlayMatch -[Playmatch](https://github.com/RetroRealm/playmatch) is a project built and hosted by a member of our comminuty. It provides a hash-based matching service for, and is used in conjunction with, IGDB. +[PlayMatch](https://github.com/RetroRealm/playmatch) is a hash-based matching service used in conjunction with IGDB to provide better matching for games, hosted by a member of our community. To enable PlayMatch, set `PLAYMATCH_API_ENABLED=true` in your environment variables. @@ -104,17 +104,17 @@ To enable PlayMatch, set `PLAYMATCH_API_ENABLED=true` in your environment variab SteamGridDB provides custom cover art for games or collections. It's not accessed through the scanner but from the "search cover" button when manually editing a game. -To access steamGridDB API, you need to login into their [website](https://www.steamgriddb.com/) with a [steam account](https://store.steampowered.com/join). Once logged in, go to your [API tab under the preferences page](https://www.steamgriddb.com/profile/preferences/api). Copy the key shown and use it to set `STEAMGRIDDB_API_KEY`. +To access the SteamGridDB API, you need to login to their [website](https://www.steamgriddb.com/) with a [Steam account](https://store.steampowered.com/join). Once logged in, go to your [API tab under the preferences page](https://www.steamgriddb.com/profile/preferences/api). Copy the key shown and use it to set `STEAMGRIDDB_API_KEY`. -### Retroachievements +### RetroAchievements -RomM is able to display your achievements from [Retroachievements](https://retroachievements.org/). To sync it with your RomM instance, you need to generate an API key from your Retroechievements account in your [settings](https://retroachievements.org/settings) +RomM is able to display your achievements from [RetroAchievements](https://retroachievements.org/). To sync it with your RomM instance, you need to generate an API key from your RetroAchievements account in your [settings](https://retroachievements.org/settings). -Copy the key shown and use it to set `RETROACHIEVEMENTS_API_KEY` and perform a partial scan targeting the platform you want to match with Retroachievements. +Copy the key shown and use it to set `RETROACHIEVEMENTS_API_KEY` and perform a `UNMATCHED` scan targeting the platform you want to match with RetroAchievements. -After that, each user need to set their own username in their profile and sync it with Retroachievements. A new `Achievements` tab will appear in the `Personal` tab in the game details. +After that, each user needs to set their own username in their profile and sync it with RetroAchievements. A new `Achievements` tab will appear in the `Personal` tab in the game details. -To avoid unneccessary API calls, a cached file with the RA database is stored in RomM. Refresh time for that cache file can be changed with the env variable `REFRESH_RETROACHIEVEMENTS_CACHE_DAYS` +To avoid unnecessary API calls, a cached file with the RA database is stored in RomM. Refresh time for that cache file can be changed with the environment variable `REFRESH_RETROACHIEVEMENTS_CACHE_DAYS`. ??? Screenshots @@ -123,11 +123,11 @@ To avoid unneccessary API calls, a cached file with the RA database is stored in ### Flashpoint -The [Flashpoint Project Database](https://flashpointproject.github.io/flashpoint-database/) is a project that enables metadata for 180,000+ flash and browser-based games. Enable this metadata source with the `FLASHPOINT_API_ENABLED=true` envrionment variable. If you are adding this provider to an existing RomM setup, perform a _partial search_ with Flashpoint selected to update an existing platform. +The [Flashpoint Project Database](https://flashpointproject.github.io/flashpoint-database/) is a project that enables metadata for 180,000+ flash and browser-based games. Enable this metadata source with the `FLASHPOINT_API_ENABLED=true` environment variable. If you are adding this provider to an existing RomM setup, perform a `UNMATCHED` scan with Flashpoint selected to update an existing platform. ### How Long To Beat -The [How Long To Beat](https://howlongtobeat.com/) project provides game completion times for more than 84,000 games. Enable this metadata source with the `HLTB_API_ENABLED=true` envrionment variable. If you are adding this provider to an existing RomM setup, perform a _partial search_ with Flashpoint selected to update an existing platform. +The [How Long To Beat](https://howlongtobeat.com/) project provides game completion times for more than 84,000 games. Enable this metadata source with the `HLTB_API_ENABLED=true` environment variable. If you are adding this provider to an existing RomM setup, perform a `UNMATCHED` scan with How Long To Beat selected to update an existing platform. Game completion times will be added to a new tab on the details page for supported matched games. @@ -137,17 +137,17 @@ EmulationStation, and it's modern successor ES-DE, use a custom XML format to st ```yaml library/ - └─ roms/ +└─ roms/ └─ gba/ - ├─ game_1.gbc - ├─ game_2.gbc - ├─ gamelist.xml - ├─ 3dboxes/ - │ ├─ game_1.png - │ └─ game_2.png - ├─ covers/ - ├─ screenshots/ - └─ etc... + ├─ game_1.gba + ├─ game_2.gba + ├─ gamelist.xml + ├─ 3dboxes/ + │ ├─ game_1.png + │ └─ game_2.png + ├─ covers/ + ├─ screenshots/ + └─ etc... ``` ## Metadata Tags in Filenames diff --git a/docs/Getting-Started/OIDC-Setup.md b/docs/Getting-Started/OIDC-Setup.md new file mode 100644 index 0000000..51786e2 --- /dev/null +++ b/docs/Getting-Started/OIDC-Setup.md @@ -0,0 +1,67 @@ +# OIDC Setup + +OpenID Connect (OIDC) allows you to authenticate to RomM using external identity providers, enabling Single Sign-On (SSO) and centralized user management. This setup eliminates the need to manage separate credentials for RomM. + +## What is OIDC? + +OIDC is an identity layer built on top of OAuth2. While OAuth2 primarily handles authorization, OIDC adds authentication, enabling applications to verify a user's identity and obtain profile information. This makes OIDC suitable for SSO solutions, where user identity is central to access management. + +## How It Works + +1. Click the OIDC login button on RomM's login page +2. You're redirected to your identity provider +3. Authenticate with your credentials +4. You're redirected back to RomM and logged in automatically + +## Supported Identity Providers + +RomM supports OIDC authentication with the following identity providers: + +### [Authelia](../OIDC-Guides/OIDC-Setup-With-Authelia.md) + +An open-source authentication and authorization server providing two-factor authentication and SSO. Ideal for self-hosters looking for a lightweight solution. + +### [Authentik](../OIDC-Guides/OIDC-Setup-With-Authentik.md) + +An open-source identity provider with support for modern authentication protocols, MFA, and comprehensive user management. + +### [PocketID](../OIDC-Guides/OIDC-Setup-With-PocketID.md) + +A simple OIDC provider that exclusively supports passkey authentication - no passwords required. + +### [Zitadel](../OIDC-Guides/OIDC-Setup-With-Zitadel.md) + +An enterprise-grade, open-source identity and access management platform supporting OAuth2, OIDC, SAML, and passwordless authentication. + +## General Setup Requirements + +Regardless of which provider you choose, you'll need to configure these environment variables in RomM: + +```env +OIDC_ENABLED=true +OIDC_PROVIDER= +OIDC_CLIENT_ID= +OIDC_CLIENT_SECRET= +OIDC_REDIRECT_URI=/api/oauth/openid +OIDC_SERVER_APPLICATION_URL= +``` + +## Important Notes + +- **Email matching**: Your email address in RomM must match the email in your identity provider +- **First-time users**: Users logging in via OIDC for the first time will be created automatically with viewer permissions +- **Existing users**: Users who already have an account in RomM need to ensure their email addresses match between RomM and the identity provider + +## Troubleshooting + +If you encounter issues with OIDC authentication: + +- Verify all environment variables are set correctly +- Check that the redirect URI matches exactly between RomM and your identity provider +- Ensure your email address in RomM matches your email in the identity provider +- Review the [Authentication Issues](../Troubleshooting/Authentication-Issues.md) documentation +- Check your identity provider's logs for any authentication errors + +## Next Steps + +Choose a provider from the list above and follow its specific setup guide. Each guide provides detailed step-by-step instructions for configuring both the identity provider and RomM. diff --git a/docs/Getting-Started/Quick-Start-Guide.md b/docs/Getting-Started/Quick-Start-Guide.md index 30c2b6c..5fa99ed 100644 --- a/docs/Getting-Started/Quick-Start-Guide.md +++ b/docs/Getting-Started/Quick-Start-Guide.md @@ -1,20 +1,16 @@ -This quick start guide will help you get a RomM instance up and running. It is split into 3 parts: - -- Prepare -- Build -- Configure +This quick start guide will help you get a RomM instance up and running. It is split into 3 parts: Prepare, Build and Configure. ## Prepare -This guide will assume that you already have the following done, if not - stop here and come back when you do. +There are a few things you need to have in place before you can start: -- [Docker installed](https://docs.docker.com/get-docker/) and running on your system +- [Docker](https://docs.docker.com/get-docker/) installed and running on your system - Your ROMs organized in the correct [folder structure](./Folder-Structure.md) - The recommended [metadata providers](./Metadata-Providers.md) set up -- A copy of the [config.yml](https://github.com/rommapp/romm/blob/master/examples/config.example.yml) in the config folder +- A copy of the [config.yml](./Configuration-File.md) in the config folder for your environment !!! warning @@ -45,15 +41,15 @@ Now that we have everything gathered, we can begin getting your instance set up! 5. Add your metadata sources API keys: - IGDB: `IGDB_CLIENT_ID` and `IGDB_CLIENT_SECRET` - ScreenScraper.fr: `SCREENSCRAPER_USER` and `SCREENSCRAPER_PASSWORD` - - RetroAchievements: `RETROACHIEVEMENTS_USERNAME` and `RETROACHIEVEMENTS_API_KEY` + - RetroAchievements: `RETROACHIEVEMENTS_API_KEY` - MobyGames: `MOBYGAMES_API_KEY` - SteamGridDB: `STEAMGRIDDB_API_KEY` - - PlayMatch: `PLAYMATCH_API_ENABLED=true` - Hasheous: `HASHEOUS_API_ENABLED=true` + - PlayMatch: `PLAYMATCH_API_ENABLED=true` - LaunchBox: `LAUNCHBOX_API_ENABLED=true` 6. Modify the following values in the **volumes** to configure the application - - `/path/to/library`: Path to the directory where your rom files will be stored (usually the parent folder of the `roms` folder) - - `/path/to/assets`: Path to the directory where you will store your saves, etc + - `/path/to/library`: Path to the directory where your ROM files will be stored (usually the parent folder of the `roms` folder) + - `/path/to/assets`: Path to the directory where you will store your save files and other assets - `/path/to/config`: Path to the directory where you will store the config.yml (store the `config.yml` file in this folder) 7. Save the file as _docker-compose.yml_ instead of _docker-compose.example.yml_. It should look something like this: @@ -96,12 +92,12 @@ This method is generally the fastest and recommended for first time setup. You n 1. Log into RomM with your user credentials 2. Click the `Scan` button in the sidebar 3. Select the metadata providers you want to fetch metadata from -4. The system will now begin scanning the rom files and applying metadata to them. You can click on any of the items that it has tagged to see the metadata it pulled without having to stop the scan -5. After the scan completes, click the RomM logo to go back to the main screen. You should see the platforms and recent games it has scanned. You are now ready to rock and RomM! +4. The system will now begin scanning the ROM files and applying metadata to them. You can click on any of the items that it has tagged to see the metadata it pulled without having to stop the scan +5. After the scan completes, click the RomM logo to go back to the main screen. You should see the platforms and recent games it has scanned. You are now ready to rock with RomM! ### Uploading your ROMs via Web Interface -This method is certainly viable, but not recommended if you have a lot of ROMs and/or multiple platforms. It is good for adding after the fact as your collection grows, but wouldn't be recommended for the first set up, nor for multi-file ROMs: +This method is certainly viable, but not recommended if you have a lot of ROMs and/or multiple platforms. It is good for adding files after the fact as your collection grows, but wouldn't be recommended for the first setup, nor for multi-file ROMs: 1. Log into RomM with your user credentials 2. Click the `Upload` button in the sidebar diff --git a/docs/Getting-Started/Reverse-Proxy.md b/docs/Getting-Started/Reverse-Proxy.md index 98437ea..9e51741 100644 --- a/docs/Getting-Started/Reverse-Proxy.md +++ b/docs/Getting-Started/Reverse-Proxy.md @@ -1,6 +1,6 @@ -Here are some basic configurations for popular reverse proxies. Some installations may require modifications to configuration options not listed below. +Here are some basic configurations for popular reverse proxies. Additional configuration may be required depending on your specific setup. ## Caddy @@ -90,21 +90,22 @@ server { ## Nginx Proxy Manager -Items marked with ❗ are important to set, as RomM may not correctly otherwise! +Items marked with ❗ are important to set, as RomM may not work correctly otherwise! ### ⚡ Details -- Domain Names: `romm.example.com` (replace example with your own)\* Scheme: `http` +- Domain Names: `romm.example.com` (replace example with your own) +- Scheme: `http` - Forward Hostname/IP: device IP (like 192.168.X.X) - Forward Port: `8080` - Cache Assets: `off` - Block Common Exploits: `on` - Websockets Support: `on` ❗ -- Access List: - +- Access List: - (or configure as needed) ### 🛡️ SSL -Strongly recommended, but only required if you plan to secure your site (use HTTPS) +Strongly recommended for security; enable this if you plan to use HTTPS. - SSL Certificate: "Request a new SSL Certificate" - Force SSL: `on` diff --git a/docs/Navigation.md b/docs/Navigation.md index 4a590de..5f4f75d 100644 --- a/docs/Navigation.md +++ b/docs/Navigation.md @@ -13,7 +13,6 @@ search: - [Metadata Providers](Getting-Started/Metadata-Providers.md) - [Environment Variables](Getting-Started/Environment-Variables.md) - [Reverse Proxy](Getting-Started/Reverse-Proxy.md) - - [Authentication](Getting-Started/Authentication.md) - Platforms and Players - [Supported Platforms](Platforms-and-Players/Supported-Platforms.md) - Web Players @@ -26,15 +25,21 @@ search: - [With Docker Compose](System-Setup/Unraid-Compose-Setup.md) - [Synology Setup](System-Setup/Synology-Setup-Guide.md) - [TrueNAS Setup](System-Setup/TrueNAS-Setup-Guide.md) -- OIDC Setup Guides - - [OIDC Setup With Authelia](OIDC-Guides/OIDC-Setup-With-Authelia.md) - - [OIDC Setup With Authentik](OIDC-Guides/OIDC-Setup-With-Authentik.md) - - [OIDC Setup With PocketID](OIDC-Guides/OIDC-Setup-With-PocketID.md) - - [OIDC Setup With Zitadel](OIDC-Guides/OIDC-Setup-With-Zitadel.md) - Usage - [User Management](Usage/UserManagement.md) - [Library Management](Usage/LibraryManagement.md) - - [Administration](Usage/UserManagement.md) + - [Administration](Usage/Administration.md) +- OIDC Setup + - [OIDC Setup](Getting-Started/OIDC-Setup.md) + - [With Authelia](OIDC-Guides/OIDC-Setup-With-Authelia.md) + - [With Authentik](OIDC-Guides/OIDC-Setup-With-Authentik.md) + - [With PocketID](OIDC-Guides/OIDC-Setup-With-PocketID.md) + - [With Zitadel](OIDC-Guides/OIDC-Setup-With-Zitadel.md) +- API & Development + - [Development Setup](API-and-Development/Development-Setup.md) + - [API Reference](API-and-Development/API-Reference.md) + - [Authentication](Getting-Started/Authentication.md) + - [Contributing](API-and-Development/Contributing.md) - Tools - [Igir Collection Manager](Tools/Igir-Collection-Manager.md) - Maintenance @@ -50,7 +55,7 @@ search: - [Authentication Issues](Troubleshooting/Authentication-Issues.md) - [Synology Issues](Troubleshooting/Synology-Issues.md) - [Miscellaneous Issues](Troubleshooting/Miscellaneous-Troubleshooting.md) - - [Kubernetes-Issues](Troubleshooting/Kubernetes-Issues.md) + - [Kubernetes Issues](Troubleshooting/Kubernetes-Issues.md) - Miscellaneous - [FAQs](Miscellaneous/FAQs.md) - [Branding Guidelines](Miscellaneous/Brand-Guidelines.md) diff --git a/docs/Usage/Administration.md b/docs/Usage/Administration.md index b83540a..8a565ab 100644 --- a/docs/Usage/Administration.md +++ b/docs/Usage/Administration.md @@ -3,30 +3,40 @@ title: Administration description: Navigating and using the Administration Menu --- -Clicking on your Profile icon from any screen opens the Administration Drawer. This drawer will look slightly differently based on what role you possess. The options here can include **Profile**, **User Interface**, **Library Management**, **Administration**, **Server Stats**, and **About**. +Clicking on your Profile icon from any screen opens the Administration Drawer. This drawer will look slightly different based on your role. The options available can include **Profile**, **User Interface**, **Library Management**, **Administration**, **Server Stats**, and **About**. ## Profile -All users are able to see this screen. From here you change your username, password, and email. +All users can access this screen. From here you can change your username, password, and email. -Additionally, you can submit your Retroachievements username and sychronize your achievements here. +Additionally, you can submit your RetroAchievements username and synchronize your achievements here. ## User Interface -From here you can change your language, the color scheme of RomM, what ribbons are visible to you on the home screen, how to group your platforms, and what information to display on game cards. Finally, you can configure your autogenerated collections here, and the source for those collections. +From here you can: + +- Change your language +- Adjust the color scheme of RomM +- Control which ribbons are visible on the home screen +- Configure how to group your platforms +- Set what information to display on game cards +- Configure autogenerated collections and their sources ## Library Management -From this screen, you can edit your platform bindings and versions on the config tab, and manage your missing games on the Missing Games tab. +From this screen you can: + +- Edit platform bindings and versions on the Config tab +- Manage missing games on the Missing Games tab ## Administration -From this page you can manage your users, and check your scheduled and manual tasks. +From this page you can manage users and check scheduled and manual tasks. ## Server Stats -This area shows the number of platforms, games, saves, states, and screenshots on the server as well as how much space this consumes. Platforms can be filtered here to show how much they contribute to size and game count. +This area displays the number of platforms, games, saves, states, and screenshots on the server, as well as how much disk space this consumes. Platforms can be filtered here to show how much each platform contributes to total size and game count. ## About -This pop-up shows your RomM version, with links to the community discord, github, and documentation. +This pop-up displays your RomM version with links to the community Discord, GitHub, and documentation. diff --git a/docs/Usage/LibraryManagement.md b/docs/Usage/LibraryManagement.md index 4307f3e..5486c6e 100644 --- a/docs/Usage/LibraryManagement.md +++ b/docs/Usage/LibraryManagement.md @@ -13,7 +13,7 @@ In all views, a grid icon is present in the upper right of the screen or contain ### Game and Platform cards -Platform cards can be clicked to go directly to the platform. A game card can be interacted in a few ways: putting your mouse over it allows you to download the game, play the game if the system is supported, or open a context menu giving you the option to manually match game information using a metadata agent, edit existing data, refresh the metadata, and add or remove the game from favourites or collections. +Platform cards can be clicked to go directly to the platform. A game card can be interacted with in several ways: putting your mouse over it allows you to download the game, play the game if the system is supported, or open a context menu giving you the option to manually match game information using a metadata agent, edit existing data, refresh the metadata, and add or remove the game from favourites or collections. ![game card](https://raw.githubusercontent.com/rommapp/docs/refs/heads/main/docs/resources/usage/gameCard.png) ![context menu](https://raw.githubusercontent.com/rommapp/docs/refs/heads/main/docs/resources/usage/ContextMenu.png) @@ -24,7 +24,7 @@ Clicking a platform will take you to the platform view, while clicking a game wi Filters are present on nearly every screen in RomM, allowing you to quickly drill down to see only the information relevant to your search. -If you perform a search first, the listed filters will be taken from the metadata of all present games. For example, if you searched for the word "Fox", and then clicked filters and selected a Language, the list of languages that can be selected from are taken from the displayed games. +If you perform a search first, the listed filters will be taken from the metadata of all present games. For example, if you searched for the word "Fox", and then clicked filters and selected a Language, the list of languages available will be taken from the displayed games. #### Toggles @@ -36,13 +36,13 @@ The filters that can be toggled include: - **Show Duplicates** - Show only games that have multiple copies. - **Show Playables** - Show only games that can be played in a browser. - **Show Missing** - Shows only games that exist in the database but are otherwise not present. -- **Show Verified** - Shows only games that have matched to Hashelous. -- **Show Retroachievements** - Shows only games that have support on the RetroAchievements website. +- **Show Verified** - Shows only games that have matched to Hasheous. +- **Show RetroAchievements** - Shows only games that have support on the RetroAchievements website. -Next there is a platform drop down. This allows you to select a platform you want to restrict your view to showing. +Next there is a platform dropdown. This allows you to select a platform you want to restrict your view to showing. After this you can filter by metadata: Game Genre, Franchise, Collections, Company, Age Rating, Region, and Language. -One additional filter exists after these: Status. This allows you to use the "personal" data tab on any game to track your progress of the game (never playing, backlogged, complete, etc). +One additional filter exists after these: Status. This allows you to use the "personal" data tab on any game to track your progress of the game (never played, backlogged, complete, etc). ## The Menu bar @@ -64,16 +64,19 @@ The Collections button opens a drawer listing all of your manually created colle ### Scan -This is where you'll scan for new platforms and games. Metadata sources are specified to determine where your metadata is coming from. Platforms allow you to restrict your scan operation to specific platforms. +This is where you'll scan for new platforms and games. `Metadata sources` can be selected to determine which providers will be used to fetch metadata. Use the `Platforms` dropdown to restrict your scan to specific platforms. -The Scan Operations drop down allows you to choose a specific operation to perform: +The `Scan options` dropdown allows you to choose a specific type of scan to perform: -- **New Platforms** - This will only look for platforms that aren't already in RomM. -- **Quick Scan** - Searches all existing platforms for games that aren't already in RomM. -- **Unidentified Games** - Selects all games in RomM that aren't yet matched and attempts to match them. -- **Partial Metadata** - Selects games that have been matched, but whose metadata is incomplete, attempting to add more metadata. -- **Recalculate Hashes** - Recalculates hashes for all files. -- **Total Rescan** - Rescans the all platforms (unless specific platforms are specified) and scans every file presented in the platform folder. +- **New Platforms**: This will only look for platforms that are not already in RomM. +- **Quick Scan**: Scans for games that are not in the library yet (fastest). +- **Unmatched Games**: Attempts to match games that are not matched with the selected metadata sources. + - For example, selecting `IGDB` and `ScreenScraper` will scan games that are **not matched** with IGDB **or** ScreenScraper. +- **Update Metadata**: Updates the metadata for games that have been matched with selected metadata sources using the external ID (e.g. IGDB ID). + - For example, selecting `IGDB` and `ScreenScraper` will update the metadata for games that **are matched** with IGDB **or** ScreenScraper, and will use `igdb_id` and/or `ssfr_id` to refetch the metadata from the respective providers. +- **Recalculate Hashes**: Recalculates hashes for all files in the selected platforms. +- **Total Rescan**: Rescans and rematches all games in the selected platforms (slowest). + - This will wipe all existing metadata matches, including the external IDs, and attempt to match them again, like on a fresh scan. _Saves, states and notes will be preserved._ ### Console @@ -107,7 +110,7 @@ The platform view shows all of the games for a specific platform. There is a but The platform view drawer has a large icon representing the platform, along with its title. -Below that is a button to upload roms and a button to initiate scans. +Below that is a button to upload ROMs and a button to initiate scans. Below that is a line showing how many metadata providers are being used for that platform. @@ -123,7 +126,7 @@ Finally, in the Danger Zone, is a Delete Platform button. This removes the platf Next to the platform drawer button is the firmware button. This allows you to review all of the firmware for that system, and upload firmware using the user interface. -Uploading firmware will open a file browse dialog box. Simply select the bios file or files you wish to upload and click "Upload". +Uploading firmware will open a file browse dialog box. Simply select the BIOS file or files you wish to upload and click "Upload". ## Collection View @@ -142,6 +145,6 @@ The Details tab includes metadata for the game. This will show where the data co The Game Data tab includes save files and save states, the ability to upload and download them, as well as delete them. This data is personal to the logged in user. -Finally the Personal tab has check boxes denoting if a game is backlogged, being played, or if it should be hidden. User data such as rating, difficulty, % completed, and the status of the game can also be set here. Retroachievements can be viewed from this tab for supported matched games. +Finally the Personal tab has check boxes denoting if a game is backlogged, being played, or if it should be hidden. User data such as rating, difficulty, % completed, and the status of the game can also be set here. RetroAchievements can be viewed from this tab for supported matched games. If How Long To Beat is enabled as a metadata provider, there will also be a tab here for viewing that data as well. diff --git a/docs/Usage/UserManagement.md b/docs/Usage/UserManagement.md index 6e8be46..5422e27 100644 --- a/docs/Usage/UserManagement.md +++ b/docs/Usage/UserManagement.md @@ -3,22 +3,22 @@ title: User Management description: Adding, Removing, and Managing your Users. --- -In the Administration panel are the tools used to manage users on the server. The first user created will always be given the admin Role. +The Administration panel contains the tools used to manage users on the server. The first user created will always be given the admin role. -A user will be able to manage their own game saves, save states, their profile icon, and the "Personal" data tab on games. +Users can manage their own game saves, save states, their profile icon, and the "Personal" data tab on games. ## Adding Users -Adding a User is as simple as adding a username, password, email address, and selecting a role. Users can be added manually using the "Add" button or inviting a user by link. If you invite a user in this manner, all you need to set is a role and they will be prompted to fill in the rest. +Adding a user is as simple as providing a username, password, email address, and selecting a role. Users can be added manually using the "Add" button or by inviting a user via link. When inviting a user, you only need to set a role; they will be prompted to complete the rest of the information. ### Roles Explained **Admin** - The highest authority role. This grants full permission to do everything on the server. -**Editor** - This role has the ability to edit platforms and games (adding, removing, or scanning for new content) and make collections public. +**Editor** - Can edit platforms and games (adding, removing, or scanning for new content) and make collections public. -**Viewer** - The lowest authority role. You can play games, and interact with Personal data tab. +**Viewer** - The most restricted role. Can play games and interact with the Personal data tab. ## Removing Users -Removing a user is as simple as clicking the red garbage icon, and confirming the operation. +Removing a user is as simple as clicking the red delete icon and confirming the operation. diff --git a/docs/index.md b/docs/index.md index c0ef5fc..f28cfdc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ --- title: Introduction -description: An introduction to your beautiful, powerful, self-hosted rom manager +description: An introduction to your beautiful, powerful, self-hosted rom manager and player hide: - toc --- @@ -44,7 +44,7 @@ We strive to create a safe and respectful space where everyone can contribute an Join us on Discord, where you can ask questions, submit ideas, get help, showcase your collection, and discuss RomM with other users. diff --git a/docs/resources/metadata_providers/3dboxes.png b/docs/resources/metadata_providers/3dboxes.png index 341d982..e6d7c1e 100644 Binary files a/docs/resources/metadata_providers/3dboxes.png and b/docs/resources/metadata_providers/3dboxes.png differ diff --git a/mkdocs.yml b/mkdocs.yml index e9b8707..3cbd22a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -96,7 +96,7 @@ extra: link: https://github.com/rommapp/romm name: rommapp/romm - icon: fontawesome/brands/discord - link: https://discord.com/invite/RGPJHNMMwJ + link: https://discord.com/invite/romm name: RomM Discord Channel - icon: fontawesome/solid/globe link: https://romm.app/
Structure A (recommended) + Structure A (recommended) Structure B (fallback)