Merge pull request #22 from anthonycaccese/main

Theme, Collection and gitignore updates

Author: acmeplus

.gitignore

@@ -1,3 +1,172 @@
-/.project
-/Pipfile.lock
-/*.bat
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# OS generated files #
+######################
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+Icon?
+ehthumbs.db
+Thumbs.db
+docs/.DS_Store

docs/_inc/images/collections-dynamic-1.png

@@ -0,0 +1,57 @@
+# :material-collage: Collections
+
+In addition to the systems displayed; EmulationStation (ES) has functionality to create custom collections that you can use to group and organize your game library in different ways.  For example; if you wanted to create a view that automatically grouped all of your Role Playing Games or one that only lists the games you are currently playing you can use ES collections to do that. 
+
+All of the options described below can be managed by pressing ++"START"++ anywhere in ES to open the Main Menu and then opening ++"Game Collection Settings"++
+
+![Game Collection Settings Menu](../../_inc/images/collections-main-menu.png)
+
+## Managing Your Backlog
+
+Knulli includes a `Now Playing` collection that can be used to curate and play through your backlog.  You can turn this on by going to `Game Collection Settings` > `Create New Custom Collection from Theme` while using our default system-theme.
+
+<table>
+    <tr>
+        <td><img src="../../_inc/images/collections-from-theme-1.png"></td>
+        <td><img src="../../_inc/images/collections-from-theme-2.png"></td>
+    </tr>
+</table>
+
+Once its turned on; you can add to it by pressing ++"X(NORTH)"++ on any game while in ES.  In the menu that opens you'll see `Now Playing` listed under the collections header.  Simply highlight it and press the confirm button.  
+
+You can also set Knulli to boot directly into the Now Playing collection by setting the `Start on System` value in the `Game Collection Settings` menu.  Change that value to `Now Playing` and also turn on `Start on Gamelist`.
+
+With the above settings you can create a very simple view of the games you are trying to finish that displays directly when Knulli launches.
+
+## Collection Types
+
+There are 3 collection types in ES so let's walk through each to help you decide which makes sense to use for your use cases.
+
+### Automated Collections
+
+EmulationStation has a set of built-in automated collections to easily view your last played games, favorites and all the games in your library.  You can turn these on or off in the ++"Automated Game Collections"++ menu.
+
+### Editable Collections
+
+An editable collection is one that you can specifically curate by hand.  Simply give it a name and then as you are browing your gamelists you can press ++"X(NORTH)"++ on any game and add it to the collection you created.  As an example, you could use this functionality to create a collection for all of your Final Fantasy games and then manually add each FF game to the list.
+
+### Dynamic Collections
+
+A dynamic collection enables you to create a set of filters that will automatically group your games.  For example if you wanted to create a collection that automatically grouped all of your Role Playing Games into a single view; you could create a dynamic collection called RPGs, select a genre filter of Role Playing Games and then save the filter.  Then any time you add a new game with the Role Playing genre it will automatically show up in this collection.
+
+<table>
+    <tr>
+        <td><img src="../../_inc/images/collections-dynamic-1.png"></td>
+        <td><img src="../../_inc/images/collections-dynamic-2.png"></td>
+    </tr>
+    <tr>
+        <td><img src="../../_inc/images/collections-dynamic-3.png"></td>
+        <td><img src="../../_inc/images/collections-dynamic-4.png"></td>
+    </tr>
+</table>
+
+---
+
+## Additional Notes
+
+You can also use the ++"Game Collection Settings"++ menu to manage which systems are displayed. Press ++"START"++ anywhere in ES to open the Main Menu and then go to ++"Game Collection Settings"++ > ++"Systems Displayed"++.  In this menu; uncheck the systems you would like to hide and then exit the menu.  ES will then refresh and those systems will be hidden.

docs/_inc/images/collections-dynamic-2.png

@@ -0,0 +1,115 @@
+# :material-page-next-outline: Themes
+
+Knulli's default frontend is EmulationStation and default theme is [Art Book Next](https://github.com/anthonycaccese/art-book-next-es). Also included by default is the [Carbon](https://github.com/fabricecaruso/es-theme-carbon) theme from Batocera. Both are updated automatically as part of each release.
+
+## Preview
+
+<table>
+  <tr>
+    <td><img src="../../_inc/images/screenshots/system-view.png"/></td>
+    <td><img src="../../_inc/images/screenshots/menu.png"/></td>
+  </tr>
+  <tr>
+    <td><img src="../../_inc/images/screenshots/gamelist-view-metadata-immersive.png"/></td>
+    <td><img src="../../_inc/images/screenshots/gamelist-view-no-metadata-immersive.png"/></td>
+  </tr>
+</table>
+
+## Configuration
+
+The following options can be changed directly from the main menu under `User Interface Settings > Theme Configuration`
+
+| Setting | Description | Options |
+| -- | -- | -- |
+| Distribution | Used to define which folder to look in for Theme Customization files. | `Batocera/Knulli`, `RetroBat` |
+| Aspect Ratio | Enables you to select the correct aspect ratio for your screen.  This will automatically set itself so you should not need to change it but if the theme layout looks odd or spacing looks incorrect you can use this setting to make sure the aspect ratio matches your screen. | `16:9`, `16:10`, `4:3`, `3:2`, `1:1` |
+| System Artwork | Defines the set of artwork that is displayed on the system view | `Default`, `Noir`, `Custom`, `Custom (Fullscreen)` |
+| System Logos | Defines the logo set used on all views | `Default`, `Custom` |
+| Game Artwork | Defines the type of artwork used to represent a game. These are sourced from the the selections you make in the scraper menu. Image will display the image you selected to scrape for `Image Source`.  Image (Cropped) will display that same image zoomed in to fill the screen.  Boxart will display the image you selected to scrape for `Box Source` | `Image`, `Image (Cropped)`, `Boxart` |
+| Game Metadata | Sets if metadata (e.g. description, release date, etc...) should be displayed for a game | `On`, `Off` |
+| Font Size | Set the size for text elements throughout the theme. | `Default`, `Small`, `Large` |
+| Color Scheme | Sets the color scheme that is used for the theme.  There is a set of prebuilt color schemes that you can select and an option to supply your custom color scheme (selected by choosing `custom`). You can see details on customizations below under [Theme Customizations](#theme-customizations). | `Default`, `Light`, `Steam OS`, `SNES`, `Famicom`, `DMG`, `OLED`, `Custom` |
+
+### Additional UI Settings 
+
+The following EmulationStation settings can also be changed and will update the look of the theme accordingly:
+
+* `User Interface Settings > Show Clock` - This will allow you to turn the system clock on or off
+* `User Interface Settings > On-Screen Help` - This will turn the display of EmulationStation's help system on or off (the theme's layout will automatically adapt to the available space)
+* `User Interface Settings > Show Battery Status` - This will allow you to change what is displayed for the battery status.
+
+## Customization
+
+Art Book Next allows customizations to system artwork and color schemes without the need to edit the source XML.  This enables you to change the look of the theme and still retain your changes when the theme is updated.
+
+### Start Here
+- Make sure the `Distribution` setting is set to `Batocera/Knulli` (This value determines the folder where you will add your customizations)
+    - Batocera/Knulli folder is = `/userdata/theme-customizations/art-book-next/`
+    - Create this folder and then move on to the options below...
+
+### Background Art
+
+The artwork used on the system view can be customized with your own images.
+
+#### For angled artwork:
+
+* Create your custom artwork using one of the masks i've supplied in this theme's resources directory [here](https://github.com/anthonycaccese/art-book-next-es/tree/main/resources/customizations). I've included a set of masks that should work in all major image editing programs.
+* Export your final images as transparent pngs
+* Create a folder in the path you created above called `artwork`
+* Upload your images to that folder
+* They can be named:
+    * `_default.png`
+    * `${system.theme}.png`
+    * The theme will look them them up in that order. If a given image is not found in your folder then the the images from the theme will be used as a fallback.  This allows you to customize only the images you want and still have images displayed for all systems.
+    * `_default.png` can be used for creating a single image that is used for all systems OR a fallback for systems that you did not create a custom image for (if you don't want to use the fallback that already exists in the theme)
+    * `${system.theme}.png` should be named for the system you are looking to override. For example if you wanted to override the artwork for `snes` you would create an image called `snes.png` in the artwork folder.
+* Once your images are in place you turn on custom images by changing the `System Artwork` setting to `Custom`
+
+#### For fullscreen artwork:
+
+* Create a folder in the path you created above called `artwork-fullscreen`
+* Upload your images to that folder
+* They can be named:
+    * `_default.png`
+    * `_default.jpg`
+    * `${system.theme}.png`
+    * `${system.theme}.jpg`
+    * The theme will look them them up in that order.
+    * `_default.png/jpg` can be used for creating a single image that is used for all systems OR a fallback for systems that you did not create a custom image for (if you don't want to use the fallback that already exists in the theme)
+    * `${system.theme}.png/jpg` should be named for the system you are looking to override. For example if you wanted to override the artwork for `snes` you would create an image called `snes.png` or `snes.jpg` in the artwork folder.
+* Once your images are in place you turn on custom images by changing the `System Artwork` setting to `Custom (Fullscreen)`
+
+### Color Schemes
+
+You can create your own custom color scheme to use for the theme
+
+* Download [this template](https://github.com/anthonycaccese/art-book-next-es/blob/main/resources/customizations/colors.xml)
+* Upload it in the path you created above and make sure its called `colors.xml`
+* Change any values in the template to the colors you prefer.
+* I tried to make the values as self explanatory as possible but if you have questions regarding which property does what please don't hesitate to ask.
+* After your colors are defined; in theme configuration change `Color Scheme` to `Custom`
+
+### Logos
+
+System logos can be customized by adding your own images
+
+* Create a folder in the path you created above called `logos`
+* Upload your images to that folder
+* They can be named:
+    * `${system.theme}.svg`
+    * `${system.theme}.png`
+    * The theme will look them them up in that order. If a given image is not found in your folder then the the images from the theme will be used as a fallback.  This allows you to customize only the images you want and still have images displayed for all systems.
+    * `${system.theme}.svg/png` should be named for the system you are looking to override. For example if you wanted to override the logo for `snes` you would create an image called `snes.svg` or `snes.png` in the logos folder.
+* Once your images are in place you turn on custom images by changing the `System Logos` setting to `Custom`    
+
+## Adding Additional Themes
+
+- Knulli's version of EmulationStation is sourced from the same version used in Batocera so you can also use themes that were created for Batocera directly
+- You can download themes directly using the built-in theme downloader (which includes nice previews of each theme)
+- You can also find a list of Batocera themes here: [https://batocera.org/themes.php](https://batocera.org/themes.php) if you would prefer to download them manually
+
+!!! note "There are no guarantees that themes from the above list will support the aspect ratio of your device or all of the systems we support.  Because of that; some themes may look odd, not display all systems or have layouts that do not match well to your screen."
+
+## Creating Your Own Theme
+
+An exhaustive tutorial is out of scope for this wiki.  That said; please see Batocera's theme documention @ [https://wiki.batocera.org/write_themes_for_emulationstation](https://wiki.batocera.org/write_themes_for_emulationstation).  Its a great starter guide for understanding the fundamentals of creating themes for the version of EmulationStation used by Knulli.