Lyra: Created page with "NOTOC This page covers common issues players may encounter and how to resolve them. {{Note|If your issue isn't listed here, please open a support ticket on our [https://discord.com/invite/YtchjbyQyY Discord server].}} == Patcher Issues == === Patcher won't launch === '''Cause:''' Missing .NET 8 Desktop Runtime '''Solution:''' # Download and install [https://dotnet.microsoft.com/download/dotnet/8.0 .NET 8 Desktop Runtime] from Microsoft # Restart the patcher ===..."

2025-12-25T01:55:23Z

Created page with "__NOTOC__ This page covers common issues players may encounter and how to resolve them. {{Note|If your issue isn't listed here, please open a support ticket on our [https://discord.com/invite/YtchjbyQyY Discord server].}} == Patcher Issues == === Patcher won't launch === '''Cause:''' Missing .NET 8 Desktop Runtime '''Solution:''' # Download and install [https://dotnet.microsoft.com/download/dotnet/8.0 .NET 8 Desktop Runtime] from Microsoft # Restart the patcher ===..."

New page

__NOTOC__
This page covers common issues players may encounter and how to resolve them.

{{Note|If your issue isn't listed here, please open a support ticket on our [https://discord.com/invite/YtchjbyQyY Discord server].}}

== Patcher Issues ==

=== Patcher won't launch ===

'''Cause:''' Missing .NET 8 Desktop Runtime

'''Solution:'''
# Download and install [https://dotnet.microsoft.com/download/dotnet/8.0 .NET 8 Desktop Runtime] from Microsoft
# Restart the patcher

=== "Windows protected your PC" warning ===

'''Cause:''' Windows SmartScreen doesn't recognize the patcher because it's new software

'''Solution:'''
# Click "'''More info'''"
# Click "'''Run anyway'''"

This is safe — our patcher is not malicious.

=== Patcher won't connect / Stuck at patching ===

'''Possible causes and solutions:'''

# '''Firewall blocking the connection'''
#* Add the HymnRO Patcher to your firewall's exception list
#* Temporarily disable your firewall to test
# '''Antivirus interference'''
#* Add the HymnRO folder to your antivirus exclusions
#* Common culprits: Avast, McAfee, Windows Defender
# '''Corrupted download'''
#* Delete the HymnRO folder and re-download from the [https://hymnro.com/?module=pages&action=content&path=downloads downloads page]

=== Patcher shows errors while downloading files ===

'''Solution:'''
# Close the patcher
# Re-open and let it retry
# If the issue persists, try downloading at a different time (server may be busy)

== Game Client Issues ==

=== Game won't start / Closes immediately ===

'''First-time players:'''
# Make sure you clicked '''SETUP''' in the patcher first
# Configure your resolution settings
# Then launch the game

'''If it still doesn't work:'''
# Right-click the game executable → Properties → Compatibility
# Check "'''Run as administrator'''"
# Try checking "'''Run in compatibility mode for Windows 7'''"

=== Black screen after launching ===

'''Possible causes and solutions:'''

# '''Resolution issue'''
#* Run SETUP and try a lower resolution
#* Try switching between Fullscreen and Windowed mode
# '''Graphics driver issue'''
#* Update your graphics drivers from the manufacturer's website (NVIDIA, AMD, Intel)
# '''DirectX issue'''
#* Install/repair DirectX from Microsoft

=== Game crashes randomly ===

'''Common solutions:'''

# '''Close background applications'''
#* Discord overlay can cause crashes — try closing Discord completely
#* Logitech G Hub has been known to cause issues
#* Close any screen recording or streaming software
# '''Disable overlays'''
#* Turn off NVIDIA GeForce Experience overlay
#* Disable Steam overlay (if applicable)
#* Disable Discord overlay
# '''Run as administrator'''
#* Right-click the game → Properties → Compatibility → "Run as administrator"
# '''Disable fullscreen optimizations'''
#* Right-click the game → Properties → Compatibility → "Disable fullscreen optimizations"

=== "Failed to connect to server" ===

'''Possible causes and solutions:'''

# '''Server maintenance'''
#* Check our [https://discord.com/invite/YtchjbyQyY Discord] for announcements
# '''Firewall/Antivirus blocking'''
#* Add the game to your firewall exceptions
#* Whitelist the HymnRO folder in your antivirus
# '''Internet connection issue'''
#* Restart your router
#* Try a different network if possible

=== "Disconnected from server" after character select ===

'''Possible causes and solutions:'''

# '''Unstable internet connection'''
#* Check your connection stability
#* Try using a wired connection instead of WiFi
# '''VPN interference'''
#* If using a VPN, try disabling it
#* Some VPNs can cause connection issues

=== Game freezes but doesn't crash ===

'''Solution:'''
# Press '''Alt+Tab''' to switch to another window, then switch back
# If that doesn't work, press '''Alt+F4''' to close the game
# As a last resort, open Task Manager (Ctrl+Shift+Esc) and end the process

== Performance Issues ==

=== Game is laggy / Low FPS ===

'''Solutions:'''

# '''Lower graphics settings'''
#* Run SETUP and reduce resolution
#* Enable "Reduced graphics" options if available
# '''Close background applications'''
#* Close unnecessary programs, especially browsers with many tabs
# '''Update graphics drivers'''
#* Download latest drivers from your GPU manufacturer

=== High ping / Network lag ===

'''Note:''' Our server is hosted in '''Germany'''. Players far from Europe may experience higher latency.

'''Solutions:'''
# '''Use a wired connection''' instead of WiFi
# '''Close bandwidth-heavy applications''' (streaming, downloads, etc.)
# '''Try a gaming VPN''' that has servers closer to Germany (may help for some players)

== Linux Support ==

{{Warning|Linux support is '''experimental''' and not officially supported. These instructions are community-provided.}}

The HymnRO Patcher is built with WebView2 and is Windows-only. However, the game client itself can be run on Linux using Wine or Lutris.

=== Running on Linux with Lutris ===

'''Prerequisites:'''
* Lutris installed
* Wine dependencies installed for your distro

=== Missing Dependencies ===

'''Issue:''' Linux does not have all dependencies installed by default. In particular, <code>dotnet desktop runtime</code> may not be present.

'''Solution:'''
* Install dependencies using Winetricks, or
* Unzip the binary files to the correct directory in the Wine prefix
* Default location: <code>/home/[username]/Games/umu/umu-default/</code>

'''Note:''' .NET Desktop Runtime does not have a native Linux version — it installs to the Wine prefix only, not to Linux itself.

=== Patcher doesn't render (blank blue screen) ===

'''Issue:''' When running through Lutris, the patcher displays entirely blue and never renders. Lutris may become unresponsive.

'''Explanation:''' This is likely caused by Wayland display servers. Distros using Wayland instead of X11 or XWayland may experience this issue.

'''Current status:''' No known solution at this time. As X11 is being phased out, workarounds may need to be developed.

'''Workaround:''' You may be able to patch on a Windows machine (or VM) and copy the patched files to Linux.

=== Game closes immediately when launched through Lutris ===

'''Issue:''' Setting the game executable in Lutris causes it to close immediately upon launch.

'''Solution:'''
In the Lutris game configuration, add the launch argument:
<code>1rag1</code>

'''Explanation:''' The game client expects an SSO login token from the patcher. The <code>1rag1</code> argument bypasses this and allows access to the regular login system.

=== "Incorrect user ID or Password" after bypassing SSO ===

'''Issue:''' After using the <code>1rag1</code> argument, login attempts return "Incorrect user ID or Password."

'''Current status:''' Under investigation.

'''Possible workarounds being explored:'''
* Running the Python login script inside a Winetricks instance
* Using Wine instead of Proton
* Other methods to force Proton compatibility

== Still Having Issues? ==

If none of the above solutions work:

# Take a screenshot of any error messages
# Note what you were doing when the issue occurred
# Open a support ticket on our [https://discord.com/invite/YtchjbyQyY Discord server]
# Provide as much detail as possible — this helps us help you faster!

== See Also ==

* [[Get Started]] — Installation guide
* [[FAQ]] — Frequently asked questions
* [[Commands]] — List of available commands

[[Category:Guides]]
[[Category:Technical]]

Troubleshooting - Revision history