feat: dzgui 7 alpha

docs/source/bugs.rst

@@ -0,0 +1,60 @@
+Submitting a ticket
+==========================
+
+Tickets are tracked at the `DZGUI issue tracker <https://github.com/aclist/dztui/issues>`_.
+
+You will need to `register for a GitHub account <https://github.com/signup>`_ in order to submit one.
+
+If have checked the :doc:`kb` and `closed issues <https://github.com/aclist/dztui/issues?q=is%3Aissue+is%3Aclosed>`_ area and did not find a solution, three ticket types are provided for your 
+convenience:
+
+- **Bug report**: for unexpected, breaking behavior in the application
+- **Feature request**: to propose new functionality
+- **Troubleshooting**: if all else fails, you can request help here
+
+Reports by example
+--------------------------
+
+Below are some examples of how to format a constructive report that will ensure your problem can be resolved in a timely fashion.
+
+A non-actionable report
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    Subject: add button
+
+    hi, you must add a button to show how long I have to wait to join a full server, the app is useless without this...do your job, guys!!! ;-)
+
+
+This report exhibits a number of problems:
+
+- Vague title and summary: in addition to being unclear, this will slow down filing the incoming report.
+- Problem space is poorly defined: it is not clear where the issue lies, where the feature is supposed to be implemented, nor why.
+- Lack of context: the feature may already exist, but there is not enough information to go on. Alternatively, the feature may be technically impossible to implement, but there is not enough 
+  information to go on.
+- Incorrect report type: this is a feature request filed as a bug report.
+- Unprofessional tone: the message is disrespectful towards project members and inserts the user's subjective opinion.
+
+An actionable report
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    Subject: Version 5.5.0-beta.2 crashes when selecting multiple table rows via Ctrl-click
+
+    This occurs specifically on version 5.5.0-beta.2 if the setting ALLOW_MULTI is set to ON. I was able to reproduce it using the following steps:
+
+    Distribution: Fedora
+    
+    - Ensure that ALLOW_MULTI is set to ON
+    - Open the application and immediately navigate to the Server Browser
+    - Uses the Ctrl-click binding to select multiple rows in the table
+    - After >1 row is selected, the application crashes to the desktop with the following traceback (see attached dump)
+
+    Thanks for looking into this.
+
+
+This report is actionable because it is objective, specific, and detailed:
+
+- The subject is clearly defined: specific details ensure it will be filed in a timely manner.
+- Scope is explicit: the specific version, settings, and conditions under which the problem occur were given.
+- Ample context: the user gave steps to reproduce the problem and clarified each one.
+- Courteous tone: the user interacted with project members in a professional manner.
+- Supporting information: the user provided a crash dump to expedite resolution of the issue.

docs/source/conf.py

@@ -0,0 +1,40 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'DZGUI'
+author = 'aclist'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+#html_theme = 'alabaster'
+extensions = [
+    'sphinx_rtd_theme',
+    'sphinx_copybutton',
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.githubpages"
+]
+html_theme = "sphinx_rtd_theme"
+html_static_path = ['_static']
+html_show_sphinx = False
+html_show_copyright = False
+html_show_sourcelink = False
+
+today_fmt = "%Y-%m-%d"
+release = "5.8.x"
+version = "5.8.x"

docs/source/development.rst

@@ -0,0 +1,12 @@
+Developers
+===========
+
+This project is open source under the GPLv3 license. You can find the source code on
+`GitHub <https://github.com/aclist/dztui>`_. If you wish to contribute to
+development, you will find further help in the
+`CONTRIBUTING.md <https://github.com/aclist/dztui/blob/main/CONTRIBUTING.md>`_
+file.
+
+All contributors are expected to act in accordance with the project's
+`code of conduct <https://github.com/aclist/dztui/blob/main/CODE_OF_CONDUCT.md>`_,
+and follow the project's standards and guidelines.

docs/source/index.rst

@@ -0,0 +1,69 @@
+.. DZGUI documentation master file, created by
+   sphinx-quickstart on Thu Dec 12 13:12:14 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+DZGUI documentation (|release|)
+=================================
+
+Last update: |today|
+
+What this is
+----------------
+
+A DayZ server browser/mod manager for Linux. Used to list official and community server details and quick connect to preferred servers by staging mods and concatenating launch options automatically.
+
+Source code:
+
+- `GitHub <https://www.github.com/aclist/dztui>`_
+- `Codeberg (mirror) <https://codeberg.org/aclist/dztui>`_
+
+Installation
+-------------
+- Step 1: :doc:`installation`
+- Step 2: :doc:`setup`
+
+Usage
+------
+See: :doc:`usage`.
+
+Uninstallation
+---------------
+See: :doc:`uninstallation`.
+
+Troubleshooting
+----------------
+See: :doc:`kb` or :ref:`Submitting a ticket`.
+
+.. toctree::
+   :maxdepth: 3
+   :hidden:
+
+   self
+
+.. toctree::
+   :caption: Setup
+   :maxdepth: 3
+   :hidden:
+
+   installation
+   setup
+   usage
+   uninstallation
+
+.. toctree::
+   :caption: Advanced usage
+   :maxdepth: 3
+   :hidden:
+
+   steam
+   locale
+
+.. toctree::
+   :caption: Help
+   :maxdepth: 3
+   :hidden:
+
+   kb
+   bugs
+   development

