jiriks74/dztui
1
0
Fork 0
mirror of https://github.com/aclist/dztui.git synced 2024-12-29 13:52:03 +01:00
Code Issues Wiki Activity Actions

docs: update help file

Browse source
This commit is contained in:
aclist 2023-05-15 21:55:58 +09:00
parent 4058bfe383
commit fcce81fcfe
1 changed files with 80 additions and 53 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

133
dzgui.adoc
View file

@ -64,8 +64,12 @@ This process writes the count to the file `/etc/sysctl.d/dayz.conf`.
If the map count was lower than the threshold, it is updated to 1048576.
If the system map count was already higher, that value is interpolated into this file as a redundancy check.
[NOTE]
If, for reasons unrelated to DayZ, you choose at a later time to raise your system map count higher than it originally was and
you find that the count is not sticking, check for the presence of the `dayz.conf` file to see if it is taking precedence and delete it accordingly.
**Ephemeral method:**
The map count will revert after the system is rebooted.
the map count will revert after the system is rebooted.
```
sudo sysctl -w vm.max_map_count=1048576
@ -89,12 +93,14 @@ echo 'vm.max_map_count=1048576' | sudo tee /etc/sysctl.d/dayz.conf
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] 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".
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.
=== 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.
**From the terminal:**
@ -103,9 +109,10 @@ echo 'vm.max_map_count=1048576' | sudo tee /etc/sysctl.d/dayz.conf
./dzgui.sh
```
Launching from the terminal gives more verbose information, 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)
**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)
@ -113,9 +120,9 @@ Launching from the terminal gives more verbose information, and can be a good wa
[start=2]
2. Follow the menu prompts given by the app. You will be asked to provide:
- API key (see above)
- Player name (a generic handle, required by some servers)
- At least one server ID
- BM API key (see above)
- Steam API key
==== Steam path discovery
@ -126,9 +133,9 @@ Specify the top-level entry point to Steam, not DayZ. E.g.,
`/media/mydrive/Steam`, not `/media/mydrive/Steam/steamapps/common/DayZ`
If your Steam installation is in a hidden folder but the file picker dialog does not show hidden folders, ensure that your GTK settings include the parameter `ShowHidden=true`.
If your Steam installation is in a hidden folder but the file picker dialog does not show hidden folders, ensure that your GTK settings are set to show hidden files.
For GTK 2, edit the file:
For GTK 2, edit the file below so that `ShowHidden=true`:
`~/.config/gtk-2.0/gtkfilechooser.ini`
@ -209,14 +216,18 @@ image::https://github.com/aclist/dztui/raw/testing/images/tutorial/07.png[07,700
=== Updating the app
If DZGUI detects a new upstream version, it will prompt you to download it automatically. It backs up the original version before fetching the new one, then updates your config file with your existing values. Once finished, it will ask you to relaunch the app.
If DZGUI detects a new upstream version, it will prompt you to download it automatically.
It backs up the original version before fetching the new one, then updates your config file with your existing values. Once finished, it will ask you to relaunch the app.
If you decline to upgrade to the new version, DZGUI will continue to the main menu with the current version.
[NOTE]
New versions may include changes to bugs that could prevent you from playing on certain servers. Upgrading is always advised.
New versions may include changes to bugs that could prevent you from playing on certain servers.
Upgrading is always advised.
If you experience a problem or need to restore the prior version of DZGUI and/or your configs, it is enough to simply replace the new version with the old one and relaunch the app. The files can be found at:
If you experience a problem or need to restore the prior version of DZGUI and/or your configs,
it is enough to simply replace the new version with the old one and relaunch the app.
The files can be found at:
Script:
```
@ -232,22 +243,27 @@ If launching DZGUI via its system shortcut, the backup file (similarly for log f
$HOME/.local/share/dzgui
```
Backup config files:
Backup config file:
```
$HOME/.config/dztui/dztuirc.old
```
== Usage
Select <<My servers>> to fetch details for the server IDs you provided. Select the server you wish to connect to and click OK.
Select from among the <<Menu options>> below.
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.
Connecting to a server consists of fetching metadata for the server IDs you have previously saved/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 change to take effect. It can take some time for the subscribed mods to download and update. You can continue clicking Next to regenerate the list, or wait for all of them to complete.
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.
Once all of the mods are downloaded and staged, DZGUI will notify you that it is ready to connect. The app hands the launch parameters to Steam and exits.
Once all of the mods are downloaded and staged, DZGUI will notify you that it is ready to connect.
The app hands the launch parameters to Steam and exits.
== Menu options
@ -257,11 +273,6 @@ 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.
In order to use this feature, you must have a https://steamcommunity.com/dev/apikey[Steam API key]. 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".
You will be prompted to insert this key into the app when launching the server browser for the first time.
[NOTE]
It is not currently possible to save servers from the full server browser.
@ -290,7 +301,8 @@ Note: unticking this filter will also exclude CJK languages, Cyrillic, and other
===== Table details
After retrieval, the browser presents a table of results with the following parameters.
Due to the density of information, the table will try to render at a minimum of 1920x1080 on a desktop or at fullscreen on a Steam Deck.
Due to the density of information, the table will try to render at a minimum of 1920x1080
on a desktop or at fullscreen on a Steam Deck.
- Total matches/total servers queried
- Total players online on all servers
@ -299,13 +311,13 @@ Due to the density of information, the table will try to render at a minimum of
- Gametime: the in-game time
- Players: this is zero-padded for sorting purposes
- Max players: this is zero-padded for sorting purposes
- Distance: the physical distance to the server in kilometers is calculated by geolocation
- Distance: the physical distance to the server in kilometers, calculated by geolocation
- IP: the IP address and port
- Qport: the query port used to retrieve metadata and rules
==== My servers
Fetches detailed server information on the list of servers saved in the config file. This is the main place you interact with DZGUI when choosing a server from your list. These details are:
Fetches detailed server information on the list of servers saved by <<Add server by ID>>.
Outside of the server browser, this is the main place you interact with DZGUI when choosing a server from your list. These details are:
- **Server**: name of the server, truncated to 50 chars
- **IP/port**: IP address and port in the format `ip:port`
@ -315,6 +327,9 @@ Fetches detailed server information on the list of servers saved in the config f
- **ID**: numerical ID from BattleMetrics, used as a reference when troubleshooting or sharing servers
- **Ping**: round-trip response time from the server
In the event that a server has multiple maps behind different ports, these will all be displayed
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.
@ -325,36 +340,30 @@ Provide only the IP; no port is necessary. This returns the server metadata for
If there are multiple maps hosted behind an IP (e.g. different maps on varying ports), the application will list all of them.
==== 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[DayZ server browser] to find servers of interest (proximity, player count, rules, etc.)
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.
==== Add favorite server
==== 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."
==== Change favorite server
==== Delete server
Prints a list of human-readable servers currently saved, and lets you delete them by selecting one from the list.
==== List installed mods
Prints a scrollable dialog containing all locally-installed mods and their corresponding symlink IDs and directory names.
==== Report bug
Using the system browser, opens the project's GitHub issues page to submit a report.
==== Help file
Using the system browser, opens this document.
==== View changelog
Prints the entire changelog up to the current version (and unreleased changes) in-app.
Prints the entire changelog up to the current version in-app.
===== Advanced options
==== Advanced options
If enabled, this menu contains a sub-menu with various advanced features, enumerated below.
===== Toggle branch
@ -368,17 +377,31 @@ Toggles debug mode, which is used to perform dry-runs and output what parameters
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.
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.
DZGUI tracks their version internally and will trigger an update if necessary the next time you
attempt to connect.
===== 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.
===== Help file
==== Help file
Uses xdg-open to open this documentation in the system browser.
===== Report bug
==== Report bug
Uses xdg-open to open the https://github.com/aclist/dztui/issues[bug tracker] in the system browser.
===== Forum
==== Forum
Uses xdg-open to open the https://github.com/aclist/dztui/discussions[discussion forum] 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 DZTUI.
Under normal usage, these values are populated and toggled automatically in-app. This config file is partially compatible with DZTUI.
[%autowidth]
@ -391,28 +414,32 @@ Under normal usage, these values are populated and toggled automatically in-app.
|`name`|an arbitrary "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.
|`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
|`preferred_client`|whether the user prefers native Steam or Flatpak. This value is only set if concurrent installations are found on the system
|===
== Troubleshooting/FAQ
.Mods take a long time to synchronize when subscribing from Workshop
Steam schedules the downloads in the background and processes them as they are subscribed to. This process is not instantaneous and can take some time. Check the **Downloads** pane of Steam to see live progress.
Steam schedules the downloads in the background and processes them as they are subscribed to.
This process is not instantaneous and can take some time.
.Game does not launch through Steam
Check the logs emitted by Steam in the terminal, or in `<steam path>/error.log`.
.Game launches, but throws a "mod missing/check PBO file" error when connecting
In rare cases, the server may be using misconfigured, malformed, or obsolete mods. This is out of our control and depends on server operators checking their mods for integrity. If you believe the mods are correct and this is a bug, please report it.
In rare cases, the server may be using misconfigured, malformed, or obsolete mods.
This depends on server operators checking their mods for integrity.
.Game and server launches, but when joining the game world, an error occurs
A mod is corrupted or the issue lies with the server. Replace the mods in question and reconnect.
== Testers wanted
If any of the below apply to you, your https://github.com/aclist/dztui/issues[reports] are encouraged:
- Using a high resolution (4K) monitor
- Own a Steam Deck
- Seeking DZTUI functionality in DZGUI, or vice versa
- Playing on a server with an enormous amount of mods
- Playing on a server with non-English mod names (?)
.The game is slow or prone to crashing
DayZ does not manipulate the game itself and does not contribute to/degrade its performance.
If you are experiencing performance degradation, it can be caused by too many mods installed or
by a server-side problem (underpowered server, misconfiguration, etc.) Contract the server administrator
for assistance.