tworu/dzgui
1
0 Fork 0
mirror of https://github.com/aclist/dztui.git synced 2026-10-30 14:42:54 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: update docs

Browse Source
This commit is contained in:
aclist committed 2023-11-22 15:31:08 +09:00
1 parent 035adb7d3e
commit ccf914f9bd
3 files changed
+575 -36
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/dzgui_dark.adoc
+66 -35
View File
@@ -89,23 +89,27 @@ echo 'vm.max_map_count=1048576' | sudo tee /etc/sysctl.d/dayz.conf
. **Enable a Proton version ≥ `6.8` (or use Experimental) in the `Compatibility` field of the game's right-click options.**
=== API key & server IDs
==== BattleMetrics API key
==== Steam API key (required)
1. Register for a https://steamcommunity.com/dev/apikey[Steam API key] (free) using your Steam account. You will be asked for a unique URL for your app when registering.
2. 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.
3. Once configured, you can insert this key in the app when launching it for the first time.
==== BattleMetrics API key (optional)
This step is optional. Using this key in conjunction with the above allows you to connect to and query servers by ID instead of by IP. See <<Add server by ID>>.
1. Register for an API key at https://www.battlemetrics.com/account/register?after=%2Fdevelopers[BattleMetrics] (free)
2. From the **Personal Access Tokens** area, Select **New Token**
3. Give the token any name in the field at the top
4. Leave all options **unchecked** and scroll to the bottom, select **Create Token**
5. Copy the access token for later use (see below). This is the unique token you will use to query servers.
==== Steam API key
1. Register for a https://steamcommunity.com/dev/apikey[Steam API key] (free) using your Steam account. You will be asked for a unique URL for your app when registering.
2. 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.
3. Once configured, you can insert this key in the app when launching it for the first time.
5. 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 for the first time.
=== First-time launch
0. It is always advised to have Steam running in the background. DayZ is meant to run "on top of" Steam.
1. DZGUI can be launched one of two ways.
1. DZGUI can be launched one of two ways.
**From the terminal:**
@@ -113,24 +117,23 @@ echo 'vm.max_map_count=1048576' | sudo tee /etc/sysctl.d/dayz.conf
./dzgui.sh
```
Launching from the terminal gives more verbose information in the event of a crash,
and can be a good way of troubleshooting problems.
Launching from the terminal gives 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** (if using a desktop environment based on the Freedesktop specification):
- Located under the "Games" category of your system's applications list.
- Via the DZGUI desktop shortcut (Steam Deck only)
- Via the "DZGUI" desktop shortcut (Steam Deck only)
[start=2]
2. Follow the menu prompts given by the app. You will be asked to provide:
- Player name (a generic handle, required by some servers)
- BM API key (see above)
- Steam API key
- Steam API key (required)
- BM API key (optional)
==== Steam path discovery
DZGUI will then attempt to locate your default Steam installation and DayZ path. You *must* have DayZ installed in your Steam library in order to proceed. (It can be installed to any drive of your choosing.)
DZGUI will now attempt to locate your default Steam installation and DayZ path. You *must* have DayZ installed in your Steam library in order to proceed. (It can be installed to any drive of your choosing.)
If DZGUI cannot find Steam or cannot find DayZ installed at the detected Steam path, it will prompt you to manually specify the path to your Steam installation.
Specify the top-level entry point to Steam, not DayZ. E.g.,
@@ -153,10 +156,10 @@ For GTK 3, invoke the command:
DZGUI can be added to Steam as a "non-Steam game" in order to facilitate integration with Steam Deck or desktop environments.
1. Launch Steam in the "Large" view.
1. Launch Steam in the "Large" view.
[NOTE]
Steam Deck: you must switch to "Desktop Mode" and launch Steam from the desktop.
Steam Deck: you must switch to "Desktop Mode" and launch Steam from the desktop. Steam Deck Game Mode does not support keyboard entry on some third party apps.
[start=2]
2. Select **Add a Game** > **Add a Non-Steam Game** from the lower left-hand corner.
@@ -237,11 +240,11 @@ Script:
```
<path to script><script name>.old
```
E.g., if DZGUI is named `dzgui`, in the path `$HOME/bin`, it will be located at
E.g., if DZGUI is named `dzgui`, in the path `$HOME/bin`, the backup will be located at
```
$HOME/bin/dzgui.old
```
If launching DZGUI via its system shortcut, the backup file (similarly for log files) will be located under:
If launching DZGUI via its system shortcut, the backup file will be located under:
```
$HOME/.local/share/dzgui
@@ -256,12 +259,13 @@ $HOME/.config/dztui/dztuirc.old
== Usage
Select from among the <<Menu options>> below.
Connecting to a server consists of fetching metadata for the server IDs you have previously saved/are searching for.
Connecting to a server consists of fetching metadata for the server(s) you are searching for.
DZGUI will check the server's modset against your local mods. If you are missing any,
it will prompt you to download them through the Steam Workshop and open a window in the background in the system browser.
Open each link and click Subscribe to schedule these for download.
[NOTE]
You must be logged into Steam for mod changes to take effect.
It can take some time for the subscribed mods to download and update.
@@ -277,8 +281,7 @@ These servers can be filtered by various parameters in order to display a more g
After a server is selected from the list, the application continues to the mod validation step.
[NOTE]
It is not currently possible to save servers from the full server browser.
Prior to connecting, DZGUI will prompt you if you want to add this server to your <<My servers>>.
===== Filters
@@ -337,23 +340,38 @@ after selecting the initial server.
==== Quick connect to favorite server
Bypasses the server list and quick-connects to a single favorite server specified in advance using the <<Add favorite server>> option.
==== Connect by ID
Requires a BM API key. Use the https://www.battlemetrics.com/servers/dayz[BattleMetrics site] to find servers of interest (proximity, player count, rules, etc.)
Each server has a unique ID. This is the string of numbers at the end of the URL. Copy these IDs.
For example, in the URL https://www.battlemetrics.com/servers/dayz/8039514, the ID is `8039514`.
Enter the ID of a server to have it translated to an IP. After this step, the process continues as though you were connecting by IP.
==== Connect by IP
Instead of relying on server IDs, returns the list of maps behind a given IP.
Provide only the IP; no port is necessary. This returns the server metadata for you to verify before connecting.
If there are multiple maps hosted behind an IP (e.g. different maps on varying ports), the application will list all of them.
If there are multiple maps hosted behind an IP (e.g. different maps on varying ports), the application will list all of them for you to choose from.
==== Recent servers
This feature queries the history file for the last 10 servers connected to by any means
(server browser, favorite servers, connect-by-IP, etc.).
==== Add server by ID
Use the https://www.battlemetrics.com/servers/dayz[BattleMetrics site] to find servers of interest (proximity, player count, rules, etc.)
Requires a BM API key. Use the https://www.battlemetrics.com/servers/dayz[BattleMetrics site] to find servers of interest (proximity, player count, rules, etc.)
Each server has a unique ID. This is the string of numbers at the end of the URL. Copy these IDs.
For example, in the URL https://www.battlemetrics.com/servers/dayz/8039514, the ID is `8039514`.
An indefinite number of servers can be added. These will be listed when using the <<My servers>> option.
Servers you add will be saved and listed when using the <<My servers>> option.
==== Add server by IP
Like the above, only using the direct IP of the server in question.
Provide only the IP; no port is necessary. This returns the server metadata for you to verify before connecting.
If there are multiple maps hosted behind an IP (e.g. different maps on varying ports), the application will list all of them for you to choose from.
==== Add (change) favorite server
Prompts you to add/change a favorite server to the config file by ID. The name of the server will be updated in the header of the app. This server is used when selecting the <<Quick connect to favorite server>> option. If a favorite server is already enabled, this option switches to "Change favorite server."
@@ -377,23 +395,27 @@ The app ships with the stable branch enabled, with the testing branch being used
===== Toggle debug mode
Toggles debug mode, which is used to perform dry-runs and output what parameters would have been used to connect to a server.
===== Generate debug log
Writes a list of your current settings to a local file that can be pasted into bug reports.
===== Toggle auto mod install
This feature is experimental. It attempts to queue the mods requested for download
automatically, rather than prompting the user to subscribe to each one.
This feature is experimental. It attempts to queue the mods requested for download automatically, rather than prompting the user to subscribe to each one.
Both `wmctrl` and `xdotool` must be installed to use this feature.
[NOTE]
When using auto mod installation, the mods will not appear as subscribed to in the Steam Workshop.
When using auto mod installation, the mods may not appear as subscribed to in the Steam Workshop.
DZGUI tracks their version internally and will trigger an update if necessary the next time you
attempt to connect.
===== Change player name
Used to change the in-game player name that is broadcast when on servers.
===== Output system info
Writes a list of your current settings and system configuration to a local file that can be pasted into bug reports.
===== Force update local mods
A convenience function that attempts to redownload all local mods. Can be used in the event of corruption
or file integrity issues. In conjunction with the <<Toggle auto mod install>> feature, this feature is experimental.
Attempts to refresh the version of all local mods to the newest version by checking remote mod hashes and requesting updates from Steam.
This is a convenience feature that attempts to redownload all local mods. Can be used in the event of corruption or file integrity issues. In conjunction with the <<Toggle auto mod install>> feature, this feature is experimental.
==== Help file
Uses xdg-open to open this documentation in the system browser.
@@ -404,6 +426,12 @@ Uses xdg-open to open the https://github.com/aclist/dztui/issues[bug tracker] in
==== Forum
Uses xdg-open to open the https://github.com/aclist/dztui/discussions[discussion forum] in the system browser.
==== Sponsor
Uses xdg-open to open the https://github.com/sponsors/aclist[sponsor page], where you can help fund development, in the system browser.
==== Hall of fame
Uses xdg-open to open the https://aclist.github.io/dzgui/dzgui#_hall_of_fame[Hall of Fame], which recognizes those who actively contributed to the betterment of the application through bug reports and suggestions, in the system browser.
== Config file key/value pairs
Under normal usage, these values are populated and toggled automatically in-app. This config file is partially compatible with DZTUI.
@@ -414,12 +442,12 @@ Under normal usage, these values are populated and toggled automatically in-app.
|`api_key`|the API key generated at BattleMetrics. See <<Setup>>
|`whitelist`|comma-separated list of server IDs from BattleMetrics; integer-values only
|`fav`|server to display in the `Fav` field and to quick-connect to (must be one only); integer-values only
|`name`|an arbitrary "handle" name used to identify the player on a server (required by some servers)
|`fav_server`|server to display in the `Fav` field and to quick-connect to (must be one only); a concatenation of the IP/Gameport/Queryport
|`fav_label`|the human-readable name of the fav server set above
|`name`|a custom "handle" name used to identify the player on a server (required by some servers)
|`debug`|by default, set to 0; set to `1` to print launch options that would have been run, instead of actually connecting (used for troubleshooting and submitting bug reports)
|`branch`|by default, set to `stable`; set to `testing` to fetch the testing branch
|`seen_news`|stores a hash of the news item last seen by the client. This is used to suppress news messages until a new one is posted
|`term`|the preferred terminal emulator. This key is deprecated.
|`auto_install`|permissible values are 0, 1, and 2. These are set internally depending on if the user enabled auto mod installation
|`staging_dir`|a directory used to stage mods while downloading. This feature is deprecated and is no longer user-configurable
|`default_steam_path`|the path to the default Steam client installation
@@ -473,3 +501,6 @@ Tracked down several highly obscure but key bugs in the early development of the
.StevelDusa
Played a critical role in the elaboration of many of the features we now take for granted by being an early beta tester who not only reported bugs, but
helped workshop and brainstorm various ideas that turned into QOL features.
.Thiughtduck216
Contributed extensive beta testing of Steam Deck builds and provided ongoing troubleshooting for Steam Deck users