docs/source/installation.rst

@@ -0,0 +1,64 @@
+Installation
+==================
+
+Dependencies
+----------------------
+
+If not already installed, the below can be found in your system’s package manager.
+
+If any dependencies are missing when the application starts, it will warn you, so you need not take any preemptive measures here.
+
+- curl
+- jq
+- PyGObject (python-gobject)
+- steam
+- wmctrl or xdotool
+- zenity
+
+.. note::
+    All dependencies are installed out of the box on Steam Deck.
+
+Downloading
+------------------
+
+Automatic installation
+^^^^^^^^^^^^^^^^^^^^^^^
+Invoke the command below from a terminal:
+
+.. code:: console
+
+    curl -s "https://codeberg.org/aclist/dztui/raw/branch/dzgui/install.sh" | bash
+
+
+Manual installation
+^^^^^^^^^^^^^^^^^^^^
+
+Clone the repository:
+
+.. code:: console
+
+    git clone https://codeberg.org/aclist/dztui.git
+
+Set the executable bit on ``dzgui.sh``:
+
+.. code:: console
+
+    chmod +x dzgui.sh
+
+
+Launch the script:
+
+.. code:: console
+
+    ./dzgui.sh
+
+nixOS installation
+^^^^^^^^^^^^^^^^^^^
+Two packages are independently maintained by other contributors. Each takes a slightly different approach:
+
+- https://github.com/lelgenio/dzgui-nix
+- https://github.com/jiriks74/dzgui.flake
+
+Next steps
+---------------
+Proceed to the next section for setup instructions.

docs/source/kb.rst

@@ -0,0 +1,77 @@
+Knowledge Base
+==================
+
+.. _DZG-001:
+
+DZG-001: Periodically getting dropped from servers, or servers appear unreachable
+------------------------------------------------------------------------------------
+It is a longstanding issue in DayZ that the game opens a large number of connections when querying servers and/or while connected to servers.
+This can result in excess traffic on the user's PC which, depending on how much headroom your network has, can lead to getting dropped, unresponsiveness, or a timeout.
+
+If you are on Wi-Fi, try switching to a wired connection and see if the problem resolves itself. If it does, your wireless router settings do not have enough headroom for max simultaneous connections. Use a wired connection, or update your network settings to a more permissive setup.
+
+Bohemia has acknowledged this issue going back 10+ years and stated that DayZ has a heavy impact on the network, but there is as yet no proposed solution on the DayZ side.
+
+This issue is frequently seen on Steam Deck, due to the tendency for users to use it in an untethered Wi-Fi setup.
+
+.. _DZG-002:
+
+DZG-002: Some servers appear locked in the official DayZ client, and are unreachable in DZGUI
+-----------------------------------------------------------------------------------------------
+This is a variant of :ref:`DZG-001`.
+
+.. _DZG-003:
+
+DZG-003: On Steam Deck, DayZ becomes unresponsive/sluggish over time
+---------------------------------------------------------------------------------------------
+When DayZ is open for 1+ hours, a gradual loss in performance and FPS may occur on the Steam Deck.
+
+A solution that seems to work for most users is to install `Cryo Utilities <https://github.com/CryoByte33/steam-deck-utilities>`_, a third-party performance management application.
+
+.. _DZG-004:
+
+DZG-004: On Steam Deck, some mods in the Workshop show a black screen when DZGUI attempts to open them
+---------------------------------------------------------------------------------------------------------
+This is a bug in the Steam client that is being tracked at Valve's Steam for Linux issue tracker here: https://github.com/ValveSoftware/steam-for-linux/issues/9598.
+
+To resolve this issue, manually intervene in the Steam client by selecting a different context (e.g., Store, Library), waiting for it to load, then navigating back to the Workshop context. This should 
+clear the blockage and allow the contents to render.
+
+.. _DZG-005:
+
+DZG-005: Rendering problems with objects in the Winter Chernarus v2 mod
+--------------------------------------------------------------------------
+
+This mod has LOD (level of detail) bugs that may cause objects near the player, such as leaves, to render incorrectly, or cause distant trees to pop in abruptly. This is an acknowledged issue with the mod itself, not with DayZ or DZGUI.
+
+There is no user-side fix for this issue; it is a problem solely on the mod side.
+
+.. _DZG-006:
+
+DZG-006: After moving DayZ to another drive, DZGUI fails to locate it on initial setup
+----------------------------------------------------------------------------------------
+If you recently moved the location of DayZ using Steam's internal dialogs, it may take some time for this information to update internally on Steam's side.
+
+Steam stores the location of installed games in a unified file, and DZGUI checks this file during initial setup to determine where Steam claims DayZ is installed.
+
+If you recently moved DayZ to a different drive or partition but did not restart Steam, this information may be out of date, causing Steam to report the wrong location.
+
+Try restarting the Steam client and starting the DZGUI initial setup again.
+
+.. _DZG-007:
+
+DZG-007: Why do I need a Steam Web API key? Is it safe?
+----------------------------------------------------------
+In order to provide a server browser showing a searchable list of all available servers, DZGUI utilizes the Steam Web API.
+
+Actual connections and queries to individual servers are performed directly between the computer and the DayZ server.
+
+DZGUI gets its server information directly from the most authoritative source: Steam. It does this by letting the user be solely in control of their own API key and the application in an authenticated way. Users explicitly get permission to use a Web API key instead of scraping DayZ server info from third-party sites.
+
+Everything that happens between DZGUI and the Steam Web API endpoint takes place solely on the user's computer, using a GET request (fetch server list), and no information gets sent back to the developer. DZGUI does not scrape third party DayZ APIs without permission.
+
+There is some misconception that a Steam Web API key could be used to gain information about a user's account or control their account. Not only is this not possible, but the Web API key is used solely by the user on their own computer and is protected by Steam Guard.
+
+A Steam Web API key is the most strict way of getting authentic, reliable, and consistent server information in a zero-trust model.
+
+You are responsible for the creation, storage, management, and revocation of your Web API key.

docs/source/locale.rst

@@ -0,0 +1,12 @@
+Locale support
+==================
+
+For internationalization purposes, DZGUI will inherit the default locale setting on the system when displaying numbers.
+
+This is used for thousands separators in long numbers and decimal separators in fractional numbers.
+
+If you wish to use a specific regional numbering preference while retaining a different base system language (e.g., English language with German-style numbering), pass the desired locale as a variable before launching DZGUI:
+
+``LC_ALL=de_DE.UTF-8 ./dzgui.sh``
+
+If you intend to use this frequently, you could wrap the above in a script or alias.

docs/source/setup.rst

@@ -0,0 +1,53 @@
+Setup
+=========
+
+DayZ license
+-----------------
+
+Prepare a Steam account with a DayZ license (i.e., own the game). From Steam's right-click menu for the game options, under ``Compatibility``, enable a Proton version ≥ ``6.8`` (or use Proton 
+Experimental for the latest version).
+
+As of this writing, any recent version of Proton should work, and it is encouraged to use the most recent one.
+
+
+API keys
+-------------
+
+You will need at a minimum a :ref:`Steam Web API key<steam_api>` in order to browse the server index.
+
+.. _steam_api:
+
+Steam Web API key
+^^^^^^^^^^^^^^^^^^
+
+**This step is required**.
+
+Register for a `Steam Web API key <https://steamcommunity.com/dev/apikey>`_ (free) using your Steam account. You will be asked for a unique URL for your app when registering.
+
+Since this key is for a personal use application and does not actually call back anywhere, set a generic local identifier here like "127.0.0.1" or some other name that is meaningful to you.
+
+Once configured, you can insert this key in the app when launching it for the first time.
+
+.. note::
+    If you are confused about this requirement, please refer to DZGUI Knowledge Base article :ref:`DZG-007<DZG-007>` for additional information.
+
+Battlemetrics API key
+^^^^^^^^^^^^^^^^^^^^^^
+**This step is optional, but recommended**. Using this key lets you also connect to and query servers by their shorthand ID instead of by IP.
+
+Register for an API key at `BattleMetrics <https://www.battlemetrics.com/account/register?after=%2Fdevelopers>`_ (free).
+
+From the ``Personal Access Tokens area``, select ``New Token``.
+
+Give the token any name in the field at the top.
+
+Leave **all options unchecked** and scroll to the bottom. Select ``Create Token``.
+
+Once configured, you can insert this key in the app when launching it for the first time (optional), or later on when using the connect/query by ID methods in the app.
+
+.. tip::
+    Each server has a unique ID. This is the string of numbers at the end of the URL. For example, in the URL ``https://www.battlemetrics.com/servers/dayz/8039514``, the ID is ``8039514``.
+
+Next steps
+--------------
+Proceed to the next section for usage instructions.

docs/source/steam.rst

@@ -0,0 +1,90 @@
+Steam integration
+====================
+
+DZGUI can be added to Steam as a "non-Steam game" in order to facilitate integration with Steam Deck or desktop environments.
+
+First, launch Steam in the **Large** (default) view.
+
+.. attention::
+   Steam Deck users: Gaming Mode has limited support for configuration of custom games. You will need to switch to **Desktop Mode** in order to add a non-Steam game.
+
+.. figure:: images/01.png
+   :scale: 70%
+   :alt: Adding a non-Steam game
+
+Select **Add a Game** > **Add a Non-Steam Game** from the bottom left corner of the Steam client.
+
+Navigate to ``$HOME/.local/share/applications`` and select ``dzgui.desktop``.
+
+Select **Add Selected Programs** to add a shortcut to DZGUI.
+
+Artwork
+^^^^^^^^^^
+
+DZGUI ships with custom artwork that provides various cover/splash images to allow it to integrate with the rest of your games library.
+
+.. figure:: images/02.png
+   :scale: 70%
+   :alt: Adding a non-Steam game
+
+From the main library view, navigate to the app’s details page and right-click the blank image header at the top.
+
+.. figure:: images/03.png
+   :scale: 70%
+   :alt: Adding a non-Steam game
+
+
+Select **Set Custom Background**
+
+Select to display **All Files** from the **File type** dropdown
+
+Navigate to ``$HOME/.local/share/dzgui`` and select ``hero.png``.
+
+.. figure:: images/04.png
+   :scale: 70%
+   :alt: Adding a non-Steam game
+
+Next, right-click the image background and select **Set Custom Logo**.
+
+Navigate to ``$HOME/.local/share/dzgui`` and select ``logo.png``.
+
+.. figure:: images/05.png
+   :scale: 70%
+   :alt: Adding a non-Steam game
+
+Notice that this removes the redundant app name that occluded the image, as seen above.
+
+.. figure:: images/06.png
+   :scale: 70%
+   :alt: Adding a non-Steam game
+
+Next, navigate to your Library index (looks like a bookshelf of cover art) and find the DZGUI app.
+
+Right-click its cover and select **Manage** > **Set custom artwork**.
+
+Navigate to ``$HOME/.local/share/dzgui`` and select ``grid.png``.
+
+.. figure:: images/07.png
+   :scale: 70%
+   :alt: Adding a non-Steam game
+
+The final result will create box art looking like the above.
+
+.. figure:: images/08.png
+   :scale: 100%
+   :alt: Adding a non-Steam game
+
+Next, right-click the DZGUI entry in your Library and select **Properties** to open the properties dialog. Next to the **Shortcut** field, you will see a small square box which represents the game’s 
+icon. Click this to open a file explorer, navigate to ``$HOME/.local/share/dzgui``, and select ``icon.png``. This will add a small icon to the list view.
+
+Finally, after you launch DZGUI for the first time, you should quit the application and return to the Library view. Select the **Recent Games** dropdown on the right-hand side.
+
+Steam shows a collection of box art based on categories like "Play Next", "Recent Games", etc. Look for a **downward-pointing caret icon** and click it, then select the **Recent Games** category.
+
+.. figure:: images/09.png
+   :scale: 100%
+   :alt: Adding a non-Steam game
+
+If DZGUI was the last item played, it will be shown with a landscape, rather than portrait, orientation cover, which is initially blank.
+
+To customize this cover, right click it and select **Manage** > **Set custom artwork**, navigate to ``$HOME/.local/share/dzgui``, then select ``hero.png``.

docs/source/uninstallation.rst

@@ -0,0 +1,12 @@
+Uninstallation
+==================
+
+To uninstall DZGUI and its associated files, invoke ``./dzgui.sh`` with the ``-u`` or ``--uninstall`` flag.
+
+Follow the prompts to choose from:
+
+- **Full uninstall** -- removes the application and all user-defined configuration files
+- **Partial uninstall** -- removes the application, but keeps user-defined configuration files
+
+.. tip::
+    If you intend to reinstall DZGUI again, keeping your configuration files is recommended.

docs/source/usage.rst

@@ -0,0 +1,25 @@
+Usage
+=========
+
+It is always advised to have Steam running in the background. DZGUI is meant to run "on top of" Steam.
+
+DZGUI can be launched in one of three ways.
+
+From a terminal
+------------------
+
+Invoke the command ``./dzgui.sh`` from wherever you downloaded the DZGUI script to.
+
+Launching from a terminal may give more verbose information in the event of a crash, and can be a good way of troubleshooting problems.
+
+From the shortcut shipped with the application
+--------------------------------------------------
+
+On most distributions, if you are using a desktop environment based on the Freedesktop specification, shortcuts will be installed for you.
+
+- One shortcut is located under the ``Games`` category of your system’s applications list/start menu.
+- The other is accessed via the ``DZGUI`` desktop icon (Steam Deck only)
+
+From Steam
+--------------
+See :doc:`steam`